diff options
Diffstat (limited to 'static/openbsd/man9/spl.9')
| -rw-r--r-- | static/openbsd/man9/spl.9 | 253 |
1 files changed, 253 insertions, 0 deletions
diff --git a/static/openbsd/man9/spl.9 b/static/openbsd/man9/spl.9 new file mode 100644 index 00000000..effcfb92 --- /dev/null +++ b/static/openbsd/man9/spl.9 @@ -0,0 +1,253 @@ +.\" $OpenBSD: spl.9,v 1.26 2016/08/16 23:49:35 dlg Exp $ +.\" $NetBSD: spl.9,v 1.1 1997/03/11 06:15:05 mikel Exp $ +.\" +.\" 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 $Mdocdate: August 16 2016 $ +.Dt SPLX 9 +.Os +.Sh NAME +.Nm splraise , +.Nm splhigh , +.Nm splserial , +.Nm splsched , +.Nm splclock , +.Nm splstatclock , +.Nm splvm , +.Nm spltty , +.Nm splsofttty , +.Nm splnet , +.Nm splbio , +.Nm splsoftnet , +.Nm splsoftclock , +.Nm spllowersoftclock , +.Nm spl0 , +.Nm splx , +.Nm splassert +.Nd modify system interrupt priority level +.Sh SYNOPSIS +.In machine/intr.h +.Ft int +.Fn splraise "int ipl" +.Ft int +.Fn splhigh void +.Ft int +.Fn splserial void +.Ft int +.Fn splsched void +.Ft int +.Fn splclock void +.Ft int +.Fn splstatclock void +.Ft int +.Fn splvm void +.Ft int +.Fn spltty void +.Ft int +.Fn splsofttty void +.Ft int +.Fn splnet void +.Ft int +.Fn splbio void +.Ft int +.Fn splsoftnet void +.Ft int +.Fn splsoftclock void +.Ft int +.Fn spllowersoftclock void +.Ft int +.Fn spl0 void +.Ft void +.Fn splx "int s" +.Ft void +.Fn splassert "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 (i.e., +.Fn spltty +blocks interrupts of priority less than or equal to +.Dv IPL_TTY ) . +The code may then safely access variables and data structures which +are used by kernel code that runs at an equal or lower priority level. +.Pp +An +.Nm spl +function exists for each distinct priority level which can exist in +the system. +These macros 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, while soft interrupts are generated by callouts and called +from the kernel's periodic timer interrupt service routine. +.Pp +In order of highest to lowest priority, the priority-raising macros +are: +.Bl -tag -width splsoftclockXX +.It Fn splhigh +blocks all hard and soft interrupts. +It is used for code that cannot +tolerate any interrupts, like hardware context switching code and 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. +.It Fn splsched +blocks interrupts that may access scheduler data structures. +Specifically the clock interrupt that invokes the +.Fn schedclock +function needs to be blocked. +On some systems this is a separate clock; +on others it is the same as the statistics clock and, on these, +.Fn splsched +must block everything that +.Fn splstatclock +does. +Code running at or above this level may not call +.Xr tsleep 9 +or +.Xr wakeup 9 , +nor may it post signals. +Note that "running" means invoked by an interrupt handler that +operates at this level or higher. +Kernel code that operates in the context of a process and has called +.Fn splhigh +for blocking purposes can use +.Xr tsleep 9 +or +.Xr wakeup 9 . +.It Fn splclock +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. +.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 +.Fn splclock +if there is no separate statistics clock. +.It Fn splvm +blocks hard interrupts from all devices that are allowed to use the +kernel +.Xr malloc 9 . +That includes all disk, network, and tty device interrupts. +.It Fn spltty +blocks hard interrupts from TTY devices. +.It Fn splsofttty +blocks soft interrupts generated by serial devices. +.It Fn splnet +blocks hard interrupts from network interfaces. +.It Fn splbio +blocks hard interrupts from disks and other mass-storage devices. +.It Fn splsoftnet +blocks soft network interrupts. +.It Fn splsoftclock +blocks soft clock interrupts. +.El +.Pp +Two macros lower the system priority level. +They are: +.Bl -tag -width spllowersoftclockXX +.It Fn spllowersoftclock +unblocks all interrupts but the soft clock interrupt. +.It Fn spl0 +unblocks all interrupts. +.El +.Pp +The +.Fn splraise +macro blocks interrupts at the interrupt priority level specified by +.Fa ipl . +.Pp +The +.Fn splx +macro 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 spl +macros. +.Pp +The +.Fn splassert +function checks that the system is running at a certain priority level. +The argument +.Fa s +should be one of these constants: +.Pp +.Bl -tag -width IPL_SOFTCLOCKXX -compact -offset indent +.It Dv IPL_STATCLOCK +.It Dv IPL_SCHED +.It Dv IPL_CLOCK +.It Dv IPL_VM +.It Dv IPL_BIO +.It Dv IPL_TTY +.It Dv IPL_NET +.It Dv IPL_SOFTNET +.It Dv IPL_SOFTCLOCK +.It Dv IPL_NONE +.El +.Pp +The +.Fn splassert +function is optional and is not necessarily implemented on +all architectures nor enabled in all kernel configurations. +It checks the current system priority level to see if it's +at least at the level specified in the argument +.Fa s . +If possible, it also checks if it hasn't been called from an +interrupt handler with a level higher than the one requested, which +must be an error (if some code is protected from +.Dv IPL_SOFTNET +interrupts, but accessed from an +.Dv IPL_NET +interrupt, it must be a design error in the code). +.Pp +The behavior of the +.Fn splassert +function is controlled by the kern.splassert +.Xr sysctl 8 . +Valid values for it are: +.Pp +.Bl -tag -width 1nr -compact -offset indent +.It 0 +disable error checking +.It 1 +print a message if an error is detected +.It 2 +print a message and a stack trace if possible +.It 3 +like 2 but also drop into the kernel debugger +.El +.Pp +Any other value causes a system panic on errors. |