summaryrefslogtreecommitdiff
path: root/share/man/man9/spl.9
blob: 0b3bb1628ab7a22fc6a72aad6d4b6ad7fc5936d6 (plain)
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
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
.\"	$OpenBSD: spl.9,v 1.16 2003/05/29 14:39:06 ho Exp $
.\"	$NetBSD: spl.9,v 1.1 1997/03/11 06:15:05 mikel Exp $
.\"
.\" Copyright (c) 1997 Michael Long.
.\" Copyright (c) 1997 Jonathan Stone.
.\" 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.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by Michael Long.
.\" 4. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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.
.\"
.Dd March 11, 1997
.Dt SPL 9
.Os
.Sh NAME
.Nm spl
.Nd modify system interrupt priority level
.Sh SYNOPSIS
.Fd #include <machine/intr.h>
.Ft int
.Fn splhigh void
.Ft int
.Fn splserial void
.Ft int
.Fn splsched void
.Ft int
.Fn splclock void
.Ft int
.Fn splstatclock void
.Ft int
.Fn splvm void
.Ft int
.Fn spltty void
.Ft int
.Fn splsofttty void
.Ft int
.Fn splnet void
.Ft int
.Fn splbio void
.Ft int
.Fn splsoftnet void
.Ft int
.Fn splsoftclock void
.Ft int
.Fn spllowersoftclock void
.Ft int
.Fn spl0 void
.Ft void
.Fn splx "int s"
.Ft void
.Fn splassert "int s"
.Sh DESCRIPTION
These functions raise and lower the system priority level.
They are used by kernel code to block interrupts with priority less
than or equal to the named level (i.e.,
.Fn spltty
blocks interrupts of priority less than or equal to
.Dv IPL_TTY ) .
The code may then safely access variables and data structures which
are used by kernel code that runs at an equal or lower priority level.
.Pp
A
.Nm
function exists for each distinct priority level which can exist in
the system.
These macros and the corresponding priority levels are
used for various defined purposes, and may be divided into two main
types: hard and soft.
Hard interrupts are generated by hardware
devices, while soft interrupts are generated by callouts and called
from the kernel's periodic timer interrupt service routine.
.Pp
In order of highest to lowest priority, the priority-raising macros
are:
.Bl -tag -width splsoftclockXX
.It Fn splhigh
blocks all hard and soft interrupts.
It is used for code that cannot
tolerate any interrupts, like hardware context switching code and the
.Xr ddb 4
in-kernel debugger.
.It Fn splserial
blocks hard interrupts from serial interfaces.
Code running at this level may not access the tty subsystem.
.It Fn splsched
blocks interrupts that may access scheduler data structures.
Code running at or above this level may not call
.Fn sleep ,
.Fn tsleep ,
or
.Fn wakeup ,
nor may it post signals.
Note that "running" means invoked by an interrupt handler that
operates at this level or higher.
Kernel code that operates in the context of a process and has called
.Fn splhigh
for blocking purposes can use
.Fn sleep ,
.Fn tsleep ,
or
.Fn wakeup .
.It Fn splclock
blocks the hardware clock interrupt.
It is used by
.Fn hardclock
to update kernel and process times, and must be used by any other code
that accesses time-related data.
.It Fn splstatclock
blocks the hardware statistics clock interrupt.
It is used by
.Fn statclock
to update kernel profiling and other statistics, and must be used by
any code that accesses that data.
This level is identical to
.Fn splclock
if there is no separate statistics clock.
.It Fn splvm
blocks hard interrupts from all devices that are allowed to use the
kernel
.Xr malloc 9 .
That includes all disk, network, and tty device interrupts.
.It Fn spltty
blocks hard interrupts from TTY devices.
.It Fn splsofttty
blocks soft interrupts generated by serial devices.
.It Fn splnet
blocks hard interrupts from network interfaces.
.It Fn splbio
blocks hard interrupts from disks and other mass-storage devices.
.It Fn splsoftnet
blocks soft network interrupts.
.It Fn splsoftclock
blocks soft clock interrupts.
.El
.Pp
Two macros lower the system priority level.
They are:
.Bl -tag -width spllowersoftclockXX
.It Fn spllowersoftclock
unblocks all interrupts but the soft clock interrupt.
.It Fn spl0
unblocks all interrupts.
.El
.Pp
The
.Fn splx
macro restores the system priority level to the one encoded in
.Fa s ,
which must be a value previously returned by one of the other
.Nm
macros.
.Pp
The
.Fn splassert
function checks that the system is running at a certain priority level.
The argument
.Fa s
should be one of these constants:
.Pp
.Bl -tag -width IPL_SOFTCLOCKXX -compact -offset indent
.It Dv IPL_STATCLOCK
.It Dv IPL_CLOCK
.It Dv IPL_VM
.It Dv IPL_BIO
.It Dv IPL_TTY
.It Dv IPL_NET
.It Dv IPL_SOFTNET
.It Dv IPL_SOFTCLOCK
.It Dv IPL_NONE
.El
.Pp
The
.Fn splassert
function is optional and is not necessarily implemented on
all architectures nor enabled in all kernel configurations.
It checks the current system priority level to see if it's
at least at the level specified in the argument
.Fa s .
If possible, it also checks if it hasn't been called from an
interrupt handler with a level higher than the one requested, which
must be an error (if some code is protected from
.Dv IPL_SOFTNET
interrupts, but accessed from an
.Dv IPL_NET
interrupt, it must be a design error in the code).
.Pp
The behavior of the
.Fn splassert
function is controlled by the kern.splassert
.Xr sysctl 8 .
Valid values for it are:
.Pp
.Bl -tag -width 1nr -compact -offset indent
.It 0
disable error checking
.It 1
print a message if an error is detected
.It 2
print a message and a stack trace if possible
.It 3
like 2 but also drop into the kernel debugger
.El
.Pp
Any other value causes a system panic on errors.