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