1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
.\"
.\" Copyright (c) 1996 Joerg Wunsch
.\"
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $Id$
.\" "
.Dd July 21, 1996
.Os
.Dt SPL 9
.Sh NAME
.Nm splbio,
.Nm splclock,
.Nm splhigh,
.Nm splimp,
.Nm splnet,
.Nm splsoftclock,
.Nm splsofttty,
.Nm splstatclock,
.Nm spltty,
.Nm splvm,
.Nm spl0,
.Nm splx
.Nd manipulate interrupt priorities
.Sh SYNOPSIS
.Fd #include <sys/param.h>
.Fd #include <sys/systm.h>
.Ft int
.Fn splbio "void"
.Ft int
.Fn splclock "void"
.Ft int
.Fn splhigh "void"
.Ft int
.Fn splimp "void"
.Ft int
.Fn splnet "void"
.Ft int
.Fn splsoftclock "void"
.Ft int
.Fn splsofttty "void"
.Ft int
.Fn splstatclock "void"
.Ft int
.Fn spltty "void"
.Ft void
.Fn spl0 "void"
.Ft void
.Fn splx "int ipl"
.Sh DESCRIPTION
The
.Fn spl
function family sets the interrupt priority
.Dq level
of the CPU.
This prevents interrupt handlers of the blocked priority level from
being run. This is used in the
.Dq synchronous
part of a driver (the part that runs on behalf of the user process) to
examine or modify data areas that might be examined or modified by
interrupt handlers.
.Pp
Each driver that uses interrupts is normally assigned to an interrupt
priority group by a keyword in its config line.
For example:
.Bd -literal -offset indent
device foo0 at isa? port 0x0815 irq 12 tty vector foointr
.Ed
.Pp
assigns interrupt 12 to the
.Dq tty
priority group. The system automatically arranges for interrupts in
the
.Em xxx
group to be called at a priority >=
.Ns spl Ns Em xxx
\&().
.Pp
The function
.Fn splx
sets the interrupt priority to an absolute value. The intent is that
the value returned by the other functions should be saved in a local
variable, and later passed to
.Fn splx
in order to restore the previous priority.
.Pp
The function
.Fn spl0
lowers the priority to a value where all interrupt handlers are
unblocked, but ASTs (asynchronous system traps) remain blocked until
the system is about to return to user mode.
.Pp
The traditional assignment of the various device drivers to the
interrupt priority groups can be roughly classified as:
.Bl -tag -width Fn splnet
.It Fn splnet
All network interface drivers.
.It Fn splbio
All
.Em buffered IO
(i.e., disk and the like) drivers.
.It Fn spltty
Basically, all non-network communications devices, but effectively
used for all drivers that are neither network nor disks.
.El
.Sh RETURN VALUES
All functions except
.Fn splx
and
.Fn spl0
return the previous priority value.
.Sh EXAMPLES
This is a typical example demonstrating the usage:
.Bd -literal
struct foo_softc {
...
int flags;
#define FOO_ASLEEP 1
#define FOO_READY 2
} foo_softc[NFOO];
int
foowrite(...)
{
struct foo_softc *sc;
int s, error;
...
s = spltty();
if (!(sc->flags & FOO_READY)) {
/* Not ready, must sleep on resource. */
sc->flags |= FOO_ASLEEP;
error = tsleep(sc, PZERO, "foordy", 0);
sc->flags &= ~FOO_ASLEEP;
}
sc->flags &= ~FOO_READY;
splx(s);
...
}
void
foointr(...)
{
struct foo_softc *sc;
...
sc->flags |= FOO_READY;
if (sc->flags & FOO_ASLEEP)
/* Somebody was waiting for us, awake him. */
wakeup(sc);
...
}
.Ed
Note that the interrupt handler should
.Em never
reduce the priority level. It is automatically called as it had
raised the interrupt priority to its own level, i.e. further interrupts
of the same group are being blocked.
.Sh HISTORY
The interrupt priority levels appeared in a very early version of
Unix. They have been traditionally known by number instead of by
names, and were inclusive up to higher priority levels (i.e., priority
5 has been blocking everything up to level 5). This is no longer the
case in FreeBSD. The traditional name
.Ql level
for them is still reflected in the letter
.Ql l
of the respective functions and variables, although they are not
really levels anymore, but rather different (partially inclusive)
sets of functions to be blocked during some periods of the life of
the system. The historical number scheme can be considered as a
simple linearly ordered set of interrupt priority groups.
.Sh AUTHORS
This man page was written by
.ie t J\(:org Wunsch.
.el Joerg Wunsch.
|
