196 lines
5.7 KiB
Groff
196 lines
5.7 KiB
Groff
.\" $NetBSD: spl.9,v 1.7 2000/06/08 06:45:24 cgd 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 March 11, 1997
|
|
.Dt SPL 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm spl ,
|
|
.Nm spl0 ,
|
|
.Nm splbio ,
|
|
.Nm splclock ,
|
|
.Nm splhigh ,
|
|
.Nm splimp ,
|
|
.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 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 with priority less
|
|
than or equal to the named level (e.g.
|
|
.Fn spltty
|
|
blocks interrupts of priority less than or equal to
|
|
.Dv IPL_TTY Ns ).
|
|
The code may then safely access variables or data structures which are
|
|
read or modified by interrupt service routines that run at the named
|
|
level.
|
|
.Pp
|
|
A
|
|
.Nm
|
|
function exists for each distinct priority level which can exist in
|
|
the system. These functions 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. Soft interrupts are generated by callouts, and are called
|
|
from the kernel's periodic timer interrupt service routine.
|
|
.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 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. Code
|
|
running at or above this level may not call
|
|
.Fn sleep ,
|
|
.Fn tsleep ,
|
|
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.
|
|
.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 splimp
|
|
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 splsoftserial
|
|
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 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
|