docs: update README with current project status

Check off investigation items resolved on hardware (firmware load, EFUSE, radio init, beacon, pairing, reconnect), align build commands with AGENTS.md, add xone_cli and scripts to the layout, replace the completed first-steps list with a current status section, and drop em dashes per the documentation conventions. Co-Authored-By: qwen3.8-27b@q3_k_xl: updated README with current status
2026-08-29 14:21:18 +02:00
parent 418e177b5c
commit 51192023aa
1 changed files with 93 additions and 81 deletions
@@ -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.
@@ -15,17 +15,21 @@ so configure with one of them explicitly:

 ```sh
 cmake -S . -B build -GNinja -DBUILD_TESTING=ON
-cmake --build build
+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
+```