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