INTRMAP_CREATE(9)

✨ INTRMAP_CREATE — the interrupt-to-CPU mapping API 💅

okay so bestie, this is the INTRMAP_CREATE(9) page from the Kernel Developer's Manual, and it's genuinely such a serve. it's all about how hardware drivers get to use multiple CPUs at once, and honestly? iconic. let's get into it 🫶

---

🌸 NAME 🌸

intrmap_create, intrmap_destroy, intrmap_count, intrmap_cpu — the interrupt to CPU mapping API, aka the whole little friend group of functions that lets your driver spread its interrupts across CPUs 💖

---

🎀 SYNOPSIS 🎀

#include <sys/intrmap.h>

struct intrmap *
intrmap_create(const struct device *dv, unsigned int nintr,
    unsigned int maxintr, unsigned int flags);

void
intrmap_destroy(struct intrmap *im);

unsigned int
intrmap_count(struct intrmap *im);

struct cpu_info *
intrmap_cpu(struct intrmap *im, unsigned int index);

like yes, that's the whole squad right there ⭐

---

🦋 DESCRIPTION 🦋

so the interrupt to CPU mapping API is literally there to support hardware drivers using multiple CPUs. drivers that can use multiple interrupts hit up this API to request a set of CPUs that they can establish those interrupts on. the API lowkey keeps the requested number of interrupts within what's actually available on the system, and it tries to distribute the requested interrupts over those CPUs. on some platforms the API will filter the set of available CPUs too — vibe check on the CPUs, basically 💅

intrmap_create() allocates an interrupt map data structure for the driver identified by dv. the number of interrupts the hardware supports goes in the nintr argument. the driver supplies the maximum number of interrupts it can support via maxintr, which — along with the number of available CPUs at the time the function is called — is used as a constraint on the number of requested interrupts. nintr may be zero to use the driver limit as the number of requested interrupts. 🍓

the flags argument may have the following defines OR'ed together:

• INTRMAP_POWEROF2 — the hardware only supports a power of 2 number of interrupts, so constrain the number of supplied interrupts after the system and driver limits are applied. no cap, math first, power-of-2 second ✨

intrmap_destroy() frees the memory associated with the interrupt map data structure passed via im. bye bestie, releasing your memory 🫶

intrmap_count() returns the number of interrupts that the driver can establish according to the im interrupt map. it's giving "how many do you actually get" energy 🔥

intrmap_cpu() returns which CPU the interrupt specified in index should be established on, according to the im interrupt map. interrupts are identified as a number from 0 to the value returned by intrmap_count(). so like, index 0 through intrmap_count() minus one, iykyk 💀

---

💜 CONTEXT 💜

intrmap_create(), intrmap_destroy(), intrmap_count(), and intrmap_cpu() can all be called during autoconf, or from process context. either era, they're ready 💖

---

👑 RETURN VALUES 👑

• intrmap_create() — returns a pointer to an interrupt mapping structure on success, or NULL on failure. so like, check for NULL, bestie, that's the whole point 🙈
• intrmap_count() — returns the number of interrupts that were allocated for the driver to use.
• intrmap_cpu() — returns a pointer to the cpu_info structure for the CPU that the interrupt should be established on.

---

🌈 HISTORY 🌈

the interrupt mapping API is based on the if_ringmap API in DragonFly. it was ported to OpenBSD 6.8 by David Gwynne <dlg@openbsd.org>. shoutout, periodt 💐

---

ngl bestie, if you're writing a driver that wants multiple interrupts across multiple CPUs, this is the API. go slay 🧚

---

and that's the whole page, fr fr! this gem is from the Debian build of the Kernel Developer's Manual, dated July 31, 2022 — so cute, so iconic, and now you know all of it 💖✨🎀