rxdemo Android USB-fd path + autonomous Quest RX-ring harness (issue #330)

[josephnef]

What

Makes rxdemo runnable on Android and adds a fully autonomous Quest 3 harness for the issue #330 async-RX-ring residual-loss investigation.

Android USB-fd path (the core fix)

The RX demo could never run on Android: libusb's device enumeration is SELinux-denied under the untrusted_app domain, and only the TX demo had the wrap-a-pre-opened-fd path. Ported into examples/rx/main.cpp:

• argv[1] = a numeric USB fd; LIBUSB_OPTION_NO_DEVICE_DISCOVERY + WEAK_AUTHORITY before libusb_init; libusb_wrap_sys_device; skip the reset/reopen (a wrapped app-owned fd can't be re-enumerated).
• CMakeLists.txt links Android log (was previously unlinked).

Autonomous Quest harness (tests/quest_apk/)

A minimal auto-grant APK, hand-built with aapt/d8/apksigner (no gradle), modelled on how PixelPilot avoids the USB permission dialog:

• a USB_DEVICE_ATTACHED intent-filter + device_filter auto-grants USB permission on attach — no dialog;
• a JNI fork()+execve() helper hands the UsbDeviceConnection fd to rxdemo (Android's ProcessBuilder closes fds ≥3 before exec, so the fd must be inherited across an in-process fork).

Driven headlessly from the desktop via am start extras — no in-headset interaction. tests/quest_rxq_run.sh + quest_rxq_analyze.py run the per-mode matrix; tests/build_android.sh cross-builds the arm64 bundle; runbook in tests/quest_rxq.md.

Instrumentation + modes (all off by default; async byte-unchanged when unset)

rx.ring telemetry (posted-URB depth, cb_max_us consumer stall, resubmit_fail, completions), rx.seq per-frame delivery, DEVOURER_RX_MODE {async|sync|reorder-pool|spsc-fat} with a spare-buffer pool, and a demo-side sink-spin / TX keyframe-burst stimulus. Plus the desktop constrained-host repro (tests/rxq_starve.sh, rxq_analyze.py, rxq_preempt.c).

Findings

Documented in docs/experiments/issue-330-rx-ring-starvation.md. The ~1–2% residual is not attributable to ring-servicing strategy on either the desktop or a genuinely constrained XR2 host: at load the ring absorbs the (real, large — up to ~15 ms cb_max_us on the Quest) consumer stalls, and delivery is RF- or consumer-throughput-limited. Across three load regimes async/reorder-pool/spsc-fat tie within run-to-run noise (±1.5 pts, no consistent ordering). The shippable product is the rx.ring telemetry as a field diagnostic a reporter runs on their own phone.

Test

• Native build clean; ctest 37/37 pass.
• async path unchanged when the new knobs are unset.
• On-device: full RTL8812AU bring-up + RX ring live on a Quest 3, driven entirely over adb.

🤖 Generated with Claude Code