spl(D3) spl(D3)
NAME
spl - block/allow interrupts on a processor
SYNOPSIS
#include <sys/ddi.h>
pl_t splbase(void);
pl_t spltimeout(void);
pl_t spldisk(void);
pl_t splstr(void);
pl_t spltty(void);
pl_t splhi(void);
pl_t spl0(void);
pl_t spl7(void);
void splx(pl_t level);
DESCRIPTION
The spl functions block or allow servicing of interrupts on
the processor on which the function is called.
Return Values
All spl functions, with the exception of splx, return the
previous priority level (pl_t).
USAGE
Hardware devices are assigned to interrupt priority levels
depending on the type of device. Each spl function which
blocks interrupts is associated with some machine dependent
interrupt priority level and will prevent interrupts occurring
at or below this priority level from being serviced on the
processor on which the spl function is called.
On a multiprocessor system, interrupts may be serviced by more
than one processor and, therefore, use of an spl function
alone is not sufficient to prevent interrupt code from
executing and manipulating driver data structures during a
critical section. Drivers that must prevent execution of
interrupt-level code in order to protect the integrity of
their data should use basic locks or read/write locks for this
purpose [see LOCK_ALLOC(D3) or RW_ALLOC(D3)].
The spl functions include the following:
splbase Block no interrupts. Should only be used by
base-level code that knows it is not nested
within any section of protected critical code.
Copyright 1994 Novell, Inc. Page 1
spl(D3) spl(D3)
spltimeout Block functions scheduled by itimeout and
dtimeout.
spldisk Block disk device interrupts.
splstr Block STREAMS interrupts.
spltty Used by a TTY driver to protect critical code.
spltty is mapped to splstr.
splhi Block all interrupts. Can be used in any type of
driver to mask out all interrupts including the
clock, and should be used very sparingly.
spl0 Equivalent to splbase.
spl7 On Intel processors, equivalent to splhi.
splx Restore the priority level, level. Typically,
this is the value returned from a previous spl
function.
To ensure driver portability, the named spl functions (such as
splbase or spltimeout) should be used whenever possible. The
numbered spl functions (spl0 and spl7) should be used only
when an interrupt priority level must be set to a specific
value.
Calling a given spl function will block interrupts specified
for that function as well as interrupts at equal and lower
levels. The notion of low vs. high levels assumes a defined
order of priority levels. The following partial order is
defined:
splbase <= spltimeout <= spldisk,splstr <= splhi
The ordering of spldisk and splstr relative to each other is
not defined.
When setting a given priority level, the previous level
returned should be saved and splx, UNLOCK(D3), or
RW_UNLOCK(D3) should be used as appropriate to restore this
level.
Copyright 1994 Novell, Inc. Page 2
spl(D3) spl(D3)
Interrupt-level code must never lower the interrupt priority
level below the level at which the interrupt handler was
entered. For example, if an interrupt handler is entered at
the priority level associated with spldisk, the handler must
not call spltimeout.
Level
Base or Interrupt.
Synchronization Considerations
All spl functions do not sleep.
Driver-defined basic locks and read/write locks may be held
across calls to these functions, but the spl call must not
cause the priority level to be lowered below the level
associated with the lock.
Driver-defined sleep locks may be held across calls to these
functions.
REFERENCES
LOCK(D3), LOCK_ALLOC(D3), RW_RDLOCK(D3), RW_UNLOCK(D3),
RW_WRLOCK(D3), RW_ALLOC(D3)
NOTICES
Portability
The named spl functions are supported on all processors.
Implementation of the numbered spl functions may vary across
processors.
Applicability
ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp
In versions 1, 2, 3, and 4, the spl functions are guaranteed
to be ``hard''. That is, interrupts asserted while blocked by
the spl priority level and de-asserted before being unblocked
will not result in calls to the interrupt handler(s). For
other versions, the only guarantee is that the handler(s) will
not be called while blocked.
Copyright 1994 Novell, Inc. Page 3