/share/man/man9/spl.9

  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$
 27.\"
 28.Dd July 21, 1996
 29.Dt SPL 9
 30.Os
 31.Sh NAME
 32.Nm splbio ,
 33.Nm splclock ,
 34.Nm splhigh ,
 35.Nm splimp ,
 36.Nm splnet ,
 37.Nm splsoftclock ,
 38.Nm splsofttty ,
 39.Nm splstatclock ,
 40.Nm spltty ,
 41.Nm splvm ,
 42.Nm spl0 ,
 43.Nm splx
 44.Nd manipulate interrupt priorities
 45.Sh SYNOPSIS
 46.In sys/types.h
 47.In sys/systm.h
 48.Ft intrmask_t
 49.Fn splbio "void"
 50.Ft intrmask_t
 51.Fn splclock "void"
 52.Ft intrmask_t
 53.Fn splhigh "void"
 54.Ft intrmask_t
 55.Fn splimp "void"
 56.Ft intrmask_t
 57.Fn splnet "void"
 58.Ft intrmask_t
 59.Fn splsoftclock "void"
 60.Ft intrmask_t
 61.Fn splsofttty "void"
 62.Ft intrmask_t
 63.Fn splstatclock "void"
 64.Ft intrmask_t
 65.Fn spltty "void"
 66.Ft void
 67.Fn spl0 "void"
 68.Ft void
 69.Fn splx "intrmask_t ipl"
 70.Sh DESCRIPTION
 71.Bf -symbolic
 72This API is deprecated.
 73Use mutexes to protect data structures instead.
 74See
 75.Xr mutex 9
 76for more information.
 77The API is now a complete NOP.
 78This man page documents historical behavior so you can understand the
 79code locking that the spl did when converting code from versions of the
 80kernel prior to
 81.Fx 5.0 .
 82The examples in this man page are also obsolete and should not be viewed
 83as documenting
 84.Fx 5.0
 85and newer.
 86.Ef
 87.Pp
 88The
 89.Fn spl
 90function family sets the interrupt priority
 91.Dq level
 92of the CPU.
 93This prevents interrupt handlers of the blocked priority level from
 94being run.
 95This is used in the
 96.Dq synchronous
 97part of a driver (the part that runs on behalf of the user process) to
 98examine or modify data areas that might be examined or modified by
 99interrupt handlers.
100.Pp
101Each driver that uses interrupts is normally assigned to an interrupt
102priority group by a keyword in its config line.
103For example:
104.Bd -literal -offset indent
105device foo0 at isa? port 0x0815 irq 12 tty
106.Ed
107.Pp
108assigns interrupt 12 to the
109.Dq tty
110priority group.
111The system automatically arranges for interrupts in
112the
113.Em xxx
114group to be called at a priority >=
115.Em spl Ns Fn xxx
116.Pp
117The function
118.Fn splx
119sets the interrupt priority to an absolute value.
120The intent is that
121the value returned by the other functions should be saved in a local
122variable, and later passed to
123.Fn splx
124in order to restore the previous priority.
125.Pp
126The function
127.Fn spl0
128lowers the priority to a value where all interrupt handlers are
129unblocked, but ASTs (asynchronous system traps) remain blocked until
130the system is about to return to user mode.
131.Pp
132The traditional assignment of the various device drivers to the
133interrupt priority groups can be roughly classified as:
134.Bl -tag -width Fn
135.It Fn splnet
136Software part of the network interface drivers.
137.It Fn splimp
138All network interface drivers.
139.It Fn splbio
140All
141.Em buffered IO
142(i.e., disk and the like) drivers.
143.It Fn spltty
144Basically, all non-network communications devices, but effectively
145used for all drivers that are neither network nor disks.
146.El
147.Sh RETURN VALUES
148All functions except
149.Fn splx
150and
151.Fn spl0
152return the previous priority value.
153.Sh EXAMPLES
154This is a typical example demonstrating the usage:
155.Bd -literal
156struct foo_softc {
157	...
158	int flags;
159#define	FOO_ASLEEP	1
160#define	FOO_READY	2
161
162} foo_softc[NFOO];
163
164int
165foowrite(...)
166{
167	struct foo_softc *sc;
168	int s, error;
169
170	...
171	s = spltty();
172	if (!(sc->flags & FOO_READY)) {
173		/* Not ready, must sleep on resource. */
174		sc->flags |= FOO_ASLEEP;
175		error = tsleep(sc, PZERO, "foordy", 0);
176		sc->flags &= ~FOO_ASLEEP;
177	}
178	sc->flags &= ~FOO_READY;
179	splx(s);
180
181	...
182}
183
184void
185foointr(...)
186{
187	struct foo_softc *sc;
188
189	...
190	sc->flags |= FOO_READY;
191	if (sc->flags & FOO_ASLEEP)
192		/* Somebody was waiting for us, awake him. */
193		wakeup(sc);
194	...
195}
196
197.Ed
198Note that the interrupt handler should
199.Em never
200reduce the priority level.
201It is automatically called as it had
202raised the interrupt priority to its own level, i.e., further interrupts
203of the same group are being blocked.
204.Sh HISTORY
205The interrupt priority levels appeared in a very early version of
206.Ux .
207They have been traditionally known by number instead of by
208names, and were inclusive up to higher priority levels (i.e., priority
2095 has been blocking everything up to level 5).
210This is no longer the case in
211.Fx .
212The traditional name
213.Ql level
214for them is still reflected in the letter
215.Ql l
216of the respective functions and variables, although they are not
217really levels anymore, but rather different (partially inclusive)
218sets of functions to be blocked during some periods of the life of
219the system.
220The historical number scheme can be considered as a
221simple linearly ordered set of interrupt priority groups.
222.Pp
223.Fx 5.0
224eliminated spl entirely in favor of locking primitives which scale
225to more than one processor.
226.Sh AUTHORS
227This manual page was written by
228.An J\(:org Wunsch .