[src/uebayasi-xip]: src/share/man/man9 kpreempt(9): add a note when kernel pr...

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

details:   https://anonhg.NetBSD.org/src/rev/048ee4e8d7eb
branches:  uebayasi-xip
changeset: 751579:048ee4e8d7eb
user:      rmind <rmind%NetBSD.org@localhost>
date:      Tue Feb 16 19:21:31 2010 +0000

description:
kpreempt(9): add a note when kernel preemption is disabled/deferred.
Sprinkle cross-links, bump dates.

diffstat:

 share/man/man9/kpreempt.9 |   87 +++++++++++++++
 share/man/man9/spl.9      |  266 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 353 insertions(+), 0 deletions(-)

diffs (truncated from 361 to 300 lines):

diff -r d764a40070a3 -r 048ee4e8d7eb share/man/man9/kpreempt.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/kpreempt.9 Tue Feb 16 19:21:31 2010 +0000
@@ -0,0 +1,87 @@
+.\"    $NetBSD: kpreempt.9,v 1.3.2.2 2010/02/16 19:21:31 rmind Exp $
+.\"
+.\" Copyright (c)2008 YAMAMOTO Takashi,
+.\" 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 AUTHOR 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 AUTHOR 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 16, 2010
+.Dt KPREEMPT 9
+.Os
+.\" ------------------------------------------------------------
+.Sh NAME
+.Nm kpreempt
+.Nd control kernel preemption
+.\" ------------------------------------------------------------
+.Sh SYNOPSIS
+.In sys/systm.h
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft void
+.Fn kpreempt_disable \
+"void"
+.Ft void
+.Fn kpreempt_enable \
+"void"
+.Ft bool
+.Fn kpreempt_disabled \
+"void"
+.\" ------------------------------------------------------------
+.Sh DESCRIPTION
+These functions are used to control kernel preemption of the calling LWP.
+.Pp
+On architectures where kernel preemption is not supported natively, these
+functions may still be used.
+.Pp
+It should be noted that kernel preemption is also disabled when holding
+the interrupt priority level above IPL_NONE, e.g. using
+.Xr spl 9
+or spinning
+.Xr mutex 9
+calls or holding kernel_lock (indicating that the code is not MT safe).
+.Pp
+.Fn kpreempt_disable
+disables kernel preemption of the calling LWP.
+Note that disabling kernel preemption can prevent LWPs with higher priorities
+from running.
+.Pp
+.Fn kpreempt_enable
+enables kernel preemption of the calling LWP, which was previously disabled by
+.Fn kpreempt_disable .
+.Pp
+.Fn kpreempt_disable
+and
+.Fn kpreempt_enable
+can be nested.
+.Pp
+.Fn kpreempt_disabled
+returns
+.Dv true
+if preemption of the calling LWP is disabled.
+It is only for diagnostic purpose.
+.\" ------------------------------------------------------------
+.\" .Sh RETURN VALUES
+.\" ------------------------------------------------------------
+.Sh SEE ALSO
+.Xr intro 9 ,
+.Xr mutex 9 ,
+.Xr spl 9
diff -r d764a40070a3 -r 048ee4e8d7eb share/man/man9/spl.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/spl.9      Tue Feb 16 19:21:31 2010 +0000
@@ -0,0 +1,266 @@
+.\"    $NetBSD: spl.9,v 1.39.2.2 2010/02/16 19:21:31 rmind Exp $
+.\"
+.\" Copyright (c) 2000, 2001 Jason R. Thorpe.  All rights reserved.
+.\" Copyright (c) 1997 Michael Long.
+.\" Copyright (c) 1997 Jonathan Stone.
+.\" 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.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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 16, 2010
+.Dt SPL 9
+.Os
+.Sh NAME
+.Nm spl ,
+.Nm spl0 ,
+.Nm splhigh ,
+.Nm splvm ,
+.Nm splsched ,
+.Nm splsoftbio ,
+.Nm splsoftclock ,
+.Nm splsoftnet ,
+.Nm splsoftserial ,
+.Nm splx
+.Nd modify system interrupt priority level
+.Sh SYNOPSIS
+.In sys/intr.h
+.Ft void
+.Fn spl0 void
+.Ft int
+.Fn splhigh void
+.Ft int
+.Fn splsched void
+.Ft int
+.Fn splvm void
+.Ft int
+.Fn splsoftbio void
+.Ft int
+.Fn splsoftclock void
+.Ft int
+.Fn splsoftserial void
+.Ft int
+.Fn splsoftnet void
+.Ft void
+.Fn splx "int s"
+.Sh DESCRIPTION
+These functions raise and lower the interrupt priority level.
+They are used by kernel code to block interrupts in critical
+sections, in order to protect data structures.
+.Pp
+In a multi-CPU system, these functions change the interrupt
+priority level on the local CPU only.
+In general, device drivers should not make use of these interfaces.
+To ensure correct synchronization, device drivers should use the
+.Xr condvar 9 ,
+.Xr mutex 9 ,
+and
+.Xr rwlock 9
+interfaces.
+.Pp
+Interrupt priorities are arranged in a strict hierarchy, although
+sometimes levels may be equivalent (overlap).
+The hierarchy means that raising the IPL to any level will block
+interrupts at that level, and at all lower levels.
+The hierarchy is used to minimize data loss due to interrupts not
+being serviced in a timely fashion.
+.Pp
+The levels may be divided into two groups: hard and soft.
+Hard interrupts are generated by hardware devices.
+Soft interrupts are a way of deferring hardware interrupts to do more
+expensive processing at a lower interrupt priority, and are explicitly
+scheduled by the higher-level interrupt handler.
+Software interrupts are further described by
+.Xr softint 9 .
+.Pp
+Note that hard interrupt handlers do not possess process (thread) context
+and so it is not valid to use kernel facilities that may attempt to sleep
+from a hardware interrupt.
+For example, it is not possible to acquire a reader/writer lock from
+a hardware interrupt.
+Soft interrupt handlers possess limited process context and so may sleep
+briefly in order to acquire a reader/writer lock or adaptive mutex,
+but may not sleep for any other reason.
+.Pp
+In order of highest to lowest priority, the priority-raising functions
+along with their counterpart symbolic tags are:
+.Bl -tag -width splsoft
+.It Fn splhigh , IPL_HIGH
+.Pp
+Blocks all hard and soft interrupts, including the highest level I/O
+interrupts, such as interrupts from serial interfaces and the
+statistics clock (if any).
+It is also used for code that cannot tolerate any interrupts.
+.Pp
+Code running at this level may not (in general) directly access
+machine independent kernel services.
+For example, it is illegal to call the kernel
+.Fn printf
+function or to try and allocate memory.
+The methods of synchronization available are: spin mutexes and
+scheduling a soft interrupt.
+Generally, all code run at this level must schedule additional
+processing to run in a software interrupt.
+.Pp
+Code with thread context running at this level must not use a kernel
+interface that may cause the current LWP to sleep, such as the
+.Xr condvar 9
+interfaces.
+.Pp
+Interrupt handlers at this level cannot acquire the global kernel_lock
+and so must be coded to ensure correct synchronization on multiprocessor
+systems.
+.It Fn splsched , IPL_SCHED
+.Pp
+Blocks all medium priority hardware interrupts, such as interrupts
+from audio devices, and the clock interrupt.
+.Pp
+Interrupt handlers running at this level endure the same restrictions as
+at IPL_HIGH, but may access scheduler interfaces, and so may awaken LWPs
+(light weight processes) using the
+.Xr condvar 9
+interfaces, and may schedule callouts using the
+.Xr callout 9
+interfaces.
+.Pp
+Code with thread context running at this level may sleep via the
+.Xr condvar 9
+interfaces, and may use other kernel facilities that could cause the
+current LWP to sleep.
+.It Fn splvm , IPL_VM
+.Pp
+Blocks hard interrupts from
+.Dq low
+priority hardware interrupts, such
+as interrupts from network, block I/O and tty devices.
+.Pp
+Code running at this level endures the same restrictions as at IPL_SCHED,
+but may use the deprecated
+.Xr malloc 9
+or endorsed
+.Xr pool_cache 9
+interfaces to allocate memory.
+.Pp
+At the time of writing, the global
+.Dv kernel_lock
+is automatically acquired for interrupts at this level, in order to
+support device drivers that do not provide their own multiprocessor
+synchronization.
+A future release of the system may allow the automatic acquisition of
+.Dv kernel_lock
+to be disabled for individual interrupt handlers.
+.It Fn splsoftserial , IPL_SOFTSERIAL
+.Pp
+Blocks soft interrupts at the IPL_SOFTSERIAL symbolic level.
+.Pp
+This is the first of the software levels.
+Soft interrupts at this level and lower may acquire reader/writer
+locks or adaptive mutexes.
+.It Fn splsoftnet , IPL_SOFTNET
+.Pp
+Blocks soft interrupts at the IPL_SOFTNET symbolic level.
+.It Fn splsoftbio , IPL_SOFTBIO
+.Pp
+Blocks soft interrupts at the IPL_SOFTBIO symbolic level.
+.It Fn splsoftclock , IPL_SOFTCLOCK
+.Pp
+Blocks soft interrupts at the IPL_SOFTCLOCK symbolic level.
+.Pp
+This is the priority at which callbacks generated by the
+.Xr callout 9
+facility runs.
+.El
+.Pp
+One function lowers the system priority level:
+.Bl -tag -width splsoft
+.It Fn spl0 , IPL_NONE
+.Pp
+Unblocks all interrupts.
+This should rarely be used directly;
+.Fn splx
+should be used instead.
+.El
+.Pp
+The
+.Fn splx
+function restores the system priority level to the one encoded in