SWI(9)

💖 SWI 💖

okay bestie, sit down, hydrate, and let me tell you about swi_add, swi_remove and swi_sched — the software interrupt handler girlies of the FreeBSD kernel. this is from the Kernel Developer's Manual, section 9, and it's genuinely so good. 🎀

---

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

so these functions are the whole point of the page, and what they do is register and schedule software interrupt handlers. 💅 software interrupt handlers get attached to a software interrupt thread, exactly the same way hardware interrupt handlers get attached to a hardware interrupt thread. and the way multiple handlers can be attached to the same thread?? iconic. lowkey the whole design.

the reason you'd even want this: software interrupt handlers let you queue up the less critical processing from inside a hardware interrupt handler, so that work can be done at a later time. deferring, but make it cute. ✨

and here's the thing that makes software interrupt threads special — they're not like other kernel threads. they're treated as an interrupt thread. which means:

• time spent executing these threads counts as interrupt time
• they can be run via a lightweight context switch

main character energy, honestly. 👑

---

🌸 swi_add() 🌸

swi_add() adds a new software interrupt handler to a specified interrupt event. let's go through the args because every single one matters:

• eventp — an optional pointer to a struct intr_event pointer. if it points to an existing event that holds a list of interrupt handlers, then your handler gets attached to that event. otherwise, a new event gets created, and if eventp is not NULL, then the pointer at that address gets modified to point to the newly created event. 🫶
• name — associates a name with a specific handler. this name is appended to the name of the software interrupt thread that this handler is attached to.
• handler — the function that will be executed when the handler is scheduled to run.
• arg — passed in as the only parameter to handler when the function is executed.
• pri — 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.
• flags — specifies the attributes of a handler, such as INTR_MPSAFE.
• cookiep — points to a void * cookie. this cookie gets set to a value that uniquely identifies this handler, and it's used to schedule the handler for execution later on. keep it safe, bestie. 🎀

---

🌸 swi_remove() 🌸

swi_remove() tears down an interrupt handler pointed to by the cookie argument. it detaches the interrupt handler from the associated interrupt event and frees its memory. it's giving cleanup era. 🧚

---

🌸 swi_sched() 🌸

swi_sched() schedules an interrupt handler and its associated thread to run. the cookie argument says which software interrupt handler should be scheduled to run. the flags argument says how and when it should run, and it's a mask of one or more</s> of these flags:

• SWI_DELAY — says 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. ✨
• SWI_FROMNMI — says that swi_sched() is called from NMI context and should be careful about used KPIs. on platforms allowing IPI sending from NMI context it immediately wakes clk_intr_event via the IPI, otherwise it works just like SWI_DELAY. 🙈

---

🌸 the global girlies 🌸

• tty_intr_event and clk_intr_event are 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.
• vm_ih is the handler cookie used to schedule software interrupt threads to run for the VM subsystem. 🦋

---

✨ RETURN VALUES ✨

swi_add() and swi_remove() return zero on success and non-zero on failure. that's it, that's the whole vibe check. 💅

---

✨ ERRORS ✨

😭 swi_add() 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.

😭 swi_remove() will fail if:

• [EINVAL] — a software interrupt handler pointed to by cookie is NULL.

---

✨ SEE ALSO ✨

• ithread(9)
• taskqueue(9)

go read those too, they're part of the lore. 🫶

---

✨ HISTORY ✨

• swi_add() and swi_sched() 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.
• swi_remove() first appeared in FreeBSD 6.1.

the glow-up is real, no cap. 👑

---

✨ 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>. not me exposing the whole thing 💀

---

and that's the page, bestie!! this one came from the Debian crew, dated July 25, 2020 — swi(9), kernel developer's manual, forever iconic. mwah 💖✨🎀