softint(9) - NetBSD Manual Pages

SOFTINT(9)             NetBSD Kernel Developer's Manual             SOFTINT(9)


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 soft-
     ware interrupt mechanism which can be used any time a low-priority call-
     back is needed.

     It allows dynamic registration of software interrupts for loadable driv-
     ers 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 high-
     est) 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 exam-
     ple: 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 synchro-
     nization objects, sleep, and resume execution at a later time.

     Since software interrupts are a limited resource and run with higher pri-
     ority 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 per-
     form 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 con-
     dition variables or to wait for resources to become available (for exam-
     ple, 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.

NetBSD 8.1                      August 3, 2009                      NetBSD 8.1