USB4 and Thunderbolt on the J516M (M3 Max) #1

Destination

An implementation spec for USB4 and Thunderbolt on the J516M (M3 Max, T6034): every build slice, from NHI bring-up to eGPU compute, specified sharply enough to become its own patch, derived from the sibling boards' work already in integration/aurora.

Notes

• Domain: Linux kernel bring-up on Apple Silicon (drivers/thunderbolt, drivers/phy/apple, drivers/pci/controller/pcie-apple*, arch/arm64/boot/dts/apple), plus m1n1 where needed.
• Vocabulary: GLOSSARY.md on the usb4-m3max branch. Use its terms (port, ACIO, NHI, ATC PHY, tunnel root port, bring-up, baseline).
• Skills: research for research tickets; grilling and domain-modeling for grilling tickets; ipsw for macOS kext and device-tree work.
• Scope: NHI bring-up on all three ports; PCIe and USB3 tunnels; DisplayPort tunnels through a dock; hotplug and s2idle; AMD eGPU compute.
• Acceptance: a USB4 NVMe enclosure reaches at least 90% of the macOS baseline on the same port. A TB4/USB4 dock works, including its display output to a monitor. eGPU compute is specified, but its acceptance waits for eGPU hardware.
• Hardware on hand: a TB4/USB4 dock, a USB4 NVMe enclosure, a monitor. macOS still boots on the J516M, for baselines and m1n1 hypervisor traces.
• Standing preferences:
  • m1n1 changes are allowed only as isolated slices with a rollback plan; kernel-only slices come first.
  • Upstream hears about this effort at PR time.
  • Commits are authored and signed off as Benjamin Nguyen, with no AI attribution.
  • Branch usb4-m3max is based on the J516M kernel.
• Starting fact: on the J516M today, the three ACIOs and four ATC PHYs bind, but no NHI binds. /sys/bus/thunderbolt is empty and only the internal PCIe controller is up.

Decisions so far

• Why no NHI binds on the J516M: nothing connects yet, and the NHI is only created on USB4 mode entry; the real gap is the T6031 ACIO start sequence (needs a t6030-usb4.dtsi-style overlay with MxWrap cpu/pcie-adapter windows plus .mxwrap in apple_cio_t6031_hw), with no m1n1 change for bring-up. Contested by draft PR T6034 (J516M): external displays over Thunderbolt, tested with a Studio Display at 5K (stacked on #405, overlaps #292) omacom/linux-aurora#406 (another J516M got a USB4 domain with the stock start), but macOS code confirms MxWrap; the first plug-in decides whether it is required or only correct

• Existing Apple USB4 work and what applies to the T6034: the Thunderbolt core, Apple NHI/ACIO driver and CIO reset apply unchanged. No PCIe or USB3 tunnel work exists for any M3 Max (the J516M's three tunnel ports need their own ADT values). The T6031 DP-tunnel code on our branch is inert, because the J516M is apple,t6034. Draft PR T6034 (J516M): external displays over Thunderbolt, tested with a Studio Display at 5K (stacked on #405, overlaps #292) omacom/linux-aurora#406 (another J516M) has T6034 DP tunnels working at 5K. PR USB4 eGPU on Apple Silicon: AMD RX 7600 runs llama.cpp on Vulkan (non-posted BARs, identity tunnel windows) omacom/linux-aurora#188's eGPU code carries over, but its identity-window rule must go into the new tunnel nodes

• J516M device tree against Apple's ADT for USB4: what Linux describes matches the ADT. Missing on all three ports: the tunnel root ports (apciec0..2, plus their DARTs and PIO-DMA), each ACIO's pcie-adapter and MxWrap cpu regions, the never-attached ps_atcN_pcie, and two tunable families. Tunnel MSIs must use the per-port slices 1886, 1918 and 1950 (the J516S pattern would collide with internal PCIe). Identical on the J516C

• What macOS does to bring up USB4 on the T6034: the T6031/T6034 run the same kexts as the T6030 (MxWrap ACIO, T8122 PHY and PCIe-C), so every difference is Linux's hw table and device tree. macOS starts MxWrap (cpu+0x28), sets LSTX through rc+0x0c and waits strictly for firmware-ready, none of which the Linux T6031 path does. It also lists the PHY steps (EQ start bit, delays, tunable order) and the PCIe-C gaps (MSI check, interrupt map, M1 reset values, apcie-common, power domain on the wrong node, T6031 missing from the pre-init and cold-init lists). Static analysis only

Not yet specified

• Whether the tunnel and DisplayPort slices need m1n1 (bring-up does not: m1n1 already fills the ACIO, NHI and PHY tunables on the J516M).
• Hotplug and s2idle behaviour per tunnel type, and what the J516S sleep work already covers; macOS also switches the CIO power rail off when every port is off, which Linux never does.
• Whether an m1n1 hypervisor trace of macOS attaching the dock is needed, to settle the CIO reconfigure trigger, power-gate index 4 and the live tunable values. It depends on what the first Linux plug-in and the live ADT dump show, and it needs a second computer.
• Throughput tuning if the enclosure falls short of 90% (link width and generation in the tunnel, interrupt and DMA paths).
• How the finished slices are stacked into test kernels on the J516M kernel, and how they are cut into upstream PRs.

Out of scope

• eGPU display output and gaming (x86 games through FEX/Proton): beyond compute, much larger, ruled out at charting.
• NVIDIA eGPUs: no open arm64 path in this tree; ruled out at charting.
• Thunderbolt networking, USB4 v2 / Thunderbolt 5 speeds: not needed for the destination.