DECLARE_MODULE(9)

💖 DECLARE_MODULE — bestie edition 💖

okay so welcome to the DECLARE_MODULE(9) page, part of the Kernel Developer's Manual, section 9, and no I will not be normal about this one because it's literally the moment your kernel module goes from "a folder of vibes" to "registered with the actual system". 🌸

✨ NAME ✨

DECLARE_MODULE — the kernel module declaration macro, aka the glow-up line that makes your module official 💅

🎀 SYNOPSIS 🎀

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

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

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

🦋 DESCRIPTION 🦋

The DECLARE_MODULE() macro declares a generic kernel module. It's how you register the module with the system, and it does that by leaning on the SYSINIT() macro behind the scenes. Sneaky? No. Iconic? Yes. 👑

DECLARE_MODULE() is usually used within other macros — think DRIVER_MODULE(9), DEV_MODULE(9) and SYSCALL_MODULE(9). But bestie, it can absolutely be called directly too, for example if you want to implement dynamic sysctls. Main character behavior only. ✨

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. Not similar. Not close enough. Identical. 🫶 This declaration should be used by modules that depend on interfaces beyond the stable kernel KBI — like ABI emulators, or hypervisors that rely on internal kernel structures. DECLARE_MODULE() will behave like DECLARE_MODULE_TIED() when compiled with modules built with the kernel. Why do we care? Because it allows locks and other synchronization primitives to be inlined safely. 🔥

Now, the arguments, one by one, because we do not skip details in this house:

• name — the module name. It gets used in the SYSINIT() call to identify the module. That's its whole job and it does it flawlessly. 💜
• data — a moduledata_t structure. It holds two main things: the official name of the module (used in the module_t structure) and a pointer to the event handler function of type modeventhand_t.
• sub — an argument directed to the SYSINIT() macro. Valid values live in the sysinit_sub_id enumeration (peep <sys/kernel.h>) and they specify the type of system startup interfaces. The DRIVER_MODULE(9) macro uses a value of SI_SUB_DRIVERS here, for example, since those modules contain a driver for a device. For kernel modules loaded at runtime, a value of SI_SUB_EXEC is common.
• 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>).

🌈 SEE ALSO 🌈

• DEV_MODULE(9)
• DRIVER_MODULE(9)
• module(9)
• SYSCALL_MODULE(9)
• /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>. absolute legends, we stan 🫶✨

okay that's the whole page, go forth and declare your modules bestie, ily 💖

— this cutie was brought to you by Debian, dated February 13, 2018 🎀