Inject more truth into this document.

share/man/man9/spl.9

@@ -1,5 +1,6 @@
-.\"	$NetBSD: spl.9,v 1.7 2000/06/08 06:45:24 cgd Exp $
+.\"	$NetBSD: spl.9,v 1.8 2000/08/21 22:53:53 thorpej Exp $
 .\"
+.\" Copyright (c) 2000 Jason R. Thorpe.  All rights reserved.
 .\" Copyright (c) 1997 Michael Long.
 .\" Copyright (c) 1997 Jonathan Stone.
 .\" All rights reserved.
@@ -26,7 +27,7 @@
 .\" (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 March 11, 1997
+.Dd August 21, 2000
 .Dt SPL 9
 .Os
 .Sh NAME
@@ -81,23 +82,44 @@
 .Fn splx "int s"
 .Sh DESCRIPTION
 These functions raise and lower the system priority level.
-They are used by kernel code to block interrupts with priority less
-than or equal to the named level (e.g.
-.Fn spltty
-blocks interrupts of priority less than or equal to
-.Dv IPL_TTY Ns ).
-The code may then safely access variables or data structures which are
-read or modified by interrupt service routines that run at the named
-level.
+They are used by kernel code to block interrupts in critical
+sections, in order to protect data structures (much like
+a locking primitive) or to ensure uninterrupted access to
+hardware devices which are sensitive to timing.
+.Pp
+Interrupt priorities are not arranged in a strict heirarchy, although
+interrupt hardware sometimes is.  For this reason the priorities
+listed here are arranged from
+.Dq highest
+to
+.Dq lowest .
+In other words, if a platform's hardware interrutps are arranged in
+a heirarchical manner, a priority level should also block all of the
+levels listed below it.
+.Pp
+Note that a strict heirarchy is not required.  For example,
+.Fn splnet
+is not required to block disk controller interrupts, as they
+do not access the same data structures.  However, the priorities
+are presented as a heirarchy in order to minimize data loss due
+to blocked interrupts, or interrupts not being serviced in a
+timely fashion.
 .Pp
 A
 .Nm
 function exists for each distinct priority level which can exist in
-the system.  These functions and the corresponding priority levels are
-used for various defined purposes, and may be divided into two main
-types: hard and soft.  Hard interrupts are generated by hardware
-devices.  Soft interrupts are generated by callouts, and are called
-from the kernel's periodic timer interrupt service routine.
+the system, as well as for some special priority levels that are
+designed to be used in conjunction with multiprocessor-safe locking
+primitives.  These levels may be divided into two main types: 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.  The most common use
+of this is in the networking code, where network interface drivers
+defer the more expensive TCP/IP processing in order to avoid dropping
+additional incoming packets.  Software interrutps are further described
+by
+.Xr softintr 9 .
 .Pp
 In order of highest to lowest priority, the priority-raising functions
 are:
@@ -109,13 +131,20 @@ the
 .Xr ddb 4
 in-kernel debugger.
 .It Fn splserial
-blocks hard interrupts from serial interfaces.  Code running at this
-level may not access the tty subsystem.
+blocks hard interrupts from serial interfaces (IPL_SERIAL).
+Code running at this level may not access the tty subsystem.
+Generally, all code run at this level must schedule additional
+processing to run in a software interrupt.  Note that code running
+at this priority is not blocked by
+.Fn splimp
+(described below), and is therefore prohibited from using the
+kernel memory allocators.
 .It Fn splsched
-blocks interrupts that may access scheduler data structures.  Code
-running at or above this level may not call
+blocks all hard and soft interrupts that may access scheduler data
+structures.  Code running at or above this level may not call
 .Fn sleep ,
 .Fn tsleep ,
+.Fn ltsleep ,
 or
 .Fn wakeup ,
 nor may it post signals.
@@ -123,32 +152,52 @@ nor may it post signals.
 blocks the hardware clock interrupt.  It is used by
 .Fn hardclock
 to update kernel and process times, and must be used by any other code
-that accesses time-related data.
+that accesses time-related data, specifically the
+.Va time
+and
+.Va mono_time
+global variables.
+This level also protects the
+.Xr callout 9
+data structures, and nothing running at or above this level may
+schedule, cancel, or otherwise access any callout-related data
+structures.
 .It Fn splstatclock
 blocks the hardware statistics clock interrupt.  It is used by
 .Fn statclock
 to update kernel profiling and other statistics, and must be used by
-any code that accesses that data.
-This level is identical to
+any code that accesses that data.  This is the clock that drives
+scheduling.  This level is identical to
 .Fn splclock
 if there is no separate statistics clock.
 .It Fn splimp
 blocks hard interrupts from all devices that are allowed to use the
 kernel
-.Xr malloc 9 .
+.Xr malloc 9 ,
+or any virtual memory operations.
 That includes all disk, network, and tty device interrupts.
 .It Fn spltty
-blocks hard interrupts from TTY devices.
+blocks hard and soft interrupts from TTY devices (IPL_TTY).  This
+must also block soft serial interrupts.
 .It Fn splsoftserial
-blocks soft interrupts generated by serial devices.
+blocks soft interrupts generated by serial devices (IPL_SOFTSERIAL).
 .It Fn splnet
-blocks hard interrupts from network interfaces.
+blocks hard interrupts from network interfaces (IPL_NET).
 .It Fn splbio
-blocks hard interrupts from disks and other mass-storage devices.
+blocks hard interrupts from disks and other mass-storage
+devices (IPL_BIO).
 .It Fn splsoftnet
-blocks soft network interrupts.
+blocks soft network interrupts (IPL_SOFTNET).  Soft interrupts blocked
+by this priority are also blocked by all of the priorities listed
+above.
 .It Fn splsoftclock
-blocks soft clock interrupts.
+blocks soft clock interrupts.  This is the priority at which the
+.Xr callout 9
+facility runs.  Soft interrupts blocked by this priority are also blocked
+by all of the priorities listed above.  In particular,
+.Fn splsoftnet
+must be a higher priority than
+.Fn splsoftclock .
 .El
 .Pp
 Two functions lower the system priority level.  They are: