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