1.\" $NetBSD: spl.9,v 1.41 2017/04/06 03:00:13 pgoyette 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 6, 2017 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 172At the time of writing, the global 173.Dv kernel_lock 174is automatically acquired for interrupts at this level, in order to 175support device drivers that do not provide their own multiprocessor 176synchronization. 177A future release of the system may allow the automatic acquisition of 178.Dv kernel_lock 179to be disabled for individual interrupt handlers. 180.Pp 181.Fn splbio , 182.Fn splnet , 183and 184.Fn spltty 185are synonyms for 186.Fn splvm . 187Their use is deprecated; all new code should use 188.Fn splvm . 189.It Fn splsoftserial , IPL_SOFTSERIAL 190.Pp 191Blocks soft interrupts at the IPL_SOFTSERIAL symbolic level. 192.Pp 193This is the first of the software levels. 194Soft interrupts at this level and lower may acquire reader/writer 195locks or adaptive mutexes. 196.It Fn splsoftnet , IPL_SOFTNET 197.Pp 198Blocks soft interrupts at the IPL_SOFTNET symbolic level. 199.It Fn splsoftbio , IPL_SOFTBIO 200.Pp 201Blocks soft interrupts at the IPL_SOFTBIO symbolic level. 202.It Fn splsoftclock , IPL_SOFTCLOCK 203.Pp 204Blocks soft interrupts at the IPL_SOFTCLOCK symbolic level. 205.Pp 206This is the priority at which callbacks generated by the 207.Xr callout 9 208facility runs. 209.El 210.Pp 211One function lowers the system priority level: 212.Bl -tag -width splsoft 213.It Fn spl0 , IPL_NONE 214.Pp 215Unblocks all interrupts. 216This should rarely be used directly; 217.Fn splx 218should be used instead. 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.Sh SEE ALSO 229.Xr condvar 9 , 230.Xr i386/splraise 9 , 231.Xr kpreempt 9 , 232.Xr mutex 9 , 233.Xr rwlock 9 234.Sh HISTORY 235In 236.Bx 4.4 , 237.Fn splnet 238was used to block network software interrupts. 239Most device drivers used 240.Fn splimp 241to block hardware interrupts. 242To avoid unnecessarily blocking other interrupts, in 243.Nx 1.1 244a new function was added that blocks only network hardware interrupts. 245For consistency with other 246.Nm 247functions, the old 248.Fn splnet 249function was renamed to 250.Fn splsoftnet , 251and the new function was named 252.Fn splnet . 253.Pp 254Originally, 255.Fn splsoftclock 256lowered the system priority level. 257During the 258.Nx 1.5 259development cycle, 260.Fn spllowersoftclock 261was introduced and the semantics of 262.Fn splsoftclock 263were changed. 264.Pp 265The 266.Fn splimp 267call was removed from the kernel between 268.Nx 1.5 269and 270.Nx 1.6 . 271The function of 272.Fn splimp 273was replaced by 274.Fn splvm 275and code which abused the semantics of 276.Fn splimp 277was changed to not mix interrupt priority levels. 278.Pp 279Between 280.Nx 4.0 281and 282.Nx 5.0 , 283the hardware levels were reduced in number and a strict hierarchy 284defined. 285