reverb-m1

NOTES.md (12862B)

---

 # HP Reverb G1 on M1 Mac: findings
 
 ## Root cause of the dark panel: HDCP
 When the DP link comes up, the headset turns the panel on (status `05 01 ...`). macOS's DCP then enables
 HDCP 2.x encryption about 2-3 s after hotplug; the headset blanks within ~300 ms, drops HPD, and retries every
 ~8 s forever. Ruled out: power (same hub works on Linux), refresh rate/mode, bit depth (8-bit RGB), our HID commands.
 
 ## Fix (CONFIRMED 2026-10-20): boot-arg `hdcp-fuse-mask=0`. Desktop output confirmed in hardware testing; full recipe in SETUP.md
 From disassembling this machine's arm64 kernelcache (macOS 15.6.1):
 - DPTX init: `PE_parse_boot_argn("hdcp-fuse-mask", &mask, 4)`, default = fuse & 3.
 - Then checks device-tree `/chosen/disable-av-content-protection` (iBoot-set, not a boot-arg). If true it logs
   "HDCP suppressed per disable-av-content-protection" and sets mask = 0. `-restore` does the same.
 - So `hdcp-fuse-mask=0` reproduces Apple's own HDCP-suppressed state. Parsed at 2 call sites.
 - Other HDCP boot-args (semantics not decoded): av_hdcp_protocol_mask, av_hdcp_auth_policy,
   av_protection_delay_ms, av_cp_failure_mitigation_enabled.
 - `amfi_get_out_of_my_way=1` affects code signing, not HDCP.
 
 ## HID (works)
 - Control 03f0:0c6a: 4x feature [0x50,0x01]+get, get 0x09/0x08/0x06, feature [0x04,0x01] = screen on.
 - IMU 045e:0659: output [0x02,0x07] starts 1000 Hz IMU (381-byte reports).
 - Status 0x05 (11 bytes): [1],[4] appear to track panel on. [5] is NOT a reliable refresh measurement (nonzero in some
   sessions, 0 while video was visibly running in others); do not infer refresh from it.
 
 ## After reboot
 Run `tools/verify.sh` (boot-args + log summaries only; no ioreg/system_profiler). Panel lit must be confirmed physically.
 
 ## Link reliability (2026-10-20, vr1 + vr0)
 - Periodic ~70-80 s drops ([time redacted]-[time redacted]) happened while `ioreg -c IOPortTransportStateDisplayPort` was polled at 1 Hz and a
   287 s run without polling had none, but causation is UNPROVEN. Signature: sink pulls HPD fully low (DP [HPD=0,IRQ=0]).
   Counter-evidence: an HPD=0 drop at [time redacted] with NO polling running, 18.6 s after a 90 Hz mode-set link-up.
   Still: never poll that class.
 - Post-DRST transient (2 of 3 trials, +5.05 s after link-up): headset raises IRQ_HPD (DP [HPD=1,IRQ=1]); DCP
   DCPDP13Service::handleCheckLink reports INTERLANE_ALIGN_DONE=0 -> "link unstable, retraining" -> terminates the video
   interface (macOS sees REMOVE) -> retrains at HBR3 x4 -> ADD ~0.63 s later. A link-integrity failure, different from
   the HPD=0 drops. Hypothesis: HBR3 margin through the adapter; 60 Hz fits HBR2 (~15.2 of 17.28 Gbps).
 - DCP firmware has per-port link limits (max_link_rate, max_link_rate_4_lanes, min_link_rate, max_lane_count) read
   from boot-args with default prefix "appledptx" (format strings "%s-%s" present, so likely `appledptx-max_link_rate=`);
   name format VERIFIED (DCP fw 0x708b0: snprintf(key[0]=='-' ? "-%s%s" : "%s-%s", prefix, key)) => boot-arg is exactly
   `appledptx-max_link_rate`; value is 1 byte in DisplayPort link-rate codes (VERIFIED: min_link_rate defaults to 6 =
   RBR at DCP fw 0x56914; compared against the logged linkRate at 0x52a7c). HBR2 cap = `appledptx-max_link_rate=0x14`
   (hex vs decimal parsing of the value not verified; 20 = 0x14). Untested; needs a reboot.
 - Stuck state (headset display gone, adapter reports HPD=0 to the Mac): **recoverable in software** with a USB-PD
   Data Reset on port 2's controller: `sudo tools/hpmctl 1 cmd DRST` (4CC passed big-endian, see
   tools/kernel/HPM_RE.md section 8). First success: display back 2.2 s after the command, no replug.
 - RETRACTED: "only a physical replug recovers it"; "deeper off state"; "HRST untested/unsupported" claims made
   before the byte order was fixed. With correct encoding HRST is rejected by the firmware (!CMD), DRST works.
 - HID screen_off (0x04 0x00) reliably induces the stuck state; screen_on / full wake alone do not undo it.
 
 ## App recovery path (2026-10-20, vr0 implementation, vr1 review)
 - macOS SkyLight blocks the app's MAIN thread for exactly ~10.0 s right after delivering a display REMOVE
   (sample: CGSPostLocalNotification -> SLSWaitThroughReconfigurationCycleForcingNotificationHandling ->
   connection_fetch_updated_event_queue). Not triggered by our code; IMU callbacks on main stall with it.
 - Fix: recovery state machine on its own serial queue, fed directly from the CG callback before the main hop;
   rendering on a dedicated CAMetalDisplayLink thread. Forced outage 14.4 s -> 4.4 s.
 - Tested, not supported (vr1 hypothesis): "the window server waits for us to release the captured display".
   CGDisplayRelease inside the REMOVE callback returns 1001 = kCGErrorIllegalArgument (the id is no longer valid there)
   and outages stayed ~4.6 s, so that release was removed. This does NOT conclusively rule out every capture-related
   cause; the root cause of the ~10 s SkyLight wait remains unknown.
 - Helper result: DATA1 byte0 = 0x04 observed after a DRST whose IOReturn was 0 and after which the display returned.
   Meaning of 0x04 unknown (TI documents 0 = success, 1 = timeout/abort, 3 = rejected). The helper conservatively
   exits 1; the app relies on display ADD.
 - Remaining outage = 2 s grace (avoids resetting during 0.6-0.8 s self-heals) + ~2.2 s DRST/retrain/re-add.
   Millisecond continuity would need the HPD-blip ride-through below (untested, needs a reboot).
 
 ## Candidate: ride through brief HPD drops (millisecond-level, no display REMOVE) — static, UNTESTED
 DCP firmware (FUD/DCP.img4, t8103) AppleDCPDPTXController config, verified in disassembly:
 - 0x56c0c: key `hot_unplug_delay_ms` -> boot-arg `appledptx-hot_unplug_delay_ms` (prefix + "-" + key, see above).
 - 0x56c1c-0x56c28: default = (0x4bc5c(this) ? 0 : 200) ms; 0x4bc5c = (port-type vmethod +0x1a0 == 1), true for our
   USB-C alt-mode port => default 0 => macOS removes the display the instant HPD drops ("HPD Lost period over").
 - 0x573f0: stores the boot-arg's numeric value if present, else the default. Property `hot-unplug-delay-ms` (8 bytes)
   may override afterwards if present (it is not in our device tree).
 - handleUnplugEvent (0x55134) logs "HPD Lost, delay = %llu" from this field when non-zero.
 The headset's HPD=0 self-heals restored HPD in ~120 ms ([time redacted] -> .997). With
 `appledptx-hot_unplug_delay_ms=300` those would not reach macOS at all. Does NOT cover the IRQ_HPD/INTERLANE retrain
 mode (that path calls handleRemoveInterfaces directly). Needs a reboot; proposed boot-args:
 `amfi_get_out_of_my_way=1 hdcp-fuse-mask=0 appledptx-hot_unplug_delay_ms=300` (optionally `appledptx-max_link_rate=0x14`
 for 60 Hz-only operation).
 
 ## Milestones
 - 2026-10-20 ~[time redacted]: the stereo 3D test scene was visible inside the headset, after an automatic app
   recovery. App: captured display, native 4320x2160 @ 90 Hz, strict presented-frame telemetry 89.90 fps
   (presentAge 0.01 s, GPU 1.75 ms/frame, 0 GPU errors, 7 skipped frames at startup only). No boot-arg changes needed.
 - Display-loss detection latency in the app: 10.7 s -> 0.98 s after moving callback work to CFRunLoopPerformBlock.
 - Still open: millisecond-level continuity (candidate boot-arg appledptx-hot_unplug_delay_ms, parked), head tracking,
   lens-distortion calibration.
 - 2026-10-20 ~[time redacted]: RELIABILITY MILESTONE PASSED. 650 s no-fault soak at native 90 Hz: 89.9987 presented fps,
   skipped +3, 0 GPU errors, clean exit, zero DP resets (evidence/verified-90hz-soak.json). Fault recovery (separate
   trials): 4.4 s outage via recovery queue + DRST.
 - Factory calibration was read successfully. Measured per-unit optical geometry is omitted from this public history; the demo reads each headset at runtime.
 - Factory chromatic calibration motivated the per-channel correction pass. Per-unit measurements are omitted.
 - GPU warp check (Tests/LensWarpChecks.swift, evidence/lenswarp-gpu-checks.txt): 1632 channel samples, max error
   0.0041511 against the Double CPU model. Resolution is limited by 8-bit coordinate gradients (~12 texels per step);
   catches gross/channel-swap errors, not sub-12-texel ones; blue position is not checked.
 
 ## Factory optical correction (2026-10-20)
 
 Optical compensation is separate from head tracking. The factory store was read twice (10,737 bytes),
 and both reads matched byte for byte. The saved JSON supplies the per-eye affine transform, asymmetric field of view,
 and separate Polynomial-3K coefficients for red, green, and blue. Source: Monado WMR driver and distortion utilities;
 see DEPENDENCIES.md and LICENSES/BSL-1.0.txt for provenance.
 
 The renderer now always uses that calibration: 6048x3024 offscreen stereo rendering, then a per-color correction pass
 into native 4320x2160. The optics grid uses angular coordinates, so its straight-ahead cross agrees between eyes.
 Raw output snapshots intentionally show curved lines and separated colors: the physical lenses should cancel that
 pre-compensation. That is a software/model expectation, not proof that all observed optical defocus is corrected.
 
 Validation: offline calibration fixtures pass; the production Metal coordinate function agrees with the Double CPU
 model over 3,750 RGB coordinate pairs (max normalized error 4.574e-7). The additional end-to-end 8-bit gradient sampling
 check passes (1,632 channel samples, max error 0.004152, limited by 8-bit quantization). Asymmetric projection edges
 also pass. The 180 s calibrated hardware trial exits cleanly: 89.996 presented fps in the 160 s settled interval,
 zero display removes, one additional skipped frame, 0 GPU errors, 5.97 ms GPU/frame. Detailed results are in evidence/.
 Physical optical validation remains separate from software/model checks. Optical focus/fit and the headset's intrinsic peripheral limits
 may remain after correct geometric/chromatic compensation; do not claim blur has been eliminated based on GPU tests.
 
 Offline checks:
 ```sh
 swiftc -O Sources/VRWorkstation/Calibration.swift Tests/CalibrationChecks.swift -o /tmp/vr-calibration-checks
 /tmp/vr-calibration-checks
 swiftc -O -D LENS_WARP_CHECKS Sources/VRWorkstation/Calibration.swift Sources/VRWorkstation/LensWarp.swift Tests/LensWarpChecks.swift -framework Metal -o /tmp/vr-lenswarp-checks
 /tmp/vr-lenswarp-checks "$HOME/Library/Application Support/ReverbM1Demo/factory.json"
 ```
 
 The calibrated live build also passed a forced panel-off recovery: display ADD after 4.576 s, then the known
 0.654 s post-reset retrain healed automatically; native 90 Hz rendering resumed with no GPU errors.
 See `evidence/calibrated-recovery-trial.json` and `evidence/calibrated-recovery-live.txt`.
 The running demo logs to `/tmp/vr-calibrated-live.txt`; Q or Escape in its window quits it.
 
 ## Live optical tuning and floor-grid filtering (2026-10-21)
 
 The Mac has a Headset optics window with
 scene/white-grid/green-grid patterns, red strength, and separate horizontal/vertical blue strengths (-100% to 400%).
 100% is the original factory compensation; zero uses green geometry for that channel. The controls pass settings to
 the render worker under a lock, and debounce-save them to Application Support/ReverbM1Demo/optics-adjustments.json.
 Factory JSON remains unchanged. Green-only mode disables the color sliders. Reset restores factory color strengths.
 
 Separately, the floor's 1.5 cm geometric grid strips projected below one panel pixel at distance. They were replaced
 with one floor surface and a derivative-filtered grid in its fragment shader: minimum readable pixel footprint,
 smoothed coverage, and per-axis fading when line spacing becomes unresolved. This reduces different aliasing between
 the two eyes, but does not change the stereo view matrices. An isolated infinity-alignment target was discussed but
 has NOT been added; the white/green patterns are angular grids.
 
 Operator feedback confirmed an improvement with optical tuning. Personal adjustment values and verbatim feedback are omitted.
 Current evidence/optics-controls-live.txt shows approximately 90 presented fps and zero GPU errors.
 
 The optical tuning shader passes float-coordinate comparisons including independent blue axes; the test also retains
 the end-to-end quantized sampling check. Screenshots show pre-compensated output before the physical lenses, so they
 cannot establish the blur/fringe that reaches a user's eye. Software rendering, optical compensation, and physical
 lens/eye placement are separate contributors; do not infer a hardware defect from the remaining residuals.
 
 ## Desktop coexistence
 
 The demo uses a non-activating headset panel without exclusive display capture. Its session-only display layout places the headset to the right of other displays. The application does not change Dock preferences. Native 90 Hz rendering and clean shutdown were checked; see evidence/desktop-coexistence.txt.