Skip to content

Apple Driver Thunderbolt

Jump to bottom
Abdelkader Boudih edited this page Aug 24, 2026 · 4 revisions

Thunderbolt

Upstream status: early skeleton, USB4 only, not usable on Apple Intel Macs. FreeBSD main has thunderbolt(4) under sys/dev/thunderbolt/: USB4 code imported 2025-09-27 (2ed9833791f2), controller resets added 2026-08. Read the fine print before celebrating:

  • Since 2026-04-15 (bb36c457ea49) the driver attaches only to generic USB4 NHIs, matched by PCI class/prog-if. All firmware-CM (ICM) code and the whole PCI ID table were removed in that commit.
  • The thunderbolt.4 man page says it plainly: "This driver does not provide working Thunderbolt or USB4 support."
  • It is commented out in GENERIC because it broke suspend/resume on some systems.
  • HCM stands for Host Configuration Manager (per hcm.c), the host-side configuration model for USB4 and later TB3.

Consequence for this page: no Apple Intel Mac controller matches the upstream probe. Light Ridge, Cactus Ridge, Falcon Ridge, and Alpine or Titan Ridge are TB1/TB2/TB3 parts without the USB4 class code. Everything below the line is in-development work, not stock FreeBSD behavior.

flowchart TD
    subgraph UP["Upstream thunderbolt(4), USB4 only"]
        NHI["NHI driver<br/>generic USB4 NHIs by class code"] --> HCM["HCM<br/>Host Configuration Manager"]
        HCM --> R["router config space<br/>enumeration"]
    end
    subgraph DEV["In development (driver proving ground)"]
        FW["Firmware CM mode<br/>TB firmware enumerates the fabric,<br/>the OS observes"] --> TB12["Apple TB1/TB2 controllers<br/>Light Ridge, Cactus Ridge, Falcon Ridge"]
    end

    style HCM fill:#1a4a7a,color:#fff
    style FW fill:#8a6d1a,color:#fff
Loading

Apple controller generations

Controller TB gen Machine Upstream thunderbolt(4) In-development FW CM work
Light Ridge (8086:1513) TB1, 4 channel iMac12,2 (anvil) no probe match FW CM comes up, verified
Cactus Ridge TB1 Macmini6,2 (ember) no probe match FW CM comes up, verified
Falcon Ridge TB2 MacBookPro11,5 (voyager) no probe match test target
Alpine / Titan Ridge TB3 T2 machines no probe match (pre-USB4) untested

Notes from the in-development work

These come from bring-up on the fleet, not from stock FreeBSD:

  • Load the driver at boot. Use nextboot or loader.conf, never a late kldload. Loading late reads firmware status as 0xdeadbeaf and the fabric looks dead. That value is an artifact of late attach, not a bricked controller. A reboot with boot-time load recovers it.
  • Upstream has no device_shutdown method (probe/attach/detach/ suspend/resume only). On Apple firmware that matters: without a shutdown handler a reboot can hang at the Apple logo for around 7 minutes; with one it takes under 90 seconds. This fix is proving-ground work.
  • Host-to-host XDomain networking has been demonstrated on the firmware CM in local testing (anvil to ember cable). Upstream has no XDomain code at all.

History

Scott Long laid out the design space at BSDCan 2020: security modes, bandwidth management, and the dependency on solid PCIe hotplug. That talk is still the best background read.

Back to Apple Hardware.

Clone this wiki locally