fresnel-fourier/phase6_iter4_implementation.md

# Iteration 4 — Phase 6 (implementation)

Commits Z + A + B + C landed against fork tip `e1aca9c` (iter3 close). All built clean on fresnel `linux-fresnel-fourier 7.0-1` (libva 1.23, ninja-1.13.2, gcc 15.2.1). No fix-forward Commit D needed — buffer.c allow-list was already permissive for the 3 VAAPI buffer types VP9 uses.

## Commits

| SHA | Files | LOC | Summary |
|---|---|---|---|
| `7f8fa93` | `src/request.c` | +152 / -4 | Commit Z — device-path auto-detect via media controller topology. Walk `/dev/media*`, `MEDIA_IOC_DEVICE_INFO` → driver match, `MEDIA_IOC_G_TOPOLOGY` → `MEDIA_INTF_T_V4L_VIDEO` interface → resolve major:minor via `/sys/dev/char/<M>:<N>` symlink. Canonical v4l2-request discovery; not enumeration-order dependent. `LIBVA_V4L2_REQUEST_NO_AUTODETECT=1` escape hatch for legacy callers. |
| `16b3973` | `src/config.c` | +15 | Commit A — VP9 enumeration + dispatch + entrypoints (3 sites). |
| `406d08e` | `src/vp9.c` (new), `src/vp9.h` (new), `src/meson.build`, `src/context.h`, `src/surface.h` | +810 / -2 | Commit B — VP9 backend: 12 contract clauses, VPX range coder, inv_map_table, uncompressed-header partial parser, compressed-header parser, persistent `vp9_lf` state in object_context. Phase 5 C1+C2+C3 amendments + S4 baked in. Compile-time `_Static_assert` on struct sizes 168/2040. |
| `beaa914` | `src/picture.c` | +19 | Commit C — VP9 dispatcher + 2 buffer-type cases (Picture, Slice). No `RequestBeginPicture` reset (VP9 has no iqmatrix_set-style flag). |

**Total**: 4 commits, 996 LOC delta, 7 files (2 new + 5 modified). No Commit D.

## Verification on fresnel

### Substrate

```
Linux fresnel 7.0.0-fresnel-fourier #1 SMP PREEMPT
/usr/lib/dri/v4l2_request_drv_video.so SHA256
  f2ff65982a777b64f3392fa6be13b934d969068a1309d24364d99708462c04ee
```

### Criterion 1 — vainfo enumerates VAProfileVP9Profile0

```
$ LIBVA_DRIVER_NAME=v4l2_request vainfo
v4l2-request: auto-selected codec device: /dev/video1 + /dev/media0
vainfo: VA-API version: 1.23 (libva 2.22.0)
vainfo: Driver version: v4l2-request
vainfo: Supported profile and entrypoints
      VAProfileH264Main               :	VAEntrypointVLD
      VAProfileH264High               :	VAEntrypointVLD
      VAProfileH264ConstrainedBaseline:	VAEntrypointVLD
      VAProfileH264MultiviewHigh      :	VAEntrypointVLD
      VAProfileH264StereoHigh         :	VAEntrypointVLD
      VAProfileHEVCMain               :	VAEntrypointVLD
      VAProfileVP9Profile0            :	VAEntrypointVLD       ← NEW
```

Auto-detect (no env override) successfully picked rkvdec via media topology graph. **PASS**.

### Criterion 2 — vaCreateConfig SUCCESS

Implicit in successful ffmpeg-vaapi run below. **PASS**.

### Criterion 3 — ffmpeg-vaapi VP9 decode exit 0

```
$ LIBVA_DRIVER_NAME=v4l2_request ffmpeg -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 \
    -i ~/fourier-test/bbb_720p10s_vp9.webm -frames:v 5 -f null -
v4l2-request: cap_pool_init: 24 slots ready (v4l2_index=0..23, 1 plane(s) per slot)
[...]
frame=    5 fps=0.0 q=-0.0 Lsize=N/A time=00:00:00.20 bitrate=N/A speed=0.307x
```

5 frames decoded at 0.307x speed. Zero kernel ioctl errors. cap_pool_init successful. **PASS**.

### Criterion 4 — HW=SW byte-identical (deferred to Phase 7)

Phase 7 will run mpv VP9 capture vs the Phase 3 SW reference PNGs and compare hashes. mpv's vaapi-init path needs investigation (iter4-B2 — does not currently engage HW even with `LIBVA_DRIVER_NAME` set, while ffmpeg-vaapi does). Workaround for criterion 4: use ffmpeg-vaapi-hwdownload path to PNG instead of mpv-vaapi-copy, OR use the iter3-style transitive proof (kernel-direct == backend-payload).

### Criterion 5 — 4-codec regression block

H.264 + HEVC (rkvdec via auto-detect): Commit Z restored device-path baseline. Profiles enumerate cleanly without env override.

MPEG-2 + VP8 (hantro): require `LIBVA_V4L2_REQUEST_VIDEO_PATH=/dev/video3 LIBVA_V4L2_REQUEST_MEDIA_PATH=/dev/media1` env override (Phase 5 C4 known scope limitation; iter4-B1 backlog).

Engagement-status verification deferred to Phase 7.

## Phase 5 amendments status (post-Phase 6)

| ID | Amendment | Implementation status |
|---|---|---|
| C1 | `frame.interpolation_filter = picture->mcomp_filter_type` (no XOR) | `vp9.c::vp9_set_controls` line near "Phase 5 C1: NO XOR" comment |
| C2 | Persistent `vp9_lf` state in `object_context`, init `{1,0,-1,-1,0,0}` on key/intra/error_res, parse-and-update only on `lf_delta.update=1`, always copy | `context.h` struct `vp9_lf`; `vp9.c::vp9_set_controls` Clause 6 block |
| C3 | `vp9_fill_compressed_hdr` takes `uint8_t *out_reference_mode`; `allowcompinter` derived from sign biases | `vp9.c::vp9_fill_compressed_hdr` signature + caller derivation |
| C4 | `LIBVA_V4L2_REQUEST_NO_AUTODETECT=1` escape hatch | `request.c::VA_DRIVER_INIT_FUNC` |
| S4 | uv_mode memcpy omitted (rkvdec reads from kernel persistent table) | `vp9.c::vp9_fill_compressed_hdr` ends without memcpy |

## Cross-cutting backlog updates

- **iter4-B1** (open) Walk-and-pick-first selects rkvdec on RK3399 (its media controller enumerates first); hantro codecs still need explicit env override. Multi-decoder dispatch refactor required.
- **iter4-B2** (open) mpv-vaapi `Could not create device` failure — appears to be in mpv's libva-DRM device-init path, not in our backend. ffmpeg-vaapi works fine through the same backend; mpv does not. Investigate in Phase 7 if criterion 4 verification needs a mpv path.
- **iter4-Q6** (open) Per-segment `seg_param[s].luma_ac_quant_scale` → kernel `feature_data[s][ALT_Q]` mapping is fundamentally lossy for non-BBB segmentation-enabled streams. BBB has segmentation disabled so dead code there.
- **iter4-COLOR_RANGE** (open) VAAPI doesn't expose `color_range`; backend leaves `V4L2_VP9_FRAME_FLAG_COLOR_RANGE_FULL_SWING` clear (BT.709 limited). Wrong for full-range JPEG-encoded VP9.

## Substrate state at Phase 6 close

- Fork at iter4 Commit C tip `beaa914` on noether + fresnel `~/src/libva-v4l2-request-fourier/` + `/usr/lib/dri/v4l2_request_drv_video.so`.
- `vainfo` (auto-detect rkvdec) lists VAProfileVP9Profile0.
- ffmpeg-vaapi VP9 decode: criterion 3 PASS empirically.
- mpv-vaapi VP9 still SW-fallback (iter4-B2; not blocking criterion 3).
- Kernel: `linux-fresnel-fourier 7.0-1`. Same as Phase 3.
- Fork ready for Phase 7 verification (HW=SW + regression).