Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src/share/man/man9 KERNEL_LOCK(9): New man page for old not-dead...
details: https://anonhg.NetBSD.org/src/rev/ae9928434ede
branches: trunk
changeset: 361579:ae9928434ede
user: riastradh <riastradh%NetBSD.org@localhost>
date: Tue Feb 15 22:46:29 2022 +0000
description:
KERNEL_LOCK(9): New man page for old not-dead-yet hack.
I'm not documenting this to encourage anyone to use it. I'm only
documenting this to remind myself what the semantics is, because it's
kind of confusing and not at all like mutex(9).
diffstat:
distrib/sets/lists/comp/mi | 17 ++-
share/man/man9/KERNEL_LOCK.9 | 312 +++++++++++++++++++++++++++++++++++++++++++
share/man/man9/Makefile | 8 +-
3 files changed, 335 insertions(+), 2 deletions(-)
diffs (truncated from 383 to 300 lines):
diff -r 21b26378f7f8 -r ae9928434ede distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi Tue Feb 15 20:35:37 2022 +0000
+++ b/distrib/sets/lists/comp/mi Tue Feb 15 22:46:29 2022 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2411 2022/02/12 17:10:20 riastradh Exp $
+# $NetBSD: mi,v 1.2412 2022/02/15 22:46:29 riastradh Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -11162,6 +11162,11 @@
./usr/share/man/cat9/KASSERTMSG.0 comp-sys-catman .cat
./usr/share/man/cat9/KDASSERT.0 comp-sys-catman .cat
./usr/share/man/cat9/KDASSERTMSG.0 comp-sys-catman .cat
+./usr/share/man/cat9/KERNEL_LOCK.0 comp-sys-catman .cat
+./usr/share/man/cat9/KERNEL_LOCKED_P.0 comp-sys-catman .cat
+./usr/share/man/cat9/KERNEL_UNLOCK_ALL.0 comp-sys-catman .cat
+./usr/share/man/cat9/KERNEL_UNLOCK_LAST.0 comp-sys-catman .cat
+./usr/share/man/cat9/KERNEL_UNLOCK_ONE.0 comp-sys-catman .cat
./usr/share/man/cat9/KNOTE.0 comp-sys-catman .cat
./usr/share/man/cat9/LWP_CACHE_CREDS.0 comp-sys-catman .cat
./usr/share/man/cat9/MALLOC.0 comp-sys-catman .cat
@@ -19411,6 +19416,11 @@
./usr/share/man/html9/KASSERTMSG.html comp-sys-htmlman html
./usr/share/man/html9/KDASSERT.html comp-sys-htmlman html
./usr/share/man/html9/KDASSERTMSG.html comp-sys-htmlman html
+./usr/share/man/html9/KERNEL_LOCK.html comp-sys-htmlman html
+./usr/share/man/html9/KERNEL_LOCKED_P.html comp-sys-htmlman html
+./usr/share/man/html9/KERNEL_UNLOCK_ALL.html comp-sys-htmlman html
+./usr/share/man/html9/KERNEL_UNLOCK_LAST.html comp-sys-htmlman html
+./usr/share/man/html9/KERNEL_UNLOCK_ONE.html comp-sys-htmlman html
./usr/share/man/html9/KNOTE.html comp-sys-htmlman html
./usr/share/man/html9/LWP_CACHE_CREDS.html comp-sys-htmlman html
./usr/share/man/html9/MALLOC.html comp-sys-htmlman html
@@ -27741,6 +27751,11 @@
./usr/share/man/man9/KASSERTMSG.9 comp-sys-man .man
./usr/share/man/man9/KDASSERT.9 comp-sys-man .man
./usr/share/man/man9/KDASSERTMSG.9 comp-sys-man .man
+./usr/share/man/man9/KERNEL_LOCK.9 comp-sys-man .man
+./usr/share/man/man9/KERNEL_LOCKED_P.9 comp-sys-man .man
+./usr/share/man/man9/KERNEL_UNLOCK_ALL.9 comp-sys-man .man
+./usr/share/man/man9/KERNEL_UNLOCK_LAST.9 comp-sys-man .man
+./usr/share/man/man9/KERNEL_UNLOCK_ONE.9 comp-sys-man .man
./usr/share/man/man9/KNOTE.9 comp-sys-man .man
./usr/share/man/man9/LWP_CACHE_CREDS.9 comp-sys-man .man
./usr/share/man/man9/MALLOC.9 comp-sys-man .man
diff -r 21b26378f7f8 -r ae9928434ede share/man/man9/KERNEL_LOCK.9
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/KERNEL_LOCK.9 Tue Feb 15 22:46:29 2022 +0000
@@ -0,0 +1,312 @@
+.\" $NetBSD: KERNEL_LOCK.9,v 1.1 2022/02/15 22:46:29 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 13, 2022
+.Dt KERNEL_LOCK 9
+.Os
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh NAME
+.Nm KERNEL_LOCK
+.Nd compatibility with legacy uniprocessor code
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SYNOPSIS
+.In sys/systm.h
+.\"
+.Ft void
+.Fn KERNEL_LOCK "int nlocks" "struct lwp *l"
+.Ft void
+.Fn KERNEL_UNLOCK_ONE "struct lwp *l"
+.Ft void
+.Fn KERNEL_UNLOCK_ALL "struct lwp *l" "int *nlocksp"
+.Ft void
+.Fn KERNEL_UNLOCK_LAST "struct lwp *l"
+.Ft bool
+.Fn KERNEL_LOCKED_P
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh DESCRIPTION
+The
+.Nm
+facility serves to gradually transition software from the kernel's
+legacy uniprocessor execution model, where the kernel runs on only a
+single CPU and never in parallel on multiple CPUs, to a multiprocessor
+system.
+.Pp
+.Sy New code should not use Nm .
+.Nm
+is meant only for gradual transition of
+.Nx
+to natively MP-safe code, which uses
+.Xr mutex 9
+or other
+.Xr locking 9
+facilities to synchronize between threads and interrupt handlers.
+Use of
+.Nm
+hurts system performance and responsiveness.
+This man page exists only to document the legacy API in order to make
+it easier to transition away from.
+.Pp
+The kernel lock, sometimes also known as
+.Sq giant lock
+or
+.Sq big lock ,
+is a recursive exclusive spin-lock that can be held by a CPU at any
+interrupt priority level and is dropped while sleeping.
+This means:
+.Bl -tag -width "held by a CPU"
+.It recursive
+If a CPU already holds the kernel lock, it can be acquired again and
+again, as long as it is released an equal number of times.
+.It exclusive
+Only one CPU at a time can hold the kernel lock.
+.It spin-lock
+When one CPU holds the kernel lock and another CPU wants to hold it,
+the second CPU
+.Sq spins ,
+i.e., repeatedly executes instructions to see if the kernel lock is
+available yet, until the first CPU releases it.
+During this time, no other threads can run on the spinning CPU.
+.Pp
+This means holding the kernel lock for long periods of time, such as
+nontrivial computation, must be avoided.
+Under
+.Dv LOCKDEBUG
+kernels, holding the kernel lock for too long can lead to
+.Sq spinout
+crashes.
+.It held by a CPU
+The kernel lock is held by a CPU, not by a process, kthread, LWP, or
+interrupt handler.
+It may be shared by a kthread LWP and several softint LWPs at the same
+time, for example, if the softints interrupted the thread on a CPU.
+.It any interrupt priority level
+The kernel lock
+.Em does not
+block interrupts; subsystems running with the kernel lock use
+.Xr spl 9
+to synchronize with interrupt handlers.
+.Pp
+Interrupt handlers that are not marked MP-safe are always run with the
+kernel lock.
+If the interrupt arrives on a CPU where the kernel lock is already
+held, it is simply taken again recursively on interrupt entry and
+released to its original recursion depth on interrupt exit.
+.It dropped while sleeping
+Any time the kernel sleeps to let other threads run, for any reason
+including
+.Xr tsleep 9
+or
+.Xr condvar 9
+or even adaptive
+.Xr mutex 9
+locks, it releases the kernel lock before going to sleep and then
+reacquires it afterward.
+.Pp
+This means, for instance, that although data structures accessed only
+under the kernel lock won't be changed before the sleep, they may be
+changed by another thread during the sleep.
+For example, the following program may crash on an assertion failure
+because the sleep in
+.Xr mutex_enter 9
+can allow another CPU to run and change the global variable
+.Dv x :
+.Bd -literal
+ KERNEL_LOCK(1, NULL);
+ x = 42;
+ mutex_enter(...);
+ ...
+ mutex_exit(...);
+ KASSERT(x == 42);
+ KERNEL_UNLOCK_ONE(NULL);
+.Ed
+.Pp
+This means simply introducing calls to
+.Xr mutex_enter 9
+and
+.Xr mutex_exit 9
+can break kernel-locked assumptions.
+Subsystems need to be consistently converted from
+.Xr KERNEL_LOCK 9
+and
+.Xr spl 9
+to
+.Xr mutex 9 ,
+.Xr condvar 9 ,
+etc.; mixing
+.Xr mutex 9
+and
+.Nm
+usually doesn't work.
+.El
+.Pp
+Holding the kernel lock
+.Em does not
+prevent other code from running on other CPUs at the same time.
+It only prevents other
+.Em kernel-locked
+code from running on other CPUs at the same time.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh FUNCTIONS
+.Bl -tag -width abcd
+.It Fn KERNEL_LOCK nlocks l
+Acquire
+.Fa nlocks
+recursive levels of kernel lock.
+.Pp
+If the kernel lock is already held by another CPU, spins until it can
+be acquired by this one.
+If the kernel lock is already held by this CPU, records the kernel
+lock recursion depth and returns immediately.
+.Pp
+Most of the time
+.Fa nlocks
+is 1, but code that deliberately releases all of the kernel locks held
+by the current CPU in order to sleep and later reacquire the same
+number of kernel locks will pass a value of
+.Fa nlocks
+obtained from
+.Fn KERNEL_UNLOCK_ALL .
+.It Fn KERNEL_UNLOCK_ONE l
+Release one level of the kernel lock.
+Equivalent to
+.Fo KERNEL_UNLOCK
+.Li 1 ,
+.Fa l ,
+.Dv NULL
+.Fc .
+.It Fn KERNEL_UNLOCK_ALL l nlocksp
+Store the kernel lock recursion depth at
+.Fa nlocksp
+and release all recursive levels of the kernel lock.
+.Pp
+This is often used inside logic implementing sleep, around a call to
+.Xr mi_switch 9 ,
+so that the same number of recursive kernel locks can be reacquired
+afterward once the thread is reawoken:
+.Bd -literal
+ int nlocks;
+
+ KERNEL_UNLOCK_ALL(l, &nlocks);
+ ... mi_switch(l) ...
+ KERNEL_LOCK(nlocks, l);
+.Ed
+.It Fn KERNEL_UNLOCK_LAST l
+Release the kernel lock, which must be held at exactly one level.
+.Pp
+This is normally used at the end of a non-MP-safe thread, which was
+known to have started with exactly one level of the kernel lock, and is
+now about to exit.
+.It Fn KERNEL_LOCKED_P
+True if the kernel lock is held.
+.Pp
+To be used only in diagnostic assertions with
+.Xr KASSERT 9 .
+.El
+.Pp
+The legacy argument
+.Fa l
+must be
+.Dv NULL
+or
+.Dv curlwp ,
+which mean the same thing.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh NOTES
+Some
+.Nx
+kernel abstractions execute caller-specified funtions with the kernel
+lock held by default, for compatibility with legacy code, but can be
+explicitly instructed
+.Em not
+to hold the kernel lock by passing an MP-safe flag:
+.Bl -bullet
+.It
+.Xr callout 9 ,
+.Dv CALLOUT_MPSAFE
+.It
+.Xr kfilter_register 9
+and
Home |
Main Index |
Thread Index |
Old Index