Files
UniXNU/docs/porting/usb.md

7.4 KiB

USB adaptation

Complete platform interrupts and DMA first. QcomDwc3 derives from Apple's AppleUSBXDCI and AppleUSBXHCI. The port supplies the register window, interrupt, power and PHYs. Apple's USB stacks, configd and lockdownd run unchanged.

Use driver build integration to connect the recipe, then run this page's checks.

Sources and interfaces

Implementation Source What to read and implement
Controller QcomDwc3.cpp bringUp, qcom_dwc3_publish, class overrides and role changes
PHYs QcomEusb2Phy.h, QcomQmpUsb3.h eUSB2, repeater and QMP sequences
Cable role QcomUcsi.h, ShengBattery.cpp UCSI messages over the charger's GLINK channel
Board entry UsbProbe.cpp Kext loads and class registration
Build build-gop-legacy-display-27.py, board.toml Generated class header and prelink roots

The hardware sequences follow mainline Linux.

1. Collect the hardware inputs

Read these from the target's DTS and clock definitions:

Input sheng value
DWC3 base and Apple register window 0x0a600000, window at base + 0xc000
Interrupt GIC INTID 165
SMMU stream 0x40
eUSB2 reference clock 38.4 MHz
PHYs and rails eUSB2 PHY, PMIC repeater, QMP combo PHY, retimer, GDSCs, RPMh rails

The SoC values are constants in QcomDwc3.cpp. Generate a QMP table for another SoC from its Linux tree, in the device repository:

python3 scripts/gen-qmp-usb3-table.py LINUX_TREE drivers/QcomDwc3/QcomQmpUsb3.h

2. Bring up the controller

bringUp runs in this order and stores each step in native_usb_stats[0]. A negative value is the step that failed.

Stage Step
1 Map the clock, TCSR, PHY and QSCRATCH windows
2 Vote the rails
3 Enable the GDSCs
4 Enable clocks and release resets
5 Create the stream's SMMU context
6 Start the repeater
7 Start the eUSB2 PHY, then the QMP PHY; fall back to the UTMI clock if QMP does not start
8 Read the core ID through the register window
9 Hardware ready

AppleUSBXDCI does no cache maintenance. Give the controller's stream a stage 1 identity context with write-back inner shareable blocks.

Expected result: stage 9 with a DWC3 core ID in native_usb_stats[1].

3. Register the classes

The board starts one worker thread when usb is set. It runs:

  1. qcom_dwc3_bring_up.
  2. OSKextLoadKextWithIdentifier for com.apple.driver.AppleUSBXDCI and com.apple.driver.usb.AppleUSBXHCI. AppleUSBXDCI has no personality, so nothing else loads it.
  3. OSMetaClass::preModLoad, the driver's static initializer and postModLoad.
  4. qcom_dwc3_publish, which attaches the provider nub and starts the device stack.

Add the USB stacks to the prelink roots in [kernel.prelink] of board.toml.

The class layouts come from the selected kernelcache. scripts/gen-usb27-abi.py and scripts/gen-usb27-host-abi.py write scripts/usb-xdci-24A446.json and scripts/usb-xhci-24A446.json. Both scripts name the 24A446 kernelcache and class addresses; change these for another OS build.

Keep two overrides when the layouts change:

  • Slot 179 of AppleUSBXDCI returns false without an IOPort transport object.
  • In host mode the xHCI subclass answers on for the family's desired power, and the device stack answers 0.

Expected result: stage 12, and IOUSBDeviceFamily starts on the nub.

4. Connect the cable role

Call these from the board's charger driver:

Function Use
qcom_dwc3_vbus(int) The charger's USB online value
qcom_ucsi_start, qcom_ucsi_receive, qcom_ucsi_tick Send each returned message on the GLINK channel
qcom_ucsi_polling True while the driver needs the 20 ms timer
qcom_ucsi_request_data_host, qcom_ucsi_data_host Request and observe the host data role for a compatible charger
qcom_ucsi_connection Read connector status and its attachment generation

MiPPS authentication requests the host data role with UCSI SET_UOR. The DSP owns the power role and PD/PPS contract. The connector generation advances on connection changes, including coalesced reconnect notifications; the charger retires authentication from the previous attachment before starting another exchange. See sheng charging.

A host on the cable selects the device role and a peripheral selects the host role. With no answer from either source, the device role runs. Check the UCSI client from drivers/QcomDwc3/tests:

clang++ -std=c++17 -I.. ucsi_host.cpp && ./a.out

5. Answer the Mac's pairing checks

Answer Where
chip-id [payload.adt] in board.toml
board-id, security-domain adt.chosen.u32 in the OS profile
One file system number for /System and system daemons native-union-statfs-fsid
Lock state 3 aks-sls=3

Use the model's row in the device map inside MobileDevice.framework for the three IDs.

6. Build and verify

From the UniXNU checkout, with usb=1 and log-sys=1 in the board's boot arguments:

./unixnu build kernel payload -D ../UniXNU-<device> --os <profile>
./unixnu bootimg -D ../UniXNU-<device> --os <profile> --dtb <device>.dtb -o boot.img
fastboot boot boot.img

Connect the device to a Mac:

ioreg -p IOUSB -l -w0 | grep -E 'idVendor|idProduct|Device Speed'

Expected result: the Mac lists the device, with Device Speed 4 on a USB 3 cable. Unlock it and tap Trust; the Mac then reports it as paired and starts a lockdown session. Capture the log to read the [usb] rows.

Symptom Check
Chirp passes, high-speed data fails eUSB2 reference clock table
ep0OutEventOccurred: event 0 Stage 1 SMMU context
PAC panic while creating the TRB pool AppleUSBXDCI kext load before class registration
bNumConfigurations is 0 and the host resets Slot 179
The Mac asks for a software update chip-id, board-id, security-domain
UserDeniedPairing with no dialog on the panel File system number of /System
A passcode prompt after Trust Lock state

To test host mode, set usb-host=<s> to force it after a delay and usb-back=<s> to return to the cable's role. Record device results as described in Porting record.

Next step

Continue with baseband and cellular on devices with a modem, or DSP, audio and power.