xref: /netbsd-src/share/man/man9/spl.9 (revision 1ad9454efb13a65cd7535ccf867508cb14d9d30e)
1.\"	$NetBSD: spl.9,v 1.24 2006/09/23 11:25:47 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 September 23, 2006
31.Dt SPL 9
32.Os
33.Sh NAME
34.Nm spl ,
35.Nm spl0 ,
36.Nm splaudio ,
37.Nm splbio ,
38.Nm splclock ,
39.Nm splhigh ,
40.Nm splvm ,
41.Nm spllock ,
42.Nm spllowersoftclock ,
43.Nm splnet ,
44.Nm splsched ,
45.Nm splserial ,
46.Nm splsoftclock ,
47.Nm splsoftnet ,
48.Nm splsoftserial ,
49.Nm splstatclock ,
50.Nm spltty ,
51.Nm splvm ,
52.Nm splx
53.Nd modify system interrupt priority level
54.Sh SYNOPSIS
55.In sys/param.h
56.Ft int
57.Fn splaudio void
58.Ft int
59.Fn splhigh void
60.Ft int
61.Fn spllock void
62.Ft int
63.Fn splserial void
64.Ft int
65.Fn splsched void
66.Ft int
67.Fn splclock void
68.Ft int
69.Fn splstatclock void
70.Ft int
71.Fn splvm void
72.Ft int
73.Fn spltty void
74.Ft int
75.Fn splsoftserial void
76.Ft int
77.Fn splnet void
78.Ft int
79.Fn splbio void
80.Ft int
81.Fn splsoftnet void
82.Ft int
83.Fn splsoftclock void
84.Ft void
85.Fn spllowersoftclock void
86.Ft void
87.Fn spl0 void
88.Ft void
89.Fn splx "int s"
90.Sh DESCRIPTION
91These functions raise and lower the system priority level.
92They are used by kernel code to block interrupts in critical
93sections, in order to protect data structures (much like
94a locking primitive) or to ensure uninterrupted access to
95hardware devices which are sensitive to timing.
96.Pp
97Interrupt priorities are not arranged in a strict hierarchy, although
98interrupt hardware sometimes is.
99For this reason the priorities listed here are arranged from
100.Dq highest
101to
102.Dq lowest .
103In other words, if a platform's hardware interrupts are arranged in
104a hierarchical manner, a priority level should also block all of the
105levels listed below it.
106.Pp
107Note that a strict hierarchy is not required.
108For example,
109.Fn splnet
110is not required to block disk controller interrupts, as they
111do not access the same data structures.
112However, the priorities are presented as a hierarchy in order to
113minimize data loss due to blocked interrupts, or interrupts not being
114serviced in a timely fashion.
115.Pp
116A
117.Nm
118function exists for each distinct priority level which can exist in
119the system, as well as for some special priority levels that are
120designed to be used in conjunction with multiprocessor-safe locking
121primitives.
122These levels may be divided into two main types: hard and soft.
123Hard interrupts are generated by hardware devices.
124Soft interrupts are a way of deferring hardware interrupts to do more
125expensive processing at a lower interrupt priority, and are explicitly
126scheduled by the higher-level interrupt handler.
127The most common use of this is in the networking code, where network
128interface drivers defer the more expensive TCP/IP processing in order
129to avoid dropping additional incoming packets.
130Software interrupts are further described by
131.Xr softintr 9 .
132.Pp
133In order of highest to lowest priority, the priority-raising functions
134are:
135.Bl -tag -width splsoftserialXX
136.It Fn splhigh
137blocks all hard and soft interrupts.
138It is used for code that cannot tolerate any interrupts, like hardware
139context switching code and the
140.Xr ddb 4
141in-kernel debugger.
142.It Fn spllock
143blocks all hard and soft interrupts that can acquire a simple lock.
144This is provided as a distinct level from
145.Fn splhigh
146as some platforms may need to make use of extremely high priority
147interrupts while locks are spinning, which would be blocked by
148.Fn splhigh .
149.It Fn splserial
150blocks hard interrupts from serial interfaces (IPL_SERIAL).
151Code running at this level may not access the tty subsystem.
152Generally, all code run at this level must schedule additional
153processing to run in a software interrupt.
154Note that code running at this priority is not blocked by
155.Fn splvm
156(described below), and is therefore prohibited from using the
157kernel memory allocators.
158.It Fn splsched
159blocks all hard and soft interrupts that may access scheduler data
160structures.
161Code running at or above this level may not call
162.Fn sleep ,
163.Fn tsleep ,
164.Fn ltsleep ,
165or
166.Fn wakeup ,
167nor may it post signals.
168.It Fn splclock
169blocks the hardware clock interrupt.
170It is used by
171.Fn hardclock
172to update kernel and process times, and must be used by any other code
173that accesses time-related data, specifically the
174.Va time
175and
176.Va mono_time
177global variables.
178This level also protects the
179.Xr callout 9
180data structures, and nothing running at or above this level may
181schedule, cancel, or otherwise access any callout-related data
182structures.
183.It Fn splstatclock
184blocks the hardware statistics clock interrupt.
185It is used by
186.Fn statclock
187to update kernel profiling and other statistics, and must be used by
188any code that accesses that data.
189This is the clock that drives scheduling.
190This level is identical to
191.Fn splclock
192if there is no separate statistics clock.
193.It Fn splvm
194blocks hard interrupts from all devices that are allowed to use the
195kernel
196.Xr malloc 9 ,
197or any virtual memory operations.
198That includes all disk, network, and tty device interrupts.
199The temptation to abuse the semantics of
200.Fn splvm
201should be avoided; if you feel as if you need to block more than
202one class of interrupts at a time, use software interrupts instead.
203.It Fn spltty
204blocks hard and soft interrupts from TTY devices (IPL_TTY).
205This must also block soft serial interrupts.
206.It Fn splaudio
207blocks hard interrupts generated by audio devices (IPL_AUDIO).
208.It Fn splsoftserial
209blocks soft interrupts generated by serial devices (IPL_SOFTSERIAL).
210.It Fn splnet
211blocks hard interrupts from network interfaces (IPL_NET).
212.It Fn splbio
213blocks hard interrupts from disks and other mass-storage
214devices (IPL_BIO).
215.It Fn splsoftnet
216blocks soft network interrupts (IPL_SOFTNET).
217Soft interrupts blocked by this priority are also blocked by all
218of the priorities listed above.
219.It Fn splsoftclock
220blocks soft clock interrupts.
221This is the priority at which the
222.Xr callout 9
223facility runs.
224Soft interrupts blocked by this priority are also blocked by all
225of the priorities listed above.
226In particular,
227.Fn splsoftnet
228must be a higher priority than
229.Fn splsoftclock .
230.El
231.Pp
232Two functions lower the system priority level.
233They are:
234.Bl -tag -width spllowersoftclockXX
235.It Fn spllowersoftclock
236unblocks all interrupts but the soft clock interrupt.
237.It Fn spl0
238unblocks all interrupts.
239.El
240.Pp
241The
242.Fn splx
243function restores the system priority level to the one encoded in
244.Fa s ,
245which must be a value previously returned by one of the other
246.Nm
247functions.
248.Pp
249Note that the functions which lower the system priority level
250.Po
251.Fn spllowersoftclock ,
252.Fn spl0 ,
253and
254.Fn splx
255.Pc
256do not return a value.
257They should only be used in places where the system priority level
258is being decreased permanently.
259It is inappropriate to attempt to use them where the
260system priority level is being decreased temporarily, and would
261need to be restored to a previous value before continuing.
262.Sh HISTORY
263In
264.Bx 4.4 ,
265.Fn splnet
266was used to block network software interrupts.
267Most device drivers used
268.Fn splimp
269to block hardware interrupts.
270To avoid unnecessarily blocking other interrupts, in
271.Nx 1.1
272a new function was added that blocks only network hardware interrupts.
273For consistency with other
274.Nm
275functions, the old
276.Fn splnet
277function was renamed to
278.Fn splsoftnet ,
279and the new function was named
280.Fn splnet .
281.Pp
282Originally,
283.Fn splsoftclock
284lowered the system priority level.
285During the
286.Nx 1.5
287development cycle,
288.Fn spllowersoftclock
289was introduced and the semantics of
290.Fn splsoftclock
291were changed.
292.Pp
293The
294.Fn splimp
295call was removed from the kernel between
296.Nx 1.5
297and
298.Nx 1.6 .
299The function of
300.Fn splimp
301was replaced by
302.Fn splvm
303and code which abused the semantics of
304.Fn splimp
305was changed to not mix interrupt priority levels.
306