NetBSD/share/man/man9/spl.9

306 lines
9.0 KiB
Groff
Raw Normal View History

2006-09-23 15:25:47 +04:00
.\" $NetBSD: spl.9,v 1.24 2006/09/23 11:25:47 wiz Exp $
.\"
2001-04-14 04:15:41 +04:00
.\" 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.
1997-10-10 10:18:30 +04:00
.\" 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.
.\"
2006-09-23 15:25:47 +04:00
.Dd September 23, 2006
.Dt SPL 9
.Os
.Sh NAME
1997-11-11 13:06:37 +03:00
.Nm spl ,
.Nm spl0 ,
.Nm splaudio ,
1997-11-11 13:06:37 +03:00
.Nm splbio ,
.Nm splclock ,
.Nm splhigh ,
2001-04-14 04:15:41 +04:00
.Nm splvm ,
2000-08-22 23:56:08 +04:00
.Nm spllock ,
.Nm spllowersoftclock ,
1997-11-11 13:06:37 +03:00
.Nm splnet ,
.Nm splsched ,
.Nm splserial ,
.Nm splsoftclock ,
.Nm splsoftnet ,
.Nm splsoftserial ,
.Nm splstatclock ,
.Nm spltty ,
2001-04-18 09:56:05 +04:00
.Nm splvm ,
1997-11-11 13:06:37 +03:00
.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
2000-08-22 23:56:08 +04:00
.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
2001-04-14 04:15:41 +04:00
.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.
2000-08-22 02:53:53 +04:00
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
2000-08-22 03:16:01 +04:00
Interrupt priorities are not arranged in a strict hierarchy, although
2002-10-14 17:43:14 +04:00
interrupt hardware sometimes is.
For this reason the priorities listed here are arranged from
2000-08-22 02:53:53 +04:00
.Dq highest
to
.Dq lowest .
2000-08-22 05:33:52 +04:00
In other words, if a platform's hardware interrupts are arranged in
2000-08-22 03:16:01 +04:00
a hierarchical manner, a priority level should also block all of the
2000-08-22 02:53:53 +04:00
levels listed below it.
.Pp
2002-10-14 17:43:14 +04:00
Note that a strict hierarchy is not required.
For example,
2000-08-22 02:53:53 +04:00
.Fn splnet
is not required to block disk controller interrupts, as they
2002-10-14 17:43:14 +04:00
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
2000-08-22 02:53:53 +04:00
the system, as well as for some special priority levels that are
designed to be used in conjunction with multiprocessor-safe locking
2002-10-14 17:43:14 +04:00
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
2000-08-22 02:53:53 +04:00
expensive processing at a lower interrupt priority, and are explicitly
2002-10-14 17:43:14 +04:00
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
2000-08-22 02:53:53 +04:00
.Xr softintr 9 .
.Pp
In order of highest to lowest priority, the priority-raising functions
are:
.Bl -tag -width splsoftserialXX
.It Fn splhigh
2002-10-14 17:43:14 +04:00
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.
2000-08-22 23:56:08 +04:00
.It Fn spllock
2002-10-14 17:43:14 +04:00
blocks all hard and soft interrupts that can acquire a simple lock.
This is provided as a distinct level from
2000-08-22 23:56:08 +04:00
.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
2000-08-22 02:53:53 +04:00
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
2002-10-14 17:43:14 +04:00
processing to run in a software interrupt.
Note that code running at this priority is not blocked by
2001-04-14 04:15:41 +04:00
.Fn splvm
2000-08-22 02:53:53 +04:00
(described below), and is therefore prohibited from using the
kernel memory allocators.
.It Fn splsched
2000-08-22 02:53:53 +04:00
blocks all hard and soft interrupts that may access scheduler data
2002-10-14 17:43:14 +04:00
structures.
Code running at or above this level may not call
.Fn sleep ,
.Fn tsleep ,
2000-08-22 02:53:53 +04:00
.Fn ltsleep ,
or
.Fn wakeup ,
nor may it post signals.
.It Fn splclock
2002-10-14 17:43:14 +04:00
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
2000-08-22 02:53:53 +04:00
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
2002-10-14 17:43:14 +04:00
blocks the hardware statistics clock interrupt.
It is used by
.Fn statclock
to update kernel profiling and other statistics, and must be used by
2002-10-14 17:43:14 +04:00
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.
2001-04-14 04:15:41 +04:00
.It Fn splvm
blocks hard interrupts from all devices that are allowed to use the
kernel
2000-08-22 02:53:53 +04:00
.Xr malloc 9 ,
or any virtual memory operations.
2002-10-14 17:43:14 +04:00
That includes all disk, network, and tty device interrupts.
The temptation to abuse the semantics of
2001-04-14 04:15:41 +04:00
.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
2002-10-14 17:43:14 +04:00
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
2000-08-22 02:53:53 +04:00
blocks soft interrupts generated by serial devices (IPL_SOFTSERIAL).
.It Fn splnet
2000-08-22 02:53:53 +04:00
blocks hard interrupts from network interfaces (IPL_NET).
.It Fn splbio
2000-08-22 02:53:53 +04:00
blocks hard interrupts from disks and other mass-storage
devices (IPL_BIO).
.It Fn splsoftnet
2002-10-14 17:43:14 +04:00
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
2002-10-14 17:43:14 +04:00
blocks soft clock interrupts.
This is the priority at which the
2000-08-22 02:53:53 +04:00
.Xr callout 9
2002-10-14 17:43:14 +04:00
facility runs.
Soft interrupts blocked by this priority are also blocked by all
of the priorities listed above.
In particular,
2000-08-22 02:53:53 +04:00
.Fn splsoftnet
must be a higher priority than
.Fn splsoftclock .
.El
.Pp
2002-10-14 17:43:14 +04:00
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
2002-10-14 17:43:14 +04:00
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
2002-10-14 17:43:14 +04:00
was used to block network software interrupts.
Most device drivers used
.Fn splimp
2002-10-14 17:43:14 +04:00
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
2002-09-25 04:10:53 +04:00
.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
2001-04-14 04:15:41 +04:00
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.