swi(9)

NAME

swi_add, swi_sched - register and schedule software inter

rupt 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 soft

ware 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 dif

ferent from
other kernel threads in that they are treated as an inter

rupt thread.
This means that time spent executing these threads is count

ed as interrupt time, and that they can be run via a lightweight con

text 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 cre

ated thread.
The name argument is used to associate a name with a specif

ic 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 in

terrupt handler
relative to other software interrupt handlers. If an inter

rupt 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_MP

SAFE. 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 ar

gument 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 speci

fied handler as

needing to run, but the kernel should not sched

ule 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. Attach

ing 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 in

terrupt 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 pro

cesses under execution would be exceeded.

The limit
is given by the sysctl(3) MIB variable

KERN_MAXPROC.

[EINVAL] The flags argument specifies either IN

TR_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

BSD October 30, 2000

BSD