1.\" $NetBSD: spl.9,v 1.32 2008/02/13 16:00:18 skrll 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 13, 2008 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 interupt 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 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 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 'low' priority hardware interrupts, such 152as interrupts from network, block I/O and tty devices. 153.Pp 154Code running at this level endures the same restrictions as at IPL_SCHED, 155but may use the deprecated 156.Xr malloc 9 157or endorsed 158.Xr pool_cache 9 159interfaces to allocate memory. 160.Pp 161At the time of writing, the global 162.Dv kernel_lock 163is automatically acquired for interrupts at this level, in order to 164support device drivers that do not provide their own multiprocessor 165synchronization. 166A future release of the system may allow the automatic acquisition of 167.Dv kernel_lock 168to be disabled for individual interrupt handlers. 169.It Fn splsoftserial , IPL_SOFTSERIAL 170.Pp 171Blocks soft interrupts at the IPL_SOFTSERIAL symbolic level. 172.Pp 173This is the first of the software levels. 174Soft interrupts at this level and lower may acquire reader/writer 175locks or adaptive mutexes. 176.It Fn splsoftnet , IPL_SOFTNET 177.Pp 178Blocks soft interrupts at the IPL_SOFTNET symbolic level. 179.It Fn splsoftbio , IPL_SOFTBIO 180.Pp 181Blocks soft interrupts at the IPL_SOFTBIO symbolic level. 182.It Fn splsoftclock , IPL_SOFTCLOCK 183.Pp 184Blocks soft interrupts at the IPL_SOFTCLOCK symbolic level. 185.Pp 186This is the priority at which callbacks generated by the 187.Xr callout 9 188facility runs. 189.El 190.Pp 191One function lowers the system priority level: 192.Bl -tag -width splsoft 193.It Fn spl0 , IPL_NONE 194.Pp 195Unblocks all interrupts. 196This should rarely be used directly; 197.Fn splx 198should be used instead. 199.El 200.Pp 201The 202.Fn splx 203function restores the system priority level to the one encoded in 204.Fa s , 205which must be a value previously returned by one of the other 206.Nm 207functions. 208.Sh SEE ALSO 209.Xr condvar 9 , 210.Xr mutex 9 , 211.Xr rwlock 9 212.Sh HISTORY 213In 214.Bx 4.4 , 215.Fn splnet 216was used to block network software interrupts. 217Most device drivers used 218.Fn splimp 219to block hardware interrupts. 220To avoid unnecessarily blocking other interrupts, in 221.Nx 1.1 222a new function was added that blocks only network hardware interrupts. 223For consistency with other 224.Nm 225functions, the old 226.Fn splnet 227function was renamed to 228.Fn splsoftnet , 229and the new function was named 230.Fn splnet . 231.Pp 232Originally, 233.Fn splsoftclock 234lowered the system priority level. 235During the 236.Nx 1.5 237development cycle, 238.Fn spllowersoftclock 239was introduced and the semantics of 240.Fn splsoftclock 241were changed. 242.Pp 243The 244.Fn splimp 245call was removed from the kernel between 246.Nx 1.5 247and 248.Nx 1.6 . 249The function of 250.Fn splimp 251was replaced by 252.Fn splvm 253and code which abused the semantics of 254.Fn splimp 255was changed to not mix interrupt priority levels. 256.Pp 257Between 258.Nx 4.0 259and 260.Nx 5.0 , 261the hardware levels were reduced in number and a strict hierarchy 262defined. 263