fresnel-fourier/phase8_iteration1_close.md

Iteration 1 — Phase 8 (close)

Iteration 1 of the fresnel-fourier campaign closes 2026-05-08 with all five Phase 1 boolean-correctness criteria green. Second codec passes: campaign scoreboard advances 1/5 → 2/5 (H.264 from T4, MPEG-2 from iter1).

What iter1 fixed

MPEG-2 hardware-accelerated decode on Rockchip RK3399 / hantro-vpu-dec / libva-v4l2-request-fourier — bit-exact correct against software reference, when read via the cache-coherency-safe DMA-BUF GL import path.

Three independent bugs (per Phase 2 source-read), all in the libva backend (kernel + driver path was already solid per Phase 0 cross-validator sweep):

1. src/config.c:55-69 fall-through to default: — MPEG-2 case labels existed but lacked break;, so vaCreateConfig(VAProfileMPEG2Main) returned VA_STATUS_ERROR_UNSUPPORTED_PROFILE (= 12). Fix: 5-line break; addition.

2. src/mpeg2.c used staging-era UAPI — V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS (= V4L2_CID_MPEG_BASE+250 = 0x9909fa) and the combined slice_params struct. Mainline kernel removed these in favor of the split V4L2_CID_STATELESS_MPEG2_{SEQUENCE,PICTURE,QUANTISATION} (= 0xa409dc/dd/de) with three separate control structs. Fix: full rewrite (~120 lines) against the new API; one batched VIDIOC_S_EXT_CTRLS count=3 per frame matching FFmpeg's libavcodec/v4l2_request_mpeg2.c:130-155 reference.

3. include/mpeg2-ctrls.h was the staging-era local header — masking the kernel's modern <linux/v4l2-controls.h> definitions. Fix: delete the local header. (Required dropping #include from THREE files — src/config.c:37, src/mpeg2.c:38, and src/context.c:42. Phase 2 grep audit only found the first two; Commit D fix-forward caught the third.)

Contract that was followed

Per feedback_dev_process.md Phase 6 contract-before-code, citations from authoritative sources, mapped 1:1 to the patch hunks (full detail in phase4_iter1_plan.md Clauses 1–6):

• Linux mainline UAPI: include/uapi/linux/v4l2-controls.h:1985-2105 for the new MPEG-2 stateless control IDs, struct layouts, and flag macros.
• FFmpeg Kwiboo branch: libavcodec/v4l2_request_mpeg2.c:130-155 for the batched submission shape (3 v4l2_ext_control entries, single VIDIOC_S_EXT_CTRLS).
• Linux mainline driver: drivers/media/platform/verisilicon/hantro_mpeg2.c::hantro_mpeg2_dec_copy_qtable — confirms zigzag-to-raster permutation is kernel-side; libva backend's quantisation matrices stay in zigzag order (no permutation in userspace).
• Empirical anchor: Phase 3 Baseline C (phase0_evidence/2026-05-07/iter1_phase3/baseline_C_xvalidator/) — verbatim 256-byte QUANTISATION payload from ffmpeg-v4l2request decode of the BBB MPEG-2 fixture, used for byte-by-byte transcription of mpeg2_default_intra_matrix[64] (per Phase 5 S3 amendment that flagged spec-recall as unreliable).

What landed where

Code commits on git.reauktion.de/marfrit/libva-v4l2-request-fourier:

229d6d1 fresnel-fourier iter1 Phase 6 commit D: drop missed mpeg2-ctrls.h include from context.c (fix-forward)
3aab187 fresnel-fourier iter1 Phase 6 commit C: delete staging-era include/mpeg2-ctrls.h
5fe873c fresnel-fourier iter1 Phase 6 commit B: rewrite mpeg2.c against new V4L2 stateless API
e7dad7a fresnel-fourier iter1 Phase 6 commit A: config.c break for MPEG-2 cases
65969da iter8 Phase 4: tests/run_perf_binding_cell.sh — perf binding cell harness  (libva-multiplanar tip)

All four commits authored as Claude (noether) per memory feedback_gitea_as_claude_noether.md.

Campaign documents on git.reauktion.de/marfrit/fresnel-fourier:

ec9133a iter1 Phase 7: verification — all 5 criteria GREEN, second codec PASS
0e2e1c2 iter1 Phase 5: sonnet-architect review — 6 findings, 4 amendments
3e996d0 iter1 Phase 4: plan — contract clauses, diff scope, Phase 7 harness
cc55a6e iter1 Phase 2: situation analysis — three bugs in MPEG-2 path
b9625af iter1 Phase 3: baseline measurements — Phase 2 confirmed empirically
f720c77 iter1 Phase 0 + Phase 1 lock: MPEG-2 boolean correctness on hantro

(Plus campaign Phase 0 setup commits + this Phase 8 close.)

Phase 1 binding-cell verification (Phase 7 verbatim)

Criterion	Result
1: vainfo MPEG-2 Simple+Main enumeration	✅ both profiles with VAEntrypointVLD
2: vaCreateConfig(VAProfileMPEG2Main)	✅ VA_STATUS_SUCCESS (libva trace verbatim)
3: ffmpeg-hwaccel-vaapi engages, exit 0	✅ 5 frames, exit 0, no Failed to create decode configuration
4: DMA-BUF GL HW=SW byte-identical (+02s)	✅ HW1=SW1=6e7873030dbf..., HW2=SW2=ccc7ce08810d..., frames differ
5: T4 H.264 reference hashes match	✅ HW + SW frames match f623d5f7... and 7d7bc6f2...

Bonus: post-fix VIDIOC_S_EXT_CTRLS payload structurally matches Baseline C cross-validator (count=3, ctrl_class=0xf010000=V4L2_CTRL_CLASS_CODEC_STATELESS, sizes 12/32/256, QUANTISATION intra_matrix bytes byte-identical). One numerical divergence in vbv_buffer_size (1 MB post-fix vs 1.31 MB cross-validator) — kernel-ignored informational field, non-blocking.

Lessons (for Phase 8 memory update)

The 8-phase loop caught five lessons worth distilling. Three become durable memory entries (next section); two stay as campaign-internal backlog notes.

Worth a memory entry

L1 — Header deletion: completeness check is git rm + clean rebuild, not grep alone.

Phase 2 source-read used git grep "mpeg2-ctrls.h" to enumerate include sites. The grep returned src/config.c:37 and src/mpeg2.c:38 — Phase 4 plan and Commit B + C scope expanded only those two files. After Commit C (git rm include/mpeg2-ctrls.h), the build broke on src/context.c:42 — a third include the grep had missed (most likely because of grep tooling quirk + my path filtering). Cost: one fix-forward commit (D) and a moment of confused debugging.

Rule: when removing a header, schedule git rm during the patch series and verify with a clean rebuild. The compiler enumerates includes authoritatively; grep is best-effort. Memory entry: feedback_header_deletion_check.md.

L2 — When the Phase 5 reviewer flags a numerical discrepancy, lean empirical, not theoretical.

Phase 5 reviewer's S2 finding said: "post-fix vbv_buffer_size will be SOURCE_SIZE_MAX (1 MB), Baseline C shows 0x151800 (1.31 MB) — discrepancy unexplained." I responded with confident source-read reasoning that slot->size = sizeimage = 1382400 ergo equality holds, and rejected the finding. Phase 7 byte-compare empirically showed: post-fix produces 1 MB, NOT 1.31 MB. The reviewer was numerically right; my source-read was wrong (the actual slot->size resolution path doesn't equal the negotiated sizeimage in our backend's S_FMT setup).

Operational impact: nil (kernel ignores vbv_buffer_size per the doc). But the historical record of "I rejected this finding with the wrong reason" is itself the lesson.

Rule: when a reviewer cites a concrete numerical mismatch between two captured payloads, run the empirical byte-compare in Phase 7 BEFORE rejecting on source-read grounds. Source-read can have gaps; verbatim-vs-verbatim comparison can't lie. Memory entry: feedback_review_empirical_over_theoretical.md.

L3 — On RK3399 (and Rockchip in general?): vaDeriveImage cache-stale bug class is real and codec-agnostic.

Both H.264 (T4) and MPEG-2 (iter1) decode paths produce all-zero NV12 when read via libva's vaDeriveImage + cached mmap (the path that ffmpeg-vaapi + hwdownload uses). The kernel + driver decode is correct (verified by ffmpeg-v4l2request DRM_PRIME path producing matching pixels to SW reference). The bug is in the libva backend's image-export — same iter1 patch-0011 bug class observed on RK3568 (ohm) but pre-fixed there.

Rule: pixel verification on Rockchip platforms must use the DMA-BUF GL import path (mpv --vo=image or equivalent), NEVER the cached-mmap readback path. Treat ffmpeg-vaapi+hwdownload's correct-pixel guarantee as suspect on these SoCs until backend gains VIDIOC_EXPBUF + DMA_BUF_IOCTL_SYNC support. Memory entry: feedback_rockchip_pixel_verify_path.md.

Stays as campaign-internal backlog (not durable memory)

B1 — V4L2 /dev/videoN numbering shuffles across reboots on RK3399. Phase 0/3 had rkvdec=video3+media1, hantro=video5+media2; this boot has rkvdec=video1+media0, hantro=video3+media1. Hardcoded env-var paths in Phase 1 binding cells are fragile. Backend should probe /dev/media* for driver=hantro-vpu/rkvdec rather than rely on env var stability. Iter2+ Phase 4 cross-cutting candidate.

B2 — mpv --hwdec=vaapi-copy silently filters MPEG-2 out before libva is loaded. mpv's hwdec policy or ffmpeg-mpv glue layer rejects MPEG-2 from the vaapi-copy candidates, so the binding cell never engaged the libva backend. mpv --hwdec=vaapi (DMA-BUF, not -copy) DOES engage. Phase 1 criterion 3 anchored on ffmpeg-direct as a result; mpv-vaapi-copy-MPEG-2 is a separate follow-up task (mpv-side investigation, possibly an --hwdec-codecs filter override).

Latent bugs surfaced but deferred

B3 — src/picture.c:287 params.h264.matrix_set = false writes byte 240 of the surface's params union, which (per offsetof verification on fresnel via gcc + libva) lands inside mpeg2.iqmatrix.chroma_intra_quantiser_matrix[20]. For ffmpeg-vaapi-driven flows this byte is overwritten by the per-frame VAIQMatrixBufferType (which codec_store_buffer:140-146 copies wholesale). For VAAPI clients that reuse a surface without re-sending the IQMatrix on every cycle, the corruption persists. Latent bug; not exercised by iter1's binding cells. Iter2+ candidate — the fix is making the BeginPicture matrix_set reset profile-aware, or simpler memset(&params, 0, sizeof params).

B4 — src/context.c:142-155 H.264 device-init runs unconditionally on every CreateContext regardless of profile. Returns EINVAL on hantro-vpu-dec (which has no H.264 controls). Intentional best-effort behavior — return cast to (void) and discarded — but src/v4l2.c:484: request_log("Unable to set control(s): %s\n", strerror(errno)) still fires unconditionally, so every MPEG-2 decode session prints v4l2-request: Unable to set control(s): Invalid argument once at init. Cosmetic only; iter2+ cleanup candidate (suppress the log when caller intent is best-effort silent fail).

B5 — vbv_buffer_size = SOURCE_SIZE_MAX = 1 MB rather than the kernel-negotiated sizeimage. Informational field, kernel ignores. Low-priority post-iter1 polish.

What's next (campaign roadmap)

Per phase0_evidence/2026-05-07/cross_validator_traces.md suggested ordering, the campaign now has:

Iter	Codec	Status
iter1	MPEG-2 (hantro)	✅ closed (this iteration)
iter2	HEVC (rkvdec)	open — re-enable h265.c in build, audit against rkvdec kernel contract
iter3	VP8 (hantro)	open — implement vp8.c
iter4	VP9 (rkvdec)	open — implement vp9.c (largest kernel control surface)
iterN	Phase 4 cross-cutting	open — vaDeriveImage cache-stale fix; V4L2 device-discovery; B3-B5 polish

Phase 8 doesn't pre-lock iter2; that decision is the next operator-driven moment. When iter2 opens, its Phase 0 substrate carries forward iter1's findings (especially B3-B5 if those iterations risk exercising them).

Memory updates (next section)

Three new memory entries land alongside this close:

• feedback_header_deletion_check.md (L1)
• feedback_review_empirical_over_theoretical.md (L2)
• feedback_rockchip_pixel_verify_path.md (L3)

Plus an update to phase5_iter1_review.md to acknowledge S2 was numerically right (the historical-record correction).

Plus update to MEMORY.md index.

Iteration close acknowledgement

Per feedback_dev_process.md's Phase 8: "Loop terminates here." Iteration 1 of fresnel-fourier closes here. The 8-phase loop ran once end-to-end, no Phase 7 → Phase 4 loopbacks needed (one Phase 6 → Phase 4 mid-implementation surface for Commit D fix-forward). Phase 5 sonnet review caught two amendments worth landing (S3, Q4) plus one finding (S2) my response was wrong about. The campaign is on track.