267 lines
8.0 KiB
Groff
267 lines
8.0 KiB
Groff
.\" $NetBSD: spl.9,v 1.39 2010/02/16 19:21:30 rmind Exp $
|
|
.\"
|
|
.\" 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.
|
|
.\" 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 February 16, 2010
|
|
.Dt SPL 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm spl ,
|
|
.Nm spl0 ,
|
|
.Nm splhigh ,
|
|
.Nm splvm ,
|
|
.Nm splsched ,
|
|
.Nm splsoftbio ,
|
|
.Nm splsoftclock ,
|
|
.Nm splsoftnet ,
|
|
.Nm splsoftserial ,
|
|
.Nm splx
|
|
.Nd modify system interrupt priority level
|
|
.Sh SYNOPSIS
|
|
.In sys/intr.h
|
|
.Ft void
|
|
.Fn spl0 void
|
|
.Ft int
|
|
.Fn splhigh void
|
|
.Ft int
|
|
.Fn splsched void
|
|
.Ft int
|
|
.Fn splvm void
|
|
.Ft int
|
|
.Fn splsoftbio void
|
|
.Ft int
|
|
.Fn splsoftclock void
|
|
.Ft int
|
|
.Fn splsoftserial void
|
|
.Ft int
|
|
.Fn splsoftnet void
|
|
.Ft void
|
|
.Fn splx "int s"
|
|
.Sh DESCRIPTION
|
|
These functions raise and lower the interrupt priority level.
|
|
They are used by kernel code to block interrupts in critical
|
|
sections, in order to protect data structures.
|
|
.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.
|
|
To ensure correct synchronization, device drivers should use the
|
|
.Xr condvar 9 ,
|
|
.Xr mutex 9 ,
|
|
and
|
|
.Xr rwlock 9
|
|
interfaces.
|
|
.Pp
|
|
Interrupt priorities are arranged in a strict hierarchy, although
|
|
sometimes levels may be equivalent (overlap).
|
|
The hierarchy means that raising the IPL to any level will block
|
|
interrupts at that level, and at all lower levels.
|
|
The hierarchy is used to minimize data loss due to interrupts not
|
|
being serviced in a timely fashion.
|
|
.Pp
|
|
The levels may be divided into two groups: 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.
|
|
Software interrupts are further described by
|
|
.Xr softint 9 .
|
|
.Pp
|
|
Note that hard interrupt 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
|
|
In order of highest to lowest priority, the priority-raising functions
|
|
along with their counterpart symbolic tags are:
|
|
.Bl -tag -width splsoft
|
|
.It Fn splhigh , IPL_HIGH
|
|
.Pp
|
|
Blocks all hard and soft interrupts, including the highest level I/O
|
|
interrupts, such as interrupts from serial interfaces and the
|
|
statistics clock (if any).
|
|
It is also used for code that cannot tolerate any interrupts.
|
|
.Pp
|
|
Code running at this level may not (in general) directly access
|
|
machine independent kernel services.
|
|
For example, it is illegal to call the kernel
|
|
.Fn printf
|
|
function or to try and allocate memory.
|
|
The methods of synchronization available are: spin mutexes and
|
|
scheduling a soft interrupt.
|
|
Generally, all code run at this level must schedule additional
|
|
processing to run in a software interrupt.
|
|
.Pp
|
|
Code with thread context running at this level must not use a kernel
|
|
interface that may cause the current LWP to sleep, such as the
|
|
.Xr condvar 9
|
|
interfaces.
|
|
.Pp
|
|
Interrupt handlers at this level cannot acquire the global kernel_lock
|
|
and so must be coded to ensure correct synchronization on multiprocessor
|
|
systems.
|
|
.It Fn splsched , IPL_SCHED
|
|
.Pp
|
|
Blocks all medium priority hardware interrupts, such as interrupts
|
|
from audio devices, and the clock interrupt.
|
|
.Pp
|
|
Interrupt handlers running at this level endure the same restrictions as
|
|
at IPL_HIGH, but may access scheduler interfaces, and so may awaken LWPs
|
|
(light weight processes) using the
|
|
.Xr condvar 9
|
|
interfaces, and may schedule callouts using the
|
|
.Xr callout 9
|
|
interfaces.
|
|
.Pp
|
|
Code with thread context running at this level may sleep via the
|
|
.Xr condvar 9
|
|
interfaces, and may use other kernel facilities that could cause the
|
|
current LWP to sleep.
|
|
.It Fn splvm , IPL_VM
|
|
.Pp
|
|
Blocks hard interrupts from
|
|
.Dq low
|
|
priority hardware interrupts, such
|
|
as interrupts from network, block I/O and tty devices.
|
|
.Pp
|
|
Code running at this level endures the same restrictions as at IPL_SCHED,
|
|
but may use the deprecated
|
|
.Xr malloc 9
|
|
or endorsed
|
|
.Xr pool_cache 9
|
|
interfaces to allocate memory.
|
|
.Pp
|
|
At the time of writing, the global
|
|
.Dv kernel_lock
|
|
is automatically acquired for interrupts at this level, in order to
|
|
support device drivers that do not provide their own multiprocessor
|
|
synchronization.
|
|
A future release of the system may allow the automatic acquisition of
|
|
.Dv kernel_lock
|
|
to be disabled for individual interrupt handlers.
|
|
.It Fn splsoftserial , IPL_SOFTSERIAL
|
|
.Pp
|
|
Blocks soft interrupts at the IPL_SOFTSERIAL symbolic level.
|
|
.Pp
|
|
This is the first of the software levels.
|
|
Soft interrupts at this level and lower may acquire reader/writer
|
|
locks or adaptive mutexes.
|
|
.It Fn splsoftnet , IPL_SOFTNET
|
|
.Pp
|
|
Blocks soft interrupts at the IPL_SOFTNET symbolic level.
|
|
.It Fn splsoftbio , IPL_SOFTBIO
|
|
.Pp
|
|
Blocks soft interrupts at the IPL_SOFTBIO symbolic level.
|
|
.It Fn splsoftclock , IPL_SOFTCLOCK
|
|
.Pp
|
|
Blocks soft interrupts at the IPL_SOFTCLOCK symbolic level.
|
|
.Pp
|
|
This is the priority at which callbacks generated by the
|
|
.Xr callout 9
|
|
facility runs.
|
|
.El
|
|
.Pp
|
|
One function lowers the system priority level:
|
|
.Bl -tag -width splsoft
|
|
.It Fn spl0 , IPL_NONE
|
|
.Pp
|
|
Unblocks all interrupts.
|
|
This should rarely be used directly;
|
|
.Fn splx
|
|
should be used instead.
|
|
.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.
|
|
.Sh SEE ALSO
|
|
.Xr condvar 9 ,
|
|
.Xr i386/splraise 9 ,
|
|
.Xr kpreempt 9 ,
|
|
.Xr mutex 9 ,
|
|
.Xr rwlock 9
|
|
.Sh HISTORY
|
|
In
|
|
.Bx 4.4 ,
|
|
.Fn splnet
|
|
was used to block network software interrupts.
|
|
Most device drivers used
|
|
.Fn splimp
|
|
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
|
|
.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
|
|
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.
|
|
.Pp
|
|
Between
|
|
.Nx 4.0
|
|
and
|
|
.Nx 5.0 ,
|
|
the hardware levels were reduced in number and a strict hierarchy
|
|
defined.
|