GPU autodetection on FreeBSD — kmodloader vs. xconfig vs. initgfx vs. xlibre vs. Linux

An honest comparison of how this project's kmodloader stacks up against the GPU/driver autodetection mechanisms in GhostBSD, NomadBSD, the xlibre X server, and Linux's udev+modprobe stack. Includes the failure-mode analysis: what happens when a DRM kmod loads but doesn't recognize your GPU.

1. Comparison matrix

Eight axes that matter for GPU autodetection on FreeBSD.

2. kmodloader (this project)

An ObjC daemon at /usr/libexec/kmodloader, started by launchd's org.freebsd.kmodloader.plist with RunAtLoad=true, KeepAlive=false. Three match paths run sequentially in a single runOneShot:

2.1 What's distinctive

• Single daemon, single ObjC binary versus the shell-script-per-purpose pattern of GhostBSD/NomadBSD. Code lives at kmodloader/src/KMDaemon.m (~250 LOC) plus RadeonPCIIDs.h (the frozen 699-entry uint16_t array generated from upstream).
• devmatch path covers everything in the FreeBSD driver tree that declares PNP_INFO — if_em, if_iwlwifi, if_iwm, if_rtw88/89, ahci, nvme, umass, ACPI HID drivers, etc. GhostBSD and NomadBSD don't have an equivalent — they handle only GPU and rely on either base-kernel auto-attach (anything in GENERIC) or a separate tool (NomadBSD's dsbdriverd) for the rest.
• Three vendor IDs (Intel 0x8086, AMD 0x1002, NVIDIA 0x10de) instead of hundreds. The AMD split uses the upstream-frozen radeon list (sourced from drm-kmod's include/drm/drm_pciids.h — same source GhostBSD uses), then defaults to amdgpu for everything else. New AMD silicon picks up amdgpu with no code change.
• Hypervisor guest additions deliberately out of scope. Earlier draft included a third "hypervisor scan" path that read kern.vm_guest and kldloaded VBox/VMware additions; removed because guest additions are services (loaded by their own launchd plist), not hardware drivers.
• No xorg.conf generation. kmodloader is concerned with kernel modules; X11 configuration is downstream and not its job.

3. GhostBSD xconfig

Single shell script bin/xconfig (1411 lines) plus an rc.d wrapper. Runs every boot via rc.d (logged to /var/log/xconfig_boot.log), persists choices in /etc/rc.conf's kld_list.

3.1 How it works

1. kern.vm_guest + dmesg grep for hypervisor type.
2. pciconf -lv | grep -B4 VGA | grep -qi Intel|AMD|ATI|NVIDIA for vendor.
3. For AMD: a giant inline 701-entry regex (RADEON_DEVICE at bin/xconfig:33) determines radeonkms vs amdgpu. Comment cites drm-kmod's drm_pciids.h as source.
4. For NVIDIA: detect_nvidia_driver_version matches the GPU's pretty-print description against five marketing-name pipe-strings (latest / 580 / 470 / 390 / 340) checked newest-first. No PCI IDs for NVIDIA at all.
5. Loads kmod via kldload, persists via sysrc -f /etc/rc.conf kld_list+=.... Generates X config: deletes xorg.conf for Intel/AMD (modesetting handles it); uses X -configure + sed for NVIDIA.
6. Fallback: applies static XF86Config.scfb template pinning Driver "scfb". vesa only via manual subcommand.

3.2 What it doesn't do

• No validation. Loads the kmod, writes config, declares success. If i915kms loads but doesn't bind, X just fails next start.
• No hot-plug.
• First-vendor-wins in vendor order (Intel → AMD → NVIDIA) means hybrid GPUs only get one driver.
• No efifb awareness — code knows scfb and vesa, not efifb specifically.

3.3 NVIDIA delivery

Calls pkg install nvidia-driver-NNN at runtime, or pulls from offline /xdrivers/drivers-list for live ISOs. Means a live boot may need network for NVIDIA support unless the offline pkg cache is staged.

4. NomadBSD initgfx

Shell script config/etc/rc.d/initgfx (467 lines) plus sourced DB config/etc/initgfx_device.db (1782 lines) and Xorg templates. Runs at boot; persists via initgfx_kmods= in /etc/rc.conf; smart-skip on PCI hash unchanged.

4.1 The validation feature

The standout: test_x at initgfx:120-137. After loading the candidate kmod and writing the proposed Xorg config:

1. Run a short xinit session against the proposed config (xmessage -timeout 3).
2. If xinit exits non-zero, call __reset: revert config, try the next handler.
3. For NVIDIA, on test_x failure fall through to setup_nv (basic nv driver) before going to vesa/scfb.

This catches the "kmod loaded but didn't attach" case indirectly via Xorg failing to start. None of the other systems do this.

4.2 NVIDIA via per-version pre-staged trees

Build-time, NomadBSD packs every NVIDIA branch (340 / 390 / 470 / latest per build.cfg:NVIDIA_DRIVERS) into /usr/local/nvidia/<ver>/. At boot, setup_nvidia picks the right version from marketing-name match, then symlinks the version's libGL / Xorg modules into place, runs ldconfig -m, installs libmap.d/nvidia.conf. Trades image size (~150MB extra) for offline reliability.

4.3 Fallback

get_fallback_driver() {
    case "$(sysctl -n machdep.bootmethod)" in
        BIOS) echo vesa ;;
        UEFI) echo scfb ;;
    esac
}

Cleaner than GhostBSD's "always scfb." Matches the FreeBSD Handbook's Xorg recommendation exactly.

4.4 dsbdriverd cooperation

NomadBSD ships dsbdriverd for non-GPU drivers (NICs, sound, etc.). Its config explicitly excludes DRM kmods: exclude_kmods = { "radeonkms", "amdgpu", "i915kms" }. Two daemons, clean split. kmodloader collapses these into one process via the two-path scan.

5. xlibre detection (post-kmod)

xlibre is a fork of Xorg. Its detection runs at server start, after the DRM kmod is loaded. The vendor-switch table at hw/xfree86/common/xf86pciBus.c:1046-1264 maps PCI vendor → X driver name, not kmod:

5.1 Why this doesn't help kmodloader

• xlibre runs after /dev/dri/cardN exists. It consumes the result of kmod loading; it doesn't produce guidance for it.
• The X driver name space ("intel", "modesetting", "ati") is not the kmod name space ("i915kms", "amdgpu", "radeonkms"). xlibre's ati driver covers all AMD generations and dispatches based on drmGetVersion output — there's no "skip radeonkms because xlibre would never use it" signal.
• xlibre's xf86LoadKernelModule exists but is a legacy DRI1 hook (dri.c:823) that's effectively dead on modern KMS systems. xlibre does NOT autoload i915kms/amdgpu/etc.
• The user concern "make sure we only load modules we really need" — xlibre cannot answer this because it sees the world post-kmod. Filtering decisions belong to the kmod-load layer (us), not the X layer.

5.2 The PCI_TXT_IDS_PATH supplement (Linux only)

xf86MatchDriverFromFiles() at xf86pciBus.c:1266 reads a directory of <driver>.ids files at compile-time-configured path. Disabled by default; only meaningful on Linux. Lets external X drivers advertise (vendor:device) support without source patches. Not a model we'd benefit from copying for kmod loading.

6. Linux udev + modprobe

The reference design. Five steps:

1. Compile time: each Linux kernel module declares MODULE_DEVICE_TABLE(pci, ...); emitted into the .ko's .modinfo ELF section as strings like pci:v00008086d00009A49sv*sd*bc03sc*i*.
2. Module install time: depmod -a reads .modinfo from every .ko and writes /lib/modules/$(uname -r)/modules.alias.
3. Boot/hotplug: kernel emits a uevent on netlink with MODALIAS=pci:....
4. udev catches it. /lib/udev/rules.d/80-drivers.rules contains RUN{builtin}+="kmod load $env{MODALIAS}".
5. The kmod builtin (linked into udevd) calls libkmod in-process; libkmod fnmatch-globs MODALIAS against modules.alias, finds i915, calls init_module(2).

6.1 The mapping to FreeBSD

This is exactly what FreeBSD already implements:

6.2 The single difference that matters

Linux's drm modules (i915.ko, amdgpu.ko, nouveau.ko) all declare MODULE_DEVICE_TABLE. FreeBSD's drm-kmod (a LinuxKPI port of the same code) doesn't — the LinuxKPI shim doesn't translate MODULE_DEVICE_TABLE into MODULE_PNP_INFO. That single missing translation is why we need a GPU PCI scan at all. Devmatch handles every other driver in tree.

6.3 Linux "too new" handling

If the .ko loads but the live device ID isn't in the module's pci_ids: the driver's .probe() is never called, the device sits unbound. Modern kernels expose i915.force_probe=, amdgpu.force_probe= etc. for users with too-new hardware. There is no userspace "fall back to a different kernel module" mechanism — udev hands MODALIAS to libkmod, gets a hit or miss, and that's it.

7. macOS: kextd + IOKit (the reference architecture)

The original kmodloader plan was modeled directly on Apple's kextd + IOKit personality matching. Phase 1a-c shipped a literal port of that idea (.kext bundles in /System/Library/Extensions/, IOKitPersonalities dicts, integer probe scores, highest-scoring kext wins). Phase 1d ripped it out in favor of devmatch for FreeBSD-specific reasons. Worth showing the reference architecture both for design provenance and to answer "why don't you just do what Apple does?"

7.1 The kextd loop

kextd is a launchd-supervised daemon (com.apple.kextd.plist). On startup it:

1. Walks /System/Library/Extensions/*.kext/ and /Library/Extensions/*.kext/.
2. Reads each bundle's Contents/Info.plist, extracts the IOKitPersonalities dict.
3. Hands all personalities to the kernel via kextload(8)-equivalent.
4. Listens on a Mach port for kAppleEventLoopMessage-style notifications: when a new device appears in IOKit's IORegistry, kextd is told and re-runs matching for that device.

The kernel keeps a personality registry indexed by match category ("PCI", "USB", "USBClass", etc.). When IOKit sees a new device, it walks the registry, calls IOService::probe on every personality whose match dict could apply, and binds the device to the highest-scoring service.

7.2 IOPCIMatch + IOProbeScore (the design our Phase 1a-c shipped)

An IOKit personality looks like this (Apple's actual i915 driver, simplified):

<dict>
    <key>CFBundleIdentifier</key>
    <string>com.apple.driver.AppleIntelKBLGraphicsFramebuffer</string>
    <key>IOClass</key>          <string>AppleIntelKBLFramebuffer</string>
    <key>IOMatchCategory</key>  <string>IOFramebuffer</string>
    <key>IOPCIMatch</key>
    <array>
        <string>0x59168086</string> <!-- HD Graphics 620 -->
        <string>0x591B8086</string> <!-- HD Graphics 630 -->
        <!-- ... -->
    </array>
    <key>IOProbeScore</key>     <integer>90000</integer>
</dict>

The probe call returns either 0 (don't match, skip) or a positive score. Higher score wins; ties broken by personality registration order. Non-matching personalities never get a probe call — the match dict is the gate.

This is what kmodloader Phase 1a-c implemented in kmodloader/personalities/*.kext/Contents/Info.plist with our own probe-score algorithm. Worked correctly for hardware we hand-curated; failed scaling because FreeBSD's drm-kmod doesn't ship Info.plists with IOPCIMatch arrays, so we'd be hand-curating ~2000 device IDs ourselves — without Apple's full-time staff to maintain them.

7.3 kextcache prelinking

Apple's optimization for boot speed: kextcache fuses the kernel binary plus every kext that matched at last-boot into a single signed boot image (/System/Library/PrelinkedKernels/prelinkedkernel). At boot the loader maps the prelinked kernel directly — no per-boot scan of /System/Library/Extensions/, no per-kext load decisions, no probe loop. The matching work happened once at install time.

Plan §11 Phase 4 flagged this as a future optimization for kmodloader; it remains a Phase-4 idea. The Apple-shape parallel is roughly: at install time, run kmodloader's two-path scan, write the result to a manifest, have /boot/loader consume the manifest and pre-load on next boot. Defers all the "vendor scan + devmatch" work from boot to install.

7.4 DriverKit (modern Apple userspace drivers)

Since macOS 10.15 / iOS 14, Apple has been moving drivers out of the kernel and into sandboxed userspace processes called .dext bundles (DriverExtension). Each dext is a launchd-launched signed binary that talks to a small in-kernel "personality" stub via IOKit's DriverKit framework. Match logic stays the same (IOPCIMatch in the dext's Info.plist); the actual driver code runs in userspace.

Genuinely interesting as a long-term direction but not on kmodloader's roadmap. FreeBSD has no equivalent to DriverKit's userspace-driver kernel infrastructure today, and porting one is a project comparable to launchd itself.

7.5 Why we don't do exactly this on FreeBSD

We started here (Phase 1a-c) and reached a different place (Phase 1d-1g) for three reasons:

1. Apple ships finite hardware. A handful of staff curate the IOPCIMatch tables for the SoCs/GPUs Apple ships. FreeBSD targets every PC ever made; hand-curated personality plists don't scale to that hardware breadth.
2. FreeBSD already has the data, just in a different format. linker.hints built from MODULE_PNP_INFO macros gives us the same (vendor:device → kld) map for every in-tree driver. devmatch(8) is the canonical reader. We don't need to reinvent the registry; we need to use the one FreeBSD already has.
3. The narrow gap (drm-kmod) is closeable with a 3-vendor map plus one frozen 699-ID list. No need for Apple-style full personality plists when the actual missing data is "which of three vendor IDs do I have."

The Apple-shape design we kept: launchd supervision, ObjC implementation, plist-based config, the conceptual model of "a daemon that owns kernel-extension loading." The Apple-shape design we dropped: the per-driver IOPCIMatch personality plist as the load-decision data structure.

8. The "too-new GPU" failure case

The user's specific concern: what happens in our case when the device is too new for the latest drm-kmods? Detailed answer with FreeBSD source citations.

7.1 Probe path (LinuxKPI shim)

drm-kmod's i915kms registers as a pci_driver via LinuxKPI. Newbus calls linux_pci_probe() at sys/compat/linuxkpi/common/src/linux_pci.c:506:

if ((pdrv = linux_pci_find(dev, &id)) == NULL)
    return (ENXIO);

linux_pci_find() walks the driver's id_table matching on vendor/device/subvendor/subdevice. If the chip isn't in the table, probe returns ENXIO. Newbus tries the next driver in priority order; vgapci(4) wins by default at BUS_PROBE_GENERIC.

If the chip is in the table but flagged require_force_probe, drm-kmod's i915_pci.c emits the canonical "too-new" dmesg line:

Your graphics device 0xNNNN is not properly supported by i915 in this
kernel version. To force driver probe anyway, use i915.force_probe=NNNN
module parameter or CONFIG_DRM_I915_FORCE_PROBE=NNNN configuration option,
or (recommended) check for kernel updates.

And returns -ENODEV. Same outcome: no drmn child attaches.

7.2 What the user sees

7.3 NVIDIA edge case

nvidia.ko + nvidia-modeset.ko + nvidia-drm.ko behave differently:

• If hw.nvidiadrm.modeset is unset (or 0), nvidia-drm loads but skips DRM device creation. Kmod resident, no /dev/dri/cardN. Set in /boot/loader.conf; kmodloader does this.
• On unsupported NVIDIA GPU: prints NVRM: The NVIDIA <chip> GPU installed in this system is not supported by the <ver> NVIDIA driver and refuses. Same end state — no /dev/dri/cardN, no crash.

7.4 kmodloader's risk profile

9. Scorecard — wins and gaps

8.1 Where kmodloader wins

8.2 Where kmodloader has gaps

10. Specific takeaway: xlibre devmatch detection

The user's prompt asked specifically about xlibre's devmatch detection so kmodloader doesn't load too aggressively. Conclusion after deep-reading xlibre source:

The right framing is: don't expect xlibre to filter our kmod-load decisions. Filtering belongs to the kmod-load layer (us). What xlibre does provide is a clean fallback through its listPossibleVideoDrivers() chain (modesetting → fbdev/scfb → vesa) that handles "no DRM kmod attached" without panic — confirming that loading drm-kmod kmods speculatively is safe.

11. Recommendations

12. Open TODOs — ports-shipped kld drivers

drm-kmod is the canonical case kmodloader's GPU PCI scan addresses. But it isn't the only ports kld package that may have the same problem — "the kld ships from ports without MODULE_PNP_INFO, so devmatch can't see it, so we'd need a vendor-scan-style fallback or speculative load." Each of these needs a one-shot investigation: install the package, run kldxref -d /boot/modules/linker.hints | grep <name>, and see whether devmatch picks it up. If yes, no kmodloader change — just add the package to pkglist.txt. If no, we need the same kind of targeted handling we do for GPUs.

12.1 Investigation procedure

For any ports kld package that ships an if_* / wmt_* / similar driver kmod:

# 1. Install on a test system
pkg install <package>

# 2. Re-build hints (pkg post-install does this, but be explicit)
kldxref /boot/modules

# 3. Look for the driver in the hints database
kldxref -d /boot/modules/linker.hints | grep -i <driver>

# 4. Look for PNP_INFO sections in the .ko binary
strings /boot/modules/<driver>.ko | grep -i pnp_info

# 5. Try devmatch directly (after kldunload to make the device unattached)
devmatch | grep -i <driver>

Outcomes:

• kldxref shows entries + devmatch lists it → kmod is in the FreeBSD-canonical "data-driven" path. Add the package to pkglist.txt, devmatch handles the rest. Zero kmodloader code change.
• kldxref empty + devmatch silent → no MODULE_PNP_INFO. Same problem we have for drm-kmod. Two choices:
  1. File an upstream PR against the port adding MODULE_PNP_INFO declarations from the driver's compiled-in supported table. Best long-term answer; works for everyone.
  2. Speculative load via pkglist + kmodloader: ship the package on the ISO and add a one-line kldload to kmodloader's flow. Probe rejection is graceful (kmod stays resident, no attach, no crash — same as the "too-new GPU" analysis in §8). Cost: kernel RAM per stuck-resident kmod (~1-3 MB typical for non-GPU drivers).

12.2 Known candidates to investigate

12.3 Strategy summary

For each port-shipped kld package we want on the ISO, the decision tree is:

1. Install on a test system; run the §12.1 procedure. Get an empirical answer — has PNP_INFO or doesn't.
2. If it has PNP_INFO: add the package to pkglist.txt with a comment citing the test result. Done. devmatch handles it on every boot via the existing path.
3. If it doesn't: pick a path:
   • Best (long-term): file upstream PR adding MODULE_PNP_INFO. Upstream maintainer reviews, ships, FreeBSD pkg rebuilds, problem disappears for everyone using FreeBSD.
   • Pragmatic (now): add a targeted scan path in KMDaemon.m, similar to the GPU PCI scan but for the relevant device class (USB vendor:device for Realtek WiFi adapters; PCI vendor:device for Realtek 2.5G ethernet; etc.). Cost: per-driver code, but small.
   • Lazy (acceptable for niche cases): document that the user must kldload <name> manually after pkg install. Acceptable for low-priority hardware where the user is already in setup-mode.
4. Add the test result + chosen path to a per-package comment in pkglist.txt so future maintenance has the audit trail.

None of these candidates are blocking Phase 1 functionality; they're TODOs to work through as users surface needs. The shape of the answer is the same for each: investigate empirically, then either pkglist-only or pkglist+code.

13. References

kmodloader

• Plan: freebsd-kmodloader-plan.html
• Source: github.com/pkgdemon/freebsd-launchd/tree/main/kmodloader
• Frozen radeon ID list: kmodloader/src/RadeonPCIIDs.h (generated from drm-kmod's drm_pciids.h)

GhostBSD xconfig

• Repo: github.com/ghostbsd/xconfig
• Detection logic: bin/xconfig:374-403 (vendor probes), :456-462 (radeon split), :641-672 (NVIDIA branch)
• Fallback templates: cardDetect/XF86Config.{scfb,vesa,safe}

NomadBSD initgfx

• Repo: github.com/nomadbsd/NomadBSD
• Detection logic: config/etc/rc.d/initgfx:140-219 (PCI parser), :240-345 (handlers), :374-390 (fallback)
• Validation: config/etc/rc.d/initgfx:120-137 (test_x)
• ID database: config/etc/initgfx_device.db
• dsbdriverd cooperation: config/usr/local/etc/dsbdriverd/config.lua:7

xlibre

• Repo: github.com/X11Libre/xserver
• Detection: hw/xfree86/common/xf86AutoConfig.c:166-225 (top-level), xf86pciBus.c:1046-1264 (vendor → driver table)
• Platform/DRM match: hw/xfree86/common/xf86platformBus.c:206, os-support/shared/drm_platform.c:24

Linux

• MODULE_DEVICE_TABLE macro: kernel include/linux/module.h
• depmod / modules.alias: kernel.org kmod
• udev rules: /lib/udev/rules.d/80-drivers.rules (RUN{builtin}+="kmod load $env{MODALIAS}")
• i915 force_probe doc: docs.kernel.org/gpu/i915.html

FreeBSD failure-mode

• linux_pci.c:506 — LinuxKPI probe returning ENXIO on id_table miss
• vga_pci.c:344 — vgapci probe at BUS_PROBE_GENERIC
• vt_core.c:3275 — vt_replace_backend() only fires when DRM attaches
• FreeBSD Handbook x11 chapter: official Xorg fallback statement (UEFI→scfb, BIOS→vesa)

macOS / IOKit

• Apple kextd source: github.com/apple-oss-distributions/IOKitTools (referenced for design — not vendored)
• IOKit framework: apple-oss-distributions/IOKitUser
• IOKit Fundamentals (architecture overview, archived): developer.apple.com IOKit Fundamentals
• DriverKit framework reference: developer.apple.com/documentation/driverkit
• kextcache(8) man page (prelinked-kernel construction): macOS man pages — search kextcache