Aren
/
NetBSD
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Sync with reality.

This commit is contained in:
ad 2007-12-05 04:47:56 +00:00
parent 96302ffc73
commit be843f3b0a
1 changed files with 123 additions and 177 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

300
share/man/man9/spl.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: spl.9,v 1.26 2007/02/17 08:44:08 wiz Exp $ .\" $NetBSD: spl.9,v 1.27 2007/12/05 04:47:56 ad Exp $
.\" .\"
.\" Copyright (c) 2000, 2001 Jason R. Thorpe. All rights reserved. .\" Copyright (c) 2000, 2001 Jason R. Thorpe. All rights reserved.
.\" Copyright (c) 1997 Michael Long. .\" Copyright (c) 1997 Michael Long.
@ -27,72 +27,48 @@
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\" .\"
.Dd February 11, 2007 .Dd Decenber 5, 2007
.Dt SPL 9 .Dt SPL 9
.Os .Os
.Sh NAME .Sh NAME
.Nm spl , .Nm spl ,
.Nm spl0 , .Nm spl0 ,
.Nm splaudio ,
.Nm splbio ,
.Nm splclock ,
.Nm splhigh , .Nm splhigh ,
.Nm splvm , .Nm splvm ,
.Nm spllock ,
.Nm spllowersoftclock ,
.Nm splnet ,
.Nm splsched , .Nm splsched ,
.Nm splserial , .Nm splsoftbio ,
.Nm splsoftclock , .Nm splsoftclock ,
.Nm splsoftnet , .Nm splsoftnet ,
.Nm splsoftserial , .Nm splsoftserial ,
.Nm splstatclock ,
.Nm spltty ,
.Nm splvm ,
.Nm splx .Nm splx
.Nd modify system interrupt priority level .Nd modify system interrupt priority level
.Sh SYNOPSIS .Sh SYNOPSIS
.In sys/param.h .In sys/param.h
.Ft int .Ft void
.Fn splaudio void .Fn spl0 void
.Ft int .Ft int
.Fn splhigh void .Fn splhigh void
.Ft int .Ft int
.Fn spllock void
.Ft int
.Fn splserial void
.Ft int
.Fn splsched void .Fn splsched void
.Ft int .Ft int
.Fn splclock void
.Ft int
.Fn splstatclock void
.Ft int
.Fn splvm void .Fn splvm void
.Ft int .Ft int
.Fn spltty void .Fn splsoftbio void
.Ft int
.Fn splsoftclock void
.Ft int .Ft int
.Fn splsoftserial void .Fn splsoftserial void
.Ft int .Ft int
.Fn splnet void
.Ft int
.Fn splbio void
.Ft int
.Fn splsoftnet void .Fn splsoftnet void
.Ft int
.Fn splsoftclock void
.Ft void
.Fn spllowersoftclock void
.Ft void
.Fn spl0 void
.Ft void .Ft void
.Fn splx "int s" .Fn splx "int s"
.Sh DESCRIPTION .Sh DESCRIPTION
These functions raise and lower the system priority level. These functions raise and lower the interrupt priority level.
They are used by kernel code to block interrupts in critical They are used by kernel code to block interrupts in critical
sections, in order to protect data structures (much like sections, in order to protect data structures.
a locking primitive).
.Pp .Pp
In a multi-CPU system, these functions change the interrupt
priority level on the local CPU only.
In general, device drivers should not make use of these interfaces. In general, device drivers should not make use of these interfaces.
To ensure correct synchronization, device drivers should use the To ensure correct synchronization, device drivers should use the
.Xr condvar 9 , .Xr condvar 9 ,
@ -101,148 +77,125 @@ and
.Xr rwlock 9 .Xr rwlock 9
interfaces. interfaces.
.Pp .Pp
Interrupt priorities are not arranged in a strict hierarchy, although Interrupt priorities are arranged in a strict hierarchy, although
interrupt hardware sometimes is. sometimes levels may be equivalent (overlap).
For this reason the priorities listed here are arranged from The hierarchy means that raising the IPL to any level will block
.Dq highest interrupts at that level, and at all lower levels.
to The hierarchy is used to minimize data loss due to interrupts not
.Dq lowest . being serviced in a timely fashion.
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 .Pp
Note that a strict hierarchy is not required. The levels may be divided into two groups: hard and soft.
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. Hard interrupts are generated by hardware devices.
Soft interrupts are a way of deferring hardware interrupts to do more Soft interrupts are a way of deferring hardware interrupts to do more
expensive processing at a lower interrupt priority, and are explicitly expensive processing at a lower interrupt priority, and are explicitly
scheduled by the higher-level interrupt handler. 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 Software interrupts are further described by
.Xr softintr 9 . .Xr softint 9 .
.Pp
Note that hard interupt handlers do not possess process (thread) context
and so it is not valid to use kernel facilities that may attempt to sleep
from a hardware interrupt.
For example, it is not possible to acquire a reader/writer lock from
a hardware interrupt.
Soft interrupt handlers possess limited process context and so may sleep
briefly in order to acquire a reader/writer lock or adaptive mutex,
but may not sleep for any other reason.
.Pp .Pp
In order of highest to lowest priority, the priority-raising functions In order of highest to lowest priority, the priority-raising functions
are: along with their counterpart symbolic tags are:
.Bl -tag -width splsoftserialXX .Bl -tag -width splsoft
.It Fn splhigh .It Fn splhigh , IPL_HIGH
blocks all hard and soft interrupts. .Pp
It is used for code that cannot tolerate any interrupts, like hardware Blocks all hard and soft interrupts, including the higest level I/O
context switching code and the interrupts, such as interrupts from serial interfaces and the
.Xr ddb 4 statistics clock (if any).
in-kernel debugger. It is also used for code that cannot tolerate any interrupts.
.It Fn spllock .Pp
blocks all hard and soft interrupts that can acquire a simple lock. Code running at this level may not (in general) directly access
This is provided as a distinct level from machine indepenent kernel services.
.Fn splhigh For example, it is illegal to call the kernel
as some platforms may need to make use of extremely high priority .Fn printf
interrupts while locks are spinning, which would be blocked by function or to try and allocate memory.
.Fn splhigh . The methods of synchronization available are: spin mutexes and
.It Fn splserial scheduling a soft interrupt.
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 Generally, all code run at this level must schedule additional
processing to run in a software interrupt. processing to run in a software interrupt.
Note that code running at this priority is not blocked by .Pp
.Fn splvm Code with thread context running at this level must not use a kernel
(described below), and is therefore prohibited from using the interface that may cause the current LWP to sleep, such as the
kernel memory allocators. .Xr condvar
.It Fn splsched interfaces.
blocks all hard and soft interrupts that may access scheduler data .Pp
structures. Interrupt handlers at this level cannot acquire the global kernel_lock
Code running at or above this level may not call and so must be coded to ensure correct synchronization on muliprocessor
.Fn sleep , systems.
.Fn tsleep , .It Fn splsched , IPL_SCHED
.Fn ltsleep , .Pp
or Blocks all medium priority hardware interrupts, such as interrupts
.Fn wakeup , from audio devices, and the clock interrupt.
nor may it post signals. .Pp
.It Fn splclock Interrupt handlers running at this level endure the same restrictions as
blocks the hardware clock interrupt. at IPL_HIGH, but may access scheduler interfaces, and so may awaken LWPs
It is used by (light weight processes) using the
.Fn hardclock .Xr condvar 9
to update kernel and process times, and must be used by any other code interfaces, and may schedule callouts using the
that accesses time-related data, specifically the
.Va time
and
.Va mono_time
global variables.
This level also protects the
.Xr callout 9 .Xr callout 9
data structures, and nothing running at or above this level may interfaces.
schedule, cancel, or otherwise access any callout-related data .Pp
structures. Code with thread context running at this level may sleep via the
.It Fn splstatclock .Xr condvar
blocks the hardware statistics clock interrupt. interfaces, and may use other kernel facilities that could cause the
It is used by current LWP to sleep.
.Fn statclock .It Fn splvm , IPL_VM
to update kernel profiling and other statistics, and must be used by .Pp
any code that accesses that data. Blocks hard interrupts from 'low' priority hardware interrupts, such
This is the clock that drives scheduling. as interrupts from network, block I/O and tty devices.
This level is identical to .Pp
.Fn splclock Code running at this level endures the same restrictions as at IPL_SCHED,
if there is no separate statistics clock. but may use the deprecated
.It Fn splvm .Xr malloc 9
blocks hard interrupts from all devices that are allowed to use the or endorsed
kernel .Xr pool_cache 9
.Xr malloc 9 , interfaces to allocate memory.
or any virtual memory operations. .Pp
That includes all disk, network, and tty device interrupts. At the time of writing, the global
The temptation to abuse the semantics of .Dv kernel_lock
.Fn splvm is automatically acquired for interrupts at this level, in order to
should be avoided; if you feel as if you need to block more than support device drivers that do not provide their own multiprocessor
one class of interrupts at a time, use software interrupts instead. synchronization.
.It Fn spltty A future release of the system may allow the automatic acquisition of
blocks hard and soft interrupts from TTY devices (IPL_TTY). .Dv kernel_lock
This must also block soft serial interrupts. to be disabled for individual interrupt handlers.
.It Fn splaudio .It Fn splsoftserial , IPL_SOFTSERIAL
blocks hard interrupts generated by audio devices (IPL_AUDIO). .Pp
.It Fn splsoftserial Blocks soft interrupts at the IPL_SOFTSERIAL symbolic level.
blocks soft interrupts generated by serial devices (IPL_SOFTSERIAL). .Pp
.It Fn splnet This is the first of the software levels.
blocks hard interrupts from network interfaces (IPL_NET). Soft interrupts at this level and lower may acquire reader/writer
.It Fn splbio locks or adaptive mutexes.
blocks hard interrupts from disks and other mass-storage .It Fn splsoftnet , IPL_SOFTNET
devices (IPL_BIO). .Pp
.It Fn splsoftnet Blocks soft interrupts at the IPL_SOFTNET symbolic level.
blocks soft network interrupts (IPL_SOFTNET). .It Fn splsoftnet , IPL_SOFTBIO
Soft interrupts blocked by this priority are also blocked by all .Pp
of the priorities listed above. Blocks soft interrupts at the IPL_SOFTBIO symbolic level.
.It Fn splsoftclock .It Fn splsoftnet , IPL_SOFTCLOCK
blocks soft clock interrupts. .Pp
This is the priority at which the Blocks soft interrupts at the IPL_SOFTCLOCK symbolic level.
.Pp
This is the priority at which callbacks generated by the
.Xr callout 9 .Xr callout 9
facility runs. 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 .El
.Pp .Pp
Two functions lower the system priority level. One function lowers the system priority level:
They are: .Bl -tag -width splsoft
.Bl -tag -width spllowersoftclockXX .It Fn spl0 , IPL_NONE
.It Fn spllowersoftclock .Pp
unblocks all interrupts but the soft clock interrupt. Unblocks all interrupts.
.It Fn spl0 This should rarely be used directly;
unblocks all interrupts. .Fn splx
should be used instead.
.El .El
.Pp .Pp
The The
@ -252,20 +205,6 @@ function restores the system priority level to the one encoded in
which must be a value previously returned by one of the other which must be a value previously returned by one of the other
.Nm .Nm
functions. 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 SEE ALSO .Sh SEE ALSO
.Xr condvar 9 , .Xr condvar 9 ,
.Xr mutex 9 , .Xr mutex 9 ,
@ -314,3 +253,10 @@ was replaced by
and code which abused the semantics of and code which abused the semantics of
.Fn splimp .Fn splimp
was changed to not mix interrupt priority levels. was changed to not mix interrupt priority levels.
.Pp
Between
.Nx 4.0
and
.Nx 5.0 ,
the hardware levels were reduced in number and a strict hierarchy
defined.