1.\" $NetBSD: spl.9,v 1.42 2020/04/07 07:25:09 jdolecek 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 7, 2020 31.Dt SPL 9 32.Os 33.Sh NAME 34.Nm spl , 35.Nm spl0 , 36.Nm splhigh , 37.Nm splvm , 38.Nm splbio , 39.Nm splnet , 40.Nm spltty , 41.Nm splsched , 42.Nm splsoftbio , 43.Nm splsoftclock , 44.Nm splsoftnet , 45.Nm splsoftserial , 46.Nm splx 47.Nd modify system interrupt priority level 48.Sh SYNOPSIS 49.In sys/intr.h 50.Ft void 51.Fn spl0 void 52.Ft int 53.Fn splhigh void 54.Ft int 55.Fn splsched void 56.Ft int 57.Fn splvm void 58.Ft int 59.Fn splbio void 60.Ft int 61.Fn splnet void 62.Ft int 63.Fn spltty void 64.Ft int 65.Fn splsoftbio void 66.Ft int 67.Fn splsoftclock void 68.Ft int 69.Fn splsoftserial void 70.Ft int 71.Fn splsoftnet void 72.Ft void 73.Fn splx "int s" 74.Sh DESCRIPTION 75These functions raise and lower the interrupt priority level. 76They are used by kernel code to block interrupts in critical 77sections, in order to protect data structures. 78.Pp 79In a multi-CPU system, these functions change the interrupt 80priority level on the local CPU only. 81In general, device drivers should not make use of these interfaces. 82To ensure correct synchronization, device drivers should use the 83.Xr condvar 9 , 84.Xr mutex 9 , 85and 86.Xr rwlock 9 87interfaces. 88.Pp 89Interrupt priorities are arranged in a strict hierarchy, although 90sometimes levels may be equivalent (overlap). 91The hierarchy means that raising the IPL to any level will block 92interrupts at that level, and at all lower levels. 93The hierarchy is used to minimize data loss due to interrupts not 94being serviced in a timely fashion. 95.Pp 96The levels may be divided into two groups: hard and soft. 97Hard interrupts are generated by hardware devices. 98Soft interrupts are a way of deferring hardware interrupts to do more 99expensive processing at a lower interrupt priority, and are explicitly 100scheduled by the higher-level interrupt handler. 101Software interrupts are further described by 102.Xr softint 9 . 103.Pp 104Note that hard interrupt handlers do not possess process (thread) context 105and so it is not valid to use kernel facilities that may attempt to sleep 106from a hardware interrupt. 107For example, it is not possible to acquire a reader/writer lock from 108a hardware interrupt. 109Soft interrupt handlers possess limited process context and so may sleep 110briefly in order to acquire a reader/writer lock or adaptive mutex, 111but may not sleep for any other reason. 112.Pp 113In order of highest to lowest priority, the priority-raising functions 114along with their counterpart symbolic tags are: 115.Bl -tag -width splsoft 116.It Fn splhigh , IPL_HIGH 117.Pp 118Blocks all hard and soft interrupts, including the highest level I/O 119interrupts, such as interrupts from serial interfaces and the 120statistics clock (if any). 121It is also used for code that cannot tolerate any interrupts. 122.Pp 123Code running at this level may not (in general) directly access 124machine independent kernel services. 125For example, it is illegal to call the kernel 126.Fn printf 127function or to try and allocate memory. 128The methods of synchronization available are: spin mutexes and 129scheduling a soft interrupt. 130Generally, all code run at this level must schedule additional 131processing to run in a software interrupt. 132.Pp 133Code with thread context running at this level must not use a kernel 134interface that may cause the current LWP to sleep, such as the 135.Xr condvar 9 136interfaces. 137.Pp 138Interrupt handlers at this level cannot acquire the global kernel_lock 139and so must be coded to ensure correct synchronization on multiprocessor 140systems. 141.It Fn splsched , IPL_SCHED 142.Pp 143Blocks all medium priority hardware interrupts, such as interrupts 144from audio devices, and the clock interrupt. 145.Pp 146Interrupt handlers running at this level endure the same restrictions as 147at IPL_HIGH, but may access scheduler interfaces, and so may awaken LWPs 148(light weight processes) using the 149.Xr condvar 9 150interfaces, and may schedule callouts using the 151.Xr callout 9 152interfaces. 153.Pp 154Code with thread context running at this level may sleep via the 155.Xr condvar 9 156interfaces, and may use other kernel facilities that could cause the 157current LWP to sleep. 158.It Fn splvm , IPL_VM 159.Pp 160Blocks hard interrupts from 161.Dq low 162priority hardware interrupts, such 163as interrupts from network, block I/O and tty devices. 164.Pp 165Code running at this level endures the same restrictions as at IPL_SCHED, 166but may use the deprecated 167.Xr malloc 9 168or endorsed 169.Xr pool_cache 9 170interfaces to allocate memory. 171.Pp 172The global 173.Dv kernel_lock 174is automatically acquired for interrupts at this level by default, 175in order to 176support device drivers that do not provide their own multiprocessor 177synchronization. 178The automatic acquisition of 179.Dv kernel_lock 180can be disabled for individual interrupt handlers by device drivers 181if supported by subsystem, see e.g. 182.Xr pci_intr_establish 9 . 183.Pp 184.Fn splbio , 185.Fn splnet , 186and 187.Fn spltty 188are synonyms for 189.Fn splvm . 190Their use is deprecated; all new code should use 191.Fn splvm . 192.It Fn splsoftserial , IPL_SOFTSERIAL 193.Pp 194Blocks soft interrupts at the IPL_SOFTSERIAL symbolic level. 195.Pp 196This is the first of the software levels. 197Soft interrupts at this level and lower may acquire reader/writer 198locks or adaptive mutexes. 199.It Fn splsoftnet , IPL_SOFTNET 200.Pp 201Blocks soft interrupts at the IPL_SOFTNET symbolic level. 202.It Fn splsoftbio , IPL_SOFTBIO 203.Pp 204Blocks soft interrupts at the IPL_SOFTBIO symbolic level. 205.It Fn splsoftclock , IPL_SOFTCLOCK 206.Pp 207Blocks soft interrupts at the IPL_SOFTCLOCK symbolic level. 208.Pp 209This is the priority at which callbacks generated by the 210.Xr callout 9 211facility runs. 212.El 213.Pp 214One function lowers the system priority level: 215.Bl -tag -width splsoft 216.It Fn spl0 , IPL_NONE 217.Pp 218Unblocks all interrupts. 219This should rarely be used directly; 220.Fn splx 221should be used instead. 222.El 223.Pp 224The 225.Fn splx 226function restores the system priority level to the one encoded in 227.Fa s , 228which must be a value previously returned by one of the other 229.Nm 230functions. 231.Sh SEE ALSO 232.Xr condvar 9 , 233.Xr i386/splraise 9 , 234.Xr kpreempt 9 , 235.Xr mutex 9 , 236.Xr rwlock 9 237.Sh HISTORY 238In 239.Bx 4.4 , 240.Fn splnet 241was used to block network software interrupts. 242Most device drivers used 243.Fn splimp 244to block hardware interrupts. 245To avoid unnecessarily blocking other interrupts, in 246.Nx 1.1 247a new function was added that blocks only network hardware interrupts. 248For consistency with other 249.Nm 250functions, the old 251.Fn splnet 252function was renamed to 253.Fn splsoftnet , 254and the new function was named 255.Fn splnet . 256.Pp 257Originally, 258.Fn splsoftclock 259lowered the system priority level. 260During the 261.Nx 1.5 262development cycle, 263.Fn spllowersoftclock 264was introduced and the semantics of 265.Fn splsoftclock 266were changed. 267.Pp 268The 269.Fn splimp 270call was removed from the kernel between 271.Nx 1.5 272and 273.Nx 1.6 . 274The function of 275.Fn splimp 276was replaced by 277.Fn splvm 278and code which abused the semantics of 279.Fn splimp 280was changed to not mix interrupt priority levels. 281.Pp 282Between 283.Nx 4.0 284and 285.Nx 5.0 , 286the hardware levels were reduced in number and a strict hierarchy 287defined. 288