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