.\"	$NetBSD: spl.9,v 1.41 2017/04/06 03:00:13 pgoyette Exp $
.\"
.\" Copyright (c) 2000, 2001 Jason R. Thorpe.  All rights reserved.
.\" Copyright (c) 1997 Michael Long.
.\" Copyright (c) 1997 Jonathan Stone.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd April 6, 2017
.Dt SPL 9
.Os
.Sh NAME
.Nm spl ,
.Nm spl0 ,
.Nm splhigh ,
.Nm splvm ,
.Nm splbio ,
.Nm splnet ,
.Nm spltty ,
.Nm splsched ,
.Nm splsoftbio ,
.Nm splsoftclock ,
.Nm splsoftnet ,
.Nm splsoftserial ,
.Nm splx
.Nd modify system interrupt priority level
.Sh SYNOPSIS
.In sys/intr.h
.Ft void
.Fn spl0 void
.Ft int
.Fn splhigh void
.Ft int
.Fn splsched void
.Ft int
.Fn splvm void
.Ft int
.Fn splbio void
.Ft int
.Fn splnet void
.Ft int
.Fn spltty void
.Ft int
.Fn splsoftbio void
.Ft int
.Fn splsoftclock void
.Ft int
.Fn splsoftserial void
.Ft int
.Fn splsoftnet void
.Ft void
.Fn splx "int s"
.Sh DESCRIPTION
These functions raise and lower the interrupt priority level.
They are used by kernel code to block interrupts in critical
sections, in order to protect data structures.
.Pp
In a multi-CPU system, these functions change the interrupt
priority level on the local CPU only.
In general, device drivers should not make use of these interfaces.
To ensure correct synchronization, device drivers should use the
.Xr condvar 9 ,
.Xr mutex 9 ,
and
.Xr rwlock 9
interfaces.
.Pp
Interrupt priorities are arranged in a strict hierarchy, although
sometimes levels may be equivalent (overlap).
The hierarchy means that raising the IPL to any level will block
interrupts at that level, and at all lower levels.
The hierarchy is used to minimize data loss due to interrupts not
being serviced in a timely fashion.
.Pp
The levels may be divided into two groups: hard and soft.
Hard interrupts are generated by hardware devices.
Soft interrupts are a way of deferring hardware interrupts to do more
expensive processing at a lower interrupt priority, and are explicitly
scheduled by the higher-level interrupt handler.
Software interrupts are further described by
.Xr softint 9 .
.Pp
Note that hard interrupt handlers do not possess process (thread) context
and so it is not valid to use kernel facilities that may attempt to sleep
from a hardware interrupt.
For example, it is not possible to acquire a reader/writer lock from
a hardware interrupt.
Soft interrupt handlers possess limited process context and so may sleep
briefly in order to acquire a reader/writer lock or adaptive mutex,
but may not sleep for any other reason.
.Pp
In order of highest to lowest priority, the priority-raising functions
along with their counterpart symbolic tags are:
.Bl -tag -width splsoft
.It Fn splhigh , IPL_HIGH
.Pp
Blocks all hard and soft interrupts, including the highest level I/O
interrupts, such as interrupts from serial interfaces and the
statistics clock (if any).
It is also used for code that cannot tolerate any interrupts.
.Pp
Code running at this level may not (in general) directly access
machine independent kernel services.
For example, it is illegal to call the kernel
.Fn printf
function or to try and allocate memory.
The methods of synchronization available are: spin mutexes and
scheduling a soft interrupt.
Generally, all code run at this level must schedule additional
processing to run in a software interrupt.
.Pp
Code with thread context running at this level must not use a kernel
interface that may cause the current LWP to sleep, such as the
.Xr condvar 9
interfaces.
.Pp
Interrupt handlers at this level cannot acquire the global kernel_lock
and so must be coded to ensure correct synchronization on multiprocessor
systems.
.It Fn splsched , IPL_SCHED
.Pp
Blocks all medium priority hardware interrupts, such as interrupts
from audio devices, and the clock interrupt.
.Pp
Interrupt handlers running at this level endure the same restrictions as
at IPL_HIGH, but may access scheduler interfaces, and so may awaken LWPs
(light weight processes) using the
.Xr condvar 9
interfaces, and may schedule callouts using the
.Xr callout 9
interfaces.
.Pp
Code with thread context running at this level may sleep via the
.Xr condvar 9
interfaces, and may use other kernel facilities that could cause the
current LWP to sleep.
.It Fn splvm , IPL_VM
.Pp
Blocks hard interrupts from
.Dq low
priority hardware interrupts, such
as interrupts from network, block I/O and tty devices.
.Pp
Code running at this level endures the same restrictions as at IPL_SCHED,
but may use the deprecated
.Xr malloc 9
or endorsed
.Xr pool_cache 9
interfaces to allocate memory.
.Pp
At the time of writing, the global
.Dv kernel_lock
is automatically acquired for interrupts at this level, in order to
support device drivers that do not provide their own multiprocessor
synchronization.
A future release of the system may allow the automatic acquisition of
.Dv kernel_lock
to be disabled for individual interrupt handlers.
.Pp
.Fn splbio ,
.Fn splnet ,
and
.Fn spltty
are synonyms for
.Fn splvm .
Their use is deprecated; all new code should use
.Fn splvm .
.It Fn splsoftserial , IPL_SOFTSERIAL
.Pp
Blocks soft interrupts at the IPL_SOFTSERIAL symbolic level.
.Pp
This is the first of the software levels.
Soft interrupts at this level and lower may acquire reader/writer
locks or adaptive mutexes.
.It Fn splsoftnet , IPL_SOFTNET
.Pp
Blocks soft interrupts at the IPL_SOFTNET symbolic level.
.It Fn splsoftbio , IPL_SOFTBIO
.Pp
Blocks soft interrupts at the IPL_SOFTBIO symbolic level.
.It Fn splsoftclock , IPL_SOFTCLOCK
.Pp
Blocks soft interrupts at the IPL_SOFTCLOCK symbolic level.
.Pp
This is the priority at which callbacks generated by the
.Xr callout 9
facility runs.
.El
.Pp
One function lowers the system priority level:
.Bl -tag -width splsoft
.It Fn spl0 , IPL_NONE
.Pp
Unblocks all interrupts.
This should rarely be used directly;
.Fn splx
should be used instead.
.El
.Pp
The
.Fn splx
function restores the system priority level to the one encoded in
.Fa s ,
which must be a value previously returned by one of the other
.Nm
functions.
.Sh SEE ALSO
.Xr condvar 9 ,
.Xr i386/splraise 9 ,
.Xr kpreempt 9 ,
.Xr mutex 9 ,
.Xr rwlock 9
.Sh HISTORY
In
.Bx 4.4 ,
.Fn splnet
was used to block network software interrupts.
Most device drivers used
.Fn splimp
to block hardware interrupts.
To avoid unnecessarily blocking other interrupts, in
.Nx 1.1
a new function was added that blocks only network hardware interrupts.
For consistency with other
.Nm
functions, the old
.Fn splnet
function was renamed to
.Fn splsoftnet ,
and the new function was named
.Fn splnet .
.Pp
Originally,
.Fn splsoftclock
lowered the system priority level.
During the
.Nx 1.5
development cycle,
.Fn spllowersoftclock
was introduced and the semantics of
.Fn splsoftclock
were changed.
.Pp
The
.Fn splimp
call was removed from the kernel between
.Nx 1.5
and
.Nx 1.6 .
The function of
.Fn splimp
was replaced by
.Fn splvm
and code which abused the semantics of
.Fn splimp
was changed to not mix interrupt priority levels.
.Pp
Between
.Nx 4.0
and
.Nx 5.0 ,
the hardware levels were reduced in number and a strict hierarchy
defined.