306 lines
9.0 KiB
Groff
306 lines
9.0 KiB
Groff
.\" $NetBSD: spl.9,v 1.24 2006/09/23 11:25:47 wiz 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 September 23, 2006
|
|
.Dt SPL 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm spl ,
|
|
.Nm spl0 ,
|
|
.Nm splaudio ,
|
|
.Nm splbio ,
|
|
.Nm splclock ,
|
|
.Nm splhigh ,
|
|
.Nm splvm ,
|
|
.Nm spllock ,
|
|
.Nm spllowersoftclock ,
|
|
.Nm splnet ,
|
|
.Nm splsched ,
|
|
.Nm splserial ,
|
|
.Nm splsoftclock ,
|
|
.Nm splsoftnet ,
|
|
.Nm splsoftserial ,
|
|
.Nm splstatclock ,
|
|
.Nm spltty ,
|
|
.Nm splvm ,
|
|
.Nm splx
|
|
.Nd modify system interrupt priority level
|
|
.Sh SYNOPSIS
|
|
.In sys/param.h
|
|
.Ft int
|
|
.Fn splaudio void
|
|
.Ft int
|
|
.Fn splhigh void
|
|
.Ft int
|
|
.Fn spllock void
|
|
.Ft int
|
|
.Fn splserial void
|
|
.Ft int
|
|
.Fn splsched void
|
|
.Ft int
|
|
.Fn splclock void
|
|
.Ft int
|
|
.Fn splstatclock void
|
|
.Ft int
|
|
.Fn splvm void
|
|
.Ft int
|
|
.Fn spltty void
|
|
.Ft int
|
|
.Fn splsoftserial void
|
|
.Ft int
|
|
.Fn splnet void
|
|
.Ft int
|
|
.Fn splbio void
|
|
.Ft int
|
|
.Fn splsoftnet void
|
|
.Ft int
|
|
.Fn splsoftclock void
|
|
.Ft void
|
|
.Fn spllowersoftclock void
|
|
.Ft void
|
|
.Fn spl0 void
|
|
.Ft void
|
|
.Fn splx "int s"
|
|
.Sh DESCRIPTION
|
|
These functions raise and lower the system priority level.
|
|
They are used by kernel code to block interrupts in critical
|
|
sections, in order to protect data structures (much like
|
|
a locking primitive) or to ensure uninterrupted access to
|
|
hardware devices which are sensitive to timing.
|
|
.Pp
|
|
Interrupt priorities are not arranged in a strict hierarchy, although
|
|
interrupt hardware sometimes is.
|
|
For this reason the priorities listed here are arranged from
|
|
.Dq highest
|
|
to
|
|
.Dq lowest .
|
|
In other words, if a platform's hardware interrupts are arranged in
|
|
a hierarchical manner, a priority level should also block all of the
|
|
levels listed below it.
|
|
.Pp
|
|
Note that a strict hierarchy is not required.
|
|
For example,
|
|
.Fn splnet
|
|
is not required to block disk controller interrupts, as they
|
|
do not access the same data structures.
|
|
However, the priorities are presented as a hierarchy in order to
|
|
minimize data loss due to blocked interrupts, or interrupts not being
|
|
serviced in a timely fashion.
|
|
.Pp
|
|
A
|
|
.Nm
|
|
function exists for each distinct priority level which can exist in
|
|
the system, as well as for some special priority levels that are
|
|
designed to be used in conjunction with multiprocessor-safe locking
|
|
primitives.
|
|
These levels may be divided into two main types: 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.
|
|
The most common use of this is in the networking code, where network
|
|
interface drivers defer the more expensive TCP/IP processing in order
|
|
to avoid dropping additional incoming packets.
|
|
Software interrupts are further described by
|
|
.Xr softintr 9 .
|
|
.Pp
|
|
In order of highest to lowest priority, the priority-raising functions
|
|
are:
|
|
.Bl -tag -width splsoftserialXX
|
|
.It Fn splhigh
|
|
blocks all hard and soft interrupts.
|
|
It is used for code that cannot tolerate any interrupts, like hardware
|
|
context switching code and the
|
|
.Xr ddb 4
|
|
in-kernel debugger.
|
|
.It Fn spllock
|
|
blocks all hard and soft interrupts that can acquire a simple lock.
|
|
This is provided as a distinct level from
|
|
.Fn splhigh
|
|
as some platforms may need to make use of extremely high priority
|
|
interrupts while locks are spinning, which would be blocked by
|
|
.Fn splhigh .
|
|
.It Fn splserial
|
|
blocks hard interrupts from serial interfaces (IPL_SERIAL).
|
|
Code running at this level may not access the tty subsystem.
|
|
Generally, all code run at this level must schedule additional
|
|
processing to run in a software interrupt.
|
|
Note that code running at this priority is not blocked by
|
|
.Fn splvm
|
|
(described below), and is therefore prohibited from using the
|
|
kernel memory allocators.
|
|
.It Fn splsched
|
|
blocks all hard and soft interrupts that may access scheduler data
|
|
structures.
|
|
Code running at or above this level may not call
|
|
.Fn sleep ,
|
|
.Fn tsleep ,
|
|
.Fn ltsleep ,
|
|
or
|
|
.Fn wakeup ,
|
|
nor may it post signals.
|
|
.It Fn splclock
|
|
blocks the hardware clock interrupt.
|
|
It is used by
|
|
.Fn hardclock
|
|
to update kernel and process times, and must be used by any other code
|
|
that accesses time-related data, specifically the
|
|
.Va time
|
|
and
|
|
.Va mono_time
|
|
global variables.
|
|
This level also protects the
|
|
.Xr callout 9
|
|
data structures, and nothing running at or above this level may
|
|
schedule, cancel, or otherwise access any callout-related data
|
|
structures.
|
|
.It Fn splstatclock
|
|
blocks the hardware statistics clock interrupt.
|
|
It is used by
|
|
.Fn statclock
|
|
to update kernel profiling and other statistics, and must be used by
|
|
any code that accesses that data.
|
|
This is the clock that drives scheduling.
|
|
This level is identical to
|
|
.Fn splclock
|
|
if there is no separate statistics clock.
|
|
.It Fn splvm
|
|
blocks hard interrupts from all devices that are allowed to use the
|
|
kernel
|
|
.Xr malloc 9 ,
|
|
or any virtual memory operations.
|
|
That includes all disk, network, and tty device interrupts.
|
|
The temptation to abuse the semantics of
|
|
.Fn splvm
|
|
should be avoided; if you feel as if you need to block more than
|
|
one class of interrupts at a time, use software interrupts instead.
|
|
.It Fn spltty
|
|
blocks hard and soft interrupts from TTY devices (IPL_TTY).
|
|
This must also block soft serial interrupts.
|
|
.It Fn splaudio
|
|
blocks hard interrupts generated by audio devices (IPL_AUDIO).
|
|
.It Fn splsoftserial
|
|
blocks soft interrupts generated by serial devices (IPL_SOFTSERIAL).
|
|
.It Fn splnet
|
|
blocks hard interrupts from network interfaces (IPL_NET).
|
|
.It Fn splbio
|
|
blocks hard interrupts from disks and other mass-storage
|
|
devices (IPL_BIO).
|
|
.It Fn splsoftnet
|
|
blocks soft network interrupts (IPL_SOFTNET).
|
|
Soft interrupts blocked by this priority are also blocked by all
|
|
of the priorities listed above.
|
|
.It Fn splsoftclock
|
|
blocks soft clock interrupts.
|
|
This is the priority at which the
|
|
.Xr callout 9
|
|
facility runs.
|
|
Soft interrupts blocked by this priority are also blocked by all
|
|
of the priorities listed above.
|
|
In particular,
|
|
.Fn splsoftnet
|
|
must be a higher priority than
|
|
.Fn splsoftclock .
|
|
.El
|
|
.Pp
|
|
Two functions lower the system priority level.
|
|
They are:
|
|
.Bl -tag -width spllowersoftclockXX
|
|
.It Fn spllowersoftclock
|
|
unblocks all interrupts but the soft clock interrupt.
|
|
.It Fn spl0
|
|
unblocks all interrupts.
|
|
.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.
|
|
.Pp
|
|
Note that the functions which lower the system priority level
|
|
.Po
|
|
.Fn spllowersoftclock ,
|
|
.Fn spl0 ,
|
|
and
|
|
.Fn splx
|
|
.Pc
|
|
do not return a value.
|
|
They should only be used in places where the system priority level
|
|
is being decreased permanently.
|
|
It is inappropriate to attempt to use them where the
|
|
system priority level is being decreased temporarily, and would
|
|
need to be restored to a previous value before continuing.
|
|
.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.
|