NAME
swi_add, swi_sched - register and schedule software interrupt handlers
SYNOPSIS
#include <sys/param.h>
#include <sys/bus.h>
#include <sys/interrupt.h>
extern struct ithd *tty_ithd;
extern struct ithd *clk_ithd;
extern void *net_ih;
extern void *softclock_ih;
extern void *vm_ih;
int
swi_add(struct ithd **ithdp, const char *name, driver_intr_t handler,
void *arg, int pri, enum intr_type flags, void **cookiep);
void
swi_sched(void *cookie, int flags);
DESCRIPTION
These functions are used to register and schedule software interrupt
handlers. Software interrupt handlers are attached to a software
interrupt thread, just as hardware interrupt handlers are attached to a
hardware interrupt thread. Multiple handlers can be attached to the same
thread. Software interrupt handlers can be used to queue up less
critical processing inside of hardware interrupt handlers so that the
work can be done at a later time. Software interrupt threads are
different from other kernel threads in that they are treated as an
interrupt thread. This means that time spent executing these threads is
counted as interrupt time, and that they can be run via a lightweight
context switch.
The swi_add() function is used to register a new software interrupt
handler. The ithdp argument is an optional pointer to a struct ithd
pointer. If this argument points to an existing software interrupt
thread, then this handler will be attached to that thread. Otherwise a
new thread will be created, and if ithdp is not NULL, then the pointer at
that address to will be modified to point to the newly created thread.
The name argument is used to associate a name with a specific handler.
This name is appended to the name of the software interrupt thread that
this handler is attached to. The handler argument is the function that
will be executed when the handler is scheduled to run. The arg parameter
will be passed in as the only parameter to handler when the function is
executed. The pri value specifies the priority of this interrupt handler
relative to other software interrupt handlers. If an interrupt thread is
created, then this value is used as the vector, and the flags argument is
used to specify the attributes of a handler such as INTR_MPSAFE. The
cookiep argument points to a void * cookie. This cookie will be set to a
value that uniquely identifies this handler, and is used to schedule the
handler for execution later on.
The swi_sched() function is used to schedule an interrupt handler and its
associated thread to run. The cookie argument specifies which software
interrupt handler should be scheduled to run. The flags argument
specifies how and when the handler should be run and is a mask of one or
more of the following flags:
SWI_DELAY Specifies that the kernel should mark the specified handler as
needing to run, but the kernel should not schedule the
software interrupt thread to run. Instead, handler will be
executed the next time that the software interrupt thread runs
after being scheduled by another event. Attaching a handler
to the clock software interrupt thread and using this flag
when scheduling a software interrupt handler can be used to
implement the functionality performed by setdelayed() in
earlier versions of FreeBSD.
The tty_ithd and clk_ithd variables contain pointers to the software
interrupt threads for the tty and clock software interrupts,
respectively. tty_ithd is used to hang tty software interrupt handlers
off of the same thread. clk_ithd is used to hang delayed handlers off of
the clock software interrupt thread so that the functionality of
setdelayed() can be obtained in conjunction with SWI_DELAY. The net_ih,
softclock_ih, and vm_ih handler cookies are used to schedule software
interrupt threads to run for the networking stack, clock interrupt, and
VM subsystem respectively.
RETURN VALUES
The swi_add() function returns zero on success and non-zero on failure.
ERRORS
The swi_add() function will fail if:
[EAGAIN] The system-imposed limit on the total number of
processes under execution would be exceeded. The
limit is given by the sysctl(3) MIB variable
KERN_MAXPROC.
[EINVAL] The flags argument specifies either INTR_ENTROPY or
INTR_FAST.
[EINVAL] The ithdp argument points to a hardware interrupt
thread.
[EINVAL] Either of the name or handler arguments are NULL.
[EINVAL] The INTR_EXCL flag is specified and the interrupt
thread pointed to by ithdp already has at least one
handler, or the interrupt thread already has an
exclusive handler.
SEE ALSO
ithread(9), taskqueue(9)
HISTORY
The swi_add() and swi_sched() functions first appeared in FreeBSD 5.0.
They replaced the register_swi() function which appeared in FreeBSD 3.0
and the setsoft*(), and schedsoft*() functions which date back to at
least 4.4BSD.
BUGS
Most of the global variables described in this manual page should not be
global, or at the very least should not be declared in