Files
UniXNU/docs/porting/usb.md

161 lines
7.4 KiB
Markdown

# USB adaptation
Complete [platform interrupts and DMA](/porting/platform) first. [QcomDwc3](https://github.com/UniXNU/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](/porting/drivers#build-integration) to connect the
recipe, then run this page's checks.
## Sources and interfaces {#source-map}
| Implementation | Source | What to read and implement |
| --- | --- | --- |
| Controller | [QcomDwc3.cpp](https://github.com/UniXNU/QcomDwc3/blob/e4efe95c903a737e0f5955e5b50a8fb4d2a7d718/QcomDwc3.cpp) | `bringUp`, `qcom_dwc3_publish`, class overrides and role changes |
| PHYs | [QcomEusb2Phy.h](https://github.com/UniXNU/QcomDwc3/blob/e4efe95c903a737e0f5955e5b50a8fb4d2a7d718/QcomEusb2Phy.h), [QcomQmpUsb3.h](https://github.com/UniXNU/QcomDwc3/blob/e4efe95c903a737e0f5955e5b50a8fb4d2a7d718/QcomQmpUsb3.h) | eUSB2, repeater and QMP sequences |
| Cable role | [QcomUcsi.h](https://github.com/UniXNU/QcomDwc3/blob/e4efe95c903a737e0f5955e5b50a8fb4d2a7d718/QcomUcsi.h), [ShengBattery.cpp](https://github.com/UniXNU/UniXNU-sheng/blob/ce0c600fa015964d4ecb6af864fa2ab66efa915f/package/ShengBattery.cpp) | UCSI messages over the charger's GLINK channel |
| Board entry | [UsbProbe.cpp](https://github.com/UniXNU/UniXNU-sheng/blob/ce0c600fa015964d4ecb6af864fa2ab66efa915f/package/UsbProbe.cpp) | Kext loads and class registration |
| Build | [build-gop-legacy-display-27.py](https://github.com/UniXNU/UniXNU-sheng/blob/ce0c600fa015964d4ecb6af864fa2ab66efa915f/scripts/build-gop-legacy-display-27.py), [board.toml](https://github.com/UniXNU/UniXNU-sheng/blob/ce0c600fa015964d4ecb6af864fa2ab66efa915f/board.toml) | Generated class header and prelink roots |
The hardware sequences follow [mainline Linux](https://github.com/ianchb/sm8550-mainline).
## 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:
```sh
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](/porting/power#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`:
```sh
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`](/xnu/patch-reference) |
| Lock state 3 | [`aks-sls=3`](/xnu/boot-arguments) |
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:
```sh
./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:
```sh
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](/porting/log-capture) 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](/porting/records).
## Next step
Continue with [baseband and cellular](/porting/baseband) on devices with a modem, or
[DSP, audio and power](/porting/power).