1.\" $OpenBSD: spl.9,v 1.23 2007/09/14 16:16:08 mk Exp $ 2.\" $NetBSD: spl.9,v 1.1 1997/03/11 06:15:05 mikel Exp $ 3.\" 4.\" Copyright (c) 1997 Michael Long. 5.\" Copyright (c) 1997 Jonathan Stone. 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. The name of the author may not be used to endorse or promote products 17.\" derived from this software without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 20.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 21.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 22.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 23.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 24.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 28.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd $Mdocdate: September 14 2007 $ 31.Dt SPL 9 32.Os 33.Sh NAME 34.Nm spl 35.Nd modify system interrupt priority level 36.Sh SYNOPSIS 37.Fd #include <machine/intr.h> 38.Ft int 39.Fn splhigh void 40.Ft int 41.Fn splserial void 42.Ft int 43.Fn splsched void 44.Ft int 45.Fn splclock void 46.Ft int 47.Fn splstatclock void 48.Ft int 49.Fn splvm void 50.Ft int 51.Fn spltty void 52.Ft int 53.Fn splsofttty void 54.Ft int 55.Fn splnet void 56.Ft int 57.Fn splbio void 58.Ft int 59.Fn splsoftnet void 60.Ft int 61.Fn splsoftclock void 62.Ft int 63.Fn spllowersoftclock void 64.Ft int 65.Fn spl0 void 66.Ft void 67.Fn splx "int s" 68.Ft void 69.Fn splassert "int s" 70.Sh DESCRIPTION 71These functions raise and lower the system priority level. 72They are used by kernel code to block interrupts with priority less 73than or equal to the named level (i.e., 74.Fn spltty 75blocks interrupts of priority less than or equal to 76.Dv IPL_TTY ) . 77The code may then safely access variables and data structures which 78are used by kernel code that runs at an equal or lower priority level. 79.Pp 80An 81.Nm 82function exists for each distinct priority level which can exist in 83the system. 84These macros and the corresponding priority levels are 85used for various defined purposes, and may be divided into two main 86types: hard and soft. 87Hard interrupts are generated by hardware 88devices, while soft interrupts are generated by callouts and called 89from the kernel's periodic timer interrupt service routine. 90.Pp 91In order of highest to lowest priority, the priority-raising macros 92are: 93.Bl -tag -width splsoftclockXX 94.It Fn splhigh 95blocks all hard and soft interrupts. 96It is used for code that cannot 97tolerate any interrupts, like hardware context switching code and the 98.Xr ddb 4 99in-kernel debugger. 100.It Fn splserial 101blocks hard interrupts from serial interfaces. 102Code running at this level may not access the tty subsystem. 103.It Fn splsched 104blocks interrupts that may access scheduler data structures. 105Specifically the clock interrupt that invokes the 106.Fn schedclock 107function needs to be blocked. 108On some systems this is a separate clock; 109on others it is the same as the statistics clock and, on these, 110.Fn splsched 111must block everything that 112.Fn splstatclock 113does. 114Code running at or above this level may not call 115.Xr tsleep 9 116or 117.Xr wakeup 9 , 118nor may it post signals. 119Note that "running" means invoked by an interrupt handler that 120operates at this level or higher. 121Kernel code that operates in the context of a process and has called 122.Fn splhigh 123for blocking purposes can use 124.Xr tsleep 9 125or 126.Xr wakeup 9 . 127.It Fn splclock 128blocks the hardware clock interrupt. 129It is used by 130.Fn hardclock 131to update kernel and process times, and must be used by any other code 132that accesses time-related data. 133.It Fn splstatclock 134blocks the hardware statistics clock interrupt. 135It is used by 136.Fn statclock 137to update kernel profiling and other statistics, and must be used by 138any code that accesses that data. 139This level is identical to 140.Fn splclock 141if there is no separate statistics clock. 142.It Fn splvm 143blocks hard interrupts from all devices that are allowed to use the 144kernel 145.Xr malloc 9 . 146That includes all disk, network, and tty device interrupts. 147.It Fn spltty 148blocks hard interrupts from TTY devices. 149.It Fn splsofttty 150blocks soft interrupts generated by serial devices. 151.It Fn splnet 152blocks hard interrupts from network interfaces. 153.It Fn splbio 154blocks hard interrupts from disks and other mass-storage devices. 155.It Fn splsoftnet 156blocks soft network interrupts. 157.It Fn splsoftclock 158blocks soft clock interrupts. 159.El 160.Pp 161Two macros lower the system priority level. 162They are: 163.Bl -tag -width spllowersoftclockXX 164.It Fn spllowersoftclock 165unblocks all interrupts but the soft clock interrupt. 166.It Fn spl0 167unblocks all interrupts. 168.El 169.Pp 170The 171.Fn splx 172macro restores the system priority level to the one encoded in 173.Fa s , 174which must be a value previously returned by one of the other 175.Nm 176macros. 177.Pp 178The 179.Fn splassert 180function checks that the system is running at a certain priority level. 181The argument 182.Fa s 183should be one of these constants: 184.Pp 185.Bl -tag -width IPL_SOFTCLOCKXX -compact -offset indent 186.It Dv IPL_STATCLOCK 187.It Dv IPL_SCHED 188.It Dv IPL_CLOCK 189.It Dv IPL_VM 190.It Dv IPL_BIO 191.It Dv IPL_TTY 192.It Dv IPL_NET 193.It Dv IPL_SOFTNET 194.It Dv IPL_SOFTCLOCK 195.It Dv IPL_NONE 196.El 197.Pp 198The 199.Fn splassert 200function is optional and is not necessarily implemented on 201all architectures nor enabled in all kernel configurations. 202It checks the current system priority level to see if it's 203at least at the level specified in the argument 204.Fa s . 205If possible, it also checks if it hasn't been called from an 206interrupt handler with a level higher than the one requested, which 207must be an error (if some code is protected from 208.Dv IPL_SOFTNET 209interrupts, but accessed from an 210.Dv IPL_NET 211interrupt, it must be a design error in the code). 212.Pp 213The behavior of the 214.Fn splassert 215function is controlled by the kern.splassert 216.Xr sysctl 8 . 217Valid values for it are: 218.Pp 219.Bl -tag -width 1nr -compact -offset indent 220.It 0 221disable error checking 222.It 1 223print a message if an error is detected 224.It 2 225print a message and a stack trace if possible 226.It 3 227like 2 but also drop into the kernel debugger 228.El 229.Pp 230Any other value causes a system panic on errors. 231