swi

SWI(9)                    BSD Kernel Developer's Manual                   SWI(9)

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

BSD                              April 19, 2012                              BSD