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