feat: Added NetBSD man pages

1 files changed, 319 insertions, 0 deletions

diff --git a/static/netbsd/man9/mutex.9 b/static/netbsd/man9/mutex.9
new file mode 100644
index 00000000..63c0cfde
--- /dev/null
+++ b/static/netbsd/man9/mutex.9
@@ -0,0 +1,319 @@
+.\"	$NetBSD: mutex.9,v 1.35 2023/02/01 03:27:45 gutteridge Exp $
+.\"
+.\" Copyright (c) 2007, 2009 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Andrew Doran.
+.\"
+.\" 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 December 8, 2017
+.Dt MUTEX 9
+.Os
+.Sh NAME
+.Nm mutex ,
+.Nm mutex_init ,
+.Nm mutex_destroy ,
+.Nm mutex_enter ,
+.Nm mutex_exit ,
+.Nm mutex_ownable ,
+.Nm mutex_owned ,
+.Nm mutex_spin_enter ,
+.Nm mutex_spin_exit ,
+.Nm mutex_tryenter
+.Nd mutual exclusion primitives
+.Sh SYNOPSIS
+.In sys/mutex.h
+.Ft void
+.Fn mutex_init "kmutex_t *mtx" "kmutex_type_t type" "int ipl"
+.Ft void
+.Fn mutex_destroy "kmutex_t *mtx"
+.Ft void
+.Fn mutex_enter "kmutex_t *mtx"
+.Ft void
+.Fn mutex_exit "kmutex_t *mtx"
+.Ft int
+.Fn mutex_ownable "kmutex_t *mtx"
+.Ft int
+.Fn mutex_owned "kmutex_t *mtx"
+.Ft void
+.Fn mutex_spin_enter "kmutex_t *mtx"
+.Ft void
+.Fn mutex_spin_exit "kmutex_t *mtx"
+.Ft int
+.Fn mutex_tryenter "kmutex_t *mtx"
+.Pp
+.Cd "options DIAGNOSTIC"
+.Cd "options LOCKDEBUG"
+.Sh DESCRIPTION
+Mutexes are used in the kernel to implement mutual exclusion among LWPs
+.Pq lightweight processes
+and interrupt handlers.
+.Pp
+The
+.Vt kmutex_t
+type provides storage for the mutex object.
+This should be treated as an opaque object and not examined directly by
+consumers.
+.Pp
+Mutexes replace the
+.Xr spl 9
+system traditionally used to provide synchronization between interrupt
+handlers and LWPs.
+.Sh OPTIONS
+The following kernel options have effect on mutex operations:
+.Bl -tag -width Cd
+.It Cd "options DIAGNOSTIC"
+Kernels compiled with the
+.Dv DIAGNOSTIC
+option perform basic sanity checks on mutex operations.
+.It Cd "options LOCKDEBUG"
+Kernels compiled with the
+.Dv LOCKDEBUG
+option perform potentially CPU intensive sanity checks
+on mutex operations.
+.El
+.Sh FUNCTIONS
+.Bl -tag -width Ds
+.It Fn mutex_init "mtx" "type" "ipl"
+Dynamically initialize a mutex for use.
+.Pp
+No other operations can be performed on a mutex until it has been initialized.
+Once initialized, all types of mutex are manipulated using the same interface.
+Note that
+.Fn mutex_init
+may block in order to allocate memory.
+.Pp
+The
+.Fa type
+argument must be given as
+.Dv MUTEX_DEFAULT .
+Other constants are defined but are for low-level system use and are not
+an endorsed, stable part of the interface.
+.Pp
+The type of mutex returned depends on the
+.Fa ipl
+argument:
+.Bl -tag -width Dv
+.It Dv IPL_NONE , No or one of the Dv IPL_SOFT* No constants
+An adaptive mutex will be returned.
+Adaptive mutexes provide mutual exclusion between LWPs,
+and between LWPs and soft interrupt handlers.
+.Pp
+Adaptive mutexes cannot be acquired from a hardware interrupt handler.
+An LWP may either sleep or busy-wait when attempting to acquire
+an adaptive mutex that is already held.
+.It Dv IPL_VM , IPL_SCHED , IPL_HIGH
+A spin mutex will be returned.
+Spin mutexes provide mutual exclusion between LWPs, and between LWPs
+and interrupt handlers.
+.Pp
+The
+.Fa ipl
+argument is used to pass a system interrupt priority level (IPL)
+that will block all interrupt handlers that may try to acquire the mutex.
+.Pp
+LWPs that own spin mutexes may not sleep, and therefore must not
+try to acquire adaptive mutexes or other sleep locks.
+.Pp
+A processor will always busy-wait when attempting to acquire
+a spin mutex that is already held.
+.Pp
+.Sy Note :
+Releasing a spin mutex may not lower the IPL to what it was when
+entered.
+If other spin mutexes are held, the IPL will not be lowered until the
+last one is released.
+.Pp
+This is usually not a problem because spin mutexes should held only for
+very short durations anyway, so blocking higher-priority interrupts a
+little longer doesn't hurt much.
+But it interferes with writing assertions that the IPL is
+.Em no higher than
+a specified level.
+.El
+.Pp
+See
+.Xr spl 9
+for further information on interrupt priority levels (IPLs).
+.It Fn mutex_destroy "mtx"
+Release resources used by a mutex.
+The mutex may not be used after it has been destroyed.
+.Fn mutex_destroy
+may block in order to free memory.
+.It Fn mutex_enter "mtx"
+Acquire a mutex.
+If the mutex is already held, the caller will block and not return until the
+mutex is acquired.
+.Pp
+All loads and stores after
+.Fn mutex_enter
+will not be reordered before it or served from a prior cache, and hence
+will
+.Em happen after
+any prior
+.Fn mutex_exit
+to release the mutex even on another CPU or in an interrupt.
+Thus, there is a global total ordering on all loads and stores under
+the same mutex.
+.Pp
+Mutexes and other types of locks must always be acquired in a
+consistent order with respect to each other.
+Otherwise, the potential for system deadlock exists.
+.Pp
+Adaptive mutexes and other types of lock that can sleep may
+not be acquired while a spin mutex is held by the caller.
+.Pp
+When acquiring a spin mutex, the IPL of the current CPU will be raised to
+the level set in
+.Fn mutex_init
+if it is not already equal or higher.
+.It Fn mutex_exit "mtx"
+Release a mutex.
+The mutex must have been previously acquired by the caller.
+Mutexes may be released out of order as needed.
+.Pp
+All loads and stores before
+.Fn mutex_exit
+will not be reordered after it or delayed in a write buffer, and hence
+will
+.Em happen before
+any subsequent
+.Fn mutex_enter
+to acquire the mutex even on another CPU or in an interrupt.
+Thus, there is a global total ordering on all loads and stores under
+the same mutex.
+.It Fn mutex_ownable "mtx"
+When compiled with
+.Dv LOCKDEBUG
+ensure that the current process can successfully acquire
+.Ar mtx .
+If
+.Ar mtx
+is already owned by the current process, the system will panic
+with a
+.Dq locking against myself\^
+error.
+.Pp
+This function is needed because
+.Fn mutex_owned
+does not differentiate if a spin mutex is owned by the current process
+vs owned by another process.
+.Fn mutex_ownable
+is reasonably heavy-weight, and should only be used with
+.Xr KDASSERT 9 .
+.It Fn mutex_owned "mtx"
+For adaptive mutexes, return non-zero if the current LWP holds the mutex.
+For spin mutexes, return non-zero if the mutex is held, potentially by the
+current processor.
+Otherwise, return zero.
+.Pp
+.Fn mutex_owned
+is provided for making diagnostic checks to verify that a lock is held.
+For example:
+.Dl KASSERT(mutex_owned(&driver_lock));
+.Pp
+It should not be used to make locking decisions at run time.
+For spin mutexes, it must not be used to verify that a lock is not held.
+.It Fn mutex_spin_enter "mtx"
+Equivalent to
+.Fn mutex_enter ,
+but may only be used when it is known that
+.Ar mtx
+is a spin mutex.
+Implies the same memory ordering as
+.Fn mutex_enter .
+On some architectures, this can substantially reduce the cost of acquiring
+a spin mutex.
+.It Fn mutex_spin_exit "mtx"
+Equivalent to
+.Fn mutex_exit ,
+but may only be used when it is known that
+.Ar mtx
+is a spin mutex.
+Implies the same memory ordering as
+.Fn mutex_exit .
+On some architectures, this can substantially reduce the cost of releasing
+a spin mutex.
+.It Fn mutex_tryenter "mtx"
+Try to acquire a mutex, but do not block if the mutex is already held.
+Returns non-zero if the mutex was acquired, or zero if the mutex was
+already held.
+.Pp
+.Fn mutex_tryenter
+can be used as an optimization when acquiring locks in the wrong order.
+For example, in a setting where the convention is that
+.Va first_lock
+must be acquired before
+.Va second_lock ,
+the following can be used to optimistically lock in reverse order:
+.Bd -literal -offset indent
+/* We hold second_lock, but not first_lock. */
+KASSERT(mutex_owned(&second_lock));
+
+if (!mutex_tryenter(&first_lock)) {
+        /* Failed to get it - lock in the correct order. */
+        mutex_exit(&second_lock);
+        mutex_enter(&first_lock);
+        mutex_enter(&second_lock);
+
+        /*
+         * We may need to recheck any conditions the code
+         * path depends on, as we released second_lock
+         * briefly.
+         */
+}
+.Ed
+.El
+.Sh CODE REFERENCES
+The core of the mutex implementation is in
+.Pa sys/kern/kern_mutex.c .
+.Pp
+The header file
+.Pa sys/sys/mutex.h
+describes the public interface, and interfaces that machine-dependent
+code must provide to support mutexes.
+.Sh SEE ALSO
+.Xr atomic_ops 3 ,
+.Xr membar_ops 3 ,
+.Xr options 4 ,
+.Xr lockstat 8 ,
+.Xr condvar 9 ,
+.Xr kpreempt 9 ,
+.Xr rwlock 9 ,
+.Xr spl 9
+.Pp
+.Rs
+.%A Jim Mauro
+.%A Richard McDougall
+.%T Solaris Internals: Core Kernel Architecture
+.%I Prentice Hall
+.%D 2001
+.%O ISBN 0-13-022496-0
+.Re
+.Sh HISTORY
+The mutex primitives first appeared in
+.Nx 5.0 .
+.Fn mutex_ownable
+first appeared in
+.Nx 8.0 .