SVR5

spl(D3)

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 ``Spin locks (DDI)'' in HDK Technical Reference.

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(D3) and timeout(D3).
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. Not supported in current version.
spl7: On Intel processors, equivalent to splhi. Not supported in current version.
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.

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.

A multithreaded driver may not use spl functions. A single-threaded driver may use both locks and spls, although the only reasonable use for locks in a non-multithreaded driver is to access data structures that are shared with other cooperating drivers or cooperating daemons. Using a lock in place of an spl call for a data structure that is managed totally within a non-multithreaded driver is overkill.

Context and synchronization

Non-blockable, interrupt, user, or blockable context.

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.

Hardware constraints

The named spl functions are supported on all processors. Implementation of the numbered spl functions may vary across processors.

Version applicability

ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8

Differences between versions

In DDI 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.

In DDI versions prior to version 8, spl0 is an alias for splbase and spl7 is an alias for splhi.

References

LOCK(D3), LOCK_ALLOC(D3), RW_RDLOCK(D3), RW_UNLOCK(D3), RW_WRLOCK(D3), RW_ALLOC(D3)

``Synchronization primitives'' in HDK Technical Reference