spl(D3)

NAME
     spl - block/allow interrupts on a processor

SYNOPSIS
     #include <sys/ddi.h>
     int splbase(void);
     int spltimeout(void);
     int spldisk(void);
     int splstr(void);
     int spltty(void);
     int splhi(void);
     int spl0(void);
     int spl7(void);
     void splx(int oldlevel);

   Arguments
     oldlevel  Last set priority value (only splx has an input argument).

DESCRIPTION
     The spl functions block or allow servicing of interrupts on the processor
     on which the function is called.

   Return Values
     All spl functions except splx return the previous priority level for use
     by splx.

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 a 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 for this purpose [see LOCK_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.

     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         Equivalent to splhi.

     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 or UNLOCK(D3) should be used as appropriate to restore
     this level.

     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),