NAME

     swi_add, swi_remove, swi_sched — register and schedule software interrupt handlers

SYNOPSIS

     #include <sys/param.h>
     #include <sys/bus.h>
     #include <sys/interrupt.h>

     extern struct intr_event *tty_intr_event;
     extern struct intr_event *clk_intr_event;
     extern void *vm_ih;

     int
     swi_add(struct intr_event **eventp, const char *name, driver_intr_t handler, void *arg,
         int pri, enum intr_type flags, void **cookiep);

     int
     swi_remove(void *cookie);

     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 add a new software interrupt handler to a specified
     interrupt event.  The eventp argument is an optional pointer to a struct intr_event pointer.
     If this argument points to an existing event that holds a list of interrupt handlers, then
     this handler will be attached to that event.  Otherwise a new event will be created, and if
     eventp is not NULL, then the pointer at that address to will be modified to point to the
     newly created event.  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 event 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_remove() function is used to teardown an interrupt handler pointed to by the cookie
     argument.  It detaches the interrupt handler from the associated interrupt event and frees
     its memory.

     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_intr_event and clk_intr_event variables contain pointers to the software interrupt
     handlers for the tty and clock software interrupts, respectively.  tty_intr_event is used to
     hang tty software interrupt handlers off of the same thread.  clk_intr_event 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 vm_ih handler cookie is
     used to schedule software interrupt threads to run for the VM subsystem.

RETURN VALUES

     The swi_add() and swi_remove() functions return 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 INTR_ENTROPY.

     [EINVAL]           The eventp 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 event pointed to by
                        eventp already has at least one handler, or the interrupt event already
                        has an exclusive handler.

     The swi_remove() function will fail if:

     [EINVAL]           A software interrupt handler pointed to by cookie is NULL.

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.  The swi_remove() function first appeared in
     FreeBSD 6.1.

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 <sys/interrupt.h>.