CVS commit: src/lib/libc/atomic
Module Name:src Committed By: uwe Date: Fri Oct 9 19:41:03 UTC 2020 Modified Files: src/lib/libc/atomic: membar_ops.3 Log Message: Add italic correction to _Atomic-qualified. To generate a diff of this commit: cvs rdiff -u -r1.7 -r1.8 src/lib/libc/atomic/membar_ops.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files. Modified files: Index: src/lib/libc/atomic/membar_ops.3 diff -u src/lib/libc/atomic/membar_ops.3:1.7 src/lib/libc/atomic/membar_ops.3:1.8 --- src/lib/libc/atomic/membar_ops.3:1.7 Fri Oct 9 17:36:16 2020 +++ src/lib/libc/atomic/membar_ops.3 Fri Oct 9 19:41:02 2020 @@ -1,4 +1,4 @@ -.\" $NetBSD: membar_ops.3,v 1.7 2020/10/09 17:36:16 riastradh Exp $ +.\" $NetBSD: membar_ops.3,v 1.8 2020/10/09 19:41:02 uwe Exp $ .\" .\" Copyright (c) 2007, 2008 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -89,7 +89,7 @@ memory operations \(em that is, all load memory \(em are affected by .Nm , not just C11 atomic operations on -.Vt _Atomic Ns -qualified +.Vt _Atomic\^ Ns -qualified objects. .Bl -tag -width abcd .It Fn membar_enter
CVS commit: src/lib/libc/atomic
Module Name:src Committed By: riastradh Date: Fri Oct 9 17:36:16 UTC 2020 Modified Files: src/lib/libc/atomic: membar_ops.3 Log Message: Reword advice about when not to use membar_exit. With help from skrll and pgoyette. While here, change the example so it doesn't violate the advice just given. Still not a great example -- abusing UINT_MAX for a reference count is kinda sketchy, but it'll serve for now. To generate a diff of this commit: cvs rdiff -u -r1.6 -r1.7 src/lib/libc/atomic/membar_ops.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files. Modified files: Index: src/lib/libc/atomic/membar_ops.3 diff -u src/lib/libc/atomic/membar_ops.3:1.6 src/lib/libc/atomic/membar_ops.3:1.7 --- src/lib/libc/atomic/membar_ops.3:1.6 Thu Sep 3 00:00:06 2020 +++ src/lib/libc/atomic/membar_ops.3 Fri Oct 9 17:36:16 2020 @@ -1,4 +1,4 @@ -.\" $NetBSD: membar_ops.3,v 1.6 2020/09/03 00:00:06 riastradh Exp $ +.\" $NetBSD: membar_ops.3,v 1.7 2020/10/09 17:36:16 riastradh Exp $ .\" .\" Copyright (c) 2007, 2008 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -140,28 +140,40 @@ A followed by a store implies a .Em store-release operation in the language of C11. -For a regular store, rather than an atomic read/modify/write store, you -should use -.Xr atomic_store_release 9 -instead of .Fn membar_exit -followed by the store. +should only be used before atomic read/modify/write, such as +.Xr atomic_inc_uint 3 . +For regular stores, instead of +.Li "membar_exit(); *p = x" , +you should use +.Li "atomic_store_release(p, x)" . .Pp .Fn membar_exit -is typically used in code that implements locking primitives to ensure -that a lock protects its data, and is typically paired with -.Fn membar_enter . +is typically paired with +.Fn membar_enter , +and is typically used in code that implements locking or reference +counting primitives. +Releasing a lock or reference count should use +.Fn membar_exit , +and acquiring a lock or handling an object after draining references +should use +.Fn membar_enter , +so that whatever happened before releasing will also have happened +before acquiring. For example: .Bd -literal -offset abcdefgh -/* thread A */ +/* thread A -- release a reference */ obj->state.mumblefrotz = 42; KASSERT(valid(>state)); membar_exit(); -obj->lock = 0; +atomic_dec_uint(>refcnt); -/* thread B */ -if (atomic_cas_uint(>lock, 0, 1) != 0) - return; +/* + * thread B -- busy-wait until last reference is released, + * then lock it by setting refcnt to UINT_MAX + */ +while (atomic_cas_uint(>refcnt, 0, -1) != 0) + continue; membar_enter(); KASSERT(valid(>state)); obj->state.mumblefrotz--; @@ -169,11 +181,11 @@ obj->state.mumblefrotz--; .Pp In this example, .Em if -the +the load in .Fn atomic_cas_uint -operation in thread B witnesses the store -.Li "obj->lock = 0" -from thread A, +in thread B witnesses the store in +.Fn atomic_dec_uint +in thread A setting the reference count to zero, .Em then everything in thread A before the .Fn membar_exit
CVS commit: src/lib/libc/atomic
Module Name:src Committed By: riastradh Date: Thu Sep 3 00:00:07 UTC 2020 Modified Files: src/lib/libc/atomic: membar_ops.3 Log Message: Update membar_ops(3) man page with examples and relation to C11. Add exhortation to always always always document how membars come in pairs for synchronization between two CPUs when you use them. To generate a diff of this commit: cvs rdiff -u -r1.5 -r1.6 src/lib/libc/atomic/membar_ops.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files. Modified files: Index: src/lib/libc/atomic/membar_ops.3 diff -u src/lib/libc/atomic/membar_ops.3:1.5 src/lib/libc/atomic/membar_ops.3:1.6 --- src/lib/libc/atomic/membar_ops.3:1.5 Tue Oct 24 18:19:17 2017 +++ src/lib/libc/atomic/membar_ops.3 Thu Sep 3 00:00:06 2020 @@ -1,4 +1,4 @@ -.\" $NetBSD: membar_ops.3,v 1.5 2017/10/24 18:19:17 abhinav Exp $ +.\" $NetBSD: membar_ops.3,v 1.6 2020/09/03 00:00:06 riastradh Exp $ .\" .\" Copyright (c) 2007, 2008 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -27,7 +27,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd November 20, 2014 +.Dd September 2, 2020 .Dt MEMBAR_OPS 3 .Os .Sh NAME @@ -38,7 +38,7 @@ .Nm membar_consumer , .Nm membar_datadep_consumer , .Nm membar_sync -.Nd memory access barrier operations +.Nd memory ordering barriers .\" .Sh LIBRARY .\" .Lb libc .Sh SYNOPSIS @@ -58,33 +58,213 @@ .Fn membar_sync "void" .Sh DESCRIPTION The -.Nm membar_ops -family of functions provide memory access barrier operations necessary +.Nm +family of functions prevent reordering of memory operations, as needed for synchronization in multiprocessor execution environments that have relaxed load and store order. -.Bl -tag -width "mem" +.Pp +In general, memory barriers must come in pairs \(em a barrier on one +CPU, such as +.Fn membar_exit , +must pair with a barrier on another CPU, such as +.Fn membar_enter , +in order to synchronize anything between the two CPUs. +Code using +.Nm +should generally be annotated with comments identifying how they are +paired. +.Pp +.Nm +affect only operations on regular memory, not on device +memory; see +.Xr bus_space 9 +and +.Xr bus_dma 9 +for machine-independent interfaces to handling device memory and DMA +operations for device drivers. +.Pp +Unlike C11, +.Em all +memory operations \(em that is, all loads and stores on regular +memory \(em are affected by +.Nm , +not just C11 atomic operations on +.Vt _Atomic Ns -qualified +objects. +.Bl -tag -width abcd .It Fn membar_enter Any store preceding .Fn membar_enter -will reach global visibility before all loads and stores following it. +will happen before all memory operations following it. +.Pp +An atomic read/modify/write operation +.Pq Xr atomic_ops 3 +followed by a +.Fn membar_enter +implies a +.Em load-acquire +operation in the language of C11. +.Pp +.Sy WARNING : +A load followed by +.Fn membar_enter +.Em does not +imply a +.Em load-acquire +operation, even though +.Fn membar_exit +followed by a store implies a +.Em store-release +operation; the symmetry of these names and asymmetry of the semantics +is a historical mistake. +In the +.Nx +kernel, you can use +.Xr atomic_load_acquire 9 +for a +.Em load-acquire +operation without any atomic read/modify/write. .Pp .Fn membar_enter is typically used in code that implements locking primitives to ensure -that a lock protects its data. +that a lock protects its data, and is typically paired with +.Fn membar_exit ; +see below for an example. .It Fn membar_exit -All loads and stores preceding +All memory operations preceding .Fn membar_exit -will reach global visibility before any store that follows it. +will happen before any store that follows it. +.Pp +A +.Fn membar_exit +followed by a store implies a +.Em store-release +operation in the language of C11. +For a regular store, rather than an atomic read/modify/write store, you +should use +.Xr atomic_store_release 9 +instead of +.Fn membar_exit +followed by the store. .Pp .Fn membar_exit is typically used in code that implements locking primitives to ensure -that a lock protects its data. +that a lock protects its data, and is typically paired with +.Fn membar_enter . +For example: +.Bd -literal -offset abcdefgh +/* thread A */ +obj->state.mumblefrotz = 42; +KASSERT(valid(>state)); +membar_exit(); +obj->lock = 0; + +/* thread B */ +if (atomic_cas_uint(>lock, 0, 1) != 0) + return; +membar_enter(); +KASSERT(valid(>state)); +obj->state.mumblefrotz--; +.Ed +.Pp +In this example, +.Em if +the +.Fn atomic_cas_uint +operation in thread B witnesses the store +.Li "obj->lock = 0" +from thread A, +.Em then +everything in thread A before the +.Fn membar_exit +is guaranteed to happen before everything in thread B after the +.Fn membar_enter , +as if the machine had sequentially executed: +.Bd -literal -offset abcdefgh
CVS commit: src/lib/libc/atomic
Module Name:src Committed By: dholland Date: Sat Jun 16 08:11:33 UTC 2018 Modified Files: src/lib/libc/atomic: atomic_and.3 atomic_ops.3 atomic_or.3 Log Message: atomic_and/atomic_or do bitwise ops, not logical ops. To generate a diff of this commit: cvs rdiff -u -r1.1 -r1.2 src/lib/libc/atomic/atomic_and.3 \ src/lib/libc/atomic/atomic_or.3 cvs rdiff -u -r1.7 -r1.8 src/lib/libc/atomic/atomic_ops.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files. Modified files: Index: src/lib/libc/atomic/atomic_and.3 diff -u src/lib/libc/atomic/atomic_and.3:1.1 src/lib/libc/atomic/atomic_and.3:1.2 --- src/lib/libc/atomic/atomic_and.3:1.1 Mon Jun 23 10:22:40 2008 +++ src/lib/libc/atomic/atomic_and.3 Sat Jun 16 08:11:32 2018 @@ -1,4 +1,4 @@ -.\" $NetBSD: atomic_and.3,v 1.1 2008/06/23 10:22:40 ad Exp $ +.\" $NetBSD: atomic_and.3,v 1.2 2018/06/16 08:11:32 dholland Exp $ .\" .\" Copyright (c) 2007 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -40,7 +40,7 @@ .Nm atomic_and_uint_nv , .Nm atomic_and_ulong_nv , .Nm atomic_and_64_nv -.Nd atomic logical +.Nd atomic bitwise .Sq and operations .\" .Sh LIBRARY @@ -68,7 +68,7 @@ The .Nm atomic_and family of functions load the value of the variable referenced by .Fa ptr , -perform a logical +perform a bitwise .Sq and with the value .Fa bits , Index: src/lib/libc/atomic/atomic_or.3 diff -u src/lib/libc/atomic/atomic_or.3:1.1 src/lib/libc/atomic/atomic_or.3:1.2 --- src/lib/libc/atomic/atomic_or.3:1.1 Mon Jun 23 10:22:40 2008 +++ src/lib/libc/atomic/atomic_or.3 Sat Jun 16 08:11:32 2018 @@ -1,4 +1,4 @@ -.\" $NetBSD: atomic_or.3,v 1.1 2008/06/23 10:22:40 ad Exp $ +.\" $NetBSD: atomic_or.3,v 1.2 2018/06/16 08:11:32 dholland Exp $ .\" .\" Copyright (c) 2007 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -40,7 +40,7 @@ .Nm atomic_or_uint_nv , .Nm atomic_or_ulong_nv , .Nm atomic_or_64_nv -.Nd atomic logical +.Nd atomic bitwise .Sq or operations .\" .Sh LIBRARY @@ -68,7 +68,7 @@ The .Nm atomic_or family of functions load the value of the variable referenced by .Fa ptr , -perform a logical +perform a bitwise .Sq or with the value .Fa bits , Index: src/lib/libc/atomic/atomic_ops.3 diff -u src/lib/libc/atomic/atomic_ops.3:1.7 src/lib/libc/atomic/atomic_ops.3:1.8 --- src/lib/libc/atomic/atomic_ops.3:1.7 Wed Feb 7 09:59:56 2018 +++ src/lib/libc/atomic/atomic_ops.3 Sat Jun 16 08:11:32 2018 @@ -1,4 +1,4 @@ -.\" $NetBSD: atomic_ops.3,v 1.7 2018/02/07 09:59:56 martin Exp $ +.\" $NetBSD: atomic_ops.3,v 1.8 2018/06/16 08:11:32 dholland Exp $ .\" .\" Copyright (c) 2007, 2008 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -47,7 +47,7 @@ There are 7 classes of atomic memory ope .It Xr atomic_add 3 These functions perform atomic addition. .It Xr atomic_and 3 -These functions perform atomic logical +These functions perform atomic bitwise .Dq and . .It Xr atomic_cas 3 These functions perform atomic compare-and-swap. @@ -56,7 +56,7 @@ These functions perform atomic decrement .It Xr atomic_inc 3 These functions perform atomic increment. .It Xr atomic_or 3 -These functions perform atomic logical +These functions perform atomic bitwise .Dq or . .It Xr atomic_swap 3 These functions perform atomic swap.
CVS commit: src/lib/libc/atomic
Module Name:src Committed By: martin Date: Wed Feb 7 09:59:56 UTC 2018 Modified Files: src/lib/libc/atomic: atomic_ops.3 Log Message: Bump date for previous To generate a diff of this commit: cvs rdiff -u -r1.6 -r1.7 src/lib/libc/atomic/atomic_ops.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files. Modified files: Index: src/lib/libc/atomic/atomic_ops.3 diff -u src/lib/libc/atomic/atomic_ops.3:1.6 src/lib/libc/atomic/atomic_ops.3:1.7 --- src/lib/libc/atomic/atomic_ops.3:1.6 Wed Feb 7 09:55:35 2018 +++ src/lib/libc/atomic/atomic_ops.3 Wed Feb 7 09:59:56 2018 @@ -1,4 +1,4 @@ -.\" $NetBSD: atomic_ops.3,v 1.6 2018/02/07 09:55:35 martin Exp $ +.\" $NetBSD: atomic_ops.3,v 1.7 2018/02/07 09:59:56 martin Exp $ .\" .\" Copyright (c) 2007, 2008 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -27,7 +27,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd April 14, 2010 +.Dd February 7, 2018 .Dt ATOMIC_OPS 3 .Os .Sh NAME
CVS commit: src/lib/libc/atomic
Module Name:src Committed By: martin Date: Wed Feb 7 09:55:35 UTC 2018 Modified Files: src/lib/libc/atomic: atomic_ops.3 Log Message: Fix typo, from Eitan Adler. To generate a diff of this commit: cvs rdiff -u -r1.5 -r1.6 src/lib/libc/atomic/atomic_ops.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files. Modified files: Index: src/lib/libc/atomic/atomic_ops.3 diff -u src/lib/libc/atomic/atomic_ops.3:1.5 src/lib/libc/atomic/atomic_ops.3:1.6 --- src/lib/libc/atomic/atomic_ops.3:1.5 Wed Apr 14 08:49:49 2010 +++ src/lib/libc/atomic/atomic_ops.3 Wed Feb 7 09:55:35 2018 @@ -1,4 +1,4 @@ -.\" $NetBSD: atomic_ops.3,v 1.5 2010/04/14 08:49:49 jruoho Exp $ +.\" $NetBSD: atomic_ops.3,v 1.6 2018/02/07 09:55:35 martin Exp $ .\" .\" Copyright (c) 2007, 2008 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -98,7 +98,7 @@ completes. If hardware CAS is not available, the store may not reach global visibility until some time after the atomic operation has completed. However, in all cases a subsequent atomic operation on the same memory cell -will be delayed until the result of any preceeding operation has reached +will be delayed until the result of any preceding operation has reached global visibility. .Pp Atomic operations are strongly ordered with respect to each other.
CVS commit: src/lib/libc/atomic
Module Name:src Committed By: abhinav Date: Tue Oct 24 18:19:17 UTC 2017 Modified Files: src/lib/libc/atomic: membar_ops.3 Log Message: Add membar_datadep_consumer to the NAME section Remove Pp before Bl To generate a diff of this commit: cvs rdiff -u -r1.4 -r1.5 src/lib/libc/atomic/membar_ops.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files. Modified files: Index: src/lib/libc/atomic/membar_ops.3 diff -u src/lib/libc/atomic/membar_ops.3:1.4 src/lib/libc/atomic/membar_ops.3:1.5 --- src/lib/libc/atomic/membar_ops.3:1.4 Thu Jan 8 22:27:17 2015 +++ src/lib/libc/atomic/membar_ops.3 Tue Oct 24 18:19:17 2017 @@ -1,4 +1,4 @@ -.\" $NetBSD: membar_ops.3,v 1.4 2015/01/08 22:27:17 riastradh Exp $ +.\" $NetBSD: membar_ops.3,v 1.5 2017/10/24 18:19:17 abhinav Exp $ .\" .\" Copyright (c) 2007, 2008 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -36,6 +36,7 @@ .Nm membar_exit , .Nm membar_producer , .Nm membar_consumer , +.Nm membar_datadep_consumer , .Nm membar_sync .Nd memory access barrier operations .\" .Sh LIBRARY @@ -61,7 +62,6 @@ The family of functions provide memory access barrier operations necessary for synchronization in multiprocessor execution environments that have relaxed load and store order. -.Pp .Bl -tag -width "mem" .It Fn membar_enter Any store preceding
CVS commit: src/lib/libc/atomic
Module Name:src Committed By: dholland Date: Sat Aug 27 08:03:13 UTC 2016 Modified Files: src/lib/libc/atomic: Makefile.inc Log Message: Add MLINKS for atomic_add_nv, atomic_cas_ni, and so forth - otherwise you have to remember that they're the same page as plain atomic_add and atomic_cas, or remember one of the types that they're defined on. PR 51033. To generate a diff of this commit: cvs rdiff -u -r1.2 -r1.3 src/lib/libc/atomic/Makefile.inc Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files. Modified files: Index: src/lib/libc/atomic/Makefile.inc diff -u src/lib/libc/atomic/Makefile.inc:1.2 src/lib/libc/atomic/Makefile.inc:1.3 --- src/lib/libc/atomic/Makefile.inc:1.2 Fri Feb 12 22:34:38 2010 +++ src/lib/libc/atomic/Makefile.inc Sat Aug 27 08:03:13 2016 @@ -1,4 +1,4 @@ -# $NetBSD: Makefile.inc,v 1.2 2010/02/12 22:34:38 dyoung Exp $ +# $NetBSD: Makefile.inc,v 1.3 2016/08/27 08:03:13 dholland Exp $ # from: @(#)Makefile.inc 8.6 (Berkeley) 5/4/95 # gen sources @@ -18,6 +18,7 @@ MLINKS+=atomic_add.3 atomic_add_32.3 \ atomic_add.3 atomic_add_long_nv.3 \ atomic_add.3 atomic_add_ptr_nv.3 \ atomic_add.3 atomic_add_64_nv.3 \ + atomic_add.3 atomic_add_nv.3 \ atomic_and.3 atomic_and_32.3 \ atomic_and.3 atomic_and_uint.3 \ atomic_and.3 atomic_and_ulong.3 \ @@ -26,6 +27,7 @@ MLINKS+=atomic_add.3 atomic_add_32.3 \ atomic_and.3 atomic_and_uint_nv.3 \ atomic_and.3 atomic_and_ulong_nv.3 \ atomic_and.3 atomic_and_64_nv.3 \ + atomic_and.3 atomic_and_nv.3 \ atomic_cas.3 atomic_cas_32.3 \ atomic_cas.3 atomic_cas_uint.3 \ atomic_cas.3 atomic_cas_ulong.3 \ @@ -36,6 +38,7 @@ MLINKS+=atomic_add.3 atomic_add_32.3 \ atomic_cas.3 atomic_cas_ulong_ni.3 \ atomic_cas.3 atomic_cas_ptr_ni.3 \ atomic_cas.3 atomic_cas_64_ni.3 \ + atomic_cas.3 atomic_cas_ni.3 \ atomic_dec.3 atomic_dec_32.3 \ atomic_dec.3 atomic_dec_uint.3 \ atomic_dec.3 atomic_dec_ulong.3 \ @@ -46,6 +49,7 @@ MLINKS+=atomic_add.3 atomic_add_32.3 \ atomic_dec.3 atomic_dec_ulong_nv.3 \ atomic_dec.3 atomic_dec_ptr_nv.3 \ atomic_dec.3 atomic_dec_64_nv.3 \ + atomic_dec.3 atomic_dec_nv.3 \ atomic_inc.3 atomic_inc_32.3 \ atomic_inc.3 atomic_inc_uint.3 \ atomic_inc.3 atomic_inc_ulong.3 \ @@ -56,6 +60,7 @@ MLINKS+=atomic_add.3 atomic_add_32.3 \ atomic_inc.3 atomic_inc_ulong_nv.3 \ atomic_inc.3 atomic_inc_ptr_nv.3 \ atomic_inc.3 atomic_inc_64_nv.3 \ + atomic_inc.3 atomic_inc_nv.3 \ atomic_or.3 atomic_or_32.3 \ atomic_or.3 atomic_or_uint.3 \ atomic_or.3 atomic_or_ulong.3 \ @@ -64,6 +69,7 @@ MLINKS+=atomic_add.3 atomic_add_32.3 \ atomic_or.3 atomic_or_uint_nv.3 \ atomic_or.3 atomic_or_ulong_nv.3 \ atomic_or.3 atomic_or_64_nv.3 \ + atomic_or.3 atomic_or_nv.3 \ atomic_swap.3 atomic_swap_32.3 \ atomic_swap.3 atomic_swap_uint.3 \ atomic_swap.3 atomic_swap_ulong.3 \
CVS commit: src/lib/libc/atomic
Module Name:src Committed By: dholland Date: Sun Feb 2 17:30:06 UTC 2014 Modified Files: src/lib/libc/atomic: atomic_cas.3 Log Message: Rework description for clarity; prompted by chat comments from bad@. To generate a diff of this commit: cvs rdiff -u -r1.2 -r1.3 src/lib/libc/atomic/atomic_cas.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files. Modified files: Index: src/lib/libc/atomic/atomic_cas.3 diff -u src/lib/libc/atomic/atomic_cas.3:1.2 src/lib/libc/atomic/atomic_cas.3:1.3 --- src/lib/libc/atomic/atomic_cas.3:1.2 Fri Feb 12 22:23:17 2010 +++ src/lib/libc/atomic/atomic_cas.3 Sun Feb 2 17:30:06 2014 @@ -1,4 +1,4 @@ -.\ $NetBSD: atomic_cas.3,v 1.2 2010/02/12 22:23:17 dyoung Exp $ +.\ $NetBSD: atomic_cas.3,v 1.3 2014/02/02 17:30:06 dholland Exp $ .\ .\ Copyright (c) 2007, 2010 The NetBSD Foundation, Inc. .\ All rights reserved. @@ -48,49 +48,53 @@ .Sh SYNOPSIS .In sys/atomic.h .Ft uint32_t -.Fn atomic_cas_32 volatile uint32_t *ptr uint32_t old uint32_t new +.Fn atomic_cas_32 volatile uint32_t *ptr uint32_t expected uint32_t new .Ft unsigned int -.Fn atomic_cas_uint volatile unsigned int *ptr unsigned int old \ +.Fn atomic_cas_uint volatile unsigned int *ptr unsigned int expected \ unsigned int new .Ft unsigned long -.Fn atomic_cas_ulong volatile unsigned long *ptr unsigned long old \ +.Fn atomic_cas_ulong volatile unsigned long *ptr unsigned long expected \ unsigned long new .Ft void * -.Fn atomic_cas_ptr volatile void *ptr void *old void *new +.Fn atomic_cas_ptr volatile void *ptr void *expected void *new .Ft uint64_t -.Fn atomic_cas_64 volatile uint64_t *ptr uint64_t old uint64_t new +.Fn atomic_cas_64 volatile uint64_t *ptr uint64_t expected uint64_t new .Ft uint32_t -.Fn atomic_cas_32_ni volatile uint32_t *ptr uint32_t old uint32_t new +.Fn atomic_cas_32_ni volatile uint32_t *ptr uint32_t expected \ +uint32_t new .Ft unsigned int -.Fn atomic_cas_uint_ni volatile unsigned int *ptr unsigned int old \ +.Fn atomic_cas_uint_ni volatile unsigned int *ptr unsigned int expected \ unsigned int new .Ft unsigned long -.Fn atomic_cas_ulong_ni volatile unsigned long *ptr unsigned long old \ -unsigned long new +.Fn atomic_cas_ulong_ni volatile unsigned long *ptr \ +unsigned long expected unsigned long new .Ft void * -.Fn atomic_cas_ptr_ni volatile void *ptr void *old void *new +.Fn atomic_cas_ptr_ni volatile void *ptr void *expected void *new .Ft uint64_t -.Fn atomic_cas_64_ni volatile uint64_t *ptr uint64_t old uint64_t new +.Fn atomic_cas_64_ni volatile uint64_t *ptr uint64_t expected \ +uint64_t new .Sh DESCRIPTION The .Nm atomic_cas -family of functions perform a compare-and-swap operation in an atomic fashion. -The value of the variable referenced by -.Fa ptr -is compared against -.Fa old . -If the values are equal, +family of functions perform an atomic conditional assignment. +The value .Fa new -is stored in the variable referenced by +is assigned to the variable referenced by .Fa ptr . -.Pp -The old value of the variable referenced by -.Fa ptr -is always returned regardless of whether or not the new value was stored. -Applications can test for success of the operation by comparing the -return value to the value passed as -.Fa old ; -if they are equal then the new value was stored. +The assignment succeeds +if and only if its current value matches the value +.Fa expected . +If the value is different, the assignment fails and no change is +made. +This operation is sometimes known as +.Dq compare-and-swap . +These functions always return the value found via +.Fa ptr . +Callers test for success by comparing the return value to the value +passed as +.Fa expected ; +if they are equal then the new value was stored; if they are not, the +value was not changed. .Pp The non-interlocked variants, .Fn *_ni ,
CVS commit: src/lib/libc/atomic
Module Name:src Committed By: dholland Date: Sun Feb 2 17:32:38 UTC 2014 Modified Files: src/lib/libc/atomic: atomic_cas.3 Log Message: Reorg second paragraph too, to group related info together. To generate a diff of this commit: cvs rdiff -u -r1.3 -r1.4 src/lib/libc/atomic/atomic_cas.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files. Modified files: Index: src/lib/libc/atomic/atomic_cas.3 diff -u src/lib/libc/atomic/atomic_cas.3:1.3 src/lib/libc/atomic/atomic_cas.3:1.4 --- src/lib/libc/atomic/atomic_cas.3:1.3 Sun Feb 2 17:30:06 2014 +++ src/lib/libc/atomic/atomic_cas.3 Sun Feb 2 17:32:38 2014 @@ -1,4 +1,4 @@ -.\ $NetBSD: atomic_cas.3,v 1.3 2014/02/02 17:30:06 dholland Exp $ +.\ $NetBSD: atomic_cas.3,v 1.4 2014/02/02 17:32:38 dholland Exp $ .\ .\ Copyright (c) 2007, 2010 The NetBSD Foundation, Inc. .\ All rights reserved. @@ -100,15 +100,11 @@ The non-interlocked variants, .Fn *_ni , guarantee atomicity within the same CPU with respect to interrupts and preemption. -For example, they are suitable for synchronizing compare-and-swap -operations on a variable shared by a thread and an interrupt -that are bound to the same CPU. -The -.Fn *_ni -variants are not atomic with respect to different CPUs. -.Fn *_ni -variants should avoid the interprocessor synchronization overhead -of the standard compare-and-swap operations. +They are not atomic with respect to different CPUs. +These can be used to avoid interprocessor synchronization overhead +in some cases; for example, they are suitable for synchronized +operations on a variable shared by a thread and an interrupt that are +bound to the same CPU. .Pp The 64-bit variants of these functions are available only on platforms that can support atomic 64-bit memory access.
CVS commit: src/lib/libc/atomic
Module Name:src Committed By: dholland Date: Sun Feb 2 18:06:33 UTC 2014 Modified Files: src/lib/libc/atomic: atomic_cas.3 Log Message: bump date for previous To generate a diff of this commit: cvs rdiff -u -r1.4 -r1.5 src/lib/libc/atomic/atomic_cas.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files. Modified files: Index: src/lib/libc/atomic/atomic_cas.3 diff -u src/lib/libc/atomic/atomic_cas.3:1.4 src/lib/libc/atomic/atomic_cas.3:1.5 --- src/lib/libc/atomic/atomic_cas.3:1.4 Sun Feb 2 17:32:38 2014 +++ src/lib/libc/atomic/atomic_cas.3 Sun Feb 2 18:06:33 2014 @@ -1,4 +1,4 @@ -.\ $NetBSD: atomic_cas.3,v 1.4 2014/02/02 17:32:38 dholland Exp $ +.\ $NetBSD: atomic_cas.3,v 1.5 2014/02/02 18:06:33 dholland Exp $ .\ .\ Copyright (c) 2007, 2010 The NetBSD Foundation, Inc. .\ All rights reserved. @@ -27,7 +27,7 @@ .\ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\ POSSIBILITY OF SUCH DAMAGE. .\ -.Dd February 11, 2010 +.Dd February 2, 2014 .Dt ATOMIC_CAS 3 .Os .Sh NAME
CVS commit: src/lib/libc/atomic
Module Name:src Committed By: wiz Date: Thu Apr 28 11:56:26 UTC 2011 Modified Files: src/lib/libc/atomic: membar_ops.3 Log Message: Fix a typo. To generate a diff of this commit: cvs rdiff -u -r1.2 -r1.3 src/lib/libc/atomic/membar_ops.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files. Modified files: Index: src/lib/libc/atomic/membar_ops.3 diff -u src/lib/libc/atomic/membar_ops.3:1.2 src/lib/libc/atomic/membar_ops.3:1.3 --- src/lib/libc/atomic/membar_ops.3:1.2 Mon May 18 12:39:17 2009 +++ src/lib/libc/atomic/membar_ops.3 Thu Apr 28 11:56:26 2011 @@ -1,4 +1,4 @@ -.\ $NetBSD: membar_ops.3,v 1.2 2009/05/18 12:39:17 wiz Exp $ +.\ $NetBSD: membar_ops.3,v 1.3 2011/04/28 11:56:26 wiz Exp $ .\ .\ Copyright (c) 2007, 2008 The NetBSD Foundation, Inc. .\ All rights reserved. @@ -62,7 +62,7 @@ .Pp .Bl -tag -width mem .It Fn membar_enter -Any store preceeding +Any store preceding .Fn membar_enter will reach global visibility before all loads and stores following it. .Pp
CVS commit: src/lib/libc/atomic
Module Name:src Committed By: jruoho Date: Wed Apr 14 08:49:49 UTC 2010 Modified Files: src/lib/libc/atomic: atomic_ops.3 Log Message: Bump date for previous. (How hard can it be to remember this.) To generate a diff of this commit: cvs rdiff -u -r1.4 -r1.5 src/lib/libc/atomic/atomic_ops.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files. Modified files: Index: src/lib/libc/atomic/atomic_ops.3 diff -u src/lib/libc/atomic/atomic_ops.3:1.4 src/lib/libc/atomic/atomic_ops.3:1.5 --- src/lib/libc/atomic/atomic_ops.3:1.4 Wed Apr 14 08:47:19 2010 +++ src/lib/libc/atomic/atomic_ops.3 Wed Apr 14 08:49:49 2010 @@ -1,4 +1,4 @@ -.\ $NetBSD: atomic_ops.3,v 1.4 2010/04/14 08:47:19 jruoho Exp $ +.\ $NetBSD: atomic_ops.3,v 1.5 2010/04/14 08:49:49 jruoho Exp $ .\ .\ Copyright (c) 2007, 2008 The NetBSD Foundation, Inc. .\ All rights reserved. @@ -27,7 +27,7 @@ .\ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\ POSSIBILITY OF SUCH DAMAGE. .\ -.Dd February 11, 2007 +.Dd April 14, 2010 .Dt ATOMIC_OPS 3 .Os .Sh NAME
CVS commit: src/lib/libc/atomic
Module Name:src Committed By: dyoung Date: Fri Feb 12 22:23:17 UTC 2010 Modified Files: src/lib/libc/atomic: atomic_cas.3 Log Message: With help from rmind@, describe the non-interlocked (*_ni) variants of the standard atomic compare-and-swap operations. Tell some caveats. Manual page links, *_ni.3 - atomic_cas.3 are coming up after a successful 'build.sh distribution'. To generate a diff of this commit: cvs rdiff -u -r1.1 -r1.2 src/lib/libc/atomic/atomic_cas.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files. Modified files: Index: src/lib/libc/atomic/atomic_cas.3 diff -u src/lib/libc/atomic/atomic_cas.3:1.1 src/lib/libc/atomic/atomic_cas.3:1.2 --- src/lib/libc/atomic/atomic_cas.3:1.1 Mon Jun 23 10:22:40 2008 +++ src/lib/libc/atomic/atomic_cas.3 Fri Feb 12 22:23:17 2010 @@ -1,6 +1,6 @@ -.\ $NetBSD: atomic_cas.3,v 1.1 2008/06/23 10:22:40 ad Exp $ +.\ $NetBSD: atomic_cas.3,v 1.2 2010/02/12 22:23:17 dyoung Exp $ .\ -.\ Copyright (c) 2007 The NetBSD Foundation, Inc. +.\ Copyright (c) 2007, 2010 The NetBSD Foundation, Inc. .\ All rights reserved. .\ .\ This code is derived from software contributed to The NetBSD Foundation @@ -27,7 +27,7 @@ .\ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\ POSSIBILITY OF SUCH DAMAGE. .\ -.Dd April 11, 2007 +.Dd February 11, 2010 .Dt ATOMIC_CAS 3 .Os .Sh NAME @@ -36,7 +36,12 @@ .Nm atomic_cas_uint , .Nm atomic_cas_ulong , .Nm atomic_cas_ptr , -.Nm atomic_cas_64 +.Nm atomic_cas_64 , +.Nm atomic_cas_32_ni , +.Nm atomic_cas_uint_ni , +.Nm atomic_cas_ulong_ni , +.Nm atomic_cas_ptr_ni , +.Nm atomic_cas_64_ni .Nd atomic compare-and-swap operations .\ .Sh LIBRARY .\ .Lb libc @@ -54,6 +59,18 @@ .Fn atomic_cas_ptr volatile void *ptr void *old void *new .Ft uint64_t .Fn atomic_cas_64 volatile uint64_t *ptr uint64_t old uint64_t new +.Ft uint32_t +.Fn atomic_cas_32_ni volatile uint32_t *ptr uint32_t old uint32_t new +.Ft unsigned int +.Fn atomic_cas_uint_ni volatile unsigned int *ptr unsigned int old \ +unsigned int new +.Ft unsigned long +.Fn atomic_cas_ulong_ni volatile unsigned long *ptr unsigned long old \ +unsigned long new +.Ft void * +.Fn atomic_cas_ptr_ni volatile void *ptr void *old void *new +.Ft uint64_t +.Fn atomic_cas_64_ni volatile uint64_t *ptr uint64_t old uint64_t new .Sh DESCRIPTION The .Nm atomic_cas @@ -75,6 +92,20 @@ .Fa old ; if they are equal then the new value was stored. .Pp +The non-interlocked variants, +.Fn *_ni , +guarantee atomicity within the same CPU with respect to +interrupts and preemption. +For example, they are suitable for synchronizing compare-and-swap +operations on a variable shared by a thread and an interrupt +that are bound to the same CPU. +The +.Fn *_ni +variants are not atomic with respect to different CPUs. +.Fn *_ni +variants should avoid the interprocessor synchronization overhead +of the standard compare-and-swap operations. +.Pp The 64-bit variants of these functions are available only on platforms that can support atomic 64-bit memory access. Applications can check for the availability of 64-bit atomic memory @@ -88,3 +119,11 @@ .Nm atomic_cas functions first appeared in .Nx 5.0 . +.Sh NOTES +On some architectures, a +.Fn *_ni +variant is merely an alias for the corresponding standard +compare-and-swap operation. +While the non-interlocked variant behaves correctly on those +architectures, it does not avoid the interprocessor synchronization +overhead.
CVS commit: src/lib/libc/atomic
Module Name:src Committed By: wiz Date: Mon May 18 12:37:28 UTC 2009 Modified Files: src/lib/libc/atomic: atomic_ops.3 Log Message: Fix typo in Dd argument. To generate a diff of this commit: cvs rdiff -u -r1.1 -r1.2 src/lib/libc/atomic/atomic_ops.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files. Modified files: Index: src/lib/libc/atomic/atomic_ops.3 diff -u src/lib/libc/atomic/atomic_ops.3:1.1 src/lib/libc/atomic/atomic_ops.3:1.2 --- src/lib/libc/atomic/atomic_ops.3:1.1 Mon Jun 23 10:22:40 2008 +++ src/lib/libc/atomic/atomic_ops.3 Mon May 18 12:37:28 2009 @@ -1,4 +1,4 @@ -.\ $NetBSD: atomic_ops.3,v 1.1 2008/06/23 10:22:40 ad Exp $ +.\ $NetBSD: atomic_ops.3,v 1.2 2009/05/18 12:37:28 wiz Exp $ .\ .\ Copyright (c) 2007, 2008 The NetBSD Foundation, Inc. .\ All rights reserved. @@ -27,7 +27,7 @@ .\ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\ POSSIBILITY OF SUCH DAMAGE. .\ -.Dd Febuary 11, 2007 +.Dd February 11, 2007 .Dt ATOMIC_OPS 3 .Os .Sh NAME
CVS commit: src/lib/libc/atomic
Module Name:src Committed By: wiz Date: Mon May 18 12:40:22 UTC 2009 Modified Files: src/lib/libc/atomic: atomic_ops.3 Log Message: Punctuation nit. Remove superfluous .Pp. To generate a diff of this commit: cvs rdiff -u -r1.2 -r1.3 src/lib/libc/atomic/atomic_ops.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files. Modified files: Index: src/lib/libc/atomic/atomic_ops.3 diff -u src/lib/libc/atomic/atomic_ops.3:1.2 src/lib/libc/atomic/atomic_ops.3:1.3 --- src/lib/libc/atomic/atomic_ops.3:1.2 Mon May 18 12:37:28 2009 +++ src/lib/libc/atomic/atomic_ops.3 Mon May 18 12:40:21 2009 @@ -1,4 +1,4 @@ -.\ $NetBSD: atomic_ops.3,v 1.2 2009/05/18 12:37:28 wiz Exp $ +.\ $NetBSD: atomic_ops.3,v 1.3 2009/05/18 12:40:21 wiz Exp $ .\ .\ Copyright (c) 2007, 2008 The NetBSD Foundation, Inc. .\ All rights reserved. @@ -41,8 +41,7 @@ The .Nm atomic_ops family of functions provide atomic memory operations. -There are 7 classes of atomic memory operations available -: +There are 7 classes of atomic memory operations available: .Pp .Bl -tag -width atomic_swap(3) .It Xr atomic_add 3 @@ -65,7 +64,6 @@ .Pp .Bl -tag -width aa .It Synchronization mechanisms -.Pp Where the architecture does not provide hardware support for atomic compare and swap (CAS), atomicity is provided by a restartable sequence or by a spinlock. @@ -74,7 +72,6 @@ The following architectures can be assumed to provide CAS in hardware: alpha, amd64, i386, powerpc, powerpc64, sparc64. .It Scope and restrictions -.Pp If hardware CAS is available, the atomic operations are globally atomic: operations within a memory region shared between processes are guaranteed to be performed atomically. @@ -97,7 +94,6 @@ Intermixing of atomic operations with other synchronization mechanisms for the same memory location results in undefined behavior. .It Visibility and ordering of memory accesses -.Pp If hardware CAS is available, stores to the target memory location by an atomic operation will reach global visibility before the operation completes. @@ -115,7 +111,6 @@ See .Xr membar_ops 3 . .It Performance -.Pp Because atomic memory operations require expensive synchronization at the hardware level, applications should take care to minimize their use. In certain cases, it may be more appropriate to use a mutex, especially
