reverb-m1

SETUP.md (13879B)

---

 # HP Reverb G1 on an M1 Mac: how we got the display working
 
 First lit successfully 2026-10-20: macOS desktop visible inside the headset, panel stays lit, no replugging.
 
 Machine: Apple M1 MacBook Air, macOS 15.6.1 (24G90). Headset: HP Reverb G1 (VR1000-2xxx).
 Display adapter: Cable Matters USB-C-to-DisplayPort adapter, model **201086**.
 
 ## The problem
 
 The Mac detected the headset as a 4320x2160 display, but the panel never stayed lit. On each connection the
 headset turned the panel on, turned it off ~300 ms later, dropped the DisplayPort link and retried every ~8 s.
 
 **Cause: HDCP.** A couple of seconds after hotplug, macOS's display coprocessor (DCP) starts HDCP 2.x
 encryption on every external DisplayPort link. The headset can't handle it and blanks. Linux never does this,
 which is why the same headset and hub worked on a Linux box.
 
 Ruled out along the way: power/hub, refresh rate and resolution, color bit depth (macOS already sends 8-bit RGB),
 the proximity sensor, and our own HID commands (the headset blanks even when we send nothing).
 
 ## The fix (exact steps)
 
 ### 1. System security prerequisites
 - SIP disabled (`csrutil disable` from Recovery). Check: `csrutil status`.
 - Boot-arg `amfi_get_out_of_my_way=1` allows the ad-hoc entitled helper used for recovery. It does not disable HDCP or fix panel blanking.
 
 ### 2. Disable HDCP with a boot-arg
 ```sh
 sudo nvram boot-args="amfi_get_out_of_my_way=1 hdcp-fuse-mask=0"
 nvram boot-args          # must print both flags
 # reboot
 ```
 Note that `boot-args` is one string, so writing it again **replaces** the previous value. Always write the
 full set of flags. (Our first reboot failed for exactly this reason: only the AMFI flag was saved.)
 
 After the reboot, verify (no headset needed):
 ```sh
 sysctl -n kern.bootargs                        # -> amfi_get_out_of_my_way=1 hdcp-fuse-mask=0
 ioreg -l -w0 | grep '"HDCPTXCapabilities"'     # every line should show {"Protocols"=()}
 # (one-off setup check only; never run ioreg while the headset is live or in a loop)
 ```
 Before the fix these show `{"Protocols"=(1,2)}` (HDCP 1.x and 2.x). The `HDCPCapabilityMask` field does
 NOT change (still 2/3); that's expected and harmless.
 
 **Revert:** `sudo nvram boot-args="amfi_get_out_of_my_way=1"` and reboot.
 Side effect: HDCP-protected content (some streaming video to external displays) won't play on external screens.
 
 ### 3. Connect the headset
 1. Headset USB-A into the (powered) Anker hub; hub into the Mac.
 2. Cable Matters USB-C-to-DisplayPort adapter (model 201086) into the Mac's other USB-C port, then the headset's DP plug into the adapter.
 3. macOS asks **"Allow accessory to connect?"**. Click **Allow**. Until you do, all HID calls fail with
    `0xe00002cd` (kIOReturnNotOpen).
 
 ### 4. Build the two demonstrations
 ```sh
 zsh tools/build.sh
 ```
 Run this from the repository root. It builds the stereo application, recovery helper,
 USB wake tool, and passive display observer using Apple's Command Line Tools.
 
 ### 5. Native macOS desktop output
 
 Quit the stereo application first, then run:
 
 ```sh
 .build/debug/hmdwake          # leave running; Ctrl-C to quit
 ```
 
 macOS treats the headset as an external display. In System Settings > Displays,
 choose the headset and use it as an extended display or select mirroring. Any
 windows placed on that display are sent directly to the headset by macOS.
 
 This reproduces the original desktop-output breakthrough. The operating system
 sends one desktop image across the headset's display surface: it does not duplicate
 the desktop for each eye or apply the demo renderer's lens correction. This is
 display bring-up, rather than a comfortable stereo desktop workspace.
 
 For a passive connection/mode check, run this in another terminal:
 
 ```sh
 .build/debug/displaywatch     # Ctrl-C to quit
 ```
 
 It reports display connections and pixel modes without capturing desktop pixels.
 Its output includes display metadata and timestamps; review it before sharing logs.
 Seeing a connected display in software is separate from confirming illumination
 and the desktop image inside the headset. The standalone wake tool does not run
 the stereo application's automatic link recovery.
 
 The wake tool sends (ported from Monado's `wmr_hmd_activate_reverb`):
 - To the QHMD control device `03f0:0c6a` (feature reports):
   4x set `[0x50, 0x01]` + get `0x50`, then get `0x09`, `0x08`, `0x06`, then set `[0x04, 0x01]` (screen on).
 - To the HoloLens Sensors device `045e:0659` (output report): `[0x02, 0x07]` + zero pad to 64 bytes (IMU on).
 
 Within ~1.5 s the DP link trains (HBR3, 8.1 Gbps x 4 lanes), macOS adds the 4320x2160 display, and the headset
 reports `05 01 01 01 01 ...` (panel on). (Drops can still occur later; see NOTES.md "Link reliability".)
 Stop `hmdwake` with Ctrl-C before starting the stereo demo. The application sends
 the wake sequence itself; the two programs must not own the HID devices together.
 
 ### 6. Stereo 3D demo (owns the headset, recovers it automatically)
 ```sh
 .build/debug/VRWorkstation --run-seconds 600        # run for 10 minutes; omit the option for indefinite
 ```
 Look for a rotating colored cube, a floor grid, and reference objects at several
 depths. Each eye receives its own rendered view through the factory lens correction.
 The Headset optics window on the Mac provides pattern/tuning controls and Quit.
 This demo uses a fixed viewpoint; head tracking is not connected to this scene.
 
 - `tools/build.sh` builds the app with `swift build`, then compiles `tools/hpmctl.c` into the same directory as the app
   executable (`.build/debug`) and ad-hoc signs it with `tools/hpmctl.entitlements`
   (`com.apple.USBCEntitlement`).
 - The app runs as a normal non-root user. When the headset display is lost and does not return within a 2 s
   grace period, it runs that helper directly to send a USB-PD Data Reset to port 2's controller. No sudo, no password:
   the kernel admits root OR that entitlement, and AMFI being off (`amfi_get_out_of_my_way=1`) lets an ad-hoc signature
   carry it. Limits: 3 s helper timeout, at most 3 resets per minute.
 - Recovery runs on its own serial queue, fed directly from the CoreGraphics display callback (before any main-thread
   work), because macOS's SkyLight blocks the main thread for ~10 s during a display reconfiguration
   (`SLSWaitThroughReconfigurationCycleForcingNotificationHandling`). Any headset display ADD cancels a pending reset.
 - The helper reports failure (exit 1) unless the controller's DATA1 result is 0. A result of 0x04 has been seen after
   an accepted DRST that still restored the display; the app treats ADD, not the helper's exit code, as proof.
 - First launch reads the headset's factory optical calibration before enabling the rendering session, then caches it at
   `~/Library/Application Support/ReverbM1Demo/factory.json`. Later launches validate and reuse that file.
   `--calibration /path/to/factory.json` explicitly selects another saved calibration; invalid calibration stops startup.
 - Each eye renders with its calibrated asymmetric field of view to a 3024x3024 target. A final pass applies the factory
   Polynomial-3K lens correction separately to red, green, and blue before native 4320x2160 output. There is no
   uncalibrated rendering fallback. Eye spacing remains 63 mm; head tracking is not connected to the scene yet.
 - `--optics-grid` shows a stationary angular grid, with its green cross at straight ahead (tangent 0,0).
   `--snapshot /tmp/calibrated.png` renders through the same correction without opening the headset.
 - Calibrated rendering passed a 180 s trial: 89.996 presented fps over the settled health interval, no display drops,
   0 GPU errors, approximately 5.97 ms GPU/frame, clean shutdown. See `evidence/calibrated-90hz-trial.json`.
   Software validation is complete; physical optical validation remains separate from software/model checks.
 - The app covers the headset with a non-activating borderless panel, without exclusive display capture, at native unscaled 4320x2160 @ 90 Hz.
   If macOS changes the mode by itself, the app restores 90 Hz (also checked every 10 s, CoreGraphics only).
 - Rendering runs on a dedicated "Headset Metal rendering" thread: a `CAMetalDisplayLink` on that thread's run loop
   hands each frame a ready drawable (no `nextDrawable` calls, nothing drawn on the main thread). The main thread only
   handles AppKit and display connect/disconnect callbacks, so a stalled frame can no longer delay drop detection
   (it previously did, by up to ~11 s). The depth buffer is created once and reused.
 - Health line every 10 s in the app log: `submitted`, `presented` (only frames Metal reports with a real
   presentation time), `skipped`, `fps` (presented per second), `presentAge`, `GPUms` per frame, `GPUerrors`, IMU sample
   count. Healthy looks like `fps=90.00 presentAge=0.01s GPUerrors=0` with `skipped` not increasing after startup.
 - Status (2026-10-20, ~[time redacted]):
   - Stereo 3D output was confirmed in hardware testing.
   - Shutdown crash (exit -11, double CAMetalDisplayLink invalidate) fixed; 2 clean-exit/restart trials exit 0.
   - Fault soak (`evidence/final-metal-worker-soak.txt`, build before the recovery queue): 3 forced outages all
     recovered; after them ~7 min untouched with zero drops, 90.00 presented fps, GPU ~1.5 ms/frame, 0 GPU errors.
   - Root cause of the ~10 s main-thread SkyLight wait after a REMOVE: unknown (see NOTES.md).
   - Forced-outage duration (display lost -> back): 14.4 s before the recovery queue, 4.4 s with it
     (= 2 s grace + ~2.2 s reset/retrain/re-add). Releasing the capture inside the callback did not help
     (CGDisplayRelease returns 1001 = kCGErrorIllegalArgument there; outages 4.6 s) and was removed.
   - Every DRST is followed ~5.7 s later by a brief lane-sync blip (IRQ_HPD/INTERLANE retrain) that the app handles automatically.
   - **Reliability milestone PASSED** (`evidence/verified-90hz-soak.json`, `evidence/verified-90hz-soak.txt`):
     no-fault soak at native 4320x2160 @ 90 Hz, exit 0, 649.965 s settled interval, 58,496 presented frames =
     89.9987 fps, skipped +3, 0 GPU errors, no render-worker join timeout, zero DP resets. One 0.637 s self-heal at
     startup, then no drops.
 - Factory calibration: `.build/debug/VRWorkstation --read-calibration <path>` reads the headset's config store over
   HID (10,737 bytes, under 1 s; do it before the app enables the IMU). The app caches it at
   `~/Library/Application Support/ReverbM1Demo/factory.json`. Lens correction using it is in progress.
 
 ## How the boot-arg was found
 `amfi_get_out_of_my_way` controls code signing, not HDCP, so we searched this Mac's own kernel:
 1. Copied the arm64 kernelcache from
    `/System/Volumes/Preboot/<uuid>/boot/<hash>/System/Library/Caches/com.apple.kernelcaches/kernelcache`
    and decompressed it with `pyimg4 img4 extract` + `pyimg4 im4p extract`.
 2. Searched its strings for HDCP names, then disassembled the code that uses them (capstone, plus a small
    ADRP/ADD cross-reference scanner).
 3. Findings:
    - `AppleDCPDPTXProxy` calls `PE_parse_boot_argn("hdcp-fuse-mask", &mask, 4)` (default = hardware fuse & 3).
      Apple's own "HDCP suppressed per disable-av-content-protection" path (a device-tree flag set by iBoot,
      not settable by us) simply sets that mask to 0.
    - `AppleSEPHDCPManager` also parses `hdcp-fuse-mask` and **replaces every HDCP channel's protocol bits**
      with it (`caps = (caps & ~0x18) | (mask & 3) << 3`) before handing them to the Secure Enclave.
    - The external display coprocessor `dcpext` (USB-C DisplayPort) owns HDCP channels 5 and 6.
    - So `hdcp-fuse-mask=0` leaves the transmitter with no HDCP protocols, and encryption never starts.
 
 ## Gotchas
 - Keep `IOHIDManager` objects alive as long as you use their devices; freeing the manager closes the device.
 - In zsh, `log` is a builtin; use `/usr/bin/log`.
 - The headset's status report `0x05`: byte 1 appears to track panel-on (unreliable on the G2 per Wintch/reverb-g2). Byte 5 is
   NOT a reliable refresh measurement: it read 0x59/0x3b in some sessions but 0 while video was visibly running in others.
   Judge the display by the native mode in use and actual Metal presentation counts, not by this byte.
 
 ## Tools (`tools/`)
 - `hmdwake` (`.build/debug/hmdwake`): wake sequence + IMU on, exposing native desktop output. Feature/control payloads are omitted from logs. `passive` arg = listen only. SIGUSR1 = screen on.
 - `displaywatch` (`.build/debug/displaywatch`): passively logs display add/remove (CoreGraphics callbacks); does not capture screen pixels.
 - Never poll `ioreg -c IOPortTransportStateDisplayPort` (the old `linkwatch.sh` did; removed).
 - `testpattern`: red LEFT / blue RIGHT fullscreen pattern on the headset.
 - `verify.sh`: passive one-shot check (boot-args + summaries of existing logs). No ioreg/system_profiler/HID. Launches nothing.
 - `build.sh`: builds the app, signed `hpmctl` helper, `hmdwake`, and `displaywatch` together (step 4).
 - `hpmctl` / `recovery_trials.py` / the app's LinkRecovery helper: see NOTES.md "Link reliability" (vr0 owns these).
 
 ### Optical tuning window
 
 The **Headset optics** window on the Mac switches between the 3D scene, a stationary white grid, and a green-only
 sharpness grid. Red correction and separate blue horizontal/vertical correction range from -100% to 400%; 100% is
 factory compensation. Changes save automatically to `~/Library/Application Support/ReverbM1Demo/optics-adjustments.json`.
 The factory reset button restores 100% for all three controls. Color controls are disabled for the green-only pattern.
 The floor now uses a filtered procedural grid to avoid subpixel line aliasing at distance.
 
 The headset uses a non-activating panel and is placed to the right of other displays for this session. The Mac controls remain a normal window with a Quit button. No Dock preferences are changed.