NAME
softint,
softint_establish,
softint_disestablish,
softint_schedule
—
machine-independent software interrupt
framework
SYNOPSIS
#include <sys/intr.h>
void *
softint_establish(
u_int
flags,
void (*func)(void
*),
void *arg);
void
softint_disestablish(
void
*cookie);
void
softint_schedule(
void
*cookie);
DESCRIPTION
The software interrupt framework is designed to provide a generic software
interrupt mechanism which can be used any time a low-priority callback is
needed.
It allows dynamic registration of software interrupts for loadable drivers and
protocol stacks, prioritization and fair queueing of software interrupts, and
allows machine-dependent optimizations to reduce cost.
Four priority levels are provided. In order of priority (lowest to highest) the
levels are: clock, bio, net, serial. The names are symbolic and in isolation
do not have any direct connection with a particular kind of device activity:
they are only meant as a guide.
The four priority levels map directly to scheduler priority levels, and where
the architecture implements “fast” software interrupts, they also
map onto interrupt priorities. The interrupt priorities are intended to be
hidden from machine independent code, which should in general use thread-safe
mechanisms to synchronize with software interrupts (for example: mutexes).
Software interrupts run with limited machine context. In particular, they do not
possess any address space context. They should not try to operate on user
space addresses, or to use virtual memory facilities other than those noted as
interrupt safe. Unlike hardware interrupts, software interrupts do have thread
context. They may block on synchronization objects, sleep, and resume
execution at a later time.
Since software interrupts are a limited resource and run with higher priority
than most other LWPs in the system, all block-and-resume activity by a
software interrupt must be kept short to allow further processing at that
level to continue. By extension, code running with process context must take
care to ensure that any lock that may be taken from a software interrupt can
not be held for more than a short period of time.
The kernel does not allow software interrupts to use facilities or perform
actions that are likely to block for a significant amount of time. This means
that it's not valid for a software interrupt to sleep on condition variables
or to wait for resources to become available (for example, memory).
The following is a brief description of each function in the framework:
-
-
- softint_establish(flags,
func, arg)
-
Register a software interrupt. The flags value must
contain one of the following constants, specifing the priority level for
the soft interrupt:
SOFTINT_CLOCK
, SOFTINT_BIO
,
SOFTINT_NET
,
SOFTINT_SERIAL
If the constant SOFTINT_MPSAFE
is not logically ORed
into flags, the global
kernel_lock
will automatically be acquired before
the soft interrupt handler is called.
The constant func specifies the function to call when
the soft interrupt is executed. The argument arg
will be passed to this function.
softint_establish() may block in order to allocate memory.
If successful, it returns a non-NULL
opaque value
to be used as an argument to softint_schedule() and/or
softint_disestablish(). If for some reason it does not
succeed, it returns NULL
.
-
-
- softint_disestablish(cookie)
-
Deallocate a software interrupt previously allocated by a call to
softint_establish().
-
-
- softint_schedule(cookie)
-
Schedule a software interrupt previously allocated by a call to
softint_establish() to be executed as soon as that
software interrupt is unblocked. softint_schedule() can
safely be called multiple times before the callback routine is invoked.
Soft interrupt scheduling is CPU-local. A request to dispatch a soft
interrupt will only be serviced on the same CPU where the request was
made. The LWPs (light weight processes) dedicated to soft interrupt
processing are bound to their home CPUs, so if a soft interrupt handler
sleeps and later resumes, it will always resume on the same CPU.
On a system with multiple processors, multiple instances of the same soft
interrupt handler can be in flight simultaneously (at most one
per-CPU).
SEE ALSO
callout(9),
condvar(9),
kthread(9),
mutex(9),
rwlock(9),
spl(9),
workqueue(9)
HISTORY
The
NetBSD machine-independent software interrupt
framework was designed in 1997 and was implemented by one port in
NetBSD 1.3. However, it did not gain wider
implementation until
NetBSD 1.5. Between
NetBSD 4.0 and
NetBSD 5.0 the
framework was re-implemented in a machine-independent way to provide software
interrupts with thread context.