BUS_DESCRIBE_INTR(9)

💖 BUS_DESCRIBE_INTR 💖

ok so bestie, welcome to BUS_DESCRIBE_INTR(9), part of the Kernel Developer's Manual ✨ — it's the one that lets you name your interrupt handlers, and honestly? iconic.

✨ NAME ✨

BUS_DESCRIBE_INTR, bus_describe_intr — associate a description with an active interrupt handler 🎀

🌸 SYNOPSIS 🌸

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

int
BUS_DESCRIBE_INTR(device_t dev, device_t child, struct resource *irq,
    void *cookie, const char *descr);

int
bus_describe_intr(device_t dev, struct resource *irq, void *cookie,
    const char *fmt, ...);

🦋 DESCRIPTION 🦋

So the BUS_DESCRIBE_INTR() method slaps a description onto an active interrupt handler. That's the whole vibe. 💅

Heads up tho — the cookie parameter must be the value that a successful call to BUS_SETUP_INTR(9) returned for the interrupt irq. Like, no substitutes, no random pointers, no vibes-based cookies. 🙈

Meanwhile bus_describe_intr() is just a cute little wrapper around BUS_DESCRIBE_INTR(). As a convenience (and honestly, a serve), bus_describe_intr() lets the caller build the description string using printf(9)-style formatting via fmt. 🍓

Now here's the lore: when an interrupt handler gets established by BUS_SETUP_INTR(9), that handler is named after the device it's established for. That name then shows up in various places — like the interrupt statistics displayed by systat(1) and vmstat(8). 📊

For devices that use a single interrupt, the device name is already unique enough to identify the interrupt handler, no notes. But for devices that use multiple interrupts? bestie, it's lowkey useful to be able to tell those handlers apart. 👀 So when a description is set for an active interrupt handler, a colon followed by the description gets appended to the device name to form the interrupt handler name. periodt. ✨

💜 RETURN VALUES 💜

Zero is returned on success. Otherwise, an appropriate error comes back at you. That's it, that's the deal. 😌

🌈 SEE ALSO 🌈

• systat(1)
• vmstat(8)
• BUS_SETUP_INTR(9)
• device(9)
• printf(9)

👑 HISTORY 👑

The BUS_DESCRIBE_INTR() method and the bus_describe_intr() functions first appeared in FreeBSD 8.1. throwback fr fr 🫶

💀 BUGS 💀

It is not currently possible to remove a description from an active interrupt handler. So like… choose your description wisely, because it's staying. no take-backsies. 😭

and that's the whole page, bestie!! 🧚 this lil writeup came from Debian, dated December 9, 2015, and it lives under the name BUS_DESCRIBE_INTR(9) 💖✨ mwah, go name some interrupts, ily 🎀