1.\" $OpenBSD: spl.9,v 1.26 2016/08/16 23:49:35 dlg 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: August 16 2016 $ 31.Dt SPLX 9 32.Os 33.Sh NAME 34.Nm splraise , 35.Nm splhigh , 36.Nm splserial , 37.Nm splsched , 38.Nm splclock , 39.Nm splstatclock , 40.Nm splvm , 41.Nm spltty , 42.Nm splsofttty , 43.Nm splnet , 44.Nm splbio , 45.Nm splsoftnet , 46.Nm splsoftclock , 47.Nm spllowersoftclock , 48.Nm spl0 , 49.Nm splx , 50.Nm splassert 51.Nd modify system interrupt priority level 52.Sh SYNOPSIS 53.In machine/intr.h 54.Ft int 55.Fn splraise "int ipl" 56.Ft int 57.Fn splhigh void 58.Ft int 59.Fn splserial void 60.Ft int 61.Fn splsched void 62.Ft int 63.Fn splclock void 64.Ft int 65.Fn splstatclock void 66.Ft int 67.Fn splvm void 68.Ft int 69.Fn spltty void 70.Ft int 71.Fn splsofttty void 72.Ft int 73.Fn splnet void 74.Ft int 75.Fn splbio void 76.Ft int 77.Fn splsoftnet void 78.Ft int 79.Fn splsoftclock void 80.Ft int 81.Fn spllowersoftclock void 82.Ft int 83.Fn spl0 void 84.Ft void 85.Fn splx "int s" 86.Ft void 87.Fn splassert "int s" 88.Sh DESCRIPTION 89These functions raise and lower the system priority level. 90They are used by kernel code to block interrupts with priority less 91than or equal to the named level (i.e., 92.Fn spltty 93blocks interrupts of priority less than or equal to 94.Dv IPL_TTY ) . 95The code may then safely access variables and data structures which 96are used by kernel code that runs at an equal or lower priority level. 97.Pp 98An 99.Nm spl 100function exists for each distinct priority level which can exist in 101the system. 102These macros and the corresponding priority levels are 103used for various defined purposes, and may be divided into two main 104types: hard and soft. 105Hard interrupts are generated by hardware 106devices, while soft interrupts are generated by callouts and called 107from the kernel's periodic timer interrupt service routine. 108.Pp 109In order of highest to lowest priority, the priority-raising macros 110are: 111.Bl -tag -width splsoftclockXX 112.It Fn splhigh 113blocks all hard and soft interrupts. 114It is used for code that cannot 115tolerate any interrupts, like hardware context switching code and the 116.Xr ddb 4 117in-kernel debugger. 118.It Fn splserial 119blocks hard interrupts from serial interfaces. 120Code running at this level may not access the tty subsystem. 121.It Fn splsched 122blocks interrupts that may access scheduler data structures. 123Specifically the clock interrupt that invokes the 124.Fn schedclock 125function needs to be blocked. 126On some systems this is a separate clock; 127on others it is the same as the statistics clock and, on these, 128.Fn splsched 129must block everything that 130.Fn splstatclock 131does. 132Code running at or above this level may not call 133.Xr tsleep 9 134or 135.Xr wakeup 9 , 136nor may it post signals. 137Note that "running" means invoked by an interrupt handler that 138operates at this level or higher. 139Kernel code that operates in the context of a process and has called 140.Fn splhigh 141for blocking purposes can use 142.Xr tsleep 9 143or 144.Xr wakeup 9 . 145.It Fn splclock 146blocks the hardware clock interrupt. 147It is used by 148.Fn hardclock 149to update kernel and process times, and must be used by any other code 150that accesses time-related data. 151.It Fn splstatclock 152blocks the hardware statistics clock interrupt. 153It is used by 154.Fn statclock 155to update kernel profiling and other statistics, and must be used by 156any code that accesses that data. 157This level is identical to 158.Fn splclock 159if there is no separate statistics clock. 160.It Fn splvm 161blocks hard interrupts from all devices that are allowed to use the 162kernel 163.Xr malloc 9 . 164That includes all disk, network, and tty device interrupts. 165.It Fn spltty 166blocks hard interrupts from TTY devices. 167.It Fn splsofttty 168blocks soft interrupts generated by serial devices. 169.It Fn splnet 170blocks hard interrupts from network interfaces. 171.It Fn splbio 172blocks hard interrupts from disks and other mass-storage devices. 173.It Fn splsoftnet 174blocks soft network interrupts. 175.It Fn splsoftclock 176blocks soft clock interrupts. 177.El 178.Pp 179Two macros lower the system priority level. 180They are: 181.Bl -tag -width spllowersoftclockXX 182.It Fn spllowersoftclock 183unblocks all interrupts but the soft clock interrupt. 184.It Fn spl0 185unblocks all interrupts. 186.El 187.Pp 188The 189.Fn splraise 190macro blocks interrupts at the interrupt priority level specified by 191.Fa ipl . 192.Pp 193The 194.Fn splx 195macro restores the system priority level to the one encoded in 196.Fa s , 197which must be a value previously returned by one of the other 198.Nm spl 199macros. 200.Pp 201The 202.Fn splassert 203function checks that the system is running at a certain priority level. 204The argument 205.Fa s 206should be one of these constants: 207.Pp 208.Bl -tag -width IPL_SOFTCLOCKXX -compact -offset indent 209.It Dv IPL_STATCLOCK 210.It Dv IPL_SCHED 211.It Dv IPL_CLOCK 212.It Dv IPL_VM 213.It Dv IPL_BIO 214.It Dv IPL_TTY 215.It Dv IPL_NET 216.It Dv IPL_SOFTNET 217.It Dv IPL_SOFTCLOCK 218.It Dv IPL_NONE 219.El 220.Pp 221The 222.Fn splassert 223function is optional and is not necessarily implemented on 224all architectures nor enabled in all kernel configurations. 225It checks the current system priority level to see if it's 226at least at the level specified in the argument 227.Fa s . 228If possible, it also checks if it hasn't been called from an 229interrupt handler with a level higher than the one requested, which 230must be an error (if some code is protected from 231.Dv IPL_SOFTNET 232interrupts, but accessed from an 233.Dv IPL_NET 234interrupt, it must be a design error in the code). 235.Pp 236The behavior of the 237.Fn splassert 238function is controlled by the kern.splassert 239.Xr sysctl 8 . 240Valid values for it are: 241.Pp 242.Bl -tag -width 1nr -compact -offset indent 243.It 0 244disable error checking 245.It 1 246print a message if an error is detected 247.It 2 248print a message and a stack trace if possible 249.It 3 250like 2 but also drop into the kernel debugger 251.El 252.Pp 253Any other value causes a system panic on errors. 254