'\"macro stdmacro
.if n .pH ddi_dki.spl @(#)spl	40.8 of 10/10/89
.\" Copyright 1989 AT&T
.de IX
.ie '\\n(.z'' .tm .Index: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9	\\n%
.el \\!.IX \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
..
.nr X
.if \nX=0 .ds x} spl D3D "3B2" "DDI" "\&"
.if \nX=1 .ds x} spl D3D "3B2" "DDI"
.if \nX=2 .ds x} spl D3D "" "\&"
.if \nX=3 .ds x} spl "" "" "\&"
.TH \*(x}
.IX "\f4spl\fP(D3D)"
.SH NAME
\f4spl\f1 \- block/allow interrupts
.SH SYNOPSIS
.nf
.na
\f4#include <sys/inline.h>
.sp 0.5
int spl0();
int spl1();	
int spl4();	
int spl5();	
int spl6();	
int spl7();	
int splvm();
int splhi();	
int splstr();	
int spltty();	
.sp 0.5
int splx(int \f2oldlevel\f4);\f1
.ad
.fi
.SH "ARGUMENT"
.RS 0n 10
.IP "\f2oldlevel\f1" 10n
Last set priority value (only \f4splx\f1 has an input argument).
.RE
.SH DESCRIPTION
\f4spl\f1 blocks or allows interrupts.
When a process is executing code in a driver,
the system will not switch
context from that process to another executing process unless it is explicitly
told to do so by the driver.
This protects the integrity of the kernel and
driver data structures.
However,
the system does allow devices to interrupt
the processor and handle these interrupts immediately.
.P
The integrity of system data structures would be destroyed if an interrupt
handler were to manipulate the same data structures as a process executing in
the driver.
To prevent such problems,
the kernel provides the \f4spl\f1
functions allowing a driver to set processor execution levels,
prohibiting
the handling of interrupts below the level set.
.P
The selection of the appropriate \f4spl\f1 function is important.  The
execution level to which the processor is set must be high enough to protect
the region of code; but this level should not be so high that it unnecessarily
locks out interrupts that need to be processed quickly.  A hardware device is
assigned to an interrupt priority level depending on the type of
device.  By using the appropriate \f4spl\f1
function, a driver can inhibit interrupts from its device or other devices at
the same or lower interrupt priority levels.
.P
The \f4spl\f1 command changes the state 
of the processor status word (PSW).
The PSW stores the current processor execution level, in addition to
information relating to the operating system internals.  The \f4spl\f1
functions block out interrupts that come in at a priority level at or below
a machine-dependent interrupt priority level.
The \f4spl\f1 functions include the following:
.RS 4n
.TP 10n
\f4spl0\f1
Restores all interrupts when executing on the base level.
A driver routine may use \f4spl0\f1 when the routine has been called through
a system call; that is, if it is known that the level being restored
is indeed at base level.
.TP
\f4spl1\f1
Used in context and process switch to protect critical code.
.TP
\f4spl4\f1
Used in character drivers to protect critical code.
.TP
\f4spl5\f1
Used in character drivers to protect critical code (this function has the same
effect as \f4spl4\f1).
.TP
\f4spl6\f1
Used in block drivers to protect critical code.
.TP
\f4spl7\f1
Used in any type of driver to mask out all interrupts including the clock,
and should be used very sparingly.
.TP
\f4splvm\f1
Used in memory management code to protect critical regions.
.TP
\f4splhi\f1
Used in any type of driver to mask out all interrupts including the clock,
and should be used very sparingly.  (This function is identical to \f4spl7\f1.)
.TP
\f4spltty\f1
Used by a TTY driver to protect critical code. 
.TP
\f4splstr\f1
Used to protect STREAMS driver and module critical regions of code.
This is defined to be high enough to block interrupts from the highest
priority STREAMS device.  \f4splstr\f1 is mapped to \f4spltty\f1.
.TP
\f4splx\f1
Used to terminate a section of protected critical code.  This function
restores the interrupt level to the previous level specified by its
argument \f2oldlevel\f1.
.RE
.P
\f3NOTE:\f1
\f4spl\f1 functions should not be used in interrupt
routines unless you save the old interrupt priority level in a variable
as it was returned from an \f4spl\f1 call.  Later, \f4splx\f1 must
be used to restore the saved old level.  Never drop the interrupt
priority level below the level at which an interrupt routine was
entered.  For example, if an interrupt routine is entered at the
interrupt priority level of an \f4spl6\f1, do not call \f4spl0\f1
through \f4spl5\f1 or the stack may become corrupted.
.SH RETURN VALUE
All \f4spl\f1 functions (except \f4splx\f1) return the former priority
level.
.SH EXAMPLE
See the \f4untimeout\f1(D3DK) function page for an example of \f4spl\f1.
