1.\" $OpenBSD: spl.9,v 1.22 2007/05/31 19:20:01 jmc 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: May 31 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.Fn sleep , 116.Fn tsleep , 117or 118.Fn wakeup , 119nor may it post signals. 120Note that "running" means invoked by an interrupt handler that 121operates at this level or higher. 122Kernel code that operates in the context of a process and has called 123.Fn splhigh 124for blocking purposes can use 125.Fn sleep , 126.Fn tsleep , 127or 128.Fn wakeup . 129.It Fn splclock 130blocks the hardware clock interrupt. 131It is used by 132.Fn hardclock 133to update kernel and process times, and must be used by any other code 134that accesses time-related data. 135.It Fn splstatclock 136blocks the hardware statistics clock interrupt. 137It is used by 138.Fn statclock 139to update kernel profiling and other statistics, and must be used by 140any code that accesses that data. 141This level is identical to 142.Fn splclock 143if there is no separate statistics clock. 144.It Fn splvm 145blocks hard interrupts from all devices that are allowed to use the 146kernel 147.Xr malloc 9 . 148That includes all disk, network, and tty device interrupts. 149.It Fn spltty 150blocks hard interrupts from TTY devices. 151.It Fn splsofttty 152blocks soft interrupts generated by serial devices. 153.It Fn splnet 154blocks hard interrupts from network interfaces. 155.It Fn splbio 156blocks hard interrupts from disks and other mass-storage devices. 157.It Fn splsoftnet 158blocks soft network interrupts. 159.It Fn splsoftclock 160blocks soft clock interrupts. 161.El 162.Pp 163Two macros lower the system priority level. 164They are: 165.Bl -tag -width spllowersoftclockXX 166.It Fn spllowersoftclock 167unblocks all interrupts but the soft clock interrupt. 168.It Fn spl0 169unblocks all interrupts. 170.El 171.Pp 172The 173.Fn splx 174macro restores the system priority level to the one encoded in 175.Fa s , 176which must be a value previously returned by one of the other 177.Nm 178macros. 179.Pp 180The 181.Fn splassert 182function checks that the system is running at a certain priority level. 183The argument 184.Fa s 185should be one of these constants: 186.Pp 187.Bl -tag -width IPL_SOFTCLOCKXX -compact -offset indent 188.It Dv IPL_STATCLOCK 189.It Dv IPL_SCHED 190.It Dv IPL_CLOCK 191.It Dv IPL_VM 192.It Dv IPL_BIO 193.It Dv IPL_TTY 194.It Dv IPL_NET 195.It Dv IPL_SOFTNET 196.It Dv IPL_SOFTCLOCK 197.It Dv IPL_NONE 198.El 199.Pp 200The 201.Fn splassert 202function is optional and is not necessarily implemented on 203all architectures nor enabled in all kernel configurations. 204It checks the current system priority level to see if it's 205at least at the level specified in the argument 206.Fa s . 207If possible, it also checks if it hasn't been called from an 208interrupt handler with a level higher than the one requested, which 209must be an error (if some code is protected from 210.Dv IPL_SOFTNET 211interrupts, but accessed from an 212.Dv IPL_NET 213interrupt, it must be a design error in the code). 214.Pp 215The behavior of the 216.Fn splassert 217function is controlled by the kern.splassert 218.Xr sysctl 8 . 219Valid values for it are: 220.Pp 221.Bl -tag -width 1nr -compact -offset indent 222.It 0 223disable error checking 224.It 1 225print a message if an error is detected 226.It 2 227print a message and a stack trace if possible 228.It 3 229like 2 but also drop into the kernel debugger 230.El 231.Pp 232Any other value causes a system panic on errors. 233