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.