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