FreeBSD kmodloader — porting plan

A FreeBSD-only daemon that ensures every hardware-class kernel module on the system autoloads at boot when its hardware is detected. Default FreeBSD does not do this aggressively (especially for GPU drivers and the third-party drm-kmod / nvidia stacks); this project closes that gap. Companion to freebsd-launchd and freebsd-configd.

1. Goal & non-goals

1.1 Goal

When hardware is present at boot, the kernel module that drives it loads without manual configuration. The user installs the system, plugs in their hardware, the system works. Zero kld_list= edits, zero kldload invocations from the user.

1.2 Non-goals (this iteration)

• No kernel patches. We use FreeBSD's existing tools (devmatch, pciconf, sysctl); we don't modify the kernel.
• No reimplementation of kldload. We wrap it via NSTask.
• No driver porting. Drivers come from FreeBSD base, drm-kmod, nvidia-driver, virtualbox-additions, etc.
• No replacement for devd(8). devd handles non-kmod-load actions (running scripts on attach, configuring network on link-up). kmodloader is narrower: only kmod loading. devd's role — if we want it — is separate (and currently absent; we replicate its essential parts case-by-case in launchd-driven daemons).
• No Mach IPC, no IOKit, no XPC. Same project-wide rule.
• No prelinked kernel image. We keep kmods as separate .ko files and load on demand.

2. Architecture

Three independent match paths run sequentially in KMDaemon.runOneShot. Each emits a list of kld names. Lists are concatenated, deduplicated, and the GPU set is pulled to the front so the framebuffer is owned by a DRM driver before peripheral driver attaches happen. Then kldload -n each.

2.1 Why three paths instead of one

FreeBSD's hardware drivers split cleanly into two categories by how match information is published:

Trying to unify both under one mechanism — the original plan's "personality plists with IOPCIMatch" — required hand-curating the device-ID lists for category 2. That doesn't scale: amdgpu's supported list grows each AMD generation, and the personality plists were always going to lag real hardware. The two-path split lets each category use the data source that already has the answer.

Hypervisor guest additions (vboxguest, vboxvfs) are intentionally NOT in scope. They're service-related kmods, not hardware drivers; the right home is the matching launchd plist (org.freebsd.vboxservice.plist) loading them before launching its userspace daemon, the same way FreeBSD's rc.d/vboxservice works. Phase 1g briefly shipped a third "hypervisor scan" path; it was reaching outside kmodloader's lane and got removed.

3. The three match paths in detail

3.1 Path 1 — devmatch + linker.hints

Bare devmatch (no flag) walks the live device tree and emits one kld basename per line for every enabled-but-unattached device that has a registered driver in linker.hints. linker.hints is built by kldxref(8) from each driver's PNP_INFO() macro at install time — pkg's post-install script regenerates it whenever a kld package lands. So at boot the index already covers everything that ships from base + ports.

$ devmatch
pchtherm.ko
rtsx.ko
if_iwlwifi.ko
if_iwm.ko
ichsmb.ko
acpi_wmi.ko

Coverage on a representative laptop (Skylake-era Lenovo): NICs (if_em), WiFi (if_iwlwifi / if_iwm), thermal (pchtherm), SD reader (rtsx), SMBus (ichsmb), ACPI WMI. Most of the system except the GPU.

NOT devmatch -a. The -a flag prints devname: kld for every enabled device including already-attached ones — wrong format, wrong filter. Bare devmatch is the canonical "what needs loading" query.

3.2 Path 2 — GPU PCI scan

drm-kmod's i915kms.ko, amdgpu.ko, radeonkms.ko, and the nvidia binary kmod do not declare PNP_INFO. kldxref -d /boot/modules/linker.hints | grep i915 is empty. strings /boot/modules/i915kms.ko | grep pnp_info is empty. devmatch will never see them.

Solution: walk pciconf -l for class 0x0300xx (display controllers; covers VGA, XGA, 3D), extract (vendor, device) per device, and route per a small in-code map:

- (NSArray<NSString *> *)gpuKldsForDevices:(NSArray<NSDictionary *> *)devices
{
    NSMutableOrderedSet<NSString *> *r = [NSMutableOrderedSet orderedSet];
    for (NSDictionary *dev in devices) {
        NSString *vendor = dev[@"vendor"];
        NSString *device = dev[@"device"];

        if ([vendor isEqualToString:@"0x8086"]) {
            [r addObject:@"i915kms"];
        }
        else if ([vendor isEqualToString:@"0x1002"]) {
            // Per-device split: radeonkms list is frozen upstream.
            uint16_t devID = (uint16_t)strtoul(device.UTF8String, NULL, 16);
            BOOL isRadeon = NO;
            for (size_t i = 0; i < kRadeonKMSDeviceIDsCount; i++) {
                if (kRadeonKMSDeviceIDs[i] == devID) { isRadeon = YES; break; }
            }
            [r addObject:isRadeon ? @"radeonkms" : @"amdgpu"];
        }
        else if ([vendor isEqualToString:@"0x10de"]) {
            [r addObject:@"nvidia-drm"];   // pulls nvidia-modeset + nvidia
        }
    }
    return r.array;
}

Three vendor IDs. 0x8086 (Intel), 0x1002 (AMD/ATI), 0x10de (NVIDIA). PCI-SIG assignments from the 1980s and 90s; will not change.

3.2.1 The AMD split: radeonkms vs. amdgpu

The only category-2 entry that needs more than vendor info. radeonkms covers TeraScale through HD 7000 + early Sea Islands; amdgpu covers GCN 1.1+ through current RDNA*. Linux's radeon driver is in maintenance-only mode upstream and stopped gaining new device IDs years ago — drm-kmod inherits the same frozen list.

So we vendor it once: 699 unique 16-bit device IDs from drm-kmod's include/drm/drm_pciids.h (the radeon_PCI_IDS macro) baked into kmodloader/src/RadeonPCIIDs.h as a static const uint16_t[]. Any AMD device whose ID matches the frozen set goes to radeonkms; everything else (Polaris onward) defaults to amdgpu. amdgpu is the open default: hardware AMD ships next year picks up amdgpu without us changing the table.

Update procedure (rare): re-fetch drm_pciids.h, re-extract the 0x1002 entries, regenerate the header. The set has not changed in years.

3.2.2 NVIDIA chain via MODULE_DEPEND

kldload nvidia-drm pulls nvidia-modeset which pulls nvidia via MODULE_DEPEND declarations in the kmods. We only have to name the leaf. Requires hw.nvidiadrm.modeset="1" in /boot/loader.conf so nvidia-drm.ko engages DRM/KMS at init — a kenv tunable, must be set kenv-time.

3.2.3 Multi-GPU + non-GPU systems

Multi-GPU laptops (Intel iGPU + Nvidia dGPU is common) are handled naturally: the scan finds both vendors, both kld sets get loaded. Bare-metal-with-no-GPU systems (some VMs) return an empty device list — the GPU pass loads nothing.

3.3 (Removed) hypervisor scan

Phase 1g briefly shipped a third match path that read kern.vm_guest and kldloaded VirtualBox / VMware guest additions kmods. Removed shortly after — for two reasons:

1. Wrong scope. Guest additions are services, not hardware drivers. The Apple-shape pattern (and FreeBSD's existing rc.d/vboxservice pattern) is for the service's launchd job to kldload its supporting kmods before starting the userspace daemon. kmodloader's job is hardware autodetection.
2. The kld names were also wrong. vboxvideo doesn't exist on FreeBSD — that's a Linux thing. vmware_drv is an Xorg driver, not a kld. vmxnet3 is in GENERIC already. Open-vm-tools ships zero kmods at all (everything is userspace daemons).

What we still ship in pkglist.txt: emulators/virtualbox-ose-additions-nox11 (provides vboxguest.ko, vboxvfs.ko, and userspace VBoxService) and emulators/open-vm-tools-nox11 (provides userspace vmtoolsd + helpers). The kmods sit on disk; the userspace daemons sit on disk. Nothing auto-runs them in Phase 1. Phase 2+ will introduce org.freebsd.vboxservice.plist and org.freebsd.vmtoolsd.plist which handle their own kmod loading and start the userspace daemon under launchd supervision.

4. Repository

4.1 Layout under freebsd-launchd/kmodloader/

freebsd-launchd/kmodloader/
├── Makefile                 gmake build, installs to /usr/libexec/kmodloader
└── src/
    ├── main.m               @autoreleasepool { [KMDaemon runOneShot]; }
    ├── KMDaemon.{h,m}       runOneShot orchestrator + the three match paths
    └── RadeonPCIIDs.h       generated frozen device list (radeon_PCI_IDS, 699 IDs)

No personalities/ directory. No KMRegistry / KMMatch / KMDevice / KMBusEnumerate classes. Phase 1d ripped them out: ~900 LOC removed, replaced by ~150 LOC of three-path orchestration.

Top-level (freebsd-launchd/) hosts:

• overlays/System/Library/LaunchDaemons/org.freebsd.kmodloader.plist
• overlays/boot/loader.conf — sets hw.nvidiadrm.modeset="1"
• pkglist.txt — lists drm-latest-kmod, nvidia-drm-latest-kmod, wifi-firmware-*-kmod, virtualbox-ose-additions-nox11, open-vm-tools-nox11
• build.sh — chroot-side, runs gmake -C kmodloader install after launchd + configd builds

4.2 How build.sh handles kmodloader

Same chroot session that builds launchd + configd. After make-configd.sh finishes, build.sh rsyncs kmodloader/ into chroot:/tmp/kmodloader/ and runs gmake -C /tmp/kmodloader install — the Makefile compiles the daemon and installs to /usr/libexec/kmodloader. No wrapper script.

5. Locked architectural decisions

6. launchd integration

6.1 The plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>             <string>org.freebsd.kmodloader</string>
    <key>ProgramArguments</key>  <array><string>/usr/libexec/kmodloader</string></array>
    <key>RunAtLoad</key>         <true/>
    <key>KeepAlive</key>         <false/>
</dict>
</plist>

One-shot at boot. KeepAlive=false — daemon exits when work is done; launchd does not respawn. Phase 2 will swap to a long-running shape with a DISPATCH_SOURCE_TYPE_READ source on /dev/devctl for hot-plug events.

6.2 Boot ordering

kmodloader runs early. Plist filenames sort alphabetically; org.freebsd.kmodloader sorts before org.freebsd.netconfigd, so any NIC kld kmodloader brings in is visible by the time netconfigd does its getifaddrs() walk. That's the dependency that matters today; finer ordering (a RequiresPhase key, or per-job dependencies) is a launchd-side feature for later.

7. Licensing

BSD-2-Clause across the board. No Apple per-file headers — this is clean-room code, not a port. The original plan referenced Apple's kextd + IOKit design; the implementation that shipped is closer to FreeBSD's own devmatch. Either way, no Apple source is vendored.

8. Phased delivery

9. Open questions

10. References

• FreeBSD devmatch(8): man 8 devmatch — primary match-data tool.
• FreeBSD devctl(4): man 4 devctl — Phase 2 event source.
• FreeBSD kldxref(8) + MODULE_PNP_INFO(): man 8 kldxref, kernel docs in sys/sys/module.h.
• FreeBSD devd(8): man 8 devd — not used directly; reference for hot-plug semantics.
• drm-kmod source: github.com/freebsd/drm-kmod. include/drm/drm_pciids.h is the source for RadeonPCIIDs.h.
• FreeBSD release engineering's fwget(8): man 8 fwget — auto-detects firmware packages needed for current hardware. Useful diagnostic during bench testing.
• Companion plans: freebsd-launchd, freebsd-configd.