1.\" $NetBSD: spl.9,v 1.17 2002/02/13 08:18:52 ross Exp $ 2.\" 3.\" Copyright (c) 2000, 2001 Jason R. Thorpe. All rights reserved. 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 April 13, 2001 31.Dt SPL 9 32.Os 33.Sh NAME 34.Nm spl , 35.Nm spl0 , 36.Nm splbio , 37.Nm splclock , 38.Nm splhigh , 39.Nm splvm , 40.Nm spllock , 41.Nm spllowersoftclock , 42.Nm splnet , 43.Nm splsched , 44.Nm splserial , 45.Nm splsoftclock , 46.Nm splsoftnet , 47.Nm splsoftserial , 48.Nm splstatclock , 49.Nm spltty , 50.Nm splvm , 51.Nm splx 52.Nd modify system interrupt priority level 53.Sh SYNOPSIS 54.Fd #include \*[Lt]machine/intr.h\*[Gt] 55.Ft int 56.Fn splhigh void 57.Ft int 58.Fn spllock void 59.Ft int 60.Fn splserial void 61.Ft int 62.Fn splsched void 63.Ft int 64.Fn splclock void 65.Ft int 66.Fn splstatclock void 67.Ft int 68.Fn splvm void 69.Ft int 70.Fn spltty void 71.Ft int 72.Fn splsoftserial void 73.Ft int 74.Fn splnet void 75.Ft int 76.Fn splbio void 77.Ft int 78.Fn splsoftnet void 79.Ft int 80.Fn splsoftclock void 81.Ft void 82.Fn spllowersoftclock void 83.Ft void 84.Fn spl0 void 85.Ft void 86.Fn splx "int s" 87.Sh DESCRIPTION 88These functions raise and lower the system priority level. 89They are used by kernel code to block interrupts in critical 90sections, in order to protect data structures (much like 91a locking primitive) or to ensure uninterrupted access to 92hardware devices which are sensitive to timing. 93.Pp 94Interrupt priorities are not arranged in a strict hierarchy, although 95interrupt hardware sometimes is. For this reason the priorities 96listed here are arranged from 97.Dq highest 98to 99.Dq lowest . 100In other words, if a platform's hardware interrupts are arranged in 101a hierarchical manner, a priority level should also block all of the 102levels listed below it. 103.Pp 104Note that a strict hierarchy is not required. For example, 105.Fn splnet 106is not required to block disk controller interrupts, as they 107do not access the same data structures. However, the priorities 108are presented as a hierarchy in order to minimize data loss due 109to blocked interrupts, or interrupts not being serviced in a 110timely fashion. 111.Pp 112A 113.Nm 114function exists for each distinct priority level which can exist in 115the system, as well as for some special priority levels that are 116designed to be used in conjunction with multiprocessor-safe locking 117primitives. These levels may be divided into two main types: hard 118and soft. Hard interrupts are generated by hardware devices. Soft 119interrupts are a way of deferring hardware interrupts to do more 120expensive processing at a lower interrupt priority, and are explicitly 121scheduled by the higher-level interrupt handler. The most common use 122of this is in the networking code, where network interface drivers 123defer the more expensive TCP/IP processing in order to avoid dropping 124additional incoming packets. Software interrupts are further described 125by 126.Xr softintr 9 . 127.Pp 128In order of highest to lowest priority, the priority-raising functions 129are: 130.Bl -tag -width splsoftserialXX 131.It Fn splhigh 132blocks all hard and soft interrupts. It is used for code that cannot 133tolerate any interrupts, like hardware context switching code and 134the 135.Xr ddb 4 136in-kernel debugger. 137.It Fn spllock 138blocks all hard and soft interrupts that can acquire a simple lock. This 139is provided as a distinct level from 140.Fn splhigh 141as some platforms may need to make use of extremely high priority 142interrupts while locks are spinning, which would be blocked by 143.Fn splhigh . 144.It Fn splserial 145blocks hard interrupts from serial interfaces (IPL_SERIAL). 146Code running at this level may not access the tty subsystem. 147Generally, all code run at this level must schedule additional 148processing to run in a software interrupt. Note that code running 149at this priority is not blocked by 150.Fn splvm 151(described below), and is therefore prohibited from using the 152kernel memory allocators. 153.It Fn splsched 154blocks all hard and soft interrupts that may access scheduler data 155structures. Code running at or above this level may not call 156.Fn sleep , 157.Fn tsleep , 158.Fn ltsleep , 159or 160.Fn wakeup , 161nor may it post signals. 162.It Fn splclock 163blocks the hardware clock interrupt. It is used by 164.Fn hardclock 165to update kernel and process times, and must be used by any other code 166that accesses time-related data, specifically the 167.Va time 168and 169.Va mono_time 170global variables. 171This level also protects the 172.Xr callout 9 173data structures, and nothing running at or above this level may 174schedule, cancel, or otherwise access any callout-related data 175structures. 176.It Fn splstatclock 177blocks the hardware statistics clock interrupt. It is used by 178.Fn statclock 179to update kernel profiling and other statistics, and must be used by 180any code that accesses that data. This is the clock that drives 181scheduling. This level is identical to 182.Fn splclock 183if there is no separate statistics clock. 184.It Fn splvm 185blocks hard interrupts from all devices that are allowed to use the 186kernel 187.Xr malloc 9 , 188or any virtual memory operations. 189That includes all disk, network, and tty device interrupts. The 190temptation to abuse the semantics of 191.Fn splvm 192should be avoided; if you feel as if you need to block more than 193one class of interrupts at a time, use software interrupts instead. 194.It Fn spltty 195blocks hard and soft interrupts from TTY devices (IPL_TTY). This 196must also block soft serial interrupts. 197.It Fn splsoftserial 198blocks soft interrupts generated by serial devices (IPL_SOFTSERIAL). 199.It Fn splnet 200blocks hard interrupts from network interfaces (IPL_NET). 201.It Fn splbio 202blocks hard interrupts from disks and other mass-storage 203devices (IPL_BIO). 204.It Fn splsoftnet 205blocks soft network interrupts (IPL_SOFTNET). Soft interrupts blocked 206by this priority are also blocked by all of the priorities listed 207above. 208.It Fn splsoftclock 209blocks soft clock interrupts. This is the priority at which the 210.Xr callout 9 211facility runs. Soft interrupts blocked by this priority are also blocked 212by all of the priorities listed above. In particular, 213.Fn splsoftnet 214must be a higher priority than 215.Fn splsoftclock . 216.El 217.Pp 218Two functions lower the system priority level. They are: 219.Bl -tag -width spllowersoftclockXX 220.It Fn spllowersoftclock 221unblocks all interrupts but the soft clock interrupt. 222.It Fn spl0 223unblocks all interrupts. 224.El 225.Pp 226The 227.Fn splx 228function restores the system priority level to the one encoded in 229.Fa s , 230which must be a value previously returned by one of the other 231.Nm 232functions. 233.Pp 234Note that the functions which lower the system priority level 235.Po 236.Fn spllowersoftclock , 237.Fn spl0 , 238and 239.Fn splx 240.Pc 241do not return a value. They should only be used 242in places where the system priority level is being decreased 243permanently. It is inappropriate to attempt to use them where the 244system priority level is being decreased temporarily, and would 245need to be restored to a previous value before continuing. 246.Sh HISTORY 247Originally, 248.Fn splsoftclock 249lowered the system priority level. 250During the 251.Nx 1.5 252development cycle, 253.Fn spllowersoftclock 254was introduced and the semantics of 255.Fn splsoftclock 256were changed. 257.Pp 258The 259.Fn splimp 260call was removed from the kernel between 261.Nx 1.5 262and 263.Nx 1.6 . 264The function of 265.Fn splimp 266was replaced by 267.Fn splvm 268and code which abused the semantics of 269.Fn splimp 270was changed to not mix interrupt priority levels. 271