summaryrefslogtreecommitdiff
path: root/lib
diff options
context:
space:
mode:
authordyoung <dyoung@NetBSD.org>2010-02-12 22:23:17 +0000
committerdyoung <dyoung@NetBSD.org>2010-02-12 22:23:17 +0000
commitba71f034aa66234758ceda396ecfcbfdc3a0d73a (patch)
treed19cea4ad375b159673389af88f83448ef8440e6 /lib
parentf88f81fcda91a459ae317a79c0b1bf39c1304cf5 (diff)
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'.
Diffstat (limited to 'lib')
-rw-r--r--lib/libc/atomic/atomic_cas.347
1 files changed, 43 insertions, 4 deletions
diff --git a/lib/libc/atomic/atomic_cas.3 b/lib/libc/atomic/atomic_cas.3
index 1d207a752d3..06804b7fc66 100644
--- a/lib/libc/atomic/atomic_cas.3
+++ b/lib/libc/atomic/atomic_cas.3
@@ -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 @@ return value to the value passed as
.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 @@ The
.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.