1 files changed, 287 insertions, 0 deletions
diff --git a/static/netbsd/man9/spl.9 b/static/netbsd/man9/spl.9
new file mode 100644
index 00000000..2bab0bc8
--- /dev/null
+++ b/static/netbsd/man9/spl.9
@@ -0,0 +1,287 @@
+.\"	$NetBSD: spl.9,v 1.42 2020/04/07 07:25:09 jdolecek 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 April 7, 2020
+.Dt SPL 9
+.Os
+.Sh NAME
+.Nm spl ,
+.Nm spl0 ,
+.Nm splhigh ,
+.Nm splvm ,
+.Nm splbio ,
+.Nm splnet ,
+.Nm spltty ,
+.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 splbio void
+.Ft int
+.Fn splnet void
+.Ft int
+.Fn spltty 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
+The global
+.Dv kernel_lock
+is automatically acquired for interrupts at this level by default,
+in order to
+support device drivers that do not provide their own multiprocessor
+synchronization.
+The automatic acquisition of
+.Dv kernel_lock
+can be disabled for individual interrupt handlers by device drivers
+if supported by subsystem, see e.g.
+.Xr pci_intr_establish 9 .
+.Pp
+.Fn splbio ,
+.Fn splnet ,
+and
+.Fn spltty
+are synonyms for
+.Fn splvm .
+Their use is deprecated; all new code should use
+.Fn splvm .
+.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
+.Fa s ,
+which must be a value previously returned by one of the other
+.Nm
+functions.
+.Sh SEE ALSO
+.Xr condvar 9 ,
+.Xr i386/splraise 9 ,
+.Xr kpreempt 9 ,
+.Xr mutex 9 ,
+.Xr rwlock 9
+.Sh HISTORY
+In
+.Bx 4.4 ,
+.Fn splnet
+was used to block network software interrupts.
+Most device drivers used
+.Fn splimp
+to block hardware interrupts.
+To avoid unnecessarily blocking other interrupts, in
+.Nx 1.1
+a new function was added that blocks only network hardware interrupts.
+For consistency with other
+.Nm
+functions, the old
+.Fn splnet
+function was renamed to
+.Fn splsoftnet ,
+and the new function was named
+.Fn splnet .
+.Pp
+Originally,
+.Fn splsoftclock
+lowered the system priority level.
+During the
+.Nx 1.5
+development cycle,
+.Fn spllowersoftclock
+was introduced and the semantics of
+.Fn splsoftclock
+were changed.
+.Pp
+The
+.Fn splimp
+call was removed from the kernel between
+.Nx 1.5
+and
+.Nx 1.6 .
+The function of
+.Fn splimp
+was replaced by
+.Fn splvm
+and code which abused the semantics of
+.Fn splimp
+was changed to not mix interrupt priority levels.
+.Pp
+Between
+.Nx 4.0
+and
+.Nx 5.0 ,
+the hardware levels were reduced in number and a strict hierarchy
+defined.