255 lines
8.1 KiB
Groff
255 lines
8.1 KiB
Groff
.\" $NetBSD: spl.9,v 1.11 2000/08/22 19:56:08 thorpej Exp $
|
|
.\"
|
|
.\" Copyright (c) 2000 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 August 21, 2000
|
|
.Dt SPL 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm spl ,
|
|
.Nm spl0 ,
|
|
.Nm splbio ,
|
|
.Nm splclock ,
|
|
.Nm splhigh ,
|
|
.Nm splimp ,
|
|
.Nm spllock ,
|
|
.Nm spllowersoftclock ,
|
|
.Nm splnet ,
|
|
.Nm splsched ,
|
|
.Nm splserial ,
|
|
.Nm splsoftclock ,
|
|
.Nm splsoftnet ,
|
|
.Nm splsoftserial ,
|
|
.Nm splstatclock ,
|
|
.Nm spltty ,
|
|
.Nm splx
|
|
.Nd modify system interrupt priority level
|
|
.Sh SYNOPSIS
|
|
.Fd #include <machine/intr.h>
|
|
.Ft int
|
|
.Fn splhigh void
|
|
.Ft int
|
|
.Fn spllock void
|
|
.Ft int
|
|
.Fn splsched void
|
|
.Ft int
|
|
.Fn splserial void
|
|
.Ft int
|
|
.Fn splclock void
|
|
.Ft int
|
|
.Fn splstatclock void
|
|
.Ft int
|
|
.Fn splimp 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 splimp
|
|
(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 splimp
|
|
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.
|
|
.It Fn spltty
|
|
blocks hard and soft interrupts from TTY devices (IPL_TTY). This
|
|
must also block soft serial interrupts.
|
|
.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.
|
|
.Pp
|
|
.Sh HISTORY
|
|
.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
|