253 lines
7.1 KiB
Groff
253 lines
7.1 KiB
Groff
.\" $OpenBSD: spl.9,v 1.26 2016/08/16 23:49:35 dlg Exp $
|
|
.\" $NetBSD: spl.9,v 1.1 1997/03/11 06:15:05 mikel Exp $
|
|
.\"
|
|
.\" 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 $Mdocdate: August 16 2016 $
|
|
.Dt SPLX 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm splraise ,
|
|
.Nm splhigh ,
|
|
.Nm splserial ,
|
|
.Nm splsched ,
|
|
.Nm splclock ,
|
|
.Nm splstatclock ,
|
|
.Nm splvm ,
|
|
.Nm spltty ,
|
|
.Nm splsofttty ,
|
|
.Nm splnet ,
|
|
.Nm splbio ,
|
|
.Nm splsoftnet ,
|
|
.Nm splsoftclock ,
|
|
.Nm spllowersoftclock ,
|
|
.Nm spl0 ,
|
|
.Nm splx ,
|
|
.Nm splassert
|
|
.Nd modify system interrupt priority level
|
|
.Sh SYNOPSIS
|
|
.In machine/intr.h
|
|
.Ft int
|
|
.Fn splraise "int ipl"
|
|
.Ft int
|
|
.Fn splhigh 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 splsofttty void
|
|
.Ft int
|
|
.Fn splnet void
|
|
.Ft int
|
|
.Fn splbio void
|
|
.Ft int
|
|
.Fn splsoftnet void
|
|
.Ft int
|
|
.Fn splsoftclock void
|
|
.Ft int
|
|
.Fn spllowersoftclock void
|
|
.Ft int
|
|
.Fn spl0 void
|
|
.Ft void
|
|
.Fn splx "int s"
|
|
.Ft void
|
|
.Fn splassert "int s"
|
|
.Sh DESCRIPTION
|
|
These functions raise and lower the system priority level.
|
|
They are used by kernel code to block interrupts with priority less
|
|
than or equal to the named level (i.e.,
|
|
.Fn spltty
|
|
blocks interrupts of priority less than or equal to
|
|
.Dv IPL_TTY ) .
|
|
The code may then safely access variables and data structures which
|
|
are used by kernel code that runs at an equal or lower priority level.
|
|
.Pp
|
|
An
|
|
.Nm spl
|
|
function exists for each distinct priority level which can exist in
|
|
the system.
|
|
These macros and the corresponding priority levels are
|
|
used for various defined purposes, and may be divided into two main
|
|
types: hard and soft.
|
|
Hard interrupts are generated by hardware
|
|
devices, while soft interrupts are generated by callouts and called
|
|
from the kernel's periodic timer interrupt service routine.
|
|
.Pp
|
|
In order of highest to lowest priority, the priority-raising macros
|
|
are:
|
|
.Bl -tag -width splsoftclockXX
|
|
.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 splserial
|
|
blocks hard interrupts from serial interfaces.
|
|
Code running at this level may not access the tty subsystem.
|
|
.It Fn splsched
|
|
blocks interrupts that may access scheduler data structures.
|
|
Specifically the clock interrupt that invokes the
|
|
.Fn schedclock
|
|
function needs to be blocked.
|
|
On some systems this is a separate clock;
|
|
on others it is the same as the statistics clock and, on these,
|
|
.Fn splsched
|
|
must block everything that
|
|
.Fn splstatclock
|
|
does.
|
|
Code running at or above this level may not call
|
|
.Xr tsleep 9
|
|
or
|
|
.Xr wakeup 9 ,
|
|
nor may it post signals.
|
|
Note that "running" means invoked by an interrupt handler that
|
|
operates at this level or higher.
|
|
Kernel code that operates in the context of a process and has called
|
|
.Fn splhigh
|
|
for blocking purposes can use
|
|
.Xr tsleep 9
|
|
or
|
|
.Xr wakeup 9 .
|
|
.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.
|
|
.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 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 .
|
|
That includes all disk, network, and tty device interrupts.
|
|
.It Fn spltty
|
|
blocks hard interrupts from TTY devices.
|
|
.It Fn splsofttty
|
|
blocks soft interrupts generated by serial devices.
|
|
.It Fn splnet
|
|
blocks hard interrupts from network interfaces.
|
|
.It Fn splbio
|
|
blocks hard interrupts from disks and other mass-storage devices.
|
|
.It Fn splsoftnet
|
|
blocks soft network interrupts.
|
|
.It Fn splsoftclock
|
|
blocks soft clock interrupts.
|
|
.El
|
|
.Pp
|
|
Two macros 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 splraise
|
|
macro blocks interrupts at the interrupt priority level specified by
|
|
.Fa ipl .
|
|
.Pp
|
|
The
|
|
.Fn splx
|
|
macro 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 spl
|
|
macros.
|
|
.Pp
|
|
The
|
|
.Fn splassert
|
|
function checks that the system is running at a certain priority level.
|
|
The argument
|
|
.Fa s
|
|
should be one of these constants:
|
|
.Pp
|
|
.Bl -tag -width IPL_SOFTCLOCKXX -compact -offset indent
|
|
.It Dv IPL_STATCLOCK
|
|
.It Dv IPL_SCHED
|
|
.It Dv IPL_CLOCK
|
|
.It Dv IPL_VM
|
|
.It Dv IPL_BIO
|
|
.It Dv IPL_TTY
|
|
.It Dv IPL_NET
|
|
.It Dv IPL_SOFTNET
|
|
.It Dv IPL_SOFTCLOCK
|
|
.It Dv IPL_NONE
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn splassert
|
|
function is optional and is not necessarily implemented on
|
|
all architectures nor enabled in all kernel configurations.
|
|
It checks the current system priority level to see if it's
|
|
at least at the level specified in the argument
|
|
.Fa s .
|
|
If possible, it also checks if it hasn't been called from an
|
|
interrupt handler with a level higher than the one requested, which
|
|
must be an error (if some code is protected from
|
|
.Dv IPL_SOFTNET
|
|
interrupts, but accessed from an
|
|
.Dv IPL_NET
|
|
interrupt, it must be a design error in the code).
|
|
.Pp
|
|
The behavior of the
|
|
.Fn splassert
|
|
function is controlled by the kern.splassert
|
|
.Xr sysctl 8 .
|
|
Valid values for it are:
|
|
.Pp
|
|
.Bl -tag -width 1nr -compact -offset indent
|
|
.It 0
|
|
disable error checking
|
|
.It 1
|
|
print a message if an error is detected
|
|
.It 2
|
|
print a message and a stack trace if possible
|
|
.It 3
|
|
like 2 but also drop into the kernel debugger
|
|
.El
|
|
.Pp
|
|
Any other value causes a system panic on errors.
|