[src/trunk]: src/lib/libc/atomic With help from rmind@, describe the non-inte...

[dyoung <dyoung%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/6af132bd22eb
branches:  trunk
changeset: 752070:6af132bd22eb
user:      dyoung <dyoung%NetBSD.org@localhost>
date:      Fri Feb 12 22:23:17 2010 +0000

description:
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:

 lib/libc/atomic/atomic_cas.3 |  47 ++++++++++++++++++++++++++++++++++++++++---
 1 files changed, 43 insertions(+), 4 deletions(-)

diffs (87 lines):

diff -r 5d9f8c11834a -r 6af132bd22eb lib/libc/atomic/atomic_cas.3
--- a/lib/libc/atomic/atomic_cas.3      Fri Feb 12 22:19:23 2010 +0000
+++ b/lib/libc/atomic/atomic_cas.3      Fri Feb 12 22:23:17 2010 +0000
@@ -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.