1 files changed, 235 insertions, 0 deletions
diff --git a/static/netbsd/man9/__cpu_simple_lock.9 b/static/netbsd/man9/__cpu_simple_lock.9
new file mode 100644
index 00000000..a847517c
--- /dev/null
+++ b/static/netbsd/man9/__cpu_simple_lock.9
@@ -0,0 +1,235 @@
+.\"	$NetBSD: __cpu_simple_lock.9,v 1.2 2024/10/26 03:05:06 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 October 25, 2024
+.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"
+.\"
+.Vt #define __SIMPLELOCK_UNLOCKED   ...
+.\"
+.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 INITIALIZATION
+The macro
+.Dv __SIMPLELOCK_UNLOCKED
+expands to an initializer for the type
+.Vt __cpu_simple_lock_t :
+.Dl "__cpu_simple_lock_t lock = __SIMPLELOCK_UNLOCKED;"
+.Pp
+A
+.Vt __cpu_simple_lock_t
+object can also be initialized with
+.Fn __cpu_simple_lock_init .
+.Pp
+No actions are needed to destroy a
+.Vt __cpu_simple_lock_t
+object.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.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.