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