FIRMLOAD(9)

💅 FIRMLOAD — the firmware loader API, explained

okay so bestie, welcome to firmload (that's the name, and yes it's section 9 of the Kernel Developer's Manual — kernel dev territory, main character energy only). it's the Firmware loader API for device drivers, and honestly? it's giving "simple and convenient." let's get into it 🎀

---

✨ NAME ✨

firmload — the Firmware loader API for device drivers. like, your driver needs a firmware image from the filesystem? this is the glow-up it needs 🦋

---

📜 SYNOPSIS ✨

#include <dev/firmload.h>

int
firmware_open(const char *drvname, const char *imgname,
    firmware_handle_t *fhp);

int
firmware_close(firmware_handle_t fh);

off_t
firmware_get_size(firmware_handle_t fh);

int
firmware_read(firmware_handle_t fh, off_t offset, void *buf,
    size_t size);

void *
firmware_malloc(size_t size);

void
firmware_free(void *buf, size_t size);

look at all these little icons, they're all so iconic 💖

---

🌸 DESCRIPTION 🌸

firmload gives device drivers a simple and convenient API to load firmware images from files that live in the file system — the ones the devices they control literally cannot function without. no firmware, no vibes.

so where do these images live? they're in sub-directories, one directory per driver, sitting inside a series of colon-separated path prefixes. and those prefixes are specified by the sysctl variable hw.firmware.path. that's the whole system, periodt ✨

---

💅 FUNCTIONS 💅

these are the functions the firmload API hands you, one by one, no gatekeeping:

🫶 firmware_open(drvname, imgname, fhp)

opens the firmware image imgname for the driver drvname. the path to the firmware image file gets constructed by appending the string /drvname/imgname to each configured path prefix — and it keeps going through them until opening the firmware image file actually succeeds, iykyk.

upon success, firmware_open() returns 0 and stores a firmware image handle in the location pointed to by fhp. otherwise, an error code is returned to indicate the reason for failure 😭 (read it, bestie, it's telling you what went wrong).

🫶 firmware_close(fh)

closes the firmware image file associated with the firmware handle fh. returns 0 upon success, or an error code to indicate the reason for failure. clean exits only 🌈

🫶 firmware_get_size(fh)

returns the size of the image file associated with the firmware handle fh. yes it's an off_t, no we're not debating it 💅

🫶 firmware_read(fh, offset, buf, size)

reads from the image file associated with the firmware handle fh, beginning at offset for length size. the firmware image data lands in the buffer specified by buf. returns 0 upon success, or an error code to indicate the reason for failure. the way that it just fills your buffer... obsessed 🔥

🫶 firmware_malloc(size)

allocates a region of wired kernel memory of size size.

💀 note: firmware_malloc() may block. like, fr fr. don't be weird about it in contexts where blocking is a problem.

🫶 firmware_free(buf, size)

frees a region of memory previously allocated by firmware_malloc(). the circle of life, and it ate 🎀

---

🗂️ FILES ✨

the default search path for firmware, in all its glory:

• /libdata/firmware
• /usr/libdata/firmware
• /usr/pkg/libdata/firmware
• /usr/pkg/libdata

four little homes, all valid 💜

---

👀 SEE ALSO 👑

• autoconf(9)
• malloc(9)
• vnsubr(9)

go read them, bestie, they're all part of the same friend group 🌸

---

⭐ HISTORY ⭐

the firmload framework first appeared in NetBSD 4.0. a legend from the jump 👑

---

🧚 AUTHORS 🧚

• Jason Thorpe <thorpej@NetBSD.org>

ty for your service, king 🫶

---

okay and for the credits scroll at the end of the movie: this page came from Debian, dated March 16, 2018 — so if you were wondering when this little slice of documentation was born, now you know ✨💖 bye bestie, go load some firmware 🦋