← NextBSD Research

NextBSD Bluetooth — bluetoothd, pairing, HID and audio Research · epic plan

The plan for EPIC E16 (nextbsd#473): 38 tickets in six stages, from five parallel deep dives covering the kernel and hardware, the engine and Classic-vs-BLE decision, the daemon and CLI, HID, and audio. Seed ticket and decision record: nextbsd#412. Background: Apple stack research. Template: WLAN plan. Every ticket in full: E16 ticket drafts.

Decided (2026-09-20)

• Classic first on netgraph. LE comes second, as a thin ATT/GATT/SMP host inside bluetoothd over the kernel’s LE sockets, so it coexists with Classic on one controller. Not NimBLE (it would need the ACL hook and would kill Classic), and not BlueZ.
• Everything is compiled into the kernel. The in-kernel matcher has no USB provider yet, so Bluetooth transports can’t be kexts.
• Link keys are stored in plaintext, in a separate 0600 SCPreferences file isolated for the keychain migration. This is the same accepted debt as WLAN.
• Pi 5 / Pi 500: a USB dongle for now. The onboard CYW43455 needs new UART, GPIO, pinctrl, H4 and patchram work (K7 measures first, K8 is parked).
• Out of scope: non-Bluetooth input and audio device management. H4 and A4 record the interfaces that future epic must provide.

Index — all 38 tickets, filed

Kernel & hardware (K)

Deep-dive notes, lightly edited. Draft ids map to issues in the index.

Scoping notes for nextbsd/nextbsd#473 (epic) and #412 (seed). Read-only research; nothing filed. Evidence paths: nextbsd-kernel/…, nextbsd/…, ul/… are the local clones; sys/…, usr.sbin/… are FreeBSD releng/15.1 unless marked 13.5.

TL;DR

1. Seven options lines bake the whole USB Bluetooth stack. Every token is stock and machine-independent (sys/conf/files:4299-4320, sys/conf/options:516-526, NOTES:813-818); the only bus dependency is usb, which GENERIC already has on amd64 and arm64 (sys/arm64/conf/std.dev:101). One change to config/NEXTBSD covers both arches and NEXTBSD-RPI5 (which includes it, config/NEXTBSD-RPI5:39).
2. There is exactly one lazy-kldload in the netgraph/BT code: sys/netgraph/ng_socket.c:281-303 — an NGM_MKPEER for an unregistered type does kern_kldload("ng_<type>"). That is how stock FreeBSD pulls in ng_hci/ng_l2cap from rc.d/bluetooth. On NextBSD it fails (no .ko tree, nextbsd-kernel/ci/assemble-image.sh:168). Baking the types makes ng_findtype() succeed before the fallback is reached, so the path is never taken. The BT directories themselves contain no kldload at all.
3. Nothing in the kernel builds the graph. ng_ubt attaches a bare ubt0 node; on stock FreeBSD sbin/devd/bluetooth.conf runs service bluetooth quietstart ubt0, and rc.d/bluetooth's bluetooth_setup_stack() does the mkpeer/connect/hccontrol initialize dance. NextBSD strips devd and ships no rc.d, so bluetoothd (area 2) owns graph assembly — the interface is spelled out in §3.
4. Firmware is a userland problem, not a firmware(9) problem. Intel (7260…AX-class, VID 0x8087) and Realtek controllers ship in bootloader/ROM mode; the in-tree ng_ubt_intel.c / ng_ubt_rtl.c refuse to attach until iwmbtfw(8) / rtlbtfw(8) have pushed firmware over ugen. The blobs come from Debian firmware-nonfree (ports comms/iwmbt-firmware, comms/rtlbt-firmware; licences allow redistribution). The trigger on stock FreeBSD is a devd rule; NextBSD has no devd, launchd's HardwareMatch is iter-1 (parse only, ul/src/launchd/src/core.c:262-270), so the trigger must be bluetoothd's job (interface in §4.5). Broadcom BCM20702/Apple parts work in ROM firmware; the only Broadcom firmware tool in tree (bcmfw/ubtbcmfw) is for the 2003-era BCM2033 and ships no firmware — skip it.
5. Raspberry Pi 5 / Pi 500 onboard Bluetooth is unsupported at every layer in 15.1 and should be parked. The BT radio hangs off uarta (brcm,bcm7271-uart, an 8250 variant FreeBSD has no compat entry for), needs brcm,brcmstb-gpio (BT_ON = gio 29) and brcm,bcm2712-pinctrl (neither in tree), a UART HCI transport (ng_h4 removed in 2021, commit 79a100e28e; hcseriald removed 66d6299848), and a patchram download of BCM4345C0.hcd that FreeBSD has never had. USB dongles over RP1's xhci are the E16 path on the Pi.
6. Bake, don't kext. The in-kernel IOCatalogue matches PCI ids and FDT compatible strings only (src-overlay/sys/sys/iocatalogue.h:24-31, iokit_catalogue.c:270-279); there is no USB provider, the personality generators are PCI-only, and the protocol nodes are not devices at all (nothing fires device_nomatch for them). ng_ubt also fails the delivery plan's own kext rule (kext ⇐ has-firmware(9) ∨ multi-version). ~10.6k LOC total, order of half a megabyte of kernel.
7. CI can prove presence, not radio. QEMU removed Bluetooth emulation in 2019 (commits 1d4ffe8dc7, 43d68d0a94). CI can assert ngctl list shows btsock_hci_raw/btsock_l2c_raw/ btsock_l2c, sysctl net.bluetooth.version, and hccontrol exiting 7 with Could not find HCI nodes (hccontrol.c:110-112) instead of EAFNOSUPPORT. A userland HCI controller emulator on the hci node's drv hook (ng_hci.h:62) can exercise the whole protocol stack without a radio — a worthwhile hardening ticket. Real dongles: qemu -device usb-host,vendorid=…,productid=… on a Linux host, or real hardware.

1. What must be compiled into NEXTBSD

1.1 The change

### config/NEXTBSD  (proposed)
options     NETGRAPH            # netgraph core: ng_base.c, ng_parse.c
options     NETGRAPH_SOCKET         # ng_socket: PF_NETGRAPH, what ngctl/libnetgraph/hccontrol use to find nodes
options     NETGRAPH_BLUETOOTH      # ng_bluetooth: net.bluetooth sysctls, shared version/timeouts
options     NETGRAPH_BLUETOOTH_HCI      # ng_hci
options     NETGRAPH_BLUETOOTH_L2CAP    # ng_l2cap
options     NETGRAPH_BLUETOOTH_SOCKET   # ng_btsocket: PF_BLUETOOTH (HCI raw, L2CAP, RFCOMM, SCO)
options     NETGRAPH_BLUETOOTH_UBT      # ng_ubt + ng_ubt_intel + ng_ubt_rtl (USB transport)

Why each is required, with the evidence:

Deliberately not baked:

• NETGRAPH_BLUETOOTH_UBTBCMFW — ubtbcmfw(4) is the 2003 BCM2033 firmware-download cdev (ubtbcmfw.c:32,66); bcmfw(8) says "Due to copyright issues I will no longer provide mini-driver and firmware files" (bcmfw.8:54-56). Dead weight.
• NETGRAPH_BLUETOOTH_H4 / _BT3C — the option tokens still exist (sys/conf/options:520-521) but gate no files: ng_h4 and ng_bt3c are gone in 14+ (§5).
• Any of the other 40 NETGRAPH_* node types (options:517-570). None is a BT dependency.

1.2 Module dependency check (both arches)

All MODULE_DEPENDs in the BT tree resolve inside the set above plus usb: ng_ubt→{netgraph, ng_hci, ng_bluetooth, usb} (ng_ubt.c:2055-2058), ng_ubt_intel/ng_ubt_rtl→{netgraph, ng_hci, usb} (ng_ubt_intel.c:288-290, ng_ubt_rtl.c:270-272), ng_hci/ng_l2cap→ng_bluetooth, ng_btsocket→{ng_bluetooth, netgraph}. device usb is in amd64 GENERIC and in arm64 std.dev:101 (device usb # USB Bus (required)), which arm64 GENERIC includes (sys/arm64/conf/GENERIC:24). The Pi 5's USB is behind RP1 (patches/0018-…, 0020-…) and the Pi 500+ already runs a USB keyboard through it, so ng_ubt on a dongle has a working uhub parent there.

amd64 vs arm64: no difference. All tokens are in the MI sys/conf/files/options, not files.amd64/files.arm64. Neither GENERIC carries any of them (grep -i netgraph sys/amd64/conf/GENERIC and sys/arm64/conf/GENERIC are empty), so this is purely additive on both. NEXTBSD-RPI5 inherits via include NEXTBSD.

1.3 Cost

Source: 10,578 lines for ng_base.c + ng_socket.c + every file under netgraph/bluetooth/ (measured, wc -l). Binary: not measured here — no build in this session. From memory of stock 14.x .ko sizes the resident text+data is on the order of 0.4–0.5 MB (netgraph ≈ 115K, ng_btsocket ≈ 105K, ng_hci/ng_l2cap ≈ 80K each, ng_ubt ≈ 40K, ng_socket ≈ 20K, ng_bluetooth ≈ 10K). K1's acceptance asks for the real size(1) delta on the CI kernel. Against the ~120 MB wired baseline the delivery plan measured, it is noise. On a machine with no radio the code is never entered beyond the SYSINIT that registers types and the btsock_* nodes.

1.4 Hidden lazy-load paths

Grep of sys/netgraph/** for kern_kldload|kldload|linker_load|modfind:

• sys/netgraph/ng_socket.c:281-303 — the only hit. Inside ngc_send(): if a message is NGM_MKPEER and ng_findtype(mkp->type) == NULL, it does kern_kldload(curthread, "ng_<type>", &fileid); on failure the mkpeer errors out (ENOENT/ENXIO). This is how stock FreeBSD's rc.d/bluetooth (required_modules="ng_bluetooth ng_hci ng_l2cap ng_btsocket", line 8, plus the mkpeers) works without anything in the kernel config. On NextBSD the kldload can never succeed; with the types baked, ng_findtype() succeeds and the branch is skipped. This should be added to the kernel#52 audit table.
• None in sys/netgraph/bluetooth/. ng_ubt attach only creates the ubt node; it never loads or mkpeers hci.
• Userland side: rc.d/bluetooth is itself a kldload consumer (required_modules), but NextBSD runs no rc.d, so it is irrelevant except as the reference for what bluetoothd must do.

2. What the kernel gives you, and what it does not

After K1, plugging in a class-E0/01/01 dongle yields:

ubt0 on uhub0
ubt0: <vendor product> on usbus0

and a netgraph node ubt0: of type ubt with one hook, hook. Nothing else. No ubt0hci, no L2CAP, no socket wiring, no HCI reset. On stock FreeBSD that is done by:

• sbin/devd/bluetooth.conf: attach 100 { device-name "ubt[0-9]+"; action "service bluetooth quietstart $device-name"; } (and quietstop on detach).
• libexec/rc/rc.d/bluetooth bluetooth_setup_stack(): ngctl mkpeer ${dev}: hci ${hook} drv → ngctl name ${dev}:${hook} ${dev}hci → mkpeer ${dev}hci: l2cap acl hci → name … ${dev}l2cap → connect ${dev}hci: btsock_hci_raw: raw ${dev}raw → connect ${dev}l2cap: btsock_l2c_raw: ctl ${dev}ctl → connect ${dev}l2cap: btsock_l2c: l2c ${dev}l2c → hccontrol -n ${dev}hci reset (3 tries) → read_bd_addr, read_local_supported_features, read_buffer_size, write_scan_enable, write_class_of_device, write_authentication_enable, write_encryption_mode, write_node_role_switch, change_local_name, initialize.

NextBSD strips /sbin/devd and /sbin/devmatch from the base (nextbsd-freebsd-compat README, "Superseded base tools": replaced by kextd + libIOKit) and never installs /etc/rc.d. So this is an interface to area 2: bluetoothd must subscribe to device arrival (libIOKit IOKitNotify / the kernel registry, the same path diskarbitrationd uses in ul/src/DiskArbitration/da_iokit_subscribe.c), and on ubt%d arrival run the equivalent of bluetooth_setup_stack() through libnetgraph (NgMkSockNode + NgSendMsg), then the HCI init sequence. Until it exists, §8's hand recipe does it with ngctl.

Good news on the userland tools: the compat base is a full buildworld with only WITHOUT_TOOLCHAIN/TESTS/LIB32/DEBUG_FILES (nextbsd-freebsd-compat .github/workflows/build.yml:30-31, README "What it builds"), and MK_BLUETOOTH/MK_NETGRAPH default to yes (share/mk/src.opts.mk:70,150; MK_BLUETOOTH is only forced off when MK_NETGRAPH=no, :444-445). So hccontrol, l2ping, l2control, sdpcontrol, sdpd, hcsecd, bthidd, bthidcontrol, iwmbtfw, rtlbtfw, ngctl, libbluetooth, libsdp, libnetgraph should already be in nextbsd-base-<arch>.tar.gz. Not verified on an image — the site's srclist plan (site/freebsd-srclist-build-plan.html) marks usr.sbin/ngctl as DEFER, but that plan is not what the compat repo builds today. K1's acceptance includes ls /usr/sbin/hccontrol /usr/sbin/ngctl on the CI image so this is settled by evidence.

3. Controllers, chipsets, firmware

3.1 What ng_ubt claims (sys/netgraph/bluetooth/drivers/ubt/ng_ubt.c)

• Generic: any interface with class UDCLASS_WIRELESS (0xE0) / subclass UDSUBCLASS_RF (0x01) / protocol UDPROTO_BLUETOOTH (0x01) — ubt_devs[]:452-455. This is every standards-conforming dongle (CSR, Cambridge, Qualcomm/CSR8510, modern Intel/Realtek/MediaTek once firmware is up).
• Vendor-class Broadcom (USB_VENDOR_BROADCOM + UICLASS_VENDOR/UDSUBCLASS_RF, :460-463), Apple (:466-469, i.e. every Mac's BCM20702/BCM4360-family combo card), Foxconn (:473-475), plus explicit BCM20702A0 ids (ASUS/Lite-On/Foxconn/Dell/Belkin, :520-526) and legacy TDK/ALPS/Ericsson/Canyon.
• ubt_ignore_devs[]:392-446: AVM BlueFritz v1, Atheros AR3011/AR3012/AR9285/AR5BBU12 with sflash firmware (need ath3kfw), all twelve Intel ids (handed to ng_ubt_intel.c), AzureWave 3602/3604. ubt_rtl_devs are likewise refused by the base probe (:625-627) and handled by ng_ubt_rtl.c.
• Probe returns BUS_PROBE_GENERIC (:638,641), so a more specific driver can outbid it.

Broadcom patchram: ng_ubt contains no patchram/.hcd download (grep broadcom|BCM in the file shows only id tables). Linux's btbcm would push a .hcd into BCM20702/BCM4350-class parts; FreeBSD runs them on ROM firmware. They work (Macs have run FreeBSD BT this way for years) but with whatever bugs the ROM has and no vendor updates. Not an E16 blocker; noted as a known gap.

3.2 Intel — ng_ubt_intel.c + iwmbtfw(8)

• Devices: VID 0x8087 PIDs 07dc,0a2a,0aa7 (7260/7265), 0a2b,0aaa,0025,0026,0029 (8260/8265/9260-era), 0032,0033,0035,0036 (9260/9560/AX-class) — ng_ubt_intel.c:89-105.
• Behaviour: the probe issues vendor HCI reads (Intel_Read_Version, TLV image type) and returns ENXIO while the part is in bootloader mode (:193-270), because attaching the stack then "locks the adapter hardly so it requires power on/off cycle to restore" (:33-37). Once iwmbtfw has loaded operational firmware the device re-enumerates and ng_ubt attaches normally.
• Firmware: iwmbtfw -d <ugenN.M> -f <dir> (iwmbtfw.8:59-61: "available in the comms/iwmbt-firmware port"). The port pulls firmware-iwlwifi_<date>_all.deb from Debian non-free-firmware and installs usr/lib/firmware/intel/ibt-* (.sfi + .ddc) to /usr/local/share/iwmbt-firmware (comms/iwmbt-firmware/Makefile; LICENSE=INTEL, LICENSE_PERMS= dist-mirror dist-sell pkg-mirror pkg-sell auto-accept). Redistribution is fine; the set is large (many ibt-* variants — size not measured, K3 asks for it).
• Trigger on stock FreeBSD: usr.sbin/bluetooth/iwmbtfw/iwmbtfw.conf — devd notify on system USB / subsystem DEVICE / type ATTACH / vendor 0x8087 / product (…12 ids…) → /usr/sbin/iwmbtfw -d $cdev -f /usr/local/share/iwmbt-firmware.

3.3 Realtek — ng_ubt_rtl.c + rtlbtfw(8)

• Devices: all of USB_VENDOR_REALTEK class E0/01/01 plus ~40 explicit VID/PIDs (ng_ubt_rtl.c:69-169); the probe reads HCI_Read_Local_Version and refuses (ENXIO) when lmp_subversion is in the "ROM firmware incompatible with ng_ubt" list (:172-181, 248-250).
• Firmware: rtlbtfw -d <ugen> -f <dir>; port comms/rtlbt-firmware (Debian firmware-realtek_<date>_all.deb → usr/lib/firmware/rtl_bt/*, LICENSE=REALTEK, same permissive LICENSE_PERMS). Small (a few MB).
• Trigger: usr.sbin/bluetooth/rtlbtfw/rtlbtfw.conf — 365 lines of devd notify rules: generic vendor 0x0bda + interface 0 + intclass 0xe0/intsubclass 0x01/intprotocol 0x01, then per-chip ids for 8821CE/8851BE/8852AE/8852BE/8852CE/8922AE/8723AE/BE/BU/DE/8761BUV/8821AE/8822BE/8822CE (VIDs 0x13d3, 0x0489, 0x04ca, 0x04c5, 0x0cb8, 0x0b05, 0x2357, 0x7392, …).

3.4 Others

• Atheros AR3011/AR3012 (ath3kfw(8)): firmware "available in the linux-firmware RPM" (ath3kfw.8:57), no port, devd rule is a commented-out example in sbin/devd/devd.conf:71-76. Rare today; park.
• MediaTek MT7921/7922 combo (0x0e8d): class E0/01/01 so ng_ubt claims it, but those parts need an mt7921-style firmware push FreeBSD has no tool for; expect a non-functional attach. Flagged, unverified.
• BCM2033 (ubtbcmfw/bcmfw): skip (§1.1).

3.5 How NextBSD ships firmware today, and why BT is different

• The image assembly deletes /boot/firmware and the .ko tree (nextbsd-kernel/ci/assemble-image.sh:168-169); nextbsd#392 is about a stray /boot/firmware/iwm* that crept back.
• Kernel-consumed firmware lives inside the kext bundle (Contents/Resources/firmware/) and is found by firmware(9) via patch 0004-NextBSD-search-firmware_path-for-raw-firmware-images.patch (kernel#12/#13; IntelWiFi.kext carries 267 MB this way per the WLAN plan).
• Bluetooth firmware is consumed by userland tools reading files from a directory, not by firmware(9). ng_ubt_intel.c deliberately does not download; it just refuses to attach. So the kext firmware path does not apply and there is no kext to hang it on (§6).
• Precedent for non-pkg blobs fetched at image build time already exists: nextbsd/build.sh:444-482 fetches the Pi DTBs and LICENCE.broadcom from raspberrypi/firmware at a pinned tag, and ships the licence next to them. K3 does the same for ibt-* and rtl_bt/* from Debian's firmware-nonfree pool (the ports' own MASTER_SITES), into /usr/share/firmware/bluetooth/{intel,rtl_bt} plus the two copyright files. Alternative considered: a data-only org.nextbsd.firmware.bluetooth bundle under /System/Library/Extensions — consistent with the naming plan, but OSKext authentication (assemble-image.sh:199-202) and kextd would have to tolerate an executable-less bundle for no functional gain. Recommend the plain directory.

3.6 The trigger problem (interface to area 2)

On stock FreeBSD devd runs the loader on USB attach. On NextBSD:

• devd is stripped (compat README).
• launchd's HardwareMatch is iter 1: parse and store only; the criteria are name/class/driver, and "iter 2 registers them against hwregd's watch RPC and dispatches" (ul/src/launchd/src/core.c:262-270, 6014-6047). There is no hwregd daemon in ul/src (only libIOKit consumers reference the name). Even at iter 2, the criteria cannot express VID/PID.
• The in-kernel IOCatalogue reacts to device_nomatch for PCI and FDT only (§6). An Intel part in bootloader mode is a ugen with no driver, which is exactly a nomatch — but there is no USB provider to hang a personality on.

So the trigger belongs to bluetoothd: subscribe to USB device arrival via libIOKit, match the union of iwmbtfw.conf/rtlbtfw.conf ids (or simply "VID 0x8087 or 0x0bda, or class E0/01/01 with no ubt sibling after N ms"), run /usr/sbin/iwmbtfw|rtlbtfw -d ugenX.Y -f /usr/share/firmware/bluetooth/<vendor>, and expect the device to detach/re-attach as ubtN. K4 records this contract for the daemon ticket set. An in-kernel port of Linux btintel/btrtl into ng_ubt_* (which would let firmware(9) + a kext bundle work) is the long-term "right" shape but is thousands of lines and not needed for E16.

4. Raspberry Pi 5 / Pi 500 onboard Bluetooth

4.1 The hardware, from the vendor device tree

raspberrypi/linux rpi-6.6.y (the tree whose bcm2712.dtsi still carries the SoC UART nodes; the rpi-6.12.y copy has moved them into includes):

• bcm2712-rpi-5-b.dts:365-380: /* uarta communicates with the BT module */ &uarta { uart-has-rtscts; auto-flow-control; clock-frequency = <96000000>; pinctrl-0 = <&uarta_24_pins &bt_shutdown_pins>; bluetooth { compatible = "brcm,bcm43438-bt"; max-speed = <3000000>; shutdown-gpios = <&gio 29 GPIO_ACTIVE_HIGH>; local-bd-address = [00 00 00 00 00 00]; }; }. The Pi 500 dts #includes the 5-B dts (bcm2712-rpi-500.dts:2), so same wiring. krnbt (bcm2712-rpi.dtsi:220) and bdaddr (:177) are the config.txt overrides on that node.
• bcm2712.dtsi:510-519 (6.6.y): uarta: serial@7d50c000 { compatible = "brcm,bcm7271-uart"; reg-shift = <2>; reg-io-width = <4>; interrupts = <GIC_SPI 276>; skip-init; } — physical 0x107d50c000. Not the PL011: the debug console NextBSD uses is uart10: serial@7d001000 (arm,pl011, bcm2712.dtsi:241-249, config/rpi5.env).
• bcm2712.dtsi:497-508: gio: gpio@7d508500 { compatible = "brcm,brcmstb-gpio"; brcm,gpio-bank-widths = <32 22>; } — BT_ON is line 29 here (not on RP1's GPIO, which NextBSD already drives with patch 0025/0048).
• bcm2712.dtsi:402-…: pinctrl: pinctrl@7d504100 { compatible = "brcm,bcm2712-pinctrl"; uarta_24_pins { pin_rts { function="uart0"; pins="gpio24" }; pin_cts { pins="gpio25" } … } and bt_shutdown_pins { function="gpio"; pins="gpio29" } (bcm2712-rpi-5-b.dts:354-357).

4.2 What FreeBSD 15.1 has for each piece

4.3 Verdict

Five independent missing pieces (UART compat/clock, brcmstb-gpio, bcm2712-pinctrl, an H4 transport rebuilt on ttyhook, a patchram tool + firmware packaging), plus a BD-address fix-up, plus an hcseriald equivalent that has to be owned by bluetoothd. Every one is a first for FreeBSD. That is XL and off E16's critical path. kernel#99 (BCM43455 WiFi over SDIO) shares the chip but not a single line of this — the BT interface is a separate UART.

Recommendation: park (K8) behind a measurement spike (K7). For E16 the supported Pi path is a USB dongle in one of RP1's xhci ports, which exercises exactly the baked stack from §1. Say so in the epic so nobody expects the onboard radio to light up.

5. Kext or baked? — Recommendation: bake all of it

The driver-delivery plan's rule (site/nextbsd-driver-delivery-plan.html §3): three tiers, and "kext ⇐ has-firmware ∨ needs-multi-version"; otherwise compiled-in or plain kld. Applying it:

1. The protocol nodes (ng_hci, ng_l2cap, ng_btsocket, ng_bluetooth, netgraph itself) are not device drivers. They are created by NGM_MKPEER from userland; no device_nomatch ever fires for them, so neither the IOCatalogue nor kextd would ever be asked to load them. The only "autoload" mechanism is ng_socket.c's kern_kldload hack, and turning that into a kextd Mach request is a new kernel feature for no benefit. They must be baked.
2. ng_ubt cannot be matched by the catalogue today. iocatalogue.h:24-31 defines exactly IOCAT_PROVIDER_IOPCIDEVICE and IOCAT_PROVIDER_IOPLATFORMDEVICE (FDT compatible); the nomatch work item carries a PCI match_word "0 if FDT" and a compat[] string (iokit_catalogue.c:270-279). The six gen-*-personalities.sh in nextbsd-kernel-extensions all emit IOProviderClass IOPCIDevice. Matching on USB class E0/01/01 (IOUSBInterface + bInterfaceClass/bInterfaceSubClass/bInterfaceProtocol, or idVendor/idProduct) is a new provider kind, a new capture path on the USB nomatch, and a new generator — real work that E16 does not need.
3. ng_ubt fails the kext bar anyway. It carries no firmware(9) firmware (Intel/Realtek firmware goes through userland tools, §3), and there is one version of it. ~2,600 LOC across the three files.
4. Cost of baking is small (§1.3) and the code is inert without a radio.

Where a kext would fit later: an IOUSBDevice provider in the catalogue is worth having for the general USB-driver population (audio, serial, WLAN dongles), and ng_ubt could move out then. That is a K-series feature, not an E16 one — listed as an open question, not a ticket. For the Pi 5 UART transport, the BT node is a child of a UART node with no bus driver enumerating it, so it too would be baked into NEXTBSD-RPI5 whenever it exists.

6. Testing

6.1 What is and is not possible

• QEMU has no Bluetooth. The core BT emulation and the usb-bt-dongle device were removed in November 2019 (qemu commits 1d4ffe8dc7 "Remove the core bluetooth code", 43d68d0a94 "hw/usb: Remove the USB bluetooth dongle device"; shipped in 4.2). There is nothing to emulate against.
• USB host passthrough works on a Linux host: -device usb-host,vendorid=0x0a12,productid=0x0001 (qemu docs/system/devices/usb.rst:160-165, :318-330), given /dev/bus/usb permissions and an xhci/ehci controller in the guest (-device qemu-xhci is already how the boot tests get USB). On macOS/HVF (nextbsd#408 runs the harness there) libusb passthrough requires detaching the host driver and is unreliable — treat it as a developer convenience, not CI. GitHub-hosted runners have no dongle either way.
• Real hardware is the real test, exactly as the WLAN plan said (nextbsd-wlan-plan.html:45).

6.2 What CI can prove without a radio (K2)

After K1, on the existing qemu boot test (nextbsd/tests/boot-test.sh, both arches):

ngctl list                       # must show btsock_hci_raw, btsock_l2c_raw, btsock_l2c (and a
                                 # `ngctl(pid)` socket node) — the ng_btsocket nodes exist at boot
                                 # (ng_btsocket_hci_raw.c:197-207 creates and names them at init)
ngctl types                      # must list types hci, l2cap, ubt, socket (registered by NETGRAPH_INIT)
sysctl -n net.bluetooth.version  # prints NG_BLUETOOTH_VERSION (ng_bluetooth.c:59-62); ENOENT before K1
hccontrol read_bd_addr; echo $?  # exit 7, stderr "Could not find HCI nodes" (hccontrol.c:110-112)
                                 # NOT "Could not create socket: Address family not supported…"
l2ping -a 00:00:00:00:00:01      # must fail on the connect, not on socket(2)
ls /usr/sbin/hccontrol /usr/sbin/ngctl /usr/sbin/iwmbtfw /usr/sbin/rtlbtfw /usr/sbin/sdpd /usr/sbin/bthidd

Plus the guard that the WLAN plan asked for in kernel#52: fail the kernel build if config -x of the built kernel lacks any of the seven options.

6.3 A controller emulator (K5, hardening)

ng_hci does not care what is on its drv hook (ng_hci.h:62: "drv" /* Driver <-> HCI */). A userland process can NgMkSockNode(), mkpeer . hci <hook> drv, name it emu0hci, wire l2cap and the btsock_* nodes exactly as rc.d/bluetooth does, and then answer HCI commands arriving on its data socket with Command Complete events (Reset, Read_BD_ADDR, Read_Local_Supported_Features, Read_Buffer_Size, Write_Scan_Enable, …), and optionally fake an inquiry result and an ACL connection. That runs the whole ng_hci/ng_l2cap/ng_btsocket path plus hccontrol/l2ping/sdpd in qemu with no hardware — the Bluetooth analogue of a loopback interface, and the only way CI will ever exercise bluetoothd's state machine before real dongles do. ~400 LOC of C over libnetgraph. Linux has the same thing (vhci/btvirt); FreeBSD never grew one.

7. Phase 1 hand-verification recipe (real dongle, after K1)

Class-E0 CSR/Cambridge dongles (0a12:0001) are the zero-firmware baseline; test Intel/Realtek only after K3/K4.

### 0. enumeration
usbconfig                                  # ugenX.Y: <…> … cfg=0 md=HOST spd=FULL (12Mbps) pwr=ON
dmesg | grep ubt                           # ubt0 on uhubN
ngctl list                                 # ubt0 (type ubt), btsock_* nodes

### 1. build the graph by hand (what bluetoothd will do; verbatim from rc.d/bluetooth)
ngctl mkpeer ubt0: hci hook drv
ngctl name ubt0:hook ubt0hci
ngctl mkpeer ubt0hci: l2cap acl hci
ngctl name ubt0hci:acl ubt0l2cap
ngctl connect ubt0hci: btsock_hci_raw: raw ubt0raw
ngctl connect ubt0l2cap: btsock_l2c_raw: ctl ubt0ctl
ngctl connect ubt0l2cap: btsock_l2c: l2c ubt0l2c

### 2. bring the controller up
hccontrol -n ubt0hci reset
hccontrol -n ubt0hci read_bd_addr                 # BD_ADDR: xx:xx:xx:xx:xx:xx  <- the real proof
hccontrol -n ubt0hci read_local_version_information
hccontrol -n ubt0hci read_local_supported_features
hccontrol -n ubt0hci read_buffer_size
hccontrol -n ubt0hci write_scan_enable 3          # discoverable + connectable
hccontrol -n ubt0hci write_class_of_device 0x1c0104
hccontrol -n ubt0hci change_local_name nextbsd
hccontrol -n ubt0hci initialize
hccontrol -n ubt0hci read_node_state              # must be "up"

### 3. see the world
hccontrol -n ubt0hci inquiry                      # lists BD_ADDR + class of nearby discoverable devices
hccontrol -n ubt0hci remote_name_request <addr> 0 0 0

### 4. L2CAP + SDP against a phone/headset in pairing mode
l2ping -a <addr>                                  # 44 bytes from … seq_no=0 time=… ms result=0
sdpcontrol -a <addr> browse                       # service records (Handsfree, A2DP sink, HID, …)

### 5. teardown (what bluetoothd does on detach)
ngctl shutdown ubt0hci:
ngctl shutdown ubt0l2cap:

Intel/Realtek addendum (after K3): usbconfig shows the part with no ubt sibling; run iwmbtfw -d ugenX.Y -f /usr/share/firmware/bluetooth/intel (or rtlbtfw … /rtl_bt), watch the device detach and come back as ubt0, then continue from step 1. Pairing (hcsecd), HID (bthidd) and audio are areas 2–4.

Record the result in the hardware matrix (K6): dongle ids, arch, board (a Pi 500+ via RP1 xhci is on the list), what worked, kernel/userland SHAs.

8. Open questions

1. Kernel size delta — measure in K1 (size /boot/kernel/kernel before/after) rather than trusting §1.3's estimate.
2. Are the BT userland tools really on the image? Expected yes (§2) but unverified; K1's acceptance settles it.
3. Firmware set size for Intel ibt-* — measure in K3; if it is tens of MB, consider trimming to the ids ng_ubt_intel.c lists (the tool picks by hw_variant/hw_revision, so the mapping is derivable from iwmbtfw's source).
4. Who runs the firmware loaders — §3.6 argues bluetoothd; if area 2 prefers a separate org.nextbsd.btfw one-shot, K4's contract still holds.
5. Pi firmware state of gio 29 / uart0 pinmux / uarta clock — K7 measures; changes K8's scope.
6. IOUSBDevice matching in the catalogue — not needed for E16; worth a K-series ticket later so USB drivers can be kexts.
7. Broadcom patchram for USB parts (BCM20702 on Macs) — ROM firmware works; a .hcd loader over ugen (~300 LOC, same shape as iwmbtfw) would be a Harden item if Mac users hit ROM bugs.
8. BLE — the stack supports LE HCI commands (hccontrol has an le_commands table, hccontrol.c:190) but no LE L2CAP/ATT/SMP; that is the seed ticket's "classic first" question, not a kernel-config one.

9. Risks

• Silent failure class (kernel#52). If any of the seven options is dropped in a future config edit, the symptom is hccontrol: Could not create socket or ngctl: send msg: No such file or directory, not a kernel message. K2's boot-test assertions are the guard.
• Intel bootloader lock-up. Attaching the stack to an Intel part in bootloader mode hard-locks it until power-cycle (ng_ubt_intel.c:33-37). ng_ubt_intel prevents this, and it is inside the same NETGRAPH_BLUETOOTH_UBT token, so it cannot be forgotten — but a future "generic class E0" kext or a hand mkpeer on the wrong node could still do it.
• Firmware licence hygiene. Intel/Realtek/Cypress blobs must ship with their copyright/EULA text; the DTB precedent (build.sh:480-482) shows how.
• Hardware coverage. Until K6 runs on real dongles, everything above the USB enumeration is reasoned from source. Same honesty clause as the WLAN plan.
• Pi 5 expectations. The onboard radio being parked must be visible in the epic, or "Bluetooth on the Pi 500" will be read as promised.

10. Ticket index (see 1-kernel-hardware-tickets.json)

Engine & Classic vs BLE (B)

Deep-dive notes, lightly edited. Draft ids map to issues in the index.

Research for nextbsd/nextbsd#473 (E16 Bluetooth), seed nextbsd/nextbsd#412. Read-only; nothing filed. All FreeBSD file:line cites are against releng/15.1 at 88e7371d9dc26f85dfc1b008cbe59ebc7e4a33da (2026-08-24, "Add UPDATING entries and bump version"), sparse-cloned to freebsd-src.

TL;DR

1. The plans-site page is wrong on the central fact. site/freebsd-bluetooth-management.html §4–5 says FreeBSD's stack "supports Classic Bluetooth only — no BLE, no GATT, no SMP" and that "the gap is in the kernel". It is not. Since Takanori Watanabe's 2015 commits (fbc48c2bfb "Initial Bluetooth LE support", 3a601a2381 "Bluetooth LE Security Management channel support") the kernel does LE HCI, LE ACL connections, and exposes the ATT (CID 4) and SMP (CID 6) fixed channels as ordinary AF_BLUETOOTH L2CAP sockets with an LE address type in sockaddr_l2cap. What is missing is entirely userland: there is no GATT client, no SMP pairing agent, no LTK store, no HOGP driver in base. Those exist as an out-of-tree prototype (takawata/FreeBSD-BLE, HOGP mouse working; rhaberkorn/FreeBSD-BLE 2025 fork adds a one-shot HID pairing script) with no license file.
2. Classic-first is still right, but for a different reason than "FreeBSD can't do LE". Classic covers every headset (A2DP/HFP are BR/EDR; LE Audio is not on Apple and is still a minority of shipping headsets), Apple's Magic Keyboard/Mouse/Trackpad (BR/EDR HID), and the older/cheaper keyboard population. It does not cover the Logitech MX line, Microsoft Surface keyboards, Keychron, or essentially any mouse/keyboard designed after ~2018 — those are LE-only (HOGP). So "Classic first" ships headsets + Apple peripherals; LE HID is the second milestone, not a someday, and the engine interface must be written for both from day one.
3. Engine recommendation: Classic engine = netgraph kernel stack driven directly by bluetoothd over the raw HCI socket (absorbing hcsecd's three-event loop and adding SSP, which the kernel now passes through since 4ae0fa8a2f, 2025-01). LE engine = a small userland ATT/GATT/SMP host over the kernel's ATT/SMP sockets — the FreeBSD-BLE shape, clean-room or relicensed — not a full third-party host. NimBLE/BTstack-style full hosts need the raw ACL stream, which on netgraph means taking ng_hci's single acl hook away from ng_l2cap and killing Classic (BTstack's own FreeBSD port documents exactly this). BlueZ stays out. A NimBLE spike is worth one ticket only to price the "tee node" alternative; the default is the thin host.
4. Kernel LE gaps that matter are small and fixable in nextbsd-kernel: LE buffer accounting ignores LE_Read_Buffer_Size; LE_Connection_Update_Complete, LE_Read_Remote_Features, LE_Enhanced_Connection_Complete are stubs; LE signalling accepts parameter-update requests but never forwards them to the controller; LE CoC (dynamic LE channels) unsupported. None block HOGP.

1. Exact state of FreeBSD 15.1's stack

1.1 What exists (LE), with cites

Commit trail (all git log via gh api repos/freebsd/freebsd-src/commits?path=…&sha=releng/15.1): bcff2d9100 2015-04-18 hccontrol LE commands; fbc48c2bfb 2015-04-07 kernel initial LE; 3a601a2381 2015-10-27 SMP channel; 483ed39512 2015-11-07 encryption error handling; b32073c458 2016-06-07 LE socket teardown; 4aa92fe2f3 2017-04-27 AD cache to userland; 2020-04..07 hselasky/takawata hccontrol le_scan, le_connect, whitelist, advertising; 4ae0fa8a2f 2025-01-27 SSP events; 2c6feab253 2026-03-18 generic AdvData. Nothing LE-related landed on main between 2025-06 and 2026-09 beyond that (checked sys/netgraph/bluetooth and usr.sbin/bluetooth paths).

1.2 What is missing (precisely)

Kernel (nextbsd-kernel, all small):

• LE buffer accounting. LE_Read_Buffer_Size is in the "no post processing" list (ng_hci_cmds.c:824); the unit's ACL packet budget comes only from the BR/EDR Read_Buffer_Size reply (ng_hci_main.c:412 area, NG_HCI_BUFF_ACL_TOTAL). Controllers with a separate, smaller LE pool can be over-driven; controllers reporting LE buffer size 0 (shared pool) are fine. Not observed as a bug in FreeBSD-BLE use (HID traffic is tiny) — unverified risk, worth a targeted fix.
• Stub LE meta handlers: LE_Connection_Update_Complete (ng_hci_evnt.c:571-578 TBD), LE_Read_Remote_Features_Complete, LE_Long_Term_Key_Request (:602-606, both //TBD fallthrough to free). Peripheral-role LTK reply therefore must come from userland via raw HCI (the event is mirrored there). LE_Enhanced_Connection_Complete (0x0a) is defined but not handled — so userland must not enable it in the LE event mask, or connections never register in the kernel.
• LE signalling: parameter-update requests are accepted but never forwarded as LE_Connection_Update (ng_l2cap_cmds.c:224-226 TBD). HOGP mice that ask for a faster interval get an ACK and no change — functional, higher latency. (rhaberkorn fork commit 6b146e2aae "commented-out connection update for optimized latency" is userland working around this via raw HCI.)
• LE CoC (ng_btsocket_l2cap.c:2188-2190) — not needed for HID; needed for some modern GATT-over-CoC/EATT devices only.
• No extended advertising / 2M-coded PHY / periodic adv OCFs in ng_hci.h (0x20+, 0x36+ absent). Root raw sockets can still send them (the security filter only gates unprivileged sockets, ng_btsocket_hci_raw.c:684-715), but process_le_params returns EINVAL for unknown OCFs (:857-866), which just logs — unverified whether the error path drops the command-complete from the raw mirror; needs a test.
• ISO channels / LE Audio: nothing.

Userland (base has none of this):

• GATT client (service/characteristic discovery, read/write/notify), ATT MTU exchange.
• SMP pairing agent (legacy LE pairing incl. Just-Works/Passkey; LE Secure Connections needs P-256 ECDH — do it in userland with libcrypto; the controller P-256 OCFs 0x25/0x26 are not in ng_hci.h).
• LTK/IRK/CSRK bond store, and the peripheral-role responder for LE_Long_Term_Key_Request → LE_Long_Term_Key_Request_Reply (defined, ng_hci.h:1778).
• HOGP (HID over GATT) → uhid/evdev bridge (bthidd is Classic only: bthidd/{client,server}.c hardcode BDADDR_BREDR, l2cap_cid = 0).
• Advertising-data parsing for the scan UI (kernel gives raw AD bytes).
• Random/resolvable-address handling (IRK resolution).

All of that is what takawata/FreeBSD-BLE implements: le_enable (scan, connect ATT, dump attributes, ~23 KB C), lepair (SMP legacy pairing, prints EDIV/Rand/LTK, ~12 KB), lesecd (hcsecd-shaped LTK responder daemon, ~12 KB + yacc/lex config), lehid (GATT client with HOGP mouse via uinput, battery, HRP, MIDI… ~100 KB of small service drivers). README: "Kernel support was already committed to main trunk." Last upstream push 2023-05-01; rhaberkorn fork (improvements branch, 2025-01) adds HOGP heuristics, mouse events via uevent, random addresses, and hid-pair.sh. License: none in either repo (GitHub reports no license; all rights reserved by default). The FreeBSD forum thread "The current state of BT-LE?" (2024-11 → 2025-02) shows it being used against an MX Master 3S with ATT timeouts on that device — i.e. a prototype, not a product.

1.3 Classic state (for completeness)

Complete for HID/A2DP-transport/RFCOMM/SDP: ng_l2cap, ng_btsocket_{l2cap,rfcomm,sco,hci_raw}, sdpd, bthidd (kbd + mouse → uinput/vkbd), btpand, rfcomm_pppd, hcsecd. Pairing is legacy PIN only in hcsecd; a device that insists on SSP/Secure Connections Only will not pair until a daemon answers IO_Capability_Request and User_Confirmation_Request over the raw socket — which the kernel now permits. No A2DP/AVRCP/HFP codec or audio path in base (area A).

2. Permissively licensed LE host stacks — comparison

Evaluated for: running in NextBSD userland, over what transport, coexisting with kernel Classic on the same controller.

Coexistence rule, from the code: anything that needs to send LE ACL data must go through ng_l2cap, because ng_hci has exactly one acl hook and the raw hook is command-only. ng_l2cap already provides exactly the two LE fixed channels a GATT/SMP host needs, as sockets, with per-socket encryption state. So the thin host is not a compromise — it is the design the kernel was built for, and it coexists with Classic by construction: the same raw HCI socket, with different event filters (SO_HCI_RAW_FILTER), serves inquiry + SSP for Classic and scan + LTK for LE, and one daemon owns both.

3. Market reality — what users bring

Reading: Classic covers audio and Apple input; LE covers nearly every third-party keyboard/mouse sold since ~2018. A desktop user with an MX Master and a Keychron gets nothing from a Classic-only stack; a user with AirPods and a Magic Keyboard gets everything. Neither half is optional for "a desktop", but Classic first is correct because (a) its kernel path is complete and battle-tested, (b) bthidd exists, (c) it is where pairing UX (PIN/SSP) and the bond store get designed once, and (d) LE's userland is the same daemon plus one more engine module, not a new architecture.

4. Recommendation

4.1 Decision

Classic-first on netgraph, LE second on the same daemon via a thin userland ATT/GATT/SMP host over the kernel's LE fixed-channel sockets. Concretely:

1. bluetoothd owns the raw HCI socket per adapter (root; privileged filter bypass). It absorbs hcsecd (three events → link-key file) and adds SSP (IO-cap reply "DisplayYesNo"/"KeyboardOnly"/"NoInputNoOutput" per UI availability, numeric comparison, passkey entry) — the kernel now forwards those events. This is engine work, not a wrapper: hcsecd is 500 lines and has no SSP; supervising it buys nothing (unlike wpa_supplicant, which is 300 k lines).
2. sdpd and bthidd are supervised as launchd jobs, wpa_supplicant-style, not absorbed; bthidd.conf is generated by bluetoothd from the bond store (area H).
3. LE engine = new module in bluetoothd (or a libbtle it links): GAP over raw HCI (scan/adv-report parsing, LE_Create_Connection — or let the kernel do it via socket connect() with an LE address type, which is simpler), ATT/GATT client over the CID-4 socket, SMP over the CID-6 socket, LTK responder for LE_Long_Term_Key_Request on raw HCI, LE_Start_Encryption for central role. HOGP → uhid/evdev bridge lives in area H but consumes this engine's GATT API.
4. Do not vendor a full host. File one spike (B7) to price a ng_btle_tee node that would let NimBLE take LE ACL — only if the thin host stalls on GATT breadth (EATT, CoC, LE Audio).
5. Engine-neutral bond record from day one: {addr, addr_type, kind: BREDR|LE, link_key | {ltk, ediv, rand, irk, csrk, key_size, authenticated, sc}, name, class/appearance, hid: bool} in SCPreferences (WLAN precedent; keychain later).

4.2 Engine interface bluetoothd should code against

Modelled on ul/src/WLAN/supplicant.h (opaque engine object, fd for the event loop, pump-events returning "state changed", caller-owned caches, no callbacks across threads). One header, two implementations sharing the adapter/raw-HCI plumbing:

/* engine.h — what bluetoothd's policy layer sees. Transport-agnostic. */
enum bt_addr_type { BT_ADDR_BREDR, BT_ADDR_LE_PUBLIC, BT_ADDR_LE_RANDOM };
struct bt_addr    { uint8_t b[6]; enum bt_addr_type type; };      /* identity, not connection */

struct bt_found   { struct bt_addr addr; char name[249]; int rssi;
                    uint32_t cod;            /* Classic class-of-device */
                    uint16_t appearance;     /* LE GAP appearance */
                    uint8_t  ad[240]; uint8_t ad_len;            /* raw AD/EIR */
                    bool     bredr, le; };   /* which engines saw it */

enum bt_pair_io   { BT_IO_NONE, BT_IO_DISPLAY_YESNO, BT_IO_KEYBOARD, BT_IO_DISPLAY_ONLY };
enum bt_pair_ask  { BT_ASK_PIN, BT_ASK_PASSKEY, BT_ASK_CONFIRM, BT_ASK_DISPLAY_PASSKEY };
struct bt_pair_prompt { enum bt_pair_ask kind; uint32_t passkey; };   /* surfaced to CLI/UI */

struct bt_bond    { struct bt_addr addr; enum { BOND_BREDR, BOND_LE } kind;
                    uint8_t link_key[16];                              /* Classic */
                    uint8_t ltk[16], irk[16], csrk[16]; uint16_t ediv; uint64_t rand;
                    uint8_t key_size; bool authenticated, secure_conn;  /* LE */ };

struct bt_engine_ops {
    const char *name;                                 /* "classic" | "le" */
    int  (*attach)(struct bt_adapter *, struct bt_engine **);
    void (*detach)(struct bt_engine *);
    int  (*event_fd)(const struct bt_engine *);       /* raw HCI / L2CAP fds for kqueue */
    bool (*pump)(struct bt_engine *);                 /* drain events; true if state changed */
    int  (*discover)(struct bt_engine *, bool on);    /* inquiry+name / LE scan */
    int  (*found_count)(const struct bt_engine *);
    bool (*found_get)(const struct bt_engine *, int i, struct bt_found *);
    int  (*pair)(struct bt_engine *, const struct bt_addr *, enum bt_pair_io);
    int  (*pair_reply)(struct bt_engine *, const struct bt_addr *, const char *pin_or_passkey, bool yes);
    int  (*connect)(struct bt_engine *, const struct bt_addr *);
    int  (*disconnect)(struct bt_engine *, const struct bt_addr *);
    int  (*bond_export)(struct bt_engine *, const struct bt_addr *, struct bt_bond *);
    int  (*bond_import)(struct bt_engine *, const struct bt_bond *);   /* at boot, from SCPreferences */
    int  (*profiles)(struct bt_engine *, const struct bt_addr *, uint16_t *uuids, int max); /* SDP / GATT primary services */
};
/* Events the policy layer consumes (queue drained by pump()): */
enum bt_ev { BT_EV_FOUND, BT_EV_PAIR_PROMPT, BT_EV_PAIRED, BT_EV_PAIR_FAILED,
             BT_EV_CONNECTED, BT_EV_DISCONNECTED, BT_EV_BOND_UPDATED };

Rules that keep the LE engine a drop-in: device identity is bt_addr with type everywhere (the CLI shows AA:BB:..:FF/le-random); the bond store is keyed on it; bt_found carries raw AD/EIR so the UI can grow icons/appearance without an interface change; pairing prompts are one shape for PIN, SSP numeric comparison and LE passkey; the dynamic-store publication State:/Bluetooth/Device/<addr> uses the same dictionary for both. The Classic engine ships first with profiles() = SDP; the LE engine adds gatt_* calls in a sub-interface (struct bt_le_ops obtained via bt_engine_le(engine)) that area H's HOGP bridge uses — the policy layer never sees GATT.

4.3 How LE slots in later without rework

• Same daemon, same raw socket (a second SO_HCI_RAW_FILTER mask is not even needed — one socket with a union filter and a dispatcher keyed on event code).
• Same adapter bring-up sequence gains three commands: Write_LE_Host_Supported(1,0), LE_Set_Event_Mask (without bit 0x0a), Set_Event_Mask | LE_META (what hccontrol le_enable does, le.c:334-361).
• Discovery merges: one bt_found list; Classic inquiry and LE scan can run back-to-back on a dual-mode controller.
• Bond store already has the LE fields; bond_import at boot means "keyboard works at the login window" for both.
• bthidd (Classic HID) and the HOGP bridge both read bonds from bluetoothd; area H decides whether HOGP lands inside bthidd (it has the uinput glue) or a sibling.

5. Open questions

1. Licence of FreeBSD-BLE. Neither takawata/FreeBSD-BLE nor rhaberkorn/FreeBSD-BLE has a licence file. Ask Takanori Watanabe (FreeBSD committer takawata@) for BSD-2 — the kernel half is already BSD in base, and Hans Petter Selasky contributed PRs to the repo. Otherwise clean-room from the spec; the ATT/GATT/SMP core is ~2–3 kLOC.
2. Does PR 265066 include an hcsecd SSP patch that never landed? bugs.freebsd.org is behind an Anubis wall for automated fetch — unverified. If a userland SSP patch exists it shortcuts B4.
3. LE buffer accounting on Intel AX2xx. Needs hccontrol le_read_buffer_size on real hardware; if the LE pool is separate and smaller than the ACL pool, B5's fix is mandatory before HOGP notifications at 125 Hz.
4. Which hardware to bless. Intel AX200/AX210 (needs iwmbtfw at boot — NextBSD has no devd; how is the firmware loader triggered? area K), Realtek 8852, and a CSR 8510 dongle as the reference; Apple Silicon/Broadcom is out.
5. Address privacy. LE peripherals using RPAs need IRK resolution in the daemon and LE_Set_Random_Address for our own privacy; MVP uses identity addresses only (rhaberkorn -r shows random works at the socket level).
6. Does the policy layer expose GATT to apps (CoreBluetooth-shaped API for Gershwin) in this epic? Recommend no — E16 ships HID/audio; a CBCentralManager face is a later epic on the same engine.

6. Risks

• Plans-site page misleads the epic. §5/§6 of freebsd-bluetooth-management.html frames LE as a kernel project ("extend Netgraph… large kernel+userland effort"). If tickets are cut from that page, weeks go into re-implementing what ng_l2cap already does. Fix the page (B8).
• Classic pairing without SSP is a growing failure mode. Devices with "Secure Connections Only" or no legacy-PIN fallback will refuse hcsecd-style PIN pairing. SSP in bluetoothd is Ship-track, not Harden.
• Prototype-grade LE userland. FreeBSD-BLE has known ATT timeouts against at least one MX Master 3S (forum, 2025-02); expect device-specific GATT quirks (MTU exchange ordering, Read_By_Group_Type responses, notifications before CCCD write). Budget a hardware-in-the-loop soak.
• Kernel LE code is 2015-era and lightly exercised (le_connection_update TBD, error paths). NextBSD bakes it into the kernel, so a panic in ng_l2cap's LE paths (note the panic() default in ng_l2cap_con_wakeup, ng_l2cap_cmds.c:228-232) is a boot-visible failure. Fuzz the LE signalling path with Bumble before enabling by default.
• No CI hardware (as WLAN). Bumble's virtual controller + a VHCI-like path does not exist on FreeBSD; the closest is two USB dongles on one test box.
• Key material in SCPreferences — accepted debt, second consumer for the keychain plan.

7. Sources

• FreeBSD releng/15.1 tree (paths above), commit list via gh api repos/freebsd/freebsd-src/commits.
• takawata/FreeBSD-BLE: https://github.com/takawata/FreeBSD-BLE (README, tree, commits to 2023-05-01); rhaberkorn fork improvements branch (commits 2025-01-09..18).
• BTstack FreeBSD netgraph port: https://github.com/bluekitchen/btstack/tree/master/port/freebsd-netgraph ; licence https://github.com/bluekitchen/btstack/blob/master/LICENSE (clause 4).
• NimBLE: https://github.com/apache/mynewt-nimble (README "Bluetooth 5.4 stack… Host runs on any board and architecture"; porting/npl/linux; nimble/transport/socket/src/ble_hci_socket.c).
• Zephyr host architecture: https://docs.zephyrproject.org/latest/services/connectivity/bluetooth/bluetooth-arch.html
• Bumble: https://github.com/google/bumble (Apache-2.0; LE + Classic incl. A2DP/HFP/HID; HCI over USB/UART/VHCI).
• NetBSD: https://github.com/NetBSD/src/tree/trunk/sys/netbt (commit ace5c075a2, 2024-03-13).
• FreeBSD forums: "The current state of BT-LE?" (t=95598, 2024-11..2025-02); "Interest in porting Direct-BT" (t=99203, 2025-09..2026-01).
• Logitech: https://support.logi.com/hc/en-in/articles/31605553413783-Specification-MX-Master-3S-Bluetooth-Edition ; https://hub.sync.logitech.com/mx-anywhere-3/post/check-for-bluetooth-low-energy-support-600LdKtzhGM1pXD
• Microsoft Surface Keyboard: https://www.microsoft.com/en-us/d/surface-keyboard/8r3rqvvflp4k ; Keychron K2: https://www.keychron.com/products/keychron-k2-wireless-mechanical-keyboard
• Apple Magic devices on Linux (BR/EDR HID): https://forums.linuxmint.com/viewtopic.php?t=471463
• LE Audio adoption: https://www.bluetooth.com/learn-about-bluetooth/feature-enhancements/le-audio/ ; https://www.alphonsolabs.com/bluetooth-le-audio-compatibility-checklist/
• NextBSD: ul/src/WLAN/{supplicant.h,wland.h,wlan.defs} (engine-interface template); nextbsd-kernel/config/NEXTBSD (0 netgraph lines, confirming #412).

bluetoothd & the bluetooth CLI (D)

Deep-dive notes, lightly edited. Draft ids map to issues in the index.

Scoping notes for nextbsd/nextbsd#473 (E16 Bluetooth), seed nextbsd/nextbsd#412. Read-only research; no issues filed. Written 2026-09-20 against local clones of the NextBSD repos and FreeBSD releng/15.1.

Agreed and not relitigated: /usr/sbin/bluetoothd, job org.nextbsd.bluetoothd, Mach service org.nextbsd.bluetooth, CLI /usr/sbin/bluetooth; C + CoreFoundation below the Mach line; MIG; pure-C MIG client CLI; SCPreferences persistence; SCDynamicStore publishing; supervise stock daemons rather than modify them.

0. TL;DR

1. wland is a 4.1 kLOC, seven-file daemon (ul/src/WLAN/, 4119 lines total) with one CF translation unit, one Mach-service thread, one flat MIG .defs, one plist, one build block, and a hand-linked CLI. Copying its file layout one-for-one gives bluetoothd its skeleton for free (§1).
2. Replace hcsecd; do not supervise it. Evidence: hcsecd handles exactly three HCI events and logs everything else as an error (hcsecd.c:124-127, :190-193); it only stores a new link key for a device that is already declared in /etc/bluetooth/hcsecd.conf (hcsecd.c:392-396 calls get_key(.., exact_match=1)), so a device paired at runtime never gets its key saved unless something rewrites the config and SIGHUPs it first; it writes keys to disk only on SIGHUP or exit (hcsecd.c:202, :423); it answers PIN requests from a static file and has no way to ask a user; and it has no Secure Simple Pairing at all. The whole daemon is 448 lines and its reply code (~120 lines) is trivially reimplemented over the same raw HCI socket. Two processes answering Link_Key_Request on the same adapter would race, so "supervise hcsecd" is not even a safe option (§3).
3. SSP is possible on FreeBSD's kernel but nothing in base exercises it. The raw HCI hook receives a copy of every event before the kernel processes it (ng_hci_main.c:719 → ng_hci_misc.c:63-78), the per-socket event filter is a 64-bit bitmap (ng_btsocket.h:71-74) so the SSP events 0x31/0x33/0x36 pass, and ng_hci.h already defines IO_Capability_Request, User_Confirmation_Request, Simple_Pairing_Complete, the reply opcodes (0x2b/0x2c/0x2d/0x34) and Write_Simple_Pairing_Mode (0x0056). But hccontrol has no SSP command, the kernel never sets the controller event mask, and User_Passkey_Request (0x34) / IO_Capability_Response (0x32) are not defined. bluetoothd must send Set_Event_Mask and Write_Simple_Pairing_Mode itself. First real exercise needs hardware (§3.3).
4. bluetoothd owns the adapter lifecycle the way wland owns the VAP. On FreeBSD the netgraph graph (ubt0 → ng_hci → ng_l2cap → btsock_*) is built by /etc/rc.d/bluetooth (libexec_rc_rc.d_bluetooth, bluetooth_setup_stack), triggered by devd. NextBSD has neither rc.d nor devd (nextbsd/README.md:31). So bt_devenum() returns nothing until bluetoothd builds the graph itself with libnetgraph (§4).
5. Nothing in the tree can prompt a logged-in user. No LaunchAgents, no per-user daemons, no CFUserNotification; the only user-facing mechanism is notify_post (hostnamed) and the CLI. So pairing confirmation is pull, not push: bluetoothd parks the pairing in State:/Bluetooth/Pairing/<addr> + notify_post, and the CLI (bluetooth pair, bluetooth confirm) is the agent. Gershwin's pane drives the same two verbs via NSTask (§5.3).
6. Link keys are plaintext in SCPreferences, a second time, but in a separate prefs file from device metadata, 0600, behind one function (bt_keys_save()) so the keychain migration later touches one file and one function. This is WLAN's Q2 decision (airport.h:40-48) with a one-file improvement (§6).
7. CI without an adapter is a first-class deliverable. wland today is UNPROBED in the wedge check (wedge-check.sh:153,156) and has no boot-test gate at all. bluetoothd ships with markers (BT-RPC-OK, BT-NOSTACK/BT-NOADAPTER, BT-CLI-OK), a bluetooth status probe in wedge-check.sh, and is automatically covered by daemon-state.sh (§8).

1. How wland is actually built (the template)

1.1 Files

1.2 Rules wland encodes that bluetoothd must inherit

• MIG out-of-line data is broken in this kernel. wlan.defs:10-16, ipconfig.defs:19-22. Every routine argument is a scalar or fixed-size array; lists are count() + entry(i) (wland_mig.c:110-119).
• Nothing large goes in the dynamic store. CONFIG_DATA_MAX is 8192 bytes (ul/src/configd/config_types.h:74); airport.h:27-30. Scan results go over MIG only.
• No launchd ordering. "No StartAfter, no Requires, and the plist directory scan is not even sorted" (org.nextbsd.wland.plist comment, wland.c:507-512). configd is opened lazily and NULL is tolerated (wland.c:376-384, airport.c:91-101).
• The engine is stock and Mach-unaware. wland.c:41-55; wpa_supplicant is spawned by wland (not launchd) because its interface does not exist until wland creates it, with an empty config so wland is the sole author (wland.c:208-247).
• The Mach service comes up before any hardware work so a client gets "zero interfaces", not a bootstrap failure (wland.c:499-505).
• Hardware may attach after the daemon starts. adopt_phys() is re-run every 2 s (wland.c:93-99, :421-470), and stops only when the subsystem is provably absent from the kernel (VAP_NO_NET80211, vap.h:35-43, wland.c:526, :620-625).
• Runtime dirs are re-created on every attempt because /var/run may not exist yet at boot (wland.c:284-296, :308-317; userland#49).
• Log markers are grep-able tokens (WLAN-IF-OK, WLAN-AIRPORT-OK, WLAN-RPC-OK: wland.c:366, airport.c:207, mach_service.c:76), because CI reads /var/log/<daemon>.stderr (run.sh:869-873).
• CF is confined to one TU (airport.c:1-13), the Makefile carries WARNS=0, -fblocks, and the exact link line -llaunch -lsystem_kernel -lSystemConfiguration -lCoreFoundation -lsystem_dispatch -l:libsystem_blocks.so (Makefile:57-78).
• The CLI links only -llaunch -lsystem_kernel (build-userland.sh:763-776) — no CF, no SC — and that is the bridge for Gershwin (wlan.c:24-40).
• SCPreferences file is 0644 by default; the caller fixes perms (airport.c:319-324).

1.3 What wland does not have (and bluetoothd should)

• No boot-test marker and no wedge probe: wedge-check.sh:153 lists org.nextbsd.wland no client tool and :156 puts it in UNPROBED; nextbsd/tests/boot-test.sh contains no WLAN expectation at all (grep). The wlan CLI exists (build-userland.sh:763) but nothing runs it. bluetoothd's plan must not repeat this.
• No notify_post. wland relies on SCDynamicStore change notifications only. hostnamed is the one daemon that posts a notify name (hostnamed.c:20, hostnamed/Makefile:82).

2. FreeBSD's Bluetooth userland, per daemon

Sources under a local releng/15.1 fetch.

The devd hook that starts rc.d/bluetooth was not found in sbin/devd/devd.conf on releng/15.1 (grep for ubt, rc.d, quietstart returned nothing) — location unverified; irrelevant on NextBSD, which has no devd at all (nextbsd/README.md:31: device events are the in-kernel IORegistry + libIOKit).

ng_ubt.c does not create the hci/l2cap nodes itself (no mkpeer/NG_HCI_NODE_TYPE use; ng_ubt.c:2056 only MODULE_DEPENDs on ng_hci). Without the rc script, a plugged-in dongle is a bare ubt0: netgraph node and bt_devenum() (lib_libbluetooth_hci.c:691-720, ioctl SIOC_HCI_RAW_NODE_LIST_NAMES) lists nothing.

Whether NextBSD's base image actually ships libbluetooth, libsdp, libnetgraph, hccontrol, sdpd, bthidd (FreeBSD's MK_BLUETOOTH/MK_NETGRAPH default to yes; no WITHOUT_ knob was found in nextbsd/build.sh or ul/build-userland.sh) is unverified — nextbsd-freebsd-compat's src.conf is not in the scratch clones. Acceptance for D1 includes checking it.

3. Process model: replace hcsecd, supervise sdpd and bthidd, own the graph

                          Gershwin (ObjC, no Mach)
                Bluetooth.prefPane ── NSTask ──▶ /usr/sbin/bluetooth
 ═══════════════════════════════ Mach line ══════════════════════════════
                /usr/sbin/bluetooth  ── MIG org.nextbsd.bluetooth ──▶
                                                        │
                        /usr/sbin/bluetoothd  (C + CF, job org.nextbsd.bluetoothd)
                        ┌─────────────┬──────────────┬──────────────┬─────────────┐
                        │ adapter.c   │ hci.c        │ security.c   │ btstore.c   │
                        │ ubt detect  │ raw HCI sock │ Link_Key_Req │ SCPrefs     │
                        │ libnetgraph │ inquiry      │ PIN / SSP    │ SCDynStore  │
                        │ graph+init  │ conn/disconn │ pairing FSM  │ notify_post │
                        └──────┬──────┴──────┬───────┴──────┬───────┴──────┬──────┘
                               │             │              │              │
      /dev/ioregistry (libIOKit watch)   PF_BLUETOOTH/SOCK_RAW/HCI    /Local/Library/Preferences/
      or 2 s poll of bt_devenum()        (sockaddr_hci "ubt0hci")     SystemConfiguration/
                               │             │                        org.nextbsd.bluetoothd.plist
   ngctl-equivalent: ubt0: ─drv─ ubt0hci ─acl─ ubt0l2cap ─┬─ btsock_l2c   org.nextbsd.bluetoothd.keys.plist (0600)
                                     └─raw─ btsock_hci_raw └─ btsock_l2c_raw
                               │
             children (spawned by bluetoothd, stock, unpatched):
               /usr/sbin/sdpd -d                (after first adapter is up)
               /usr/sbin/bthidd -d -c <generated>  (H area: when a paired HID device exists)

3.1 Why hcsecd is replaced, with the evidence

Conclusion: bluetoothd's security.c is hcsecd rewritten with a key store behind SCPreferences and a pairing state machine in front. /etc/bluetooth/hcsecd.conf is never read (NextBSD never shipped one; no migration needed). hcsecd must not be started; if the base image ships it, bluetoothd's acceptance includes "no hcsecd process exists".

3.2 Why sdpd and bthidd are supervised, not absorbed

Same argument as wpa_supplicant (wland.c:41-55, userland#46 "wpa_supplicant stays stock"): they are base FreeBSD, they speak sockets not Mach, and a CVE is a base rebuild. They are spawned by bluetoothd rather than launchd because (a) sdpd needs the L2CAP socket layer connected, which does not exist until bluetoothd has built the graph, and (b) there is no launchd ordering to express that. Spawn with -d (no detach; sdpd_main.c:75 "c:dg:hu:", bthidd.c:79 "a:c:dH:hp:t:u") so waitpid reaps them and the main loop notices death (wland.c:584-601 pattern).

3.3 SSP on FreeBSD's kernel: what exists and what is missing

Legacy PIN pairing (PIN_Code_Request → PIN_Code_Request_Reply) is what hcsecd proves works; bluetoothd keeps it for old devices.

4. Adapter lifecycle (adapter.c)

Mirrors vap.c/adopt_phys():

1. Presence of the stack. socket(PF_BLUETOOTH, SOCK_RAW, BLUETOOTH_PROTO_HCI) fails with EPROTONOSUPPORT when ng_btsocket is not compiled in. That is the VAP_NO_NET80211 sentinel (vap.h:35-43): log BT-NOSTACK: ng_btsocket absent — idling, stop polling, keep serving RPC. This is exactly the state the CI kernel is in until the K ticket lands (nextbsd-kernel/config/NEXTBSD has no netgraph/ng_* line; grep).
2. Detect a controller. Two options, decide in D2: - Poll every 2 s: list netgraph nodes of type ubt via libnetgraph (NgMkSockNode, NgSendMsg(NGM_GENERIC_COOKIE, NGM_LISTNODES); netgraph.h:48-50). Simple, matches PHY_RESCAN_INTERVAL_SEC (wland.c:99). Recommended for v0. - Subscribe to /dev/ioregistry with criteria name="ubt" or classname="ubt" (ioregistry.h:54-63; nodes carry device_get_name/devclass_get_name, iokit_registry.c:223-227) via IOServiceAddMatchingNotification, as diskarbitrationd does (da_iokit_subscribe.c:4-20, diskarbitrationd.c:107-114). Event-driven; adds -lIOKit. Do it in a follow-up once D2's poll is proven; DA's file is the template.
3. Build the graph (rc.d bluetooth_setup_stack in C): mkpeer ubtN: hci hook drv, name ubtN:hook ubtNhci, mkpeer ubtNhci: l2cap acl hci, name … ubtNl2cap, connect ubtNhci: btsock_hci_raw: raw ubtNraw, connect ubtNl2cap: btsock_l2c_raw: ctl ubtNctl, connect ubtNl2cap: btsock_l2c: l2c ubtNl2c. Idempotent: on restart, adopt an existing ubtNhci (the vap_find_existing() rule, vap.h:79-86).
4. Initialise the controller over the raw socket bound to ubtNhci (bt_devopen(), lib_libbluetooth_hci.c:54-76; bt_devreq() for command/complete pairs): Reset (retry ×3 like rc.d), Read_BD_ADDR, Read_Local_Supported_Features, Read_Buffer_Size, Write_Class_Of_Device (desktop 0x000104), Change_Local_Name (ComputerName from Setup:/System if present, else hostname), Write_Scan_Enable (page scan on, inquiry scan off unless discoverable), Set_Event_Mask (default ∪ SSP), Write_Simple_Pairing_Mode 1 if Read_Local_Supported_Features reports NG_HCI_LMP_SECURE_SIMPLE_PAIRING (ng_hci.h:118), then NGM_HCI_NODE_INIT (what hccontrol initialize sends).
5. Publish State:/Bluetooth/Adapter/ubtNhci (§7) and log BT-ADAPTER-OK: ubt0hci 00:11:22:33:44:55.
6. Power. FreeBSD has no rfkill. bluetooth power off = disconnect all, Write_Scan_Enable 0, NGM_HCI_NODE_SHUTDOWN? No: keep the graph; just scan-disable and mark Powered:false in the store, refuse scan/connect RPCs with bt_status_powered_off_e. power on reverses it. Persist the choice in prefs (Adapters/<bdaddr>/Powered).
7. Removal. Unplugging destroys ubtN: and its peers; the raw socket read returns an error. Mark the slot inactive, remove the store key, reap. (wland deliberately does not handle removal, wland.c:433-435; bluetoothd should, since USB dongles are the common case.)

5. MIG interface (bluetooth.defs, subsystem 31000)

Flat-only, forced by the OOL limitation (§1.2). Sketch:

subsystem bluetooth 31000;
serverprefix _;
import "bluetooth_mig_types.h";

type bt_adapter = array[32] of char ctype: BTAdapterName;  /* ng node name, NG_NODESIZ */
type bt_addr    = array[18] of char ctype: BTAddr;         /* "aa:bb:cc:dd:ee:ff" */
type bt_name    = array[249] of char ctype: BTDeviceName;  /* BT names are <= 248 octets */
type bt_pin = array[17] of char ctype: BTPin;          /* <= 16 ASCII digits */
type bt_status  = MACH_MSG_TYPE_INTEGER_32 ctype: bt_status_t;
type bt_devstate= MACH_MSG_TYPE_INTEGER_32 ctype: bt_devstate_t;
type bt_pairmth = MACH_MSG_TYPE_INTEGER_32 ctype: bt_pair_method_t;
type bt_pairph  = MACH_MSG_TYPE_INTEGER_32 ctype: bt_pair_phase_t;

/* adapters */
routine bt_adapter_count(server: mach_port_t; out count: int);
routine bt_adapter_info(server: mach_port_t; index: int;
        out name: bt_adapter; out addr: bt_addr; out powered: int;
        out discoverable: int; out status: bt_status);
routine bt_adapter_power(server: mach_port_t; name: bt_adapter; on: int;
        out status: bt_status);
routine bt_adapter_discoverable(server: mach_port_t; name: bt_adapter; on: int;
        seconds: int; out status: bt_status);

/* scan: returns when the inquiry is REQUESTED (wlan_scan rule) */
routine bt_scan(server: mach_port_t; name: bt_adapter; seconds: int;
        out status: bt_status);
routine bt_scan_count(server: mach_port_t; name: bt_adapter; out count: int;
        out scanning: int; out status: bt_status);
routine bt_scan_entry(server: mach_port_t; name: bt_adapter; index: int;
        out addr: bt_addr; out devname: bt_name; out cod: int; out rssi: int;
        out paired: int; out status: bt_status);

/* pairing */
routine bt_pair(server: mach_port_t; addr: bt_addr; pin: bt_pin;
        out status: bt_status);
routine bt_pair_status(server: mach_port_t; addr: bt_addr;
        out phase: bt_pairph; out method: bt_pairmth; out passkey: int;
        out status: bt_status);
routine bt_pair_confirm(server: mach_port_t; addr: bt_addr; accept: int;
        passkey: int; out status: bt_status);
routine bt_unpair(server: mach_port_t; addr: bt_addr; out status: bt_status);

/* connections + paired list */
routine bt_connect(server: mach_port_t; addr: bt_addr; out status: bt_status);
routine bt_disconnect(server: mach_port_t; addr: bt_addr; out status: bt_status);
routine bt_paired_count(server: mach_port_t; out count: int);
routine bt_paired_entry(server: mach_port_t; index: int; out addr: bt_addr;
        out devname: bt_name; out cod: int; out state: bt_devstate;
        out autoconnect: int; out status: bt_status);
routine bt_device_status(server: mach_port_t; addr: bt_addr;
        out devname: bt_name; out cod: int; out state: bt_devstate;
        out rssi: int; out status: bt_status);

Enums in bluetooth_mig_types.h (shape of wlan_mig_types.h:47-85):

• bt_status_t: success, invalid_parameter, no_stack, no_adapter, adapter_does_not_exist, powered_off, device_unknown, not_paired, busy, index_out_of_range, pairing_rejected, pairing_timeout, internal_error, operation_not_supported.
• bt_devstate_t: unknown, disconnected, connecting, connected, pairing.
• bt_pair_method_t: none, just_works, pin, numeric_comparison, passkey_entry, passkey_display.
• bt_pair_phase_t: idle, connecting, awaiting_user, in_progress, done, failed.

Notes: - No callbacks. A reverse Mach port to a "UI agent" would need a Mach-speaking client; there is none above the Mach line (§5.3). Pairing is a state the client polls (bt_pair_status), with notify_post as the wake-up. - The 8 KiB receive buffer (mach_service.c:42) is ample; the biggest reply is bt_scan_entry (18+249+scalars). - bt_scan takes seconds because a Classic inquiry length is chosen up front (Inquiry cmd, ng_hci.h:697); the CLI passes 8 (≈10 s) and polls bt_scan_count's scanning flag instead of sleep(3) (the wlan.c:197-202 wart, called out in wlan.8 BUGS).

5.1 Scan (hci.c)

Inquiry (LAP GIAC, length, unlimited responses) on the raw socket; collect Inquiry_Result (0x02) events (ng_hci.h:1871), then Inquiry_Complete. RSSI needs Write_Inquiry_Mode 1 and event 0x22, neither defined in ng_hci.h (§3.3) — carry local defines; fall back to RSSI 0 if the controller rejects the mode. Names: Remote_Name_Request per result (ng_hci.h:838; bt_devremote_name()), sequentially, cached by bdaddr so repeat scans are fast. Cache shape = struct scan_entry (supplicant.h:33-39) with bdaddr, name, cod, rssi, seen.

5.2 Pair / unpair (security.c)

State machine per bdaddr:

idle ─bt_pair─▶ connecting (Create_Connection) ─▶ Authentication_Requested
   ├─ PIN_Code_Request      → pin given? reply : phase=awaiting_user(method=pin)
   ├─ IO_Capability_Request → reply DisplayYesNo (0x01), no OOB, MITM required
   ├─ User_Confirmation_Request(numeric) → phase=awaiting_user(method=numeric_comparison, passkey)
   │        bt_pair_confirm(accept) → User_Confirmation_Request_Reply / _Negative_Reply
   ├─ User_Passkey_Request  → awaiting_user(method=passkey_entry); bt_pair_confirm(passkey)
   ├─ Link_Key_Notification → bt_keys_save(addr, key, type)   (BEFORE Simple_Pairing_Complete)
   ├─ Simple_Pairing_Complete / Authentication_Complete(status) → done|failed
   └─ timeout (no user answer in N s) → negative reply, failed(pairing_timeout)

Link_Key_Request at any time → reply from the key store or negative. bt_unpair = delete from store, Delete_Stored_Link_Key on the controller (ng_hci.h:1090, harmless if none), disconnect if connected, remove State:/Bluetooth/Device/<addr>, regenerate bthidd config (H).

Policy defaults (v0): pairing is only ever initiated by us; an incoming IO_Capability_Request for a device nobody asked to pair is answered with IO_Capability_Request_Negative_Reply (0x34). Just-works (peer NoInputNoOutput) still surfaces a User_Confirmation_Request; auto-accept it only for a pairing we initiated. The HCI/LMP authentication timeout for an unanswered confirmation is controller-defined (spec default ≈ 30 s) — unverified on real hardware; bluetoothd's own awaiting_user timeout is 60 s and it sends the negative reply itself.

5.3 Prompting the user: what the tree offers

Searched for any user-prompt path: no LaunchAgents directory in ul/overlay or nextbsd-overlays; no CFUserNotification; the only "per-user agent" mention is DA's future-iteration note (diskarbitrationd.c:26); the only notify use is hostnamed's notify_post("com.apple.system.hostname") (hostnamed.c:20), and its vendored code skipped notify_register_dispatch because it killed the daemon during bring-up (set-hostname.c:706-716) — so registration-side notify is not battle-tested; posting is.

Therefore: bluetoothd never pushes to a UI. It (1) sets State:/Bluetooth/Pairing/<addr> = {Method, Passkey, Expires}, (2) notify_post("org.nextbsd.bluetooth.pairing"), and (3) waits for bt_pair_confirm. The agent is whoever called bt_pair: the CLI prints Confirm that 123456 is shown on <name> [y/N]; Gershwin's pane calls bluetooth pair --no-prompt <addr> (exit 3 = user answer needed, prints method=numeric_comparison passkey=123456), shows its own dialog, then bluetooth confirm <addr> yes|no. That two-verb split keeps every NSTask invocation short-lived, which is the BSDBackend.m pattern the WLAN plan relies on (wlan.c:32-37).

6. Persistence (btstore.c)

Two SCPreferences application IDs, so that the secret file can move to a keychain later without touching the metadata file:

org.nextbsd.bluetoothd → /Local/Library/Preferences/SystemConfiguration/org.nextbsd.bluetoothd.plist (0644, like wland's):

PairedDevices = {
  "aa:bb:cc:dd:ee:ff" = {
    Name        = "Magic Keyboard";      # last Remote_Name
    Class       = 9536;                  # Class_of_Device, int
    Adapter     = "00:11:22:33:44:55";   # local bdaddr that holds the bond
    Paired      = 1789000000;            # unix time
    LastSeen    = 1789000000;
    AutoConnect = true;                  # reconnect at boot / when it pages us
    Profiles    = ( "HID" );             # from SDP at pair time; H/A areas append
    Trusted     = true;                  # accept incoming ACL from it without asking
  };
};
Adapters = {
  "00:11:22:33:44:55" = { Powered = true; Discoverable = false; Name = "..." };
};

org.nextbsd.bluetoothd.keys → ...SystemConfiguration/org.nextbsd.bluetoothd.keys.plist:

LinkKeys = {
  "aa:bb:cc:dd:ee:ff" = { Key = <16 bytes, CFData>; Type = 4; };   # Type = HCI key_type
};

Rules: - Written immediately on Link_Key_Notification (the hcsecd failure mode, §3.1), via SCPreferencesSetValue + SCPreferencesCommitChanges (atomic temp+rename, airport.c:276-293). - umask(077) in bluetoothd before the first commit and chmod(0600) after every commit of the keys file (a rename produces a new inode, so a one-time chmod does not survive; whether SCPreferences honours the process umask is unverified — the chmod-after-commit covers both cases). - The plaintext decision is WLAN's Q2 repeated (airport.h:40-48; keychain plan §4.G "interim", Q1 "first consumer"). E16 becomes the second consumer arguing for the System keychain; bluetoothd's bt_keys_save/find/forget are the three functions that change, and only the .keys file migrates. - Link keys are 16 bytes; store as CFData, never as a printable string in a log line (hcsecd logs "exists/doesn't exist" only, hcsecd.c:249-253 — keep that habit). - BLE LTKs (B area) get a sibling dictionary LongTermKeys in the same keys file when they exist; the schema reserves the name.

7. SCDynamicStore keys, notify names, launchd plist

Keys (all invented, like AirPort; airport.h:21-25):

Every dict stays far below CONFIG_DATA_MAX (config_types.h:74). No Setup:/Bluetooth in v0 — SCPreferences under the app IDs above is the durable side; a Setup: mirror can come with the pref-pane work.

Notify names (posted with notify_post, -lnotify, as hostnamed/Makefile:82):

• org.nextbsd.bluetooth.adapter — adapter list/power changed
• org.nextbsd.bluetooth.device — a Device/ key changed
• org.nextbsd.bluetooth.pairing — user action required or pairing finished
• org.nextbsd.bluetooth.scan — scan cache changed (the CLI/pane may re-pull bt_scan_entry)

org.nextbsd.bluetoothd.plist (ul/overlay/System/Library/LaunchDaemons/): Label org.nextbsd.bluetoothd, ProgramArguments /usr/sbin/bluetoothd, RunAtLoad true, KeepAlive true, MachServices {org.nextbsd.bluetooth = true}, StandardOutPath/StandardErrorPath /var/log/bluetoothd.stderr. "Start only when a controller exists" is not expressible: every plist in the overlay uses plain KeepAlive true (no PathState/OtherJobEnabled variants exist in the tree; grep), there is no device-triggered launch (no devd; IOKit notifications are a userland API, not a launch trigger), and wland's precedent is "always run, idle at 2 s polls, stop polling when the subsystem is provably absent" (wland.c:526-536). Do the same. daemon-state.sh then classifies it as resident and asserts a live PID automatically (its RunAtLoad/KeepAlive rule, daemon-state.sh:29-36).

8. Boot/CI tests with no adapter present

There is no Bluetooth in qemu (#412), and today no netgraph in the kernel either. Both states must pass CI:

Pattern to copy: the ipconfig block in run.sh:1512-1520 and its expect in boot-test.sh:986-997. Marker naming follows the <AREA>-<THING>-OK/FAIL convention (run.sh:1105-1298).

While here: wedge-check.sh:153,156 should get a wlan list probe too — the CLI exists and the reason recorded ("no client tool") is stale. Out of area; note for whoever owns E-network.

9. The bluetooth CLI

/usr/sbin/bluetooth, pure C, bootstrap_look_up("org.nextbsd.bluetooth"), links -llaunch -lsystem_kernel only (build-userland.sh:763-776 shape). Verbs and output mirror wlan(8) (wlan.c:4-8, wlan.8 COMMANDS/EXAMPLES):

bluetooth status [adapter]           adapter: ubt0hci  address: 00:11:..  powered: on  discoverable: off
                                     paired devices: 2 (1 connected)   [or: no Bluetooth adapters / stack: absent]
bluetooth list                       ADDRESS            NAME                 CLASS      STATE       AUTO
                                     aa:bb:cc:dd:ee:ff  Magic Keyboard       keyboard   connected   yes
bluetooth scan [-t seconds] [adapter]
                                     ADDRESS            NAME                 CLASS      SIGNAL PAIRED
                                     aa:bb:..           Magic Keyboard       keyboard   ***  -52  yes
bluetooth pair <addr> [pin] [--no-prompt]
                                     interactive: prints passkey prompt, reads y/N or the passkey, calls confirm
                                     --no-prompt: exit 0 done | 3 user answer needed (prints method=… passkey=…) | 1 failed
bluetooth confirm <addr> yes|no|<passkey>
bluetooth unpair <addr>
bluetooth connect <addr>             returns when REQUESTED; watch with `bluetooth list`
bluetooth disconnect <addr>
bluetooth power on|off [adapter]
bluetooth discoverable on|off [-t seconds] [adapter]

Exit codes: 0 ok, 1 error/RPC failure, 2 usage, 3 user answer needed (--no-prompt only). cannot reach org.nextbsd.bluetooth — is bluetoothd running? on lookup failure (wlan.c:360-366). Signal bars as wlan.c:110-122. Class-of-device rendered from the major/minor class bits (keyboard, mouse, audio, phone, computer, …). Man page bluetooth.8 with FILES (/var/log/bluetoothd.stderr, both prefs paths, "link keys are stored in plaintext"), DIAGNOSTICS (no Bluetooth adapters → check ngctl list for ubt; stack: absent → kernel lacks ng_btsocket), and BUGS.

10. Gershwin preference pane: the boundary only

Sibling of nextbsd#396. The contract the pane builds on, nothing more:

• the bluetooth CLI verbs above, invoked via NSTask (the BSDBackend.m:262-268 path cited by wlan.c:32-37), including the --no-prompt/confirm pair for the passkey dialog;
• the State:/Bluetooth/... schema (§7) for anything that later gains an SC reader;
• the four notify names (§7) for "refresh now".

Everything ObjC — a BluetoothBackend protocol, the pane, an IOBluetooth-shaped API — lives above the Mach line in Gershwin and is not scoped here.

11. Open questions

1. Does NextBSD's base image ship libbluetooth/libnetgraph/sdpd/bthidd/hccontrol? Default FreeBSD MK_BLUETOOTH/MK_NETGRAPH = yes and no WITHOUT_ knob was found, but nextbsd-freebsd-compat was not inspected. D1 checks. If absent, bluetoothd vendors libbluetooth's ~700-line hci.c (BSD-2) rather than adding a build knob.
2. Does bthidd reload its config on SIGHUP, or must bluetoothd restart it after each pairing? Not checked (bthidd.c signal handling). H area's call; D7 exposes a generic "restart child" hook either way.
3. Poll vs IORegistry watch for ubt arrival (§4.2). Poll for v0; watch as a follow-up.
4. What does Read_Local_Supported_Features report on the dongles we will test with? Determines whether SSP or legacy PIN is the default path in practice. Needs hardware.
5. Incoming pairing requests (a phone pairs to the desktop): rejected in v0 (§5.2). Needs a product decision before A2DP-sink/phone use cases.
6. Second plaintext-secret consumer: does E16 trigger the keychain plan (its Q1), or is the .keys file split (§6) the accepted debt for now?
7. Set_Event_Mask bits for LE (B area) are set from the same init sequence; agree who owns adapter_init() extensions.

12. Risks

• Everything past BT-NOADAPTER is untestable in CI. Same as WLAN (userland#46 "Testing"). Mitigation: D10 hardware checklist ticket with needs-hardware, and the hcsecd-proven legacy PIN path as a fallback if SSP misbehaves.
• Kernel-defined SSP surface is partial (§3.3). Local defines are fine for the raw socket; the risk is a controller quirk nobody in the FreeBSD ecosystem has hit because nobody has done SSP through ng_hci.
• Two security managers. If the image ships and someone starts hcsecd, both answer Link_Key_Request. bluetoothd logs BT-SEC-CONFLICT if a hcsecd process exists at start.
• USB dongle removal path in ng_ubt/ng_hci is old code; a hot-unplug during an inquiry may leave the raw socket in an odd state. Treat any recvfrom error as "adapter gone" and rebuild from scratch.
• notify registration had a bring-up bug (§5.3). bluetoothd only posts; nothing in D-area registers.
• Plaintext link keys allow impersonating the desktop to a paired keyboard by anyone who can read a root-only file. Same exposure class as WLAN PSKs; documented in bluetoothd.8.

13. Cross-area asks (not D tickets)

• K: device netgraph, ng_bluetooth, ng_hci, ng_l2cap, ng_btsocket, ng_ubt compiled in (#412 phase 0); add the missing ng_hci.h defines (§3.3) so bluetoothd's hci_compat.h can be deleted.
• H: bthidd config generation from PairedDevices[*].Profiles ∋ "HID", SDP query at pair time (bthidcontrol's sdp.c logic), SIGHUP/restart semantics.
• B: LE inquiry/pairing reuse the same raw socket, event loop, Pairing/ state and .keys file (LongTermKeys).
• A: profile registration through supervised sdpd; nothing else from D.

HID: keyboards, mice, trackpads (H)

Deep-dive notes, lightly edited. Draft ids map to issues in the index.

Scope: how a paired Bluetooth keyboard/mouse/trackpad turns into keystrokes and pointer motion on a NextBSD desktop (Gershwin on XLibre), what the kernel and image need, how bluetoothd drives FreeBSD's bthidd, pre-login behaviour, Apple/Logitech specifics, HOGP scope, and what CI can test without a radio.

Sources are FreeBSD releng/15.1 (usr.sbin/bluetooth/bthidd, sys/dev/evdev, sys/dev/vkbd, sys/dev/kbdmux, sys/dev/vt), the NextBSD clones (nextbsd, nextbsd-kernel, nextbsd-userland), gershwin-desktop/gershwin-on-nextbsd, gershwin-desktop/gershwin-system, FreeBSD ports (x11-servers/xlibre-server, x11/xlibre-minimal) and FreeBSDDesktop/libudev-devd. Paths below are relative to those trees; file:line numbers are from the copies fetched on 2026-09-20. Anything not verified against source is marked (unverified).

TL;DR

1. bthidd's sinks are fixed: keyboards always go to vkbd(4) (bthidd/session.c:108-114), mice always go to /dev/consolectl → sysmouse (bthidd/hid.c:541-566), and with -u additionally to /dev/uinput per-device evdev nodes (bthidd/btuinput.c:339-413). The uinput writes are gated by kern.evdev.rcpt_mask bits (btuinput.c:474-484, 511-519).
2. Kernel: EVDEV_SUPPORT, evdev, uinput, kbdmux are in GENERIC on amd64 and arm64 (sys/amd64/conf/GENERIC:199,381-383, sys/arm64/conf/std.dev:49,72-74) and NEXTBSD includes GENERIC (config/NEXTBSD:1). vkbd is a module only (sys/conf/files:3501 optional vkbd; not in GENERIC) and NextBSD ships no .ko tree (ci/assemble-image.sh:168) → device vkbd must be baked or no BT keyboard can ever attach. Ticket H1.
3. The crux is X hotplug, and it is already known: XLibre on FreeBSD gets input devices through libudev-devd, whose monitor connects to devd's /var/run/devd.pipe (libudev-devd/udev-monitor.c:50,188-213). NextBSD has no devd (nextbsd/README.md:31, PORTING.md:487-489), so X sees only what exists when it starts. Gershwin's own LoginWindow.sh:91-93 says it: "X enumerates input exactly once at startup and XLibre has no hotplug backend on FreeBSD". A uinput node created when a BT mouse connects is therefore invisible to a running X.
4. There is a hotplug-free route for keyboards and it is the one XLibre's package already recommends: kern.evdev.rcpt_mask bit 1 (EVDEV_RCPT_KBDMUX) makes kbdmux's evdev node "System keyboard multiplexer" (kbdmux.c:455-473, gated kbdmux.c:707) carry every keyboard, including every vkbd bthidd creates (auto-attached by kbd.c:197-231). That node exists from boot, so libinput opens it at X start and BT keyboards work whenever they connect, pre-login included. XLibre's pkg-message.in recommends kern.evdev.rcpt_mask=6 for exactly this class of problem.
5. Mice have a similar but worse hotplug-free route (consolectl → sysmouse → "System mouse" evdev node, vt_consolectl.c:55-59, vt_sysmouse.c:97-118,122-125, needs bit 0) with duplicate-event risk on psm(4) laptops; the clean per-device uinput route needs the input-hotplug interface that belongs to the other epic. Ticket H4 (decision), H5 (sequenced).
6. bthidd cannot reload: SIGHUP is a shutdown (bthidd.c:138-140,249-253, loop at bthidd.c:167). Adding a paired device means restarting bthidd, which drops every connected BT HID session. Devices not in bthidd.conf are rejected on connect (server.c:244-250). Tickets H2 (bluetoothd drives it), H3 (make it reload).
7. Apple Magic Mouse 1 (05ac:030d) is special-cased in bthidd (hid.c:73,434-512); Magic Mouse 2 and Magic Trackpad 1/2 are not (no digitizer/multitouch handling anywhere in bthidd). Logitech's current line is BLE-only → HOGP, blocked on the engine decision. Tickets H6, H7.
8. CI: the whole sink path (vkbd → kbdmux → evdev, uinput → /dev/input/eventN → X) is testable in qemu with synthetic devices, no radio needed; only the L2CAP side is not. Ticket H8.

1. How bthidd delivers input (releng/15.1)

Build and options

• usr.sbin/bluetooth/bthidd/Makefile:8-9: SRCS= bthidd.c btuinput.c client.c hid.c kbd.c lexer.l parser.y server.c session.c, LIBADD= bluetooth usbhid. uinput support is compiled in unconditionally in 15.1 (it is a runtime option, not a build option).
• bthidd.c:114-115: -u sets uinput = 1; usage text bthidd.c:272 "enable evdev protocol support". bthidd.8: "-u Enable support for input event device protocol. Requires evdev and uinput drivers to be loaded ... or compiled into the kernel."
• libexec/rc/rc.d/bthidd:18-38: stock rc script kldloads uinput (when check_kern_features evdev_support), kbdmux, vkbd, ng_btsocket and passes -u when evdev is present. On NextBSD none of those load_klds can work (no .ko tree), so every one of them must be static.

Keyboard path (always vkbd; uinput optional)

• session.c:106-121: when the device's descriptor marks it a keyboard, session_run() opens /dev/vkbdctl unconditionally and fails the session if it cannot ("Could not open /dev/vkbdctl"). This is independent of -u.
• vkbd.c:674: each open of /dev/vkbdctl clones a vkbd unit and calls kbd_register().
• sys/dev/kbd/kbd.c:197-231: kbd_register() looks up kbdmux and, if present, issues KBADDKBD so the new keyboard is multiplexed automatically. That is why bthidd.8 CAVEATS say kbdmux "must be used".
• kbd.c:358-372,401-408 (bthidd): every key change is written to the vkbd fd and to the uinput fd (uinput_kbd_write), the latter being a no-op unless -u.
• btuinput.c:378-413: uinput keyboard "Bluetooth Keyboard": EV_KEY/EV_LED/EV_SYN/EV_REP, LEDs, all HID usages via a keymap plus consumer keys; btuinput.c:300-333 sets UI_SET_PHYS (local bdaddr) and UI_SET_BSDUNIQ (remote bdaddr) so libinput sees a stable identity.
• btuinput.c:511-519: uinput_rep_key() returns early unless kern.evdev.rcpt_mask & EVDEV_RCPT_HW_KBD; the mask is re-read every 5 s (btuinput.c:422-457). If the sysctl is absent (kernel without EVDEV_SUPPORT) it assumes HW bits set.
• LED feedback: kbd.c:535-613 reads vkbd status changes and sends the HID output report; with -u also uinput_rep_leds.
• bthidd.8 KNOWN LIMITATIONS: no key auto-repeat and no double-click handling in the text console; both "work under X just fine". Comment at hid.c:515-521 confirms.

Mouse path (always consolectl; uinput optional)

• server.c:76-81: server_init() opens /dev/consolectl and fails bthidd startup if it cannot.
• hid.c:541-566: mouse motion/buttons are sent as CONS_MOUSECTL / MOUSE_ACTION ioctls on consolectl; T-axis (tilt) becomes buttons 6/7. Then, hid.c:568-573, if -u and the device is a mouse, uinput_rep_mouse() is also called.
• On a vt(4) console the ioctl lands in sys/dev/vt/vt_consolectl.c:47-68: CONS_MOUSECTL → sysmouse_process_event(mi). (The EINVAL for MOUSE_ACTION at vt_core.c:2856-2884 is the per-tty ioctl, not the consolectl cdev, so it does not affect bthidd.)
• vt_sysmouse.c:209-262: sysmouse_process_event() accumulates into the /dev/sysmouse MouseSystems FIFO and, #ifdef EVDEV_SUPPORT, sysmouse_evdev_store() pushes to an evdev device named "System mouse" (vt_sysmouse.c:97-118) only if evdev_rcpt_mask & EVDEV_RCPT_SYSMOUSE (vt_sysmouse.c:122-125).
• btuinput.c:339-370: uinput mouse "Bluetooth Mouse": REL_X/Y, REL_WHEEL/HWHEEL when the descriptor has them, 8 buttons, INPUT_PROP_POINTER. btuinput.c:474-484: writes gated on EVDEV_RCPT_HW_MOUSE. Comment btuinput.c:336: "TODO: bring in more feature detection code from ums".

What bthidd recognises

• parser.y:442-463: a device is a keyboard if its descriptor has a HUP_KEYBOARD page, mouse if it has X/Y on generic desktop, has_cons for consumer keys, has_wheel/has_hwheel.
• hid.c:227-430: handled usage pages are GENERIC_DESKTOP, KEYBOARD, BUTTON, CONSUMER and MICROSOFT (battery, 0xfe01). No HUP_DIGITIZER, no absolute axes, no multitouch. Anything trackpad-shaped is either ignored or (Apple) handled by vendor-specific code (see §5).

rcpt_mask semantics (kernel)

• sys/dev/evdev/evdev.h:48-56: bit0 SYSMOUSE, bit1 KBDMUX, bit2 HW_MOUSE, bit3 HW_KBD. evdev.c:73-82: default HW_MOUSE|HW_KBD (= 0xC) except 32-bit powerpc; sysctl kern.evdev.rcpt_mask is RWTUN (settable from loader tunables or at runtime).
• kbdmux.c:455-473: kbdmux creates an evdev "System keyboard multiplexer" (BUS_VIRTUAL, all known keys, LEDs, repeat); kbdmux.c:705-716: pushes keys only when bit1 is set; kbdmux.c:1136-1141,1218-1222,1350-1358: LED/repeat mirroring likewise.
• Net effect: the mask picks exactly one evdev route per class. With 0xC, hkbd/ukbd/psm/bthidd-uinput each emit on their own node and the aggregate nodes are silent; with bit1/bit0 set (and bit3/bit2 clear) the aggregates carry everything and per-device nodes are silent. Setting both halves duplicates events.
• (unverified) whether hidmap-based drivers (hms, hmt, hpen, the ones NEXTBSD bakes at config/NEXTBSD:165-174) honour HW_MOUSE at all — they are evdev-only and never feed sysmouse (touch spike, line 102: "No /dev/sysmouse from hms"). If they ignore the mask, clearing bit2 does not silence USB mice; if they honour it, clearing bit2 kills them. Must be checked before any mask change.

2. Kernel options: what NEXTBSD has today

The comments in config/NEXTBSD:153-159 and the touch spike describe the exact failure class: "a driver that is a module on stock FreeBSD is absent on NextBSD unless it is compiled into the kernel". vkbd is that for BT keyboards: session_run() returns -1 at session.c:110-115 and the keyboard never attaches, with only a syslog line to show for it.

Recommendation (H1): add device vkbd next to the HID block in config/NEXTBSD with the same style of comment, and have the ticket's acceptance criteria include config -x /boot/kernel/kernel | grep -E 'vkbd|uinput|kbdmux|EVDEV_SUPPORT' on the built kernel so the inherited options are verified rather than inferred. ng_btsocket etc. are area K's ticket; H1 depends on it only for end-to-end testing, not for the build.

3. How X gets input on NextBSD, and the hotplug crux

What ships

• The NextBSD base image ships no X at all: nextbsd/pkglist.txt contains only pkg (the XLibre set proposed in nextbsd#328 was later moved out).
• The desktop image is built by gershwin-desktop/gershwin-on-nextbsd: pkglist.txt = xlibre-minimal, xlibre-xf86-input-{evdev,joystick,keyboard,mouse,synaptics,vmmouse}, xlibre-xf86-video-{scfb,vesa}, mesa-dri, installed in the chroot (build.sh:193-209). build.sh:196-197: "Gershwin's LoginWindow execs /usr/local/bin/X at boot".
• x11/xlibre-minimal/Makefile: RUN_DEPENDS on x11-servers/xlibre-server and x11-drivers/xlibre-xf86-input-libinput → libinput is present and is the default driver.
• x11-servers/xlibre-server/Makefile:16-21: OPTIONS_DEFAULT=UDEV ..., UDEV_DESC= Enable udev. (For libinput & autoconfiguration/hotplug), UDEV_LIB_DEPENDS= libudev.so:devel/libudev-devd. Packages from pkg.FreeBSD.org are built with defaults, so the shipped server uses the udev config backend via libudev-devd. files/patch-config_udev.c: on kernels with the evdev_support feature, keyboards/pointers get no forced driver (so the fallback, libinput, is used); the kbdmux path is special-cased; files/20-evdev-kbd.conf sets XkbRules evdev for /dev/input/event* keyboards. x11/libinput/Makefile:16 also depends on libudev-devd.

How libudev-devd finds devices

• Enumeration at X start: udev-utils.c:100-137 scans /dev/input/event[0-9]*, /dev/ukbd*, /dev/atkbd*, /dev/kbdmux*, /dev/ums*, /dev/psm*, /dev/sysmouse, /dev/dri/card*, ...; udev-enumerate.c:191-203 does a recursive scandir. This works on NextBSD (no devd involved).
• Hotplug: udev-monitor.c:50-51 DEVD_SOCK_PATH "/var/run/devd.pipe", reconnect every 1 s; udev-monitor.c:188-213 connects and otherwise arms a timer forever; udev-monitor.c:154-175 consumes devd notices with system=DEVFS subsystem=CDEV type=CREATE|DESTROY cdev=<name> (and system=DRM). On NextBSD nothing listens on that socket, so the monitor loops on the retry timer and X never learns about new nodes.
• The kernel still emits the events: sys/kern/kern_conf.c:530-554 notify() → devctl_notify("DEVFS", "CDEV", "CREATE", "cdev=<name>") from every make_dev (kern_conf.c:832,993), and evdev nodes are make_dev_s(... "input/event%d") (evdev/cdev.c:781). /dev/devctl currently has no NextBSD reader (ul/src/kext_tools/kextd/kextd.c:23 "Not yet ... listening on /dev/devctl"; nextbsd#225 tracks whether it is retired for IOKit notifications).
• Gershwin has already hit this: gershwin-system/Library/Scripts/LoginWindow.sh:79-104 waits (on virtio) until devinfo shows (hkbd|ukbd|atkbd)[0-9] and (hms|ums)[0-9] before starting X because "X enumerates input exactly once at startup and XLibre has no hotplug backend on FreeBSD, so that keyboard is lost for the whole session (nextbsd#390/#391)". The same statement is repeated for NVIDIA at LoginWindow.sh:150-156. nextbsd-kernel#175 (USB mouse hotplug does not work) lists "the consumer: a new /dev/input/* node appearing but Gershwin/X not picking it up" as a candidate cause. Note that the LoginWindow wait would never be satisfied by a vkbd-only (BT-only keyboard) machine — it only greps for USB/AT keyboard drivers — and on bare metal (non-virtio, non-NVIDIA) there is no wait at all.

Would a newly connected BT keyboard appear to X without a restart?

Three routes, per class:

So: keyboards: yes, without restart, via K-A — and that is the configuration XLibre's own pkg-message.in tells FreeBSD users to set (kern.evdev.rcpt_mask=6). Mice/trackpads: no unless we either accept M-A's aggregate/duplicate trade-offs or the input-hotplug interface exists. Because bthidd always writes to both the aggregate sink and (with -u) the uinput sink, and the mask gates only the uinput side (btuinput.c:474-484,511-519) while also gating the aggregate's evdev emission (kbdmux.c:707, vt_sysmouse.c:125), there is no configuration in which bthidd double-delivers to X: bluetoothd can always start bthidd with -u and let the mask decide.

Interface note for the input-management epic (out of scope here)

Whatever that epic builds, BT HID needs exactly one of:

1. a process speaking devd's notice protocol on /var/run/devd.pipe (line-oriented !system=DEVFS subsystem=CDEV type=CREATE cdev=input/event5, as udev-monitor.c:154-175 parses; exact wire format (unverified) — check sys/kern/subr_bus.c/subr_devctl.c devctl_notify formatting), fed from /dev/devctl or from hwregd/IORegistry notifications; or
2. a NextBSD libudev-devd whose monitor subscribes to IOKit-style notifications instead of devd; or
3. the desktop-wide rcpt_mask aggregate policy (K-A/M-A) accepted as the design, with per-device identity given up.

Option 1 is a small shim and would also fix nextbsd-kernel#175's userland half and the LoginWindow.sh waits. This document does not choose; H4 asks the question.

4. bthidd config lifecycle and how bluetoothd drives it

Files and tools

• bthid_config.h:38-39: BTHIDD_CONFFILE /etc/bluetooth/bthidd.conf, BTHIDD_HIDSFILE /var/db/bthidd.hids.
• bthidd.conf.sample: one device { bdaddr; name; vendor_id; product_id; version; control_psm 0x11; interrupt_psm 0x13; reconnect_initiate; normally_connectable; hid_descriptor { ... }; } stanza per device. bthid_config.h:41-63 is the parsed struct (new_device, reconnect_initiate, battery_power, normally_connectable, keyboard, mouse, has_wheel, has_hwheel, has_cons).
• bthidcontrol(8): Query prints a ready-to-append stanza from the device's SDP record (bthidcontrol/sdp.c:69-80 fetches ProtocolDescriptorList, AdditionalProtocolDescriptorLists, 0x0205 HIDReconnectInitiate, 0x0206 HIDDescriptorList, 0x0209 HIDBatteryPower, 0x020d HIDNormallyConnectable, plus DeviceID vendor/product/version sdp.c:58-66); Dump pretty-prints the descriptor; Known/Forget edit /var/db/bthidd.hids.
• bthidd -c <conf> -H <hids> -p <pid> [-u] [-t secs] [-a local] (bthidd.8).

Runtime behaviour bluetoothd must model

• Unknown devices are rejected on inbound connect: server.c:244-250 "Rejecting ... connection ... Device not configured". The stanza must exist before the device tries to connect.
• Config is read once; SIGHUP/SIGINT/SIGTERM all just bump done (bthidd.c:249-253) and the main loop for (done = 0; !done; ) (bthidd.c:167) exits. Reload = restart = every connected BT HID device drops for the restart window. There is one bthidd per adapter (it binds L2CAP PSM 0x11/0x13 with listen, server.c:96-138), so you cannot run one per device.
• Reconnect policy (client.c:63-118): every -t seconds (default 10) client_rescan() looks at one device (get_next_hid_device(d) walks the list one entry per call, client.c:73), skips it if a session exists, and skips it if it is known (!new_device) and reconnect_initiate is set. Otherwise it opens an outbound control channel. new_device is cleared and the hids file rewritten when a session is first established (client.c:179, server.c:255-256). So: first connection after pairing is host-initiated (which is what makes the newly written stanza "take"); afterwards, devices that advertise HIDReconnectInitiate (all keyboards/mice in practice) are expected to connect to the host themselves, and bthidd only listens. With N configured devices the first outbound attempt for the last one happens up to N×10 s after start.
• Link keys: the device-initiated reconnect produces an HCI Link_Key_Request that hcsecd(8) must answer from /var/db/hcsecd.keys (hcsecd.8 DESCRIPTION, hcsecd.h:39). Area D owns hcsecd/key persistence; for HID the constraint is ordering: hcsecd and bthidd must both be listening before the user presses a key.

Proposed bluetoothd HID driver (ticket H2)

1. On successful pair of a device whose SDP has the HID service (UUID 0x1124): run the equivalent of bthidcontrol -a <bdaddr> Query (either exec it or link the same sdp.c logic), append the stanza to /etc/bluetooth/bthidd.conf (or a bluetoothd-owned file passed with -c), and make sure the device is not in bthidd.hids so the first connect is host-initiated.
2. Restart the supervised bthidd (-c -H -p -u, -a = adapter bdaddr for multi-adapter safety). Because that drops other sessions, batch config changes and log the restart; H3 removes this cost.
3. Unpair: remove the stanza, Forget the hids entry, restart bthidd; also remove the hcsecd key (area D).
4. Persist the stanza data (bdaddr, name, ids, descriptor, flags) in the same SCPreferences record area D keeps for paired devices, and regenerate bthidd.conf from it at boot, so the conf file is derived state, not a second source of truth.
5. Publish State:/Bluetooth/Device/<addr> with Connected/Profile=HID by watching bthidd's syslog lines or, better, by polling sessions — bthidd has no control socket. (gap) The only observable connection state is /var/db/bthidd.hids writes and syslog. H3 should add a status/dump facility if we are patching bthidd anyway.
6. Launchd: org.nextbsd.bluetoothd RunAtLoad, no dependency on the login window; bthidd/hcsecd are children. The Gershwin loginwindow job has no ordering keys (gershwin-on-nextbsd/overlays/.../io.github.gershwin-desktop.loginwindow.plist: RunAtLoad+KeepAlive only), so pre-login availability is purely "bluetoothd is up early enough and does not need the session".

5. Login window

• Requirement: a paired keyboard must type at the login window. With route K-A (rcpt_mask bit1) the kbdmux node X opened at start carries vkbd keys whenever the device (re)connects, so timing does not matter as long as the adapter is initialised, hcsecd is answering key requests and bthidd is listening. With route K-B it matters absolutely: device-initiated reconnect happens when the user presses a key, i.e. after X started, so the node is invisible until X restarts.
• LoginWindow.sh starts X once card0 (and on virtio, a USB keyboard+pointer) appear; nothing waits for Bluetooth and nothing should — the BT device is not connected yet at that point.
• Adapter bring-up on NextBSD has no devd to run rc.d/bluetooth start ubt0 on attach (libexec/rc/rc.d/bluetooth:28-30 is nostart, driven by devd on FreeBSD); area D/K must trigger stack setup from IORegistry/hwregd notification or by polling ngctl. For HID this only sets the earliest time a keyboard can reconnect; with KeepAlive bthidd/hcsecd can be started immediately after the ubt0hci node is up.
• Console (pre-X, single-user, rescue getty on other VTs): the vkbd→kbdmux route also feeds the text console (that is its original purpose), minus auto-repeat (bthidd.8). A BT-only-keyboard machine can therefore log in on a text getty once the stack is up.

6. Apple, Logitech, and LE-only devices

• Apple Wireless Keyboard (A1314) / Magic Keyboard (A1644 and later): Classic BT HID keyboards; the Magic Keyboard pairs as a standard HID keyboard over BR/EDR (unverified on 15.1 — reported widely on FreeBSD/Linux, not tested here). The Fn key is a vendor usage and is simply ignored by bthidd; media keys ride the consumer page which bthidd maps (btuinput.c:401-410).
• Magic Mouse 1 (05ac:030d): explicitly supported: hid.c:73 MAGIC_MOUSE() and hid.c:434-512 parse the undeclared report 0x29 (finger blocks, two-finger scroll converted to wheel, centre-press to middle click), battery reports 0x30/0x47. Magic Mouse 2 (05ac:0269) is not matched by the macro, so it degrades to a buttons-only mouse with no scrolling. Extending the match and the report id is a small ticket (H6, first item). Linux's hid-magicmouse is the reference (report-id details unverified here).
• Magic Trackpad 1/2 over Bluetooth: vendor multitouch reports, not Windows Precision Touchpad, so neither hmt(4) (USB/I2C HID, Precision-Touchpad TLCs) nor wsp(4)/atp(4) (USB internal trackpads) apply; bthidd has no digitizer handling (§1). Supporting them means a magicmouse-style parser in bthidd emitting evdev MT type-B events through uinput (UI_SET_ABSBIT, ABS_MT_*; FreeBSD uinput supports MT via evdev_mt.c (uinput MT support unverified)), and then libinput handles gestures. Size L, parked (H6).
• Logitech: older "Bluetooth Classic" models (K380/K480, M535/M557, Bluetooth-mode of Unifying-era devices) are standard HID and should work through bthidd. Current MX Master 3/3S, MX Keys, Pebble etc. in Bluetooth mode are BLE-only (HOGP) and cannot work on the netgraph stack today. Unifying/Bolt USB receivers are USB HID and out of scope (they already work as hkbd/hms).
• HOGP (HID over GATT), what it would need — blocked on area B's engine decision: 1. LE link: hccontrol already has le_scan, le_connect, white-list commands (hccontrol/le.c:76-1136) and ng_l2cap.h:78-80,359-361 defines ATT_CID 0x0004, SMP_CID 0x0006 and L2CA_IDTYPE_ATT/SMP, with ng_btsocket_l2cap.c referencing those idtypes — so raw ATT/SMP PDUs over L2CAP fixed channels are at least addressable from userland (depth of that support unverified). 2. SMP pairing in userland (LTK generation/exchange, then LE_Start_Encryption; FreeBSD has no SMP anywhere — bluetooth-management page, line 79: "no BLE, no GATT, no SMP") and LTK persistence (area D's secret-store problem again). 3. A GATT client: discover HID Service 0x1812, read Report Map 0x2A4B, Report 0x2A4D characteristics with Report Reference descriptors, HID Information, Protocol Mode; enable notifications (CCCD); Battery Service 0x180F. 4. Feed notified input reports into the same sinks — hid.c/kbd.c/btuinput.c are reusable almost verbatim if the HOGP client lives beside bthidd or inside bluetoothd. 5. Reconnect: LE devices reconnect by advertising; host must keep a white-list/auto-connect loop (no bthidd equivalent). Size XL; H7 is a scoping ticket only.

7. CI without a radio

qemu has no Bluetooth controller and FreeBSD has no virtual HCI, so L2CAP/SDP/pairing cannot run in CI (same as WLAN). Everything from the sink down can:

• vkbd path: a tiny test binary opens /dev/vkbdctl, writes scancodes the way kbd.c:kbd_write does, and a reader verifies (a) the key arrives on the console tty and (b) it appears on kbdmux's evdev node when kern.evdev.rcpt_mask has bit1 — this proves H1 (vkbd baked), kbdmux auto-attach, and route K-A.
• uinput path: reuse btuinput.c (it is self-contained) to create "Bluetooth Keyboard"/"Bluetooth Mouse" uinput devices, assert /dev/input/eventN appears with the expected name/uniq, and inject events; read them back with a small evdev reader. This proves the kernel side of route K-B/M-B.
• X hotplug (the crux): in the Gershwin image test (gershwin-on-nextbsd/tests/loginwindow-test.sh exists), start X (XLibre with xlibre-xf86-video-dummy or the existing scfb), create the uinput device after X is up, and check xinput list. Today this is expected to fail (documents the gap); it becomes the acceptance test for the hotplug interface once the other epic delivers it. Create the device before X and check it is listed — expected to pass today.
• bthidd itself: server_init() binds L2CAP sockets; whether bind() on NG_HCI_BDADDR_ANY succeeds with no HCI node present is (unverified). If it does, bthidd can be started in qemu against a config file to test config parsing and the restart-on-change logic of H2; if not, H2's config generation is unit-testable in isolation.

8. Recommendation

1. Ship (no external dependency): H1 bake vkbd; H2 bluetoothd HID driver around a supervised bthidd -u; ship with keyboards on route K-A, which is XLibre's recommended FreeBSD configuration anyway, so that a paired keyboard works pre-login and after any reconnect without X hotplug. Make the rcpt_mask value a deliberate, documented decision (H4) since it is desktop-wide.
2. Harden: H3 teach bthidd to reload on SIGHUP and rescan all devices per tick (carry as a NextBSD patch, upstream); H8 synthetic input-path CI.
3. Sequence: H5 BT mice/trackpads on per-device uinput nodes, blocked on the input-hotplug interface from the input-management epic; interim evaluation of route M-A.
4. Parked: H6 Apple Magic Mouse 2 / Magic Trackpad vendor reports; H7 HOGP scoping, blocked on area B.

9. Open questions

• Q1 Do hidmap-based drivers (hms/hmt/hpen) honour kern.evdev.rcpt_mask HW bits? Decides whether mask 3/6/7 is safe on NextBSD hardware. (Check sys/dev/hid/hidmap.c / hms.c for evdev_rcpt_mask.)
• Q2 Which rcpt_mask does the Gershwin image actually run with today — nothing sets it in nextbsd, nextbsd-overlays, ul/overlay or gershwin-on-nextbsd (grep found no rcpt_mask/sysctl.conf), so it is the kernel default 0xC, and per-device nodes are in use. Changing it for BT touches every keyboard on the box.
• Q3 Will the input-management epic provide a devd-protocol relay, an IOKit-backed libudev-devd, or neither? H5 cannot be scheduled until answered.
• Q4 Are evdev/uinput/kbdmux really present in the shipping NEXTBSD kernel (inferred from include GENERIC)? One config -x line settles it; put it in H1's acceptance criteria.
• Q5 Does bthidd start with no HCI node (CI question, §7)?
• Q6 Absorb vs supervise for HID specifically: bthidd's restart-to-reload, lack of a status interface and one-device-per-tick rescan are all arguments for absorbing hid.c/kbd.c/btuinput.c into bluetoothd later; H3 is the cheaper first step and keeps the agreed "supervise" shape.

10. Risks

• Restart storms: every pair/unpair restarts bthidd and disconnects all HID devices for ~1 s plus reconnect time; users pairing a mouse lose their keyboard briefly. Mitigated by H3.
• Aggregate-node identity loss: route K-A makes all keyboards one libinput device (no per-device XKB layout, no per-device disable). Acceptable for v0, must be stated.
• Duplicate events if the mask ends up with both a per-device bit and its aggregate bit set; H4 must specify the exact value and H8 must test for duplicates.
• Silent failures: missing vkbd (H1) or missing hcsecd produce only syslog lines; bluetoothd should surface bthidd's "Could not open /dev/vkbdctl" and "Rejecting ... Device not configured" as status.
• Multi-adapter: bthidd binds ANY by default; with two adapters, pass -a.
• Text console: no key repeat / double click via bthidd sinks in console (bthidd.8); X is fine.
• Trackpads: no path at all today for BT trackpads; Magic Trackpad 2 users get nothing until H6.
• LE-only peripherals (most new Logitech, many others) get nothing until HOGP; message this in the CLI (bluetooth pair should say "LE-only HID not supported yet" when the inquiry result has no BR/EDR HID service) rather than failing silently.

Bluetooth audio (A)

Deep-dive notes, lightly edited. Draft ids map to issues in the index.

Research for nextbsd/nextbsd#473 (epic) and #412 (seed). Read-only; nothing filed. Local sources: freebsd-src (releng/15.1 sparse checkout, 88e7371d), nextbsd-kernel, nextbsd-userland, nextbsd, plus raw fetches from freebsd/freebsd-src@releng/15.1, freebsd/freebsd-ports@main, freebsd/virtual_oss@main, hselasky/virtual_oss@main (copies in e16/src/).

TL;DR

1. A2DP source (PC -> headset/speaker) is not a porting project any more. FreeBSD 15 imported virtual_oss into base (usr.sbin/virtual_oss, lib/virtual_oss, lib/libcuse, private contrib/libsamplerate), and the ports tree marks audio/virtual_oss IGNORE_FreeBSD_15= included in base system. NextBSD's base is a full buildworld of releng/15.1 with MK_BLUETOOTH at its default (yes), so /usr/sbin/virtual_oss, /usr/sbin/virtual_bt_speaker, sdpd, libbluetooth, libsdp, mixer, sndctl already ship. What does not ship: the Bluetooth backend voss_bt.so (base only builds null + oss), the cuse kernel module (not in GENERIC, and NextBSD has no .ko tree), and a working kldload("cuse.ko") call inside virtual_oss (it errors out on NextBSD even with cuse baked). Three small tickets (A1-A3) close that; A2DP playback then works with zero new protocol code.
2. Codec: SBC only in practice. The backend does SBC encode+decode natively; AAC is a compile-time option that needs libav/ffmpeg from ports (HAVE_LIBAV). No aptX/LDAC anywhere. No AVRCP anywhere.
3. A2DP sink (phone -> NextBSD) exists: virtual_bt_speaker(8) (also base), registers an AudioSink SDP record via sdpd and pipes decoded SBC to an OSS device. Cheap to supervise (A5).
4. HFP/HSP is the genuine gap, and it is mostly kernel-shaped. The kernel does carry SCO over USB isochronous (ng_ubt) and a PF_BLUETOOTH/BLUETOOTH_PROTO_SCO socket (ng_btsocket_sco), but: ng_hci only issues legacy Add_SCO_Connection (HV1/HV2/HV3, CVSD) — no Setup_Synchronous_Connection, no eSCO, no mSBC/wideband; the HCI event switch has no Synchronous_Connection_Complete case; ng_ubt picks the largest isoc alt-setting rather than the one matching the SCO bandwidth; and stock rc.d/bluetooth never connects the sco hook, so SCO sockets are dead until someone runs ngctl connect ubt0hci: btsock_sco: sco ubt0sco. Nobody in FreeBSD base or ports implements the HFP AT-command state machine or an SCO<->OSS audio bridge; sdpd has no Handsfree/Headset profile records. NetBSD's btsco(4) is the nearest BSD-licensed prior art. Estimate: XL, and it starts with a kernel patch series. Park it behind a decision (A6).
5. Orchestration is a virtual_oss_cmd one-liner once virtual_oss owns /dev/dsp. virtual_oss can re-target its playback/record backend at runtime via its control device (virtual_oss_cmd /dev/vdsp.ctl -P /dev/bluetooth/<bdaddr>), so the clean interface with the future audio epic is: audio epic runs the persistent virtual_oss mixer that owns /dev/dsp; bluetoothd only publishes "device is an A2DP sink, reachable as /dev/bluetooth/<addr>" and asks for the switch. If the audio epic has not landed, bluetoothd's interim fallback is to spawn its own virtual_oss ... -P /dev/bluetooth/<addr> -d dsp.bt0 child, exactly the way wland forks wpa_supplicant (ul/src/WLAN/wland.c:262-275).
6. CI without a radio can prove everything except the air interface: cuse baked (/dev/cuse exists), virtual_oss starts under launchd against the emulated HDA (snd_hda is baked, config/NEXTBSD:240), sndctl shows a from_user device, the backend .so resolves, and bluetoothd's audio state machine runs against a fake /dev/bluetooth/ open failure path. A2DP/SCO over real links needs a dongle.

1. virtual_oss: what it is, where it lives, what it needs

1.1 In base for FreeBSD 15 (verified)

• usr.sbin/virtual_oss/Makefile (releng/15.1): SUBDIR+= virtual_oss_cmd virtual_oss; SUBDIR.${MK_BLUETOOTH}+= virtual_bt_speaker. Makefile.inc: PACKAGE?= sound.
• usr.sbin/virtual_oss/virtual_oss/Makefile: LIBADD= cuse m nv pthread samplerate, with -Wl,--export-dynamic-symbol=virtual_oss_wait etc. "because some backends make use of those symbols" — backends are dlopen'd plugins.
• lib/virtual_oss/Makefile: SUBDIR+= null oss only. lib/virtual_oss/bt/ (bt.c, avdtp.c, sbc_encode.c, SHLIB_NAME= voss_bt.so, LIBADD= bluetooth sdp, optional -DHAVE_LIBAV for AAC) and lib/virtual_oss/sndio/ exist in the tree but are not built by buildworld.
• lib/libcuse/ (cuse.3, cuse_lib.c), sys/fs/cuse/cuse.c, sys/modules/cuse/ present. sys/conf/files:3603: fs/cuse/cuse.c optional cuse. sys/amd64/conf/GENERIC and sys/arm64/conf/std.dev have no cuse line — it is module-only on stock FreeBSD.
• Ports: audio/virtual_oss/Makefile (v1.3.3, christos@FreeBSD.org, LICENSE= BSD2CLAUSE, WWW= https://github.com/freebsd/virtual_oss): IGNORE_FreeBSD_15= included in base system. audio/virtual_oss_bluetooth/Makefile: DISTVERSION=${OSVERSION}, WRKSRC=${SRC_BASE}/lib/virtual_oss/bt, PLIST_FILES= lib/virtual_oss/voss_bt.so, IGNORE= requires FreeBSD source files in ${SRC_BASE} if absent; option LIBAV (AAC) pulls multimedia/gstreamer1-libav. pkg-descr: "The backend gets loaded dynamically only when a virtual_oss(8) invocation uses a bluetooth device." Sibling audio/virtual_oss_sndio same pattern.
• Upstream moved: github.com/freebsd/virtual_oss (last push 2026-06-02, "Fix buffer overflow in voss_compressor() call"; tags v1.3.0-v1.3.3); hselasky/virtual_oss is stale (last push 2023-05-27). Copyright headers: Hans Petter Selasky 2012-2023, backend_bt also Nathanial Sloss 2015 and Itronix 2006 (BSD-2-Clause throughout).

1.2 How the backend is found and loaded (the two NextBSD traps)

usr.sbin/virtual_oss/virtual_oss/main.c (releng/15.1):

1650  snprintf(lpath, sizeof(lpath), "%s/lib/virtual_oss/voss_%s.so", prefix, name);
1671  } else if (strstr(voss_dsp_rx_device, "/dev/bluetooth/") == voss_dsp_rx_device) {
1672          voss_rx_backend = voss_load_backend("/usr/local", "bt", "rec");
1686  } else if (strstr(voss_dsp_tx_device, "/dev/bluetooth/") == voss_dsp_tx_device) {
1687          voss_tx_backend = voss_load_backend("/usr/local", "bt", "play");
...
2554  if (kldload("cuse.ko") < 0 && errno != EEXIST)
2555          err(1, "Failed to load cuse kernel module");
2557  if (cuse_init() != 0)
2558          errx(EX_USAGE, "Could not connect to cuse module");

• Trap 1 — backend path is hard-coded to /usr/local/lib/virtual_oss/voss_bt.so (the port's install location). dlopen failure is fatal (errx(1, ...), main.c:1654-1655). So NextBSD must either install the FreeBSD virtual_oss_bluetooth package or build voss_bt.so itself into that path (A2).
• Trap 2 — kldload("cuse.ko") is fatal on NextBSD even with cuse compiled in. sys/kern/kern_linker.c:1218-1224: a name containing . is treated as a file (kldname = file; modname = NULL); linker_load_module() at 2264-2282 then does linker_search_kld(kldname) and returns ENOENT when no file is found — it never consults modlist_lookup2() for a statically-linked module (that branch, which returns EEXIST, is only taken for modname != NULL). NextBSD deletes the entire .ko tree at image assembly (nextbsd-kernel/ci/assemble-image.sh:168 rm -f "$ROOTFS"/boot/kernel/*.ko) and strips /sbin/kldload from base (nextbsd-freebsd-compat/scripts/superseded), so errno is ENOENT, not EEXIST, and virtual_oss dies at line 2555. Same class as wlan_xauth (#51), but this time the userland trips. Fix options (A3): kernel patch in nextbsd-kernel/patches/ so linker_load_module() returns EEXIST when the basename (minus .ko) is already a linked module — fixes every tool of this shape at once (webcamd does the same) — and/or an upstream PR to freebsd/virtual_oss guarding the call with modfind("cuse"). Non-root callers also die here with EPERM (priv_check(PRIV_KLD_LOAD), kern_linker.c:1210) — so virtual_oss must run as root or the check must be skipped when /dev/cuse already exists.
• The ports rc script needs required_modules="cuse" and LD_PRELOADs libsamplerate/libfftw3 when starting early (audio/virtual_oss/files/virtual_oss.in); base virtual_oss links the private libsamplerate, so only the module problem carries over.

1.3 The Bluetooth backend itself (lib/virtual_oss/bt/bt.c = upstream backend_bt/backend_bt.c)

• Device string: /dev/bluetooth/<bdaddr-or-bthost-name> (bt_open, backend_bt.c:288-300; uses bt_aton / bt_gethostbyname from libbluetooth). Man page examples: playback only virtual_oss -C 2 -c 2 -r 48000 -b 16 -s 4ms -R /dev/null -P /dev/bluetooth/xx:xx:xx:xx:xx:xx -d dsp; play+rec -f /dev/bluetooth/... (virtual_oss.8:278-290).
• Transport: SDP query for SDP_SERVICE_CLASS_AUDIO_SINK (play) / AUDIO_SOURCE (rec) to find the AVDTP PSM (bt_query, backend_bt.c:227-269, via sdp_open/sdp_search, SDP_UUID_PROTOCOL_AVDTP protover >= 0x0100), then two PF_BLUETOOTH/SOCK_SEQPACKET/BLUETOOTH_PROTO_L2CAP sockets to that PSM (signalling cfg->hc at :410, transport cfg->fd at :438), MTU via SO_L2CAP_OMTU/IMTU (:460, :475). AVDTP signalling in avdtp.c (discover, get capabilities, set configuration, open, start, suspend, close, abort — INT role for source at :258-370; ACP-side handlers avdtpSendCapabilitiesResponseSBCForACP, avdtpACPHandlePacket at :191/:589 for sink use).
• Codecs: CODEC_SBC always (own encoder sbc_encode.c, decoder sbc_decode()/sbc_decode_frame() at sbc_encode.c:417/629 — so record from an A2DP source also works, SBC only); CODEC_AAC only under #ifdef HAVE_LIBAV (backend_bt.c:568-620 uses libavcodec "aac" in LATM, 128 kbit/s). No aptX, no LDAC, no AVRCP (grep -ril avrcp over the whole tree: nothing).
• Pairing/link keys: none. It assumes the ACL can be brought up by the kernel with hcsecd (or bluetoothd's equivalent) answering link-key requests — that is the D/B tracks' problem, not audio's.
• Needs at runtime: an ubtN device with ng_hci/ng_l2cap/ng_btsocket attached and btsock_l2c connected; sdpd only for the sink role (virtual_bt_speaker calls sdp_open_local + sdp_register_service(SDP_SERVICE_CLASS_AUDIO_SINK) at bt_speaker.c:80-91 and listens on the AVDTP PSM :113-127). Source role talks to the remote SDP server, so no local sdpd needed.
• Maturity: in the FreeBSD base tree, maintained by christos@ (sound maintainer), 2015-era code by hps/Nathanial Sloss (NetBSD bluetooth author). Widely used by FreeBSD desktop users for years via the port. Known limits: SBC bitpool fixed by DEFAULT_MAXBPOOL (backend_bt.c:384-397), no runtime codec renegotiation, no AVRCP absolute volume so the headset's volume keys do nothing.

2. HFP/HSP — quantified

What exists in sys/netgraph/bluetooth (releng/15.1):

Prior art: NetBSD sys/dev/bluetooth/btsco.c (Itronix/Iain Hibbert, BSD-2-Clause, "Bluetooth SCO Audio device" attaching as a kernel audio device on top of a SCO PCB) — the only BSD-licensed SCO audio implementation; it depends on NetBSD's own bt stack API, so it is a design reference, not a port.

Cost: kernel patch series (eSCO command + events + alt-setting selection in ng_ubt, all under nextbsd-kernel/patches/ since the nodes are baked) + a userland HFP daemon (RFCOMM AT parser for the AG role: AT+BRSF, +CIND, +CMER, AT+VGS/VGM, AT+BCC, ring/answer/hangup, codec negotiation) + an SCO<->cuse bridge (8 kHz mono CVSD, 48-byte SCO frames every 3.75 ms) that virtual_oss can consume as /dev/dsp.hfp. Reasonably an XL on its own, and CVSD-only narrowband unless eSCO lands. Recommendation: park behind a decision whether narrowband headset mic is worth it in E16 at all (A6, "Needs answer"). Everything users notice first — music/video output to a headset — does not need it.

3. AVRCP

Nothing anywhere in FreeBSD implements AVRCP (AVCTP over L2CAP PSM 0x0017, AVC passthrough commands). Consequence today with virtual_oss: play/pause/next keys on a headset are ignored and the headset cannot report/absorb volume (no absolute-volume). Implementing the target role subset (accept the headset's AVCTP connection on PSM 23, answer UNIT INFO/SUBUNIT INFO, decode PASSTHROUGH PLAY/PAUSE/STOP/ FORWARD/BACKWARD/VOLUME_UP/DOWN) is a userland-only L2CAP listener, no kernel work; it needs a local SDP AV_REMOTE_CONTROL_TARGET (0x110C) record, which sdpd cannot register today (profile.c list above), so either extend sdpd with a profile or let bluetoothd own the SDP server for the records it needs. The key events have no consumer on NextBSD yet (there is no media-key path from a daemon to Gershwin/X); the natural delivery is a notify(3) name (org.nextbsd.bluetooth.avrcp.<key>) plus SCDynamicStore state, and absolute-volume writes routed to the audio epic's volume API. Size L, Sequence after A4 (A7).

4. How NextBSD does sound today

• Kernel (nextbsd-kernel/config/NEXTBSD, include GENERIC at :1): device sound from GENERIC (amd64) / std.dev (arm64), plus baked snd_uaudio (:206) and snd_hda (:240) with long rationale comments about the unbaked-leaf trap. No cuse, no netgraph, no ng_* anywhere in the config.
• Userland: nextbsd-freebsd-compat = full buildworld of releng/15.1 with WITHOUT_TOOLCHAIN/TESTS/ LIB32/DEBUG_FILES (README, build.yml:30-32); Bluetooth and sound tools are not disabled, so /usr/sbin/{mixer,sndctl,virtual_oss,virtual_oss_cmd,virtual_bt_speaker,sdpd,hccontrol,...}, /usr/lib/virtual_oss/voss_{oss,null}.so, libcuse, libbluetooth, libsdp ship. (Unverified on a live image: I inferred from the build knobs, not from a file listing.) No /etc from base, so no rc.d/bluetooth, no devd (stripped; kextd/IOKit replaces it).
• No sound server: nextbsd/pkglist.txt contains only pkg; nothing pulls pulseaudio/pipewire/sndio. Apps open OSS /dev/dsp directly.
• Default device: /dev/dsp is a devfs clone resolved on every open to hw.snd.default_unit (sys/dev/sound/pcm/dsp.c:2062-2079, gated by hw.snd.basename_clone, :62-64); hw.snd.default_unit (sound.c:81-111) only indexes pcm units, and hw.snd.default_auto (:55) moves it to newly attached cards. mixer -d unit / sndctl change it (mixer.8:51). A virtual_oss/cuse device is not a pcm unit, so hw.snd.default_unit can never select a Bluetooth headset. The way virtual_oss makes itself the default is by creating a real /dev/dsp node itself (-d dsp), which devfs finds before the clone handler fires (the ports rc script defaults to exactly -f /dev/dsp0 ... -d dsp -t dsp.ctl, files/virtual_oss.in). It registers with /dev/sndstat as provider "virtual_oss" (main.c:1787-1830, SNDST_DSPS_PROVIDER), which is why sndctl(8) documents "Userland devices (e.g those registered by virtual_oss) can also be selected" (sndctl.8:60-62). Unverified: devfs lookup ordering (real node vs clone) on 15.1 with basename_clone=1 — test on hardware; fallback is hw.snd.basename_clone=0.
• Runtime re-targeting: options re-parsed through the control device call voss_tx_backend_refresh() (main.c:2205-2216), and virtual_oss_cmd.8:73-76 documents virtual_oss_cmd /dev/vdsp.ctl -P /dev/dsp4 "To change the playback device" — so a persistent virtual_oss can be pointed at /dev/bluetooth/<addr> and back without restarting, and clients holding /dev/dsp open keep playing.

5. Recommended orchestration (bluetoothd side)

Model A — preferred, once the audio epic exists: 1. Audio epic runs org.nextbsd.virtual_oss (persistent, -f /dev/dspN -d dsp -t dsp.ctl, owns /dev/dsp). 2. bluetoothd, on ACL connect + SDP shows AUDIO_SINK: publishes State:/Bluetooth/Device/<addr> {Profiles:[A2DP-sink], AudioDevice:"/dev/bluetooth/<addr>"} and sends the switch request (Mach call into the audio daemon, or interim: exec virtual_oss_cmd /dev/dsp.ctl -P /dev/bluetooth/<addr> and, if the device advertises AUDIO_SOURCE, -R). On disconnect: -P /dev/dspN (the value it recorded before switching). Policy (auto-switch on connect? user preference in SCPreferences) is the audio epic's; bluetoothd only offers.

Model B — interim, no audio epic yet (what A4 ships): - bluetoothd forks virtual_oss -S -C 2 -c 2 -r 48000 -b 16 -s 8ms -R /dev/null -P /dev/bluetooth/<addr> -d dsp.bt0 -t dsp.bt0.ctl as a supervised child (same fork/exec/waitpid shape as wland -> wpa_supplicant, ul/src/WLAN/wland.c:262-275, :356, :586), waits for /dev/dsp.bt0, publishes the node in SCDynamicStore, and kills it on disconnect/unpair. Users (or Gershwin) pick /dev/dsp.bt0 explicitly; the "make it default" step is a mixer/sndctl-shaped hole the audio epic fills. Not a launchd job per device: the child's lifetime is the ACL's, bluetoothd already owns that state, and launchd has no service ordering to express "after the link is up" (wland plist comments). - Sink role (A5): virtual_bt_speaker -B -d /dev/dsp supervised the same way, started when the adapter is discoverable; needs bluetoothd's sdpd (or bluetoothd's own SDP server) running first.

6. Needs from the future audio-device epic (interface only)

• A single owner for /dev/dsp selection. Either the epic runs virtual_oss as the system mixer (then Bluetooth is just a backend string) or it defines a "default output" switch bluetoothd can call. Today neither hw.snd.default_unit nor sndctl can name a cuse device.
• A Mach/SC-shaped API with at least: ListOutputs() (pcm units + userland devices from /dev/sndstat), SetDefaultOutput(devnode), SetVolume(devnode, level), and an "output list changed" notification. bluetoothd will publish State:/Bluetooth/Device/<addr>/Audio = {Node, Profiles, Codec} and consume SetDefaultOutput on connect (policy-gated) and on disconnect.
• Volume: AVRCP absolute volume (A7) needs a SetVolume on the virtual device, and a volume-changed callback so bluetoothd can push the level to the headset.
• Media keys: a delivery path from a daemon to the session (notify name or SC key) that Gershwin turns into NSEvent media keys.
• Sample-rate/latency defaults for BT (48 kHz, 8-16 ms) versus HDA, so the epic's virtual_oss profile does not fight the backend.

7. Open questions

1. Does the FreeBSD:15 binary package repo actually publish audio/virtual_oss_bluetooth? It is a DISTVERSION=${OSVERSION} src-based port (IGNORE without /usr/src); official builders have src, but I did not confirm the package exists on pkg.FreeBSD.org. If not, A2 falls back to building voss_bt.so in the NextBSD base build (compat repo) or nextbsd-userland.
2. Where do NextBSD userland base patches live? nextbsd-freebsd-compat has no patches dir; only nextbsd-kernel/patches/. A3's kernel-side fix avoids the question; the modfind() guard should go upstream to freebsd/virtual_oss.
3. devfs real-node-vs-clone precedence for -d dsp on 15.1 (see 4). Needs a hardware run.
4. Is narrowband (CVSD, 8 kHz) headset audio worth an XL? Video calls are the only consumer, and without eSCO/mSBC quality is telephone-grade.
5. AVRCP volume/keys need a consumer; do we file the Gershwin side under E16 or the audio epic?
6. net.bluetooth.usb_isoc_enable and alt-setting selection: does any tested dongle work with ng_ubt's largest-alt policy? (Only matters for A6.)

8. Risks

• virtual_oss adds a resampling/mixing hop with its own latency; SBC at 48 kHz over a busy 2.4 GHz band next to WLAN (E-WLAN shares the radio on most laptops) will stutter without controller-side AFH — not in our control.
• The kernel BT stack has no test suite; every SCO/eSCO patch is hardware-verified only.
• virtual_oss must run as root (cuse device creation + kldload privilege check) — one more root daemon per epic; the audio epic should decide on a _virtual_oss user + devfs rules.
• Headsets without AudioSink SDP records (some LE-audio-first devices) will never match; LE Audio is a BLE (B-track) problem and entirely out of reach of netgraph.
• Link-key persistence (D track) gates all of this: A2DP reconnect after reboot requires the stored link key to be answered by whoever replaces hcsecd.