Module Name: src
Committed By: riastradh
Date: Sat Feb 12 17:10:20 UTC 2022
Modified Files:
src/distrib/sets/lists/comp: mi
src/share/man/man9: Makefile
Added Files:
src/share/man/man9: __cpu_simple_lock.9
Log Message:
__cpu_simple_lock(9): New man page.
This doesn't mean you should use it! Mostly it's to document the
semantics to help understand existing uses, which should not
proliferate, and audit definitions.
To generate a diff of this commit:
cvs rdiff -u -r1.2410 -r1.2411 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.462 -r1.463 src/share/man/man9/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man9/__cpu_simple_lock.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.2410 src/distrib/sets/lists/comp/mi:1.2411
--- src/distrib/sets/lists/comp/mi:1.2410 Sat Jan 22 08:58:48 2022
+++ src/distrib/sets/lists/comp/mi Sat Feb 12 17:10:20 2022
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2410 2022/01/22 08:58:48 skrll Exp $
+# $NetBSD: mi,v 1.2411 2022/02/12 17:10:20 riastradh Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -11292,6 +11292,14 @@
./usr/share/man/cat9/VOP_WHITEOUT.0 comp-sys-catman .cat
./usr/share/man/cat9/VOP_WRITE.0 comp-sys-catman .cat
./usr/share/man/cat9/VREF.0 comp-obsolete obsolete
+./usr/share/man/cat9/__SIMPLELOCK_LOCKED_P.0 comp-sys-catman .cat
+./usr/share/man/cat9/__SIMPLELOCK_UNLOCKED_P.0 comp-sys-catman .cat
+./usr/share/man/cat9/__cpu_simple_lock_clear.0 comp-sys-catman .cat
+./usr/share/man/cat9/__cpu_simple_lock_init.0 comp-sys-catman .cat
+./usr/share/man/cat9/__cpu_simple_lock_set.0 comp-sys-catman .cat
+./usr/share/man/cat9/__cpu_simple_lock_try.0 comp-sys-catman .cat
+./usr/share/man/cat9/__cpu_simple_lock.0 comp-sys-catman .cat
+./usr/share/man/cat9/__cpu_simple_unlock.0 comp-sys-catman .cat
./usr/share/man/cat9/acl.0 comp-sys-catman .cat
./usr/share/man/cat9/accept_filt_add.0 comp-sys-catman .cat
./usr/share/man/cat9/accept_filt_del.0 comp-sys-catman .cat
@@ -19522,6 +19530,14 @@
./usr/share/man/html9/VOP_WHITEOUT.html comp-sys-htmlman html
./usr/share/man/html9/VOP_WRITE.html comp-sys-htmlman html
./usr/share/man/html9/VREF.html comp-obsolete obsolete
+./usr/share/man/html9/__SIMPLELOCK_LOCKED_P.html comp-sys-htmlman html
+./usr/share/man/html9/__SIMPLELOCK_UNLOCKED_P.html comp-sys-htmlman html
+./usr/share/man/html9/__cpu_simple_lock_clear.html comp-sys-htmlman html
+./usr/share/man/html9/__cpu_simple_lock_init.html comp-sys-htmlman html
+./usr/share/man/html9/__cpu_simple_lock_set.html comp-sys-htmlman html
+./usr/share/man/html9/__cpu_simple_lock_try.html comp-sys-htmlman html
+./usr/share/man/html9/__cpu_simple_lock.html comp-sys-htmlman html
+./usr/share/man/html9/__cpu_simple_unlock.html comp-sys-htmlman html
./usr/share/man/html9/acl.html comp-sys-htmlman html
./usr/share/man/html9/accept_filt_add.html comp-sys-htmlman html
./usr/share/man/html9/accept_filt_del.html comp-sys-htmlman html
@@ -27855,6 +27871,14 @@
./usr/share/man/man9/VOP_WHITEOUT.9 comp-sys-man .man
./usr/share/man/man9/VOP_WRITE.9 comp-sys-man .man
./usr/share/man/man9/VREF.9 comp-obsolete obsolete
+./usr/share/man/man9/__SIMPLELOCK_LOCKED_P.9 comp-sys-man .man
+./usr/share/man/man9/__SIMPLELOCK_UNLOCKED_P.9 comp-sys-man .man
+./usr/share/man/man9/__cpu_simple_lock_clear.9 comp-sys-man .man
+./usr/share/man/man9/__cpu_simple_lock_init.9 comp-sys-man .man
+./usr/share/man/man9/__cpu_simple_lock_set.9 comp-sys-man .man
+./usr/share/man/man9/__cpu_simple_lock_try.9 comp-sys-man .man
+./usr/share/man/man9/__cpu_simple_lock.9 comp-sys-man .man
+./usr/share/man/man9/__cpu_simple_unlock.9 comp-sys-man .man
./usr/share/man/man9/acl.9 comp-sys-man .man
./usr/share/man/man9/accept_filt_add.9 comp-sys-man .man
./usr/share/man/man9/accept_filt_del.9 comp-sys-man .man
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.462 src/share/man/man9/Makefile:1.463
--- src/share/man/man9/Makefile:1.462 Mon Jan 17 22:47:43 2022
+++ src/share/man/man9/Makefile Sat Feb 12 17:10:20 2022
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.462 2022/01/17 22:47:43 christos Exp $
+# $NetBSD: Makefile,v 1.463 2022/02/12 17:10:20 riastradh Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -71,6 +71,15 @@ MAN= accept_filter.9 accf_data.9 accf_ht
xcall.9 \
VOP_ACLCHECK.9 VOP_GETACL.9 VOP_SETACL.9
+MAN+= __cpu_simple_lock.9
+MLINKS+=__cpu_simple_lock.9 __SIMPLELOCK_LOCKED_P.9 \
+ __cpu_simple_lock.9 __SIMPLELOCK_UNLOCKED_P.9 \
+ __cpu_simple_lock.9 __cpu_simple_lock_clear.9 \
+ __cpu_simple_lock.9 __cpu_simple_lock_init.9 \
+ __cpu_simple_lock.9 __cpu_simple_lock_set.9 \
+ __cpu_simple_lock.9 __cpu_simple_lock_try.9 \
+ __cpu_simple_lock.9 __cpu_simple_unlock.9
+
MAN+= atomic_loadstore.9
MLINKS+=atomic_loadstore.9 atomic_load_acquire.9 \
atomic_loadstore.9 atomic_load_consume.9 \
Added files:
Index: src/share/man/man9/__cpu_simple_lock.9
diff -u /dev/null src/share/man/man9/__cpu_simple_lock.9:1.1
--- /dev/null Sat Feb 12 17:10:20 2022
+++ src/share/man/man9/__cpu_simple_lock.9 Sat Feb 12 17:10:20 2022
@@ -0,0 +1,217 @@
+.\" $NetBSD: __cpu_simple_lock.9,v 1.1 2022/02/12 17:10:20 riastradh Exp $
+.\"
+.\" Copyright (c) 2022 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd February 12, 2022
+.Dt __CPU_SIMPLE_LOCK 9
+.Os
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh NAME
+.Nm __cpu_simple_lock
+.Nd simple spin locks
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SYNOPSIS
+.In sys/lock.h
+.\"
+.Ft void
+.Fn __cpu_simple_lock_init "__cpu_simple_lock_t *lock"
+.\"
+.Ft void
+.Fn __cpu_simple_lock "__cpu_simple_lock_t *lock"
+.Ft int
+.Fn __cpu_simple_lock_try "__cpu_simple_lock *lock"
+.Ft void
+.Fn __cpu_simple_unlock "__cpu_simple_lock_t *lock"
+.\"
+.Ft int
+.Fn __SIMPLELOCK_LOCKED_P "__cpu_simple_lock *lock"
+.\"
+.Fd "/* obsolete and for ABI compat only -- do not use */"
+.Ft void
+.Fn __cpu_simple_lock_set "__cpu_simple_Lock *lock"
+.Ft void
+.Fn __cpu_simple_lock_clear "__cpu_simple_lock *lock"
+.Ft int
+.Fn __SIMPLELOCK_UNLOCKED_P "__cpu_simple_lock *lock"
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh DESCRIPTION
+The
+.Nm
+functions provide a simple spin-lock facility for limited purposes that
+cannot be served by
+.Xr mutex 9 ,
+such as inside the implementation of
+.Xr mutex 9
+itself on platforms with limited atomic read/modify/write operations.
+.Pp
+.Nm
+is very limited:
+.Bl -bullet
+.It
+.Nm
+provides no debugging or diagnostic support through the
+.Dv LOCKDEBUG
+option.
+.It
+.Nm
+does not synchronize between code on a CPU and interrupt handlers
+running on that CPU \(em you must use it with
+.Xr spl 9
+for any locks that may be taken in interrupt context; failing to do so
+will likely lead to hard-to-debug deadlock.
+.It
+.Nm
+does not block preemption, so a thread holding a lock may be preempted,
+potentially requiring other callers to spin for long durations until
+the scheduler runs the holder again.
+.It
+.Nm
+does no exponential backoff to reduce memory traffic during
+contention.
+.El
+.Pp
+Unless you know what you are doing, you should use
+.Xr mutex 9
+instead.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh FUNCTIONS
+.Bl -tag -width abcd
+.It Fn __cpu_simple_lock_init lock
+Initialize
+.Fa lock
+for use with the other
+.Nm
+functions.
+.Pp
+The caller is responsible for ensuring
+.Fn __cpu_simple_lock_init
+happens before any use of the other functions.
+.Fn __cpu_simple_lock_init
+implies no particular memory ordering on its own.
+.\""""""""""""""""
+.It Fn __cpu_simple_lock lock
+Acquire
+.Fa lock ,
+waiting until it is released if currently held.
+.Pp
+Any memory operations preceding the previous
+.Fn __cpu_simple_unlock
+call that released the lock happen before any memory operations after
+the next
+.Fn __cpu_simple_lock
+call that acquires it.
+.\""""""""""""""""
+.It Fn __cpu_simple_lock_try lock
+Try to acquire
+.Fa lock ,
+without waiting if it is currently held.
+Return 1 if successful, 0 if not.
+.Pp
+Any memory operations preceding the previous
+.Fn __cpu_simple_unlock
+call that released the lock happen before any memory operations after
+the next
+.Em successful
+.Fn __cpu_simple_lock_try
+call that acquires it.
+.\""""""""""""""""
+.It Fn __cpu_simple_unlock lock
+Release
+.Fa lock .
+.Pp
+Any memory operations preceding
+.Fn __cpu_simple_unlock
+happen before the next call to
+.Fn __cpu_simple_lock ,
+or the next successful call to
+.Fn __cpu_simple_lock_try ,
+that acquires
+.Fa lock .
+.\""""""""""""""""
+.It Fn __SIMPLELOCK_LOCKED_P lock
+True if
+.Fa lock
+is currently locked, by anyone.
+.Pp
+This is normally only used for diagnostic assertions, or for loops
+around
+.Fn __cpu_simple_lock_try
+that also have higher-level functions like blocking interrupts and
+performing exponential backoff.
+.Pp
+No memory ordering is implied.
+.El
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh OBSOLETE FUNCTIONS
+The following functions abuse the
+.Vt __cpu_simple_lock_t
+type to store a boolean.
+They are used inside the
+.Xr pthread 3
+library, and were included in the library ABI, so they can't be removed
+without breaking the
+.Xr pthread 3
+ABI.
+Do not use these in new code
+.Po
+except
+.Fn __SIMPLELOCK_LOCKED_P
+.Pc .
+.Bl -tag -width ".Fn __SIMPLELOCK_UNLOCKED_P lock"
+.It Fn __cpu_simple_lock_set lock
+Set
+.Fa lock
+to true.
+.It Fn __cpu_simple_lock_clear lock
+Set
+.Fa lock
+to false.
+.It Fn __SIMPLELOCK_LOCKED_P lock
+True iff
+.Fa lock
+is true.
+.It Fn __SIMPLELOCK_UNLOCKED_P lock
+True iff
+.Fa lock
+is false.
+.El
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh CODE REFERENCES
+The
+.Nm
+functions are implemented in
+.Pa sys/arch/$ARCH/include/lock.h .
+.Pp
+A machine-independent implementation, using compiler support for
+atomic and memory barrier builtins, is available in
+.Pa sys/sys/common_lock.h .
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SEE ALSO
+.Xr locking 9 ,
+.Xr mutex 9
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh HISTORY
+.Nm
+appeared a long time ago.
