--- name: "swi" section: "9" platform: "linux" package: "freebsd-manpages" version: "6.0-5" release: "Debian 4.0 (Etch)" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/swi" --- # swi(9) register and schedule software interrupt handlers ## NAME **swi\_add**, **swi\_sched** – register and schedule software interrupt handlers ## SYNOPSIS **#include \** **#include \** **#include \** *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)](/sysctl/3.md) 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)](/ithread/9.md), [taskqueue(9)](/taskqueue/9.md) ## 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 ⟨sys/interrupt.h⟩.