ITHREAD(9)

💖 ITHREAD — kernel interrupt threads 💖

Section 9 of the Kernel Developer's Manual, bestie. This is the whole ithread_* family — the interrupt thread squad in the kernel. Pull up a chair, grab a boba, we're doing this. 🧋✨

---

✨ NAME ✨

ithread_add_handler, ithread_create, ithread_destroy, ithread_priority, ithread_remove_handler, ithread_schedule — kernel interrupt threads 🧵🔥

---

🌈 SYNOPSIS 🌈

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

int
ithread_add_handler(struct ithd *ithread, const char *name,
    driver_intr_t handler, void *arg, u_char pri, enum intr_type flags,
    void **cookiep);

int
ithread_create(struct ithd **ithread, int vector, int flags,
    void (*disable)(int), void (*enable)(int), const char *fmt, ...);

int
ithread_destroy(struct ithd *ithread);

u_char
ithread_priority(enum intr_type flags);

int
ithread_remove_handler(void *cookie);

int
ithread_schedule(struct ithd *ithread, int do_switch);

---

🦋 DESCRIPTION 🦋

Okay so. Interrupt threads are kernel threads that run a whole list of handlers whenever a hardware or software interrupt goes off. Main character energy, fr. 💅

Every single interrupt handler is packing:

• a name
• a handler function
• a handler argument
• a priority
• and various flags

Each interrupt thread keeps its handler list sorted by priority, which means higher priority handlers get executed before lower priority ones. Periodt. 📋 Each thread also takes on the priority of its highest priority handler as its process priority — or PRIO_MAX if it's got zero handlers, rip. 🙈 And every interrupt thread is tied to exactly one interrupt source, which is represented as a vector number.

ithread_create() — make a new thread, slay ✨

The ithread_create() function creates a new interrupt thread.

• ithread — points to a struct ithd pointer that, on success, will point to the newly created thread. 🫶
• vector — the interrupt source this thread gets associated with.
• flags — a mask of properties for this thread. The only valid flag currently for ithread_create() is IT_SOFT, which says this interrupt thread is a software interrupt.
• enable and disable — optional functions used to enable and disable this interrupt thread's interrupt source. They receive the vector corresponding to the thread's interrupt source as their only argument. 👑
• the remaining arguments — they form a printf(9) argument list used to build the base name of the new ithread.

The full name of an interrupt thread is made by concatenating the base name of the interrupt thread with the names of all of its interrupt handlers. It's giving collab. 🤝

ithread_destroy() — bye bye 🎀

The ithread_destroy() function destroys a previously created interrupt thread by releasing its resources and arranging for the backing kernel thread to terminate.

Heads up bestie: an interrupt thread can only be destroyed if it has no handlers remaining. No handlers, no problem. Otherwise? Problem. 💀

ithread_add_handler() — new handler just dropped 🍓

The ithread_add_handler() function adds a new handler to an existing interrupt thread specified by ithread.

• name — a name for this handler.
• handler and arg — the function to execute for this handler, and an argument to pass to it.
• pri — the priority of this handler. It's used both for sorting it against the other handlers for this thread and to specify the priority of the backing kernel thread.
• flags — properties of this handler, as defined in <sys/bus.h>.
• cookiep — if it is not NULL, it gets assigned a cookie you can use later to remove this handler. 🍪

ithread_remove_handler() — yeet that handler 🙅

The ithread_remove_handler() removes a handler from an interrupt thread. The cookie argument specifies the handler to remove from its thread.

ithread_schedule() — go go go 🏃

The ithread_schedule() function schedules an interrupt thread to run. If the do_switch argument is non-zero and the interrupt thread is idle, then a context switch will be forced after putting the interrupt thread on the run queue.

ithread_priority() — translator ✨

The ithread_priority() function translates the INTR_TYPE_* interrupt flags into interrupt handler priorities.

the extra flags 🚩

The interrupt flags that are not related to the type of a particular interrupt (INTR_TYPE_*) can be used to specify additional properties of both hardware and software interrupt handlers:

• INTR_EXCL — says this handler cannot share an interrupt thread with another handler. Exclusive! 💅
• INTR_MPSAFE — says this handler is MP safe, meaning it does not need the Giant mutex to be held while it executes.
• INTR_ENTROPY — says the interrupt source this handler is tied to is a good source of entropy, so entropy should be gathered when an interrupt from the handler's source triggers. 🌈 Presently, the INTR_ENTROPY flag is not valid for software interrupt handlers.

🚨 REAL TALK: It is not permitted to sleep in an interrupt thread. So any memory or zone allocations in an interrupt thread should be specified with the M_NOWAIT flag set. And any allocation errors must be handled thereafter. Don't skip that part, I'm begging. 😭

---

⭐ RETURN VALUES ⭐

• ithread_add_handler(), ithread_create(), ithread_destroy(), ithread_remove_handler(), and ithread_schedule() all return zero on success and non-zero on failure. 💀
• ithread_priority() returns a process priority corresponding to the passed in interrupt flags.

---

🎀 EXAMPLES 🎀

The swi_add() function demonstrates the use of ithread_create() and ithread_add_handler(). Look at her go:

int
swi_add(struct ithd **ithdp, const char *name, driver_intr_t handler,
            void *arg, int pri, enum intr_type flags, void **cookiep)
{
        struct proc *p;
        struct ithd *ithd;
        int error;

        if (flags & INTR_ENTROPY)
                return (EINVAL);

        ithd = (ithdp != NULL) ? *ithdp : NULL;

        if (ithd != NULL) {
                if ((ithd->it_flags & IT_SOFT) == 0)
                        return(EINVAL);
        } else {
                error = ithread_create(&ithd, pri, IT_SOFT, NULL, NULL,
                    "swi%d:", pri);
                if (error)
                        return (error);

                if (ithdp != NULL)
                        *ithdp = ithd;
        }
        return (ithread_add_handler(ithd, name, handler, arg, pri + PI_SOFT,
                    flags, cookiep));
}

---

💀 ERRORS 💀

ithread_add_handler() will fail if:

• [EINVAL] — Any of the ithread, handler, or name arguments are NULL.
• [EINVAL] — The INTR_EXCL flag is specified and the interrupt thread ithread already has at least one handler, or the interrupt thread ithread already has an exclusive handler.
• [ENOMEM] — Could not allocate needed memory for this handler.

ithread_create() will fail if:

• [EAGAIN] — The system-imposed limit on the total number of processes under execution would be exceeded. That limit is given by the sysctl(3) MIB variable KERN_MAXPROC.
• [EINVAL] — A flag other than IT_SOFT was specified in the flags parameter.
• [ENOMEM] — Could not allocate needed memory for this interrupt thread.

ithread_destroy() will fail if:

• [EINVAL] — The ithread argument is NULL.
• [EINVAL] — The interrupt thread pointed to by ithread has at least one handler.

ithread_remove_handler() will fail if:

• [EINVAL] — The cookie argument is NULL.

ithread_schedule() will fail if:

• [EINVAL] — The ithread argument is NULL.
• [EINVAL] — The interrupt thread pointed to by ithread has no interrupt handlers.

---

👀 SEE ALSO 👀

kthread(9), malloc(9), swi(9), uma(9)

---

📜 HISTORY 📜

Interrupt threads and their corresponding API first appeared in FreeBSD 5.0. Vintage. 🕰️

---

🐛 BUGS 🐛

Currently struct ithd represents both an interrupt source and an interrupt thread. There should be a separate struct isrc that contains a vector number, enable and disable functions, etc. that an ithread holds a reference to. Like, the design said "let's do both" and honestly? 😭 It's a known thing.

---

And that's the whole page, bestie! This one came out of the Debian build of the Kernel Developer's Manual, dated August 25, 2006. Go forth and schedule some interrupts. 💖✨🦋