iter9 Phase 4: α-7 implementation contract — monotonic per-context counter

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-13 13:27:40 +00:00
parent fa771b0625
commit 4832ffc401
1 changed files with 57 additions and 0 deletions
@@ -0,0 +1,57 @@
+# Iteration 9 — Phase 4 (plan)
+
+The Phase 0 doc lays out α-7 in detail. Phase 4 just locks the implementation contract for Phase 6.
+
+## Implementation contract
+
+**File**: `src/picture.c::RequestEndPicture` (line 440 area).
+
+**Change**: replace
+```c
+gettimeofday(&surface_object->timestamp, NULL);
+```
+with a monotonic per-context counter that produces small ns values.
+
+**State storage**: `driver_data->timestamp_counter` (u64). Init to 0 wherever `request_data` is first set up (likely `request.c::v4l2_request_init`).
+
+**Counter cadence**: increment by `1` (just enough to keep each frame's timestamp unique). For 3-frame test: ts will be 0, 1, 2 — followed by `v4l2_timeval_to_ns` returning `0`, `1000` (since 1 µs = 1000 ns), `2000` ... wait, `struct timeval` is sec + usec. Mapping a counter to timeval:
+
+```c
+driver_data->timestamp_counter++;
+surface_object->timestamp.tv_sec = 0;
+surface_object->timestamp.tv_usec = driver_data->timestamp_counter;
+```
+
+This gives `tv_usec=1,2,3,...` → `v4l2_timeval_to_ns(tv) = tv_usec * 1000 = 1000, 2000, 3000, ...`. Matches kdirect's `0x2af8 = 10968` style.
+
+For long runs (>~71 minutes at 1000 fps), tv_usec wraps. Each wrap is a uniqueness collision risk. Mitigation: increment tv_sec on wrap. Code:
+
+```c
+driver_data->timestamp_counter++;
+surface_object->timestamp.tv_sec = driver_data->timestamp_counter / 1000000;
+surface_object->timestamp.tv_usec = driver_data->timestamp_counter % 1000000;
+```
+
+This is collision-free for u64 / 1e6 ≈ 5.84 × 10^11 seconds = ~18,500 years of decode. Future-proof.
+
+LOC: ~10 (counter init in request.c + 4-line replacement in picture.c + new field in request.h).
+
+## Verification (Phase 7)
+
+1. Build + install on fresnel.
+2. Run libva H.264 sweep. Hash against kdirect's `1e7a0bc9…`.
+3. Re-strace and confirm DPB.reference_ts is now small (~1000-3000) matching kdirect's pattern.
+4. Run 5-codec regression sweep. All 4 non-H.264 anchors must hold.
+
+## Risks recap (from Phase 0)
+
+- R-1 uniqueness: counter wraps in 18,500 years — non-issue.
+- R-2 regression on VP9/MPEG-2/HEVC/VP8: change is uniform across codecs; same path. VP9/MPEG-2 currently PASS — switching to counter should be neutral or improve.
+- R-3 consumer reads ts as wallclock: VAAPI surfaces don't expose timestamps to consumers.
+
+## Phase 5 review
+
+Quick review by the same reviewer agent. Key questions:
+- Does any other backend code read `surface_object->timestamp` as a real wallclock?
+- Does the V4L2 framework do anything weird with `timeval` vs `u64 ns` conversion that could cause libva's gettimeofday-based ts and DPB.reference_ts to actually differ at the kernel observation point? (Critical for M-C hypothesis.)
+- Is there an even simpler reason giant ns fail — e.g., a 32-bit truncation in the V4L2 buffer struct itself?