SYSINIT(9)

💖 SYSINIT(9) 💖

okay so bestie, welcome to the Kernel Developer's Manual section 9, and today's main character is SYSINIT — the framework for dynamic kernel initialization. yes. we're doing kernel init routines and we're doing them cutely. let's go ✨

---

🌸 NAME 🌸

SYSINIT, SYSUNINIT — a framework for dynamic kernel initialization

---

✨ SYNOPSIS ✨

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

SYSINIT(uniquifier, enum sysinit_sub_id subsystem,
    enum sysinit_elem_order order, sysinit_cfunc_t func,
    const void *ident);

SYSUNINIT(uniquifier, enum sysinit_sub_id subsystem,
    enum sysinit_elem_order order, sysinit_cfunc_t func,
    const void *ident);

like, include both headers first, no skipping, that's the vibe check 🫶

---

💅 DESCRIPTION 💅

okay so SYSINIT is literally a mechanism for scheduling the execution of initialization and teardown routines. think init and fini routines but with the glow-up of explicit ordering metadata. it lets you order subsystem initialization at runtime, in the kernel and in kernel modules (KLDs). main character energy for your boot sequence, no cap 🔥

the SYSINIT() macro creates a struct sysinit and stores it in a startup linker set. the struct sysinit type, plus the subsystem identifier constants (SI_SUB_*) and the initialization ordering constants (SI_ORDER_*), are all defined in <sys/kernel.h>. here's the whole thing, exactly:

struct sysinit {
        enum sysinit_sub_id subsystem;  /* subsystem identifier*/
        enum sysinit_elem_order order;  /* init order within subsystem*/
        sysinit_cfunc_t func;           /* function             */
        const void      *udata;         /* multiplexer/argument */
};

the SYSINIT() macro takes a uniquifier argument to identify the particular function dispatch data, the subsystem type of startup interface, the order of initialization within the subsystem (subsystem element order, bestie), the func function to call, and the data specified in the ident argument that gets passed to the function. all five. every single time. 💖

the SYSUNINIT() macro behaves similarly to the SYSINIT() macro, except — plot twist — it adds the data to a shutdown linker set. different set, same energy.

the startup linker set for the kernel is scanned during boot to build a sorted list of initialization routines. those initialization routines are then executed in the sorted order. here's the sorting tea:

• the subsystem is used as the primary key and is sorted in ascending order
• the order is used as the secondary key and is sorted in ascending order
• the relative order of two routines that have the same subsystem and the same order is undefined 😭 so don't you dare rely on it

the startup linker sets for modules that are loaded together with the kernel by the boot loader get scanned during the SI_SUB_KLD subsystem initialization. those modules' initialization routines are sorted and merged into the kernel's list of startup routines, and they execute during boot right alongside the kernel's own initialization routines. ✨

heads up bestie: this has the effect that any initialization routines in a kernel module that are scheduled earlier than SI_SUB_KLD are not executed until after SI_SUB_KLD during boot. yes really. the ordering you wrote is not the ordering you get. iykyk 😭

the startup linker set for a kernel module loaded at runtime via kldload(2) is scanned, sorted, and executed when the module is loaded. 🦋

the shutdown linker set for a kernel module is scanned, sorted, and executed when a kernel module is unloaded. the teardown routines are sorted in the reverse order of the initialization routines. and — important — the teardown routines of the kernel and any loaded modules are not executed during shutdown. like, at all. periodt. 💀

---

🎀 EXAMPLES 🎀

this example shows the SYSINIT which displays the copyright notice during boot:

static void
print_caddr_t(void *data)
{
        printf("%s", (char *)data);
}
SYSINIT(announce, SI_SUB_COPYRIGHT, SI_ORDER_FIRST, print_caddr_t,
    copyright);

look at her. iconic. 👑

---

🌈 SEE ALSO 🌈

• kld(4)
• DECLARE_MODULE(9)
• DEV_MODULE(9)
• DRIVER_MODULE(9)
• MTX_SYSINIT(9)
• SYSCALL_MODULE(9)

go read those too, bestie, they're all part of the same friend group 🫶

---

🧚 HISTORY 🧚

the SYSINIT framework first appeared in FreeBSD 2.2. vintage. lowkey a classic. 💜

---

🌸 AUTHORS 🌸

the SYSINIT framework was written by Terrence Lambert <terry@FreeBSD.org>.

this manual page was written by Hiten Pandya <hmp@FreeBSD.org>.

---

and that's the whole page, bestie!! this one came to you from Debian, dated December 1, 2010, and it lives in section SYSINIT(9) of the manual. thank you for coming to my ted talk, go sort your subsystems in ascending order, drink some water, and slay 💖✨🎀🦋