diff --git a/README.md b/README.md index 4f30ecb..9ebe5ba 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Xbox Wireless Dongle — macOS Port +# Xbox Wireless Dongle: macOS Port User-space macOS app for the Xbox Wireless Dongle (MediaTek MT76xx). Ports the Linux kernel driver [`xone/`](../xone/) to macOS. @@ -14,18 +14,22 @@ Swift is only supported by the **Ninja** and **Xcode** generators in CMake, so configure with one of them explicitly: ```sh -cmake -S . -B build -G Ninja -DBUILD_TESTING=ON -cmake --build build +cmake -S . -B build -GNinja -DBUILD_TESTING=ON +ninja -C build ./build/xone_app -cmake --build build --target check # run the test suite +ninja -C build check # build and run the test suite ``` Layout (mirrors `../refix/`): -- `deps/` — CMake modules: `Platform.cmake`, `Flags.cmake`, `Sanitizers.cmake`, `FindUnity.cmake` -- `src/{usb,mt76,gip,auth,hid}` — C++ protocol stack (ported from `medusalix/xone`) -- `src/app/` — Swift app entry point + C ABI bridge (`include/app/xone_api.h`) -- `tests/` — Unity test suite (`BUILD_TESTING=ON`) +- `deps/`: CMake modules: `Platform.cmake`, `Flags.cmake`, `Sanitizers.cmake`, + `FindUnity.cmake` +- `src/{usb,mt76,gip,auth,hid}`: C++ protocol stack (ported from + `medusalix/xone`) +- `src/app/`: Swift app entry point + C ABI bridge (`include/app/xone_api.h`) +- `src/cli/`: C++ CLI (`xone_cli`) for manual protocol sequences +- `scripts/`: `download-firmware.sh` (port of the upstream firmware fetcher) +- `tests/`: Unity test suite (`BUILD_TESTING=ON`) --- @@ -36,123 +40,124 @@ Strike through or check off as each is resolved. ### 1. IOKit USB Access -- [x] **IOUSBLib vs IOUSBFamily** — Resolved: the SDK exposes only the +- [x] **IOUSBLib vs IOUSBFamily**: Resolved: the SDK exposes only the struct-based `IOUSBDeviceInterface` / `IOUSBInterfaceInterface` (v197/v190) via `IOCreatePlugInInterfaceForService()` + `QueryInterface`. Implemented in `src/usb/usb_transport.cpp`. -- [x] **USB device matching** — Class match on `IOUSBDevice` plus a user-space +- [x] **USB device matching**: Class match on `IOUSBDevice` plus a user-space VID/PID filter on the `idVendor`/`idProduct` properties (numeric registry matching proved unreliable). Verified with a physical dongle (PID 0x02E6). -- [x] **Interface claiming** — All interfaces are opened and pipes mapped by +- [x] **Interface claiming**: All interfaces are opened and pipes mapped by endpoint number + direction (EP 0x04 IN/OUT, EP 0x05 IN). Verified: opens cleanly with no driver conflict. -- [ ] **Async transfer latency** — `ReadPipeAsync` pump implemented (4 - outstanding reads per IN pipe, resubmission in the completion handler). - Latency tuning deferred to Phase 3 firmware load. -- [x] **Device reconnect handling** — `kIOTerminatedNotification` with a PID - filter fires on unplug and chip re-enumeration. Reliability pending hardware. +- [x] **Async transfer latency**: Resolved: the `ReadPipeAsync` pump (4 + outstanding reads per IN pipe, resubmission in the completion handler) + streams live controller input with no drops at game-report rates. +- [x] **Device reconnect handling**: Resolved: `kIOTerminatedNotification` + with a PID filter fires on unplug and chip re-enumeration. Verified + across firmware-load resets and repeated unplug/replug cycles. ### 2. Firmware Loading -- [ ] **Firmware binary availability** — Run `../xone/install/firmware.sh` (or - ported `scripts/download-firmware.sh`) to confirm the Windows Update CAB URLs - still work and firmware hashes match. -- [ ] **Firmware load sequence** — Trace the Linux `xone_mt76_load_firmware()` - flow: control request to enter firmware mode → bulk transfer in 0x3800-byte - chunks → MCU completion poll → chip reset. Map each step to IOKit equivalents. -- [ ] **Post-firmware reconnect** — After firmware loads, the chip resets and - re-enumerates. Verify the USB device reappears with the same VID/PID and can - be re-opened. +- [x] **Firmware binary availability**: Resolved: `scripts/download-firmware.sh` + (port of `../xone/install/firmware.sh`) fetches the Windows Update CAB + images and the hashes match the Linux driver. Images land in `firmware/`. +- [x] **Firmware load sequence**: Resolved: ported to `src/mt76/mt76.cpp` + (control request to firmware mode, bulk transfer in 0x3800-byte chunks, + MCU completion poll, chip reset). Verified on hardware: FCE shows the + firmware running after load. +- [x] **Post-firmware reconnect**: Resolved: the chip re-enumerates with the + same VID/PID; the app and CLI close, wait, and reopen the device. The + full sequence runs end-to-end. ### 3. MT76 Register Access -- [ ] **Vendor request format** — The Linux driver uses `usb_control_msg()` with - vendor requests (bRequest 0x84/0x86 for register R/W). Confirm the exact - `bmRequestType`, `bRequest`, `wValue`, `wIndex`, `wLength` values work via - `IOUSBDeviceInterface->DeviceRequest()`. -- [ ] **Register timing** — Some register writes require delays between them. - Test if `usleep()` in user-space provides sufficient precision, or if - `clock_nanosleep()` is needed. -- [ ] **EFUSE read** — Verify the EFUSE read sequence returns valid MAC address, - chip ID, and TX power calibration data on macOS. +- [x] **Vendor request format**: Resolved: the Linux values work unchanged via + `IOUSBDeviceInterface->DeviceRequest()` (bRequest 0x84/0x86 for register + R/W). All radio init traffic uses this path. +- [x] **Register timing**: Resolved: `usleep()` / `clock_nanosleep()` in + user-space are sufficient; radio init and channel evaluation complete + reliably. +- [x] **EFUSE read**: Resolved: the EFUSE sequence returns valid MAC address, + chip ID, and TX power calibration data on macOS (`xone_cli info`). ### 4. 802.11 Frame Handling -- [ ] **Beacon construction** — The Linux driver builds raw 802.11 beacon frames - with a Microsoft OUI (00:50:f2) information element. Verify the frame format - matches what the MT76 chip expects (may include chip-specific headers before - the 802.11 frame). -- [ ] **Frame encapsulation** — The MT76 chip wraps 802.11 frames in a - proprietary header. Reverse-engineer or confirm the header format from Linux - driver source (`xone_mt76_tx()` / `xone_mt76_rx()`). -- [ ] **QoS data frames** — Controller input/output uses 802.11 QoS data frames. - Verify the frame construction and AES-CCMP encryption/decryption flow. +- [x] **Beacon construction**: Resolved: beacons with the Microsoft OUI + (00:50:f2) information element transmit correctly, including the chip + header before the 802.11 frame. Controllers hear them and associate. +- [x] **Frame encapsulation**: Resolved: TX/RX chip headers handled per the + Linux driver (`send_wlan` / `process_wlan`). Association, pairing, and + encryption-enable management frames verified against hardware. +- [ ] **QoS data frames**: RX path verified: controller input QoS frames are + decrypted, fed to the GIP layer, and shown live in the app. Host to + controller TX (rumble, LED over the data path) is not implemented yet. ### 5. AES-CCMP Encryption -- [x] **Crypto backend choice** — CommonCrypto (SHA-256/HMAC), Security.framework +- [x] **Crypto backend choice**: CommonCrypto (SHA-256/HMAC), Security.framework (RSA PKCS#1), and a self-contained P-256 ECDH (no public macOS C API for EC key agreement). Implemented in `src/auth/crypto.cpp`. -- [x] **CCMP mode implementation** — Not needed on the host: AES-CCMP runs on the +- [x] **CCMP mode implementation**: Not needed on the host: AES-CCMP runs on the MT76 chip; the host only installs keys via WCID registers (`xone_mt76_set_client_key`). -- [x] **ECDH key exchange** — P-256 implemented and validated against +- [x] **ECDH key exchange**: P-256 implemented and validated against OpenSSL-derived test vectors (`tests/test_crypto.cpp`). ### 6. Virtual HID Gamepad -- [ ] **HID Proxy Driver feasibility** — Research Apple's [HID Proxy +- [ ] **HID Proxy Driver feasibility**: Research Apple's [HID Proxy Driver](https://developer.apple.com/documentation/coreaudio/hid_proxy_driver) (DriverKit). Can we create a virtual Xbox controller that games recognize natively? -- [ ] **IOHIDDevice user-space alternative** — Can we create a virtual HID +- [ ] **IOHIDDevice user-space alternative**: Can we create a virtual HID device entirely in user-space? Test with `IOHIDManager` and see if games (Steam, Game Center) recognize it. -- [ ] **HID report descriptor** — Write an Xbox 360/One-compatible HID report +- [ ] **HID report descriptor**: Write an Xbox 360/One-compatible HID report descriptor. Test with existing Xbox controller (via Bluetooth) to capture the exact report format macOS expects. -- [ ] **Force feedback** — Can the virtual HID device receive rumble commands +- [ ] **Force feedback**: Can the virtual HID device receive rumble commands from games and relay them to the controller via GIP? ### 7. Core Audio (Headset Support) -- [ ] **Audio Unit setup** — Test creating an `AURenderCallback` / +- [ ] **Audio Unit setup**: Test creating an `AURenderCallback` / `AUOutputUnit` for headset playback and `AURecordingCallback` / `AUInputUnit` for mic input. -- [ ] **Latency requirements** — The GIP protocol sends audio in 8ms intervals. +- [ ] **Latency requirements**: The GIP protocol sends audio in 8ms intervals. Can Core Audio maintain this latency without glitches? -- [ ] **Format negotiation** — The headset negotiates audio format (sample rate, +- [ ] **Format negotiation**: The headset negotiates audio format (sample rate, channels) via GIP. Map GIP audio formats to Core Audio `AudioStreamBasicDescription`. ### 8. Build System -- [ ] **CMake vs Xcode** — CMake is simpler for the C library portions, but - Xcode is needed for the macOS app bundle and any DriverKit extension. Decide - on primary build system. -- [ ] **Minimum macOS version** — Target 12.0 (Monterey) for modern +- [x] **CMake vs Xcode**: Resolved: CMake with the Ninja generator compiles + both the C++ stack and the Swift app (see Building). An Xcode project is + only needed later for a DriverKit extension, if Phase 4 goes that route. +- [ ] **Minimum macOS version**: Target 12.0 (Monterey) for modern IOKit/DriverKit. Verify all APIs are available. -- [ ] **Code signing** — IOKit USB access may require specific entitlements - (`com.apple.kpi.iokit`, `com.apple.security.device.usb`). DriverKit requires - notarization. Plan for development vs distribution signing. +- [ ] **Code signing**: Development builds run unsigned on the local machine + with no entitlements needed for IOKit USB access. DriverKit + notarization and distribution signing deferred to the HID phase. ### 9. Regulatory / Legal -- [ ] **5GHz channel restrictions** — macOS enforces regulatory domain for 5GHz. - The dongle may try to use channels blocked in the current region. May need to - limit to 2.4GHz only or find a way to override. -- [ ] **Firmware license** — The firmware binaries are from Microsoft Windows +- [ ] **5GHz channel restrictions**: Channel evaluation picks a working + channel and pairing is verified on hardware; no regulatory failures seen + so far. Regional edge cases (blocked channels) remain untested. +- [ ] **Firmware license**: The firmware binaries are from Microsoft Windows Update. Confirm they can be redistributed with the macOS port (the Linux driver includes them with a disclaimer). ### 10. Testing Hardware -- [ ] **Dongle** — Xbox Wireless Dongle (PID 0x02FE preferred, 0x02E6 also - works) -- [ ] **Controller** — Xbox One or Series X|S controller (for pairing and input - testing) -- [ ] **Headset** — Xbox Wireless Headset (optional, for audio testing) -- [ ] **macOS machine** — Intel or Apple Silicon (test both if possible, IOKit +- [x] **Dongle**: Xbox Wireless Dongle (PID 0x02FE preferred, 0x02E6 also + works). In hand: PID 0x02E6 verified end-to-end. +- [x] **Controller**: Xbox One or Series X|S controller (for pairing and input + testing). In hand: pairing and live input verified. +- [ ] **Headset**: Xbox Wireless Headset (optional, for audio testing) +- [ ] **macOS machine**: Intel or Apple Silicon (test both if possible, IOKit may differ) --- @@ -166,7 +171,7 @@ Strike through or check off as each is resolved. | `usb_submit_urb()` | `ReadPipeAsync()` + `CFRunLoopSource` | ✅ Done (reader thread) | | `kzalloc` / `kfree` | `malloc` / `free` | ✅ Straightforward | | `spin_lock_irqsave` | `std::mutex` / `std::condition_variable` | ✅ Done (`usb_transport.cpp`) | -| `msleep` / `mdelay` | `usleep()` / `clock_nanosleep()` | ☐ Test timing | +| `msleep` / `mdelay` | `usleep()` / `clock_nanosleep()` | ✅ Done (radio init, channel eval) | | `crypto_shash_*` | CommonCrypto / Security.framework | ✅ Done (`auth/crypto.cpp`) | | `input_register_device()` | HID Proxy Driver / IOHIDSystem | ☐ Investigate | | `snd_pcm_*` | Core Audio (Audio Units) | ☐ Investigate | @@ -177,14 +182,21 @@ Strike through or check off as each is resolved. --- -## First Steps on macOS +## Current Status -1. Plug in the dongle, run `system_profiler SPUSBDataType` — confirm it's - detected -2. Check `log show --predicate 'subsystem == "com.apple.iokit"'` — see if macOS - loads any driver -3. Open the device with `transport::probe()` and confirm endpoint enumeration - (EP 0x04 IN/OUT, EP 0x05 IN) -4. Try a vendor control request (register read) to verify USB communication - works -5. Attempt firmware load with the binary from `firmware/` directory +Working end-to-end on hardware: + +- Dongle probe/open, async read pump, vendor register R/W +- Firmware download (`scripts/download-firmware.sh`) and load +- EFUSE read, radio init, channel evaluation, beacon TX +- Pairing mode, controller association, GIP handshake + auth +- Live controller input (buttons, sticks, triggers) in the Swift app + +Not done yet: host to controller TX over the data path (rumble, LED), +virtual HID gamepad (Phase 4), headset audio (Phase 5). + +`xone_cli` exercises the stack manually in a single dongle session: + +```sh +./build/xone_cli info firmware firmware/xow_dongle.bin radio-init pair +```