Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
SWI(9)                 FreeBSD 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>.

FreeBSD 11.0-PRERELEASE         April 19, 2012         FreeBSD 11.0-PRERELEASE

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | HISTORY | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=swi&manpath=FreeBSD+10.3-RELEASE+and+Ports>

home | help