SYSINIT(9)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💖 SYSINIT(9) — the kernel dev manual, bestie edition 💖

okay so this is SYSINIT(9) from the Kernel Developer's Manual, and honestly? it's giving backstage-pass-to-the-kernel energy. sit down, grab a strawberry drink 🍓, we're learning how the kernel schedules its own glow-up.

✨ NAME ✨

SYSINIT, SYSUNINIT — a framework for dynamic kernel initialization. literally the vibe coordinator for when stuff starts up and shuts down 💅

🎀 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);

bestie. copy these exactly. character for character. no creative liberties, i'm begging 🫶

🦋 DESCRIPTION 🦋

SYSINIT is a mechanism for scheduling the execution of initialization and teardown routines. think of it like init and fini routines but with ✨extra✨ — the addition of explicit ordering metadata. it lets the kernel order subsystem initialization at runtime, and it works for kernel modules (KLDs) too. main character framework, honestly 👑

the SYSINIT() macro creates a struct sysinit and stores it in a startup linker set. the struct sysinit type, the subsystem identifier constants (SI_SUB_*) and the initialization ordering constants (SI_ORDER_*) all live in <sys/kernel.h>:

struct sysinit {
        enum sysinit_sub_id subsystem;  /* subsystem identifier*/
        enum sysinit_elem_order order;  /* init order within subsystem*/
        SLIST_ENTRY(sysinit) next;      /* singly-linked list */
        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 subsystem element order of initialization within the subsystem, the func function to call, and the data specified in the ident argument to pass the function. yeah it's a lot of arguments. it ate though 💅

the SYSUNINIT() macro behaves similarly to the SYSINIT() macro except that it adds the data to a shutdown linker set. same energy, opposite direction 🔄

the startup linker set for the kernel is scanned during boot to build a sorted list of initialization routines. then those routines get executed in sorted order. the subsystem is the primary key and sorts in ascending order. the order is the secondary key and also sorts in ascending order. and for two routines with the same subsystem and the same order? the relative order is undefined — so don't @ me, that's just how it is 😭

the startup linker sets for modules loaded together with the kernel by the boot loader are 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're executed during boot along with the kernel's initialization routines. heads up though: this means any initialization routines in a kernel module scheduled earlier than SI_SUB_KLD are not executed until after SI_SUB_KLD during boot. the timeline said no 🙈

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

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 the teardown routines of the kernel and any loaded modules are not executed during shutdown — yep, that's real, it's right there in the fine print 💀

🌈 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);

iconic little function. does one thing and does it well 🎀

🌸 SEE ALSO 🌸

the whole friend group, fr fr 🫶

⭐ HISTORY ⭐

the SYSINIT framework first appeared in FreeBSD 2.2. vintage. lowkey a legend 🕰️

👑 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, no cap, every single detail preserved 💖 go forth and order your subsystems responsibly ✨

— cute lil sign-off: this was the Debian build, dated December 1, 2010, filed under SYSINIT(9). periodt 💅🌟

📦 where this page comes from