2 .\" Copyright (c) 1996 Joerg Wunsch
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
44 .Nd manipulate interrupt priorities
59 .Fn splsoftclock "void"
63 .Fn splstatclock "void"
69 .Fn splx "intrmask_t ipl"
72 This API is deprecated.
73 Use mutexes to protect data structures instead.
77 The API is now a complete NOP.
78 This man page documents historical behavior so you can understand the
79 code locking that the spl did when converting code from versions of the
82 The examples in this man page are also obsolete and should not be viewed
90 function family sets the interrupt priority
93 This prevents interrupt handlers of the blocked priority level from
97 part of a driver (the part that runs on behalf of the user process) to
98 examine or modify data areas that might be examined or modified by
101 Each driver that uses interrupts is normally assigned to an interrupt
102 priority group by a keyword in its config line.
104 .Bd -literal -offset indent
105 device foo0 at isa? port 0x0815 irq 12 tty
108 assigns interrupt 12 to the
111 The system automatically arranges for interrupts in
114 group to be called at a priority >=
120 sets the interrupt priority to an absolute value.
122 the value returned by the other functions should be saved in a local
123 variable, and later passed to
125 in order to restore the previous priority.
129 lowers the priority to a value where all interrupt handlers are
130 unblocked, but ASTs (asynchronous system traps) remain blocked until
131 the system is about to return to user mode.
133 The traditional assignment of the various device drivers to the
134 interrupt priority groups can be roughly classified as:
137 Software part of the network interface drivers.
139 All network interface drivers.
143 (i.e., disk and the like) drivers.
145 Basically, all non-network communications devices, but effectively
146 used for all drivers that are neither network nor disks.
153 return the previous priority value.
155 This is a typical example demonstrating the usage:
168 struct foo_softc *sc;
173 if (!(sc->flags & FOO_READY)) {
174 /* Not ready, must sleep on resource. */
175 sc->flags |= FOO_ASLEEP;
176 error = tsleep(sc, PZERO, "foordy", 0);
177 sc->flags &= ~FOO_ASLEEP;
179 sc->flags &= ~FOO_READY;
188 struct foo_softc *sc;
191 sc->flags |= FOO_READY;
192 if (sc->flags & FOO_ASLEEP)
193 /* Somebody was waiting for us, awake him. */
199 Note that the interrupt handler should
201 reduce the priority level.
202 It is automatically called as it had
203 raised the interrupt priority to its own level, i.e., further interrupts
204 of the same group are being blocked.
206 The interrupt priority levels appeared in a very early version of
208 They have been traditionally known by number instead of by
209 names, and were inclusive up to higher priority levels (i.e., priority
210 5 has been blocking everything up to level 5).
211 This is no longer the case in
215 for them is still reflected in the letter
217 of the respective functions and variables, although they are not
218 really levels anymore, but rather different (partially inclusive)
219 sets of functions to be blocked during some periods of the life of
221 The historical number scheme can be considered as a
222 simple linearly ordered set of interrupt priority groups.
224 .Fx 5.0 eliminated spl entirely in favor of locking primitives which scale
225 to more than one processor.
227 This manual page was written by