Cleanup remaining tsleep priority issues.
[dragonfly.git] / share / man / man9 / spl.9
CommitLineData
984263bc
MD
1.\"
2.\" Copyright (c) 1996 Joerg Wunsch
3.\"
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
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.
14.\"
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.
25.\"
26.\" $FreeBSD: src/share/man/man9/spl.9,v 1.8.2.5 2001/12/17 11:30:19 ru Exp $
2f65cd66 27.\" $DragonFly: src/share/man/man9/Attic/spl.9,v 1.3 2003/08/01 17:46:25 dillon Exp $
984263bc
MD
28.\"
29.Dd July 21, 1996
30.Os
31.Dt SPL 9
32.Sh NAME
33.Nm splbio ,
34.Nm splclock ,
35.Nm splhigh ,
36.Nm splimp ,
37.Nm splnet ,
38.Nm splsoftclock ,
39.Nm splsofttty ,
40.Nm splstatclock ,
41.Nm spltty ,
42.Nm splvm ,
43.Nm spl0 ,
44.Nm splx
45.Nd manipulate interrupt priorities
46.Sh SYNOPSIS
47.In sys/types.h
48.In sys/systm.h
49.Ft intrmask_t
50.Fn splbio "void"
51.Ft intrmask_t
52.Fn splclock "void"
53.Ft intrmask_t
54.Fn splhigh "void"
55.Ft intrmask_t
56.Fn splimp "void"
57.Ft intrmask_t
58.Fn splnet "void"
59.Ft intrmask_t
60.Fn splsoftclock "void"
61.Ft intrmask_t
62.Fn splsofttty "void"
63.Ft intrmask_t
64.Fn splstatclock "void"
65.Ft intrmask_t
66.Fn spltty "void"
67.Ft void
68.Fn spl0 "void"
69.Ft void
70.Fn splx "intrmask_t ipl"
71.Sh DESCRIPTION
72The
73.Fn spl
74function family sets the interrupt priority
75.Dq level
76of the CPU.
77This prevents interrupt handlers of the blocked priority level from
78being run. This is used in the
79.Dq synchronous
80part of a driver (the part that runs on behalf of the user process) to
81examine or modify data areas that might be examined or modified by
82interrupt handlers.
83.Pp
84Each driver that uses interrupts is normally assigned to an interrupt
85priority group by a keyword in its config line.
86For example:
87.Bd -literal -offset indent
88device foo0 at isa? port 0x0815 irq 12 tty
89.Ed
90.Pp
91assigns interrupt 12 to the
92.Dq tty
93priority group. The system automatically arranges for interrupts in
94the
95.Em xxx
96group to be called at a priority >=
97.Ns spl Ns Em xxx
98\&().
99.Pp
100The function
101.Fn splx
102sets the interrupt priority to an absolute value. The intent is that
103the value returned by the other functions should be saved in a local
104variable, and later passed to
105.Fn splx
106in order to restore the previous priority.
107.Pp
108The function
109.Fn spl0
110lowers the priority to a value where all interrupt handlers are
111unblocked, but ASTs (asynchronous system traps) remain blocked until
112the system is about to return to user mode.
113.Pp
114The traditional assignment of the various device drivers to the
115interrupt priority groups can be roughly classified as:
116.Bl -tag -width Fn
117.It Fn splnet
118All network interface drivers.
119.It Fn splbio
120All
121.Em buffered IO
122(i.e., disk and the like) drivers.
123.It Fn spltty
124Basically, all non-network communications devices, but effectively
125used for all drivers that are neither network nor disks.
126.El
127.Sh RETURN VALUES
128All functions except
129.Fn splx
130and
131.Fn spl0
132return the previous priority value.
133.Sh EXAMPLES
134This is a typical example demonstrating the usage:
135.Bd -literal
136struct foo_softc {
137 ...
138 int flags;
139#define FOO_ASLEEP 1
140#define FOO_READY 2
141
142} foo_softc[NFOO];
143
144int
145foowrite(...)
146{
147 struct foo_softc *sc;
148 int s, error;
149
150 ...
151 s = spltty();
152 if (!(sc->flags & FOO_READY)) {
153 /* Not ready, must sleep on resource. */
154 sc->flags |= FOO_ASLEEP;
2f65cd66 155 error = tsleep(sc, 0, "foordy", 0);
984263bc
MD
156 sc->flags &= ~FOO_ASLEEP;
157 }
158 sc->flags &= ~FOO_READY;
159 splx(s);
160
161 ...
162}
163
164void
165foointr(...)
166{
167 struct foo_softc *sc;
168
169 ...
170 sc->flags |= FOO_READY;
171 if (sc->flags & FOO_ASLEEP)
172 /* Somebody was waiting for us, awake him. */
173 wakeup(sc);
174 ...
175}
176
177.Ed
178Note that the interrupt handler should
179.Em never
180reduce the priority level. It is automatically called as it had
181raised the interrupt priority to its own level, i.e. further interrupts
182of the same group are being blocked.
183.Sh HISTORY
184The interrupt priority levels appeared in a very early version of
185Unix. They have been traditionally known by number instead of by
186names, and were inclusive up to higher priority levels (i.e., priority
1875 has been blocking everything up to level 5). This is no longer the
188case in
189.Fx .
190The traditional name
191.Ql level
192for them is still reflected in the letter
193.Ql l
194of the respective functions and variables, although they are not
195really levels anymore, but rather different (partially inclusive)
196sets of functions to be blocked during some periods of the life of
197the system. The historical number scheme can be considered as a
198simple linearly ordered set of interrupt priority groups.
199.Sh AUTHORS
200This man page was written by
201.An J\(:org Wunsch .