DECLARE_MODULE(9)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💅 DECLARE_MODULE(9) — like, the kernel module declaration macro bestie 💅

okay so this is a page from the Kernel Developer's Manual (section 9, the big-kid kernel section, iykyk) and it's literally all about DECLARE_MODULE — the macro that tells your kernel "hey bestie, here's a module, please register it" 🎀

✨ NAME ✨

DECLARE_MODULE — the kernel module declaration macro. that's it, that's the vibe 💖

🌸 SYNOPSIS 🌸

the includes first, always, no skipping:

#include <sys/param.h>
#include <sys/kernel.h>
#include <sys/module.h>

and then the actual stars of the show:

DECLARE_MODULE(name, moduledata_t data, sub, order);

DECLARE_MODULE_TIED(name, moduledata_t data, sub, order);

two macros, same argument shape, very demure, very mindful 🦋

🔥 DESCRIPTION 🔥

so DECLARE_MODULE() declares a generic kernel module. it's the thing that registers your module with the system, and it does it by using the SYSINIT() macro under the hood (yes, that one 👀).

fr fr, DECLARE_MODULE() is usually used inside other macros — like DRIVER_MODULE(9), DEV_MODULE(9) and SYSCALL_MODULE(9). those are the popular girlies. but you can absolutely call it directly too, for example if you wanna implement dynamic sysctls. main character energy either way 👑

🧚 the TIED variant (the picky one)

a module declared with DECLARE_MODULE_TIED() will load only if the running kernel version (as specified by __FreeBSD_version) is identical to the one it was built on. like, exact match. no substitutions. periodt 💅

this declaration should be used by modules that depend on interfaces beyond the stable kernel KBI — think ABI emulators or hypervisors that rely on internal kernel structures. those ones are living dangerously, they need the strict version 🙈

and plot twist: DECLARE_MODULE() will behave like DECLARE_MODULE_TIED() when compiled with modules built with the kernel. why? because that allows locks and other synchronization primitives to be inlined safely. slay, safety first 💀

🍓 the arguments (all four of them, in order)

  • name — the module name, bestie. it gets used in the SYSINIT() call to identify the module. your name tag at the kernel party 🎀
  • data — a moduledata_t structure. it's holding two main items: the official name of the module name (yes, that's how the page says it — it's the name that'll be used in the module_t structure), and a pointer to the event handler function of type modeventhand_t. so: name + vibes-callback ✨
  • sub — an argument directed to the SYSINIT() macro. valid values for this live in the sysinit_sub_id enumeration (see <sys/kernel.h>) and they specify the type of system startup interfaces. example time: the DRIVER_MODULE(9) macro uses a value of SI_SUB_DRIVERS here, because those modules contain a driver for a device. and for kernel modules that are loaded at runtime, a value of SI_SUB_EXEC is common. pick your lane 🌈
  • order — an argument for SYSINIT(). it represents the KLDs order of initialization within the subsystem. valid values are defined in the sysinit_elem_order enumeration (<sys/kernel.h>). line up in order, no cutting 🧚‍♀️

🦋 SEE ALSO 🦋

and the actual files, in case you wanna snoop:

  • /usr/include/sys/kernel.h
  • /usr/share/examples/kld

👑 AUTHORS 👑

this manual page was written by Alexander Langer <alex@FreeBSD.org>, inspired by the KLD Facility Programming Tutorial by Andrew Reiter <arr@watson.org>. legends, both of them 🫶

ngl, this whole thing is a Debian page dated February 13, 2018 — vintage, iconic, still eating 💖

that's the page, bestie — go forth and declare your modules 💅✨

📦 where this page comes from