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