fresnel-fourier/phase8_iteration2_close.md

Iteration 2 — Phase 8 (close)

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

What iter2 fixed

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

Six bugs (per Phase 2 source-read), all in the libva backend (kernel + driver path was already proven by Phase 0 cross-validator sweep). Iter1's three-bug pattern repeated for HEVC, plus three additional bugs unique to HEVC's larger contract surface:

1. src/config.c:67 HEVCMain fall-through — case label existed but lacked break;, so vaCreateConfig(VAProfileHEVCMain) returned VA_STATUS_ERROR_UNSUPPORTED_PROFILE (12). Same iter1-Bug-1 pattern. Fix: 5-line break; (Commit A).

2. src/picture.c:204-206 HEVCMain explicit reject — case VAProfileHEVCMain: return VA_STATUS_ERROR_UNSUPPORTED_PROFILE; with stale /* Fourier-local: HEVC stripped, no HW support on RK3566. */ comment. RK3566 was ohm context; fresnel is RK3399 where rkvdec does support HEVC. Fix: replace explicit reject with dispatch to h265_set_controls() (Commit B).

3. src/h265.c used staging-era CIDs — V4L2_CID_MPEG_VIDEO_HEVC_PPS/SPS/SLICE_PARAMS removed from kernel UAPI (mainline split into 7 controls: V4L2_CID_STATELESS_HEVC_{SPS,PPS,SLICE_PARAMS,SCALING_MATRIX,DECODE_PARAMS,DECODE_MODE,START_CODE}). Test-compile rejected the old CIDs. Fix: full 588-line rewrite (Commit B).

4. HEVC slice_params is now a dynamic-array, not single-slot — kernel rkvdec advertises elems=1 dims=[600] dynamic-array. Old h265.c memcpy-overwrote the single slot per VASliceParameterBufferType arrival; multi-slice frames lost data. Fix: per-slice append to params.h265.slices[64] array in codec_store_buffer, batched dynamic-array submission in h265_set_controls (Commit B).

5. Missing controls in submission — old code submitted only PPS+SPS+SLICE_PARAMS. New API needs DECODE_PARAMS (per-frame DPB info, NEW), SCALING_MATRIX (conditional), DECODE_MODE+START_CODE (device-wide). Fix: 5-control batched per-frame submission + 2-control device-wide init in context.c (Commit B).

6. src/meson.build excluded h265.c + h265.h — left commented out from the libva-multiplanar iter5 sweep. Fix: uncomment both (Commit B).

Contract that was followed

Per feedback_dev_process.md Phase 6 contract-before-code: 10 contract clauses cited from authoritative sources, mapped 1:1 to the patch hunks (full detail in phase4_iter2_plan.md + Phase 5 review amendments in phase5_iter2_review.md):

• Linux mainline UAPI <linux/v4l2-controls.h>:2090-2300 for the 7 stateless HEVC control struct definitions, flag bit positions, and DPB entry semantics.
• FFmpeg Kwiboo branch libavcodec/v4l2_request_hevc.c:505-565 for batched submission shape and get_ref_pic_index() DPB-classification pattern.
• Linux mainline driver drivers/staging/media/rkvdec/ — NOT available for HEVC (mainline 7.1-rc2 has only h264 + vp9 in staging rkvdec; HEVC is out-of-tree per Christian Hewitt patches). Contract anchor instead leans on UAPI doc + FFmpeg + Phase 3 cross-validator bytes.
• Empirical anchor: Phase 3 Baseline B verbatim (phase0_evidence/2026-05-08/iter2_phase3/) — verbatim 5-control batched submission per frame, used to validate Phase 7 byte-compare.

What landed where

Code commits on git.reauktion.de/marfrit/libva-v4l2-request-fourier (master 229d6d1 → 8d71e20):

8d71e20 fresnel-fourier iter2 Phase 6 commit B: rewrite h265.c against new V4L2 stateless HEVC API
        (6 files, 463 insertions, 236 deletions: src/h265.c rewrite + src/picture.c
         dispatch+accumulation+reset + src/surface.h slices[64] extension + src/h265.h
         HEVC_MAX_SLICES_PER_FRAME #define + src/context.c HEVC device-init + src/meson.build
         uncomment h265.c+h265.h)
cca539d fresnel-fourier iter2 Phase 6 commit A: config.c break for HEVCMain case
229d6d1 fresnel-fourier iter1 Phase 6 commit D (libva-multiplanar tip + iter1 work)

Both iter2 commits authored as Claude (noether) per memory feedback_gitea_as_claude_noether.md.

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

05b4bd5 iter2 Phase 7: verification — all 5 criteria GREEN, third codec PASS
9eae068 iter2 Phase 5: sonnet review — 3 critical UAPI errors caught, 7 amendments
348736e iter2 Phase 4: plan — 10 contract clauses, ~400-line h265.c rewrite
d35a247 iter2 Phase 3: baselines — substrate verified post-upgrade, HEVC anchor captured
b3ba157 iter2 Phase 2: situation analysis — six bugs in HEVC path
6e8c970 iter2 Phase 0 + Phase 1 lock: HEVC Main on rkvdec

(Plus this Phase 8 close.)

Phase 1 binding-cell verification (Phase 7 verbatim)

Criterion	Result
1: vainfo VAProfileHEVCMain enumeration on rkvdec bind	✅ enumerated, no regression
2: vaCreateConfig(VAProfileHEVCMain)	✅ VA_STATUS_SUCCESS (libva trace verbatim)
3: ffmpeg-hwaccel-vaapi exit 0	✅ 5 frames, no Failed-to-create, cap_pool engaged
4: DMA-BUF GL HW=SW byte-identical (+02s)	✅ HW1=SW1=47a5f3850df5..., HW2=SW2=a467b3bc9d7b..., frames differ
5: iter1 MPEG-2 + T4 H.264 reference hashes	✅ all 4 hashes match references byte-identical

Bonus: post-fix VIDIOC_S_EXT_CTRLS payload structurally matches Baseline B cross-validator (count=5, ctrl_class=V4L2_CTRL_CLASS_CODEC_STATELESS, sizes 40/64/280/1000/328). Two informational SPS field-value divergences (sps_max_num_reorder_pics, sps_max_latency_increase_plus1) — VAAPI doesn't expose; non-blocking per Criterion 4 byte-identical pixel pass.

Lessons (for Phase 8 memory update)

The 8-phase loop ran cleanly: zero Phase 7 → Phase 4 loopbacks. Phase 5 review caught all the would-be loopback triggers in advance — 3 Critical findings (data_byte_offset rename, dpb.rps→index-arrays semantics, pic_order_cnt_val rename) that would have been Phase 6 compile failures or silent semantic bugs.

Worth a memory update

L1 — Empirical-over-theoretical applies in BOTH directions of Phase 5 review

iter1 lesson feedback_review_empirical_over_theoretical.md codified: when a Phase 5 reviewer cites a numerical mismatch, lean empirical (defer to Phase 7 byte-compare) instead of rejecting on source-read theory. iter2 surfaced the reverse direction: when a reviewer SUGGESTS a field mapping that the original plan was missing, the author should also verify the suggestion empirically before adopting.

Concretely: Phase 5 review S1 suggested picture->pic_fields.bits.uniform_spacing_flag exists in VAAPI as the source for V4L2_HEVC_PPS_FLAG_UNIFORM_SPACING. I incorporated the suggestion into the Phase 4 plan amendments without verifying. Phase 6 build failed:

../src/h265.c:224:37: error: 'struct <anonymous>' has no member named 'uniform_spacing_flag'

Test-compile would have caught it before Phase 6. The lesson generalizes the iter1 rule: empirical evidence trumps source-read theory in BOTH directions — author-rebuttals AND reviewer-suggested-amendments. The right discipline:

• Reviewer flags a numerical mismatch → defer to Phase 7 byte-compare; don't rebut on source-read.
• Reviewer suggests a field mapping → empirically verify (gcc test-compile, struct dump, kernel UAPI grep) before incorporating into the plan.

Memory action: extend the existing feedback_review_empirical_over_theoretical.md entry with this iter2-derived corollary. Keep the existing iter1 example, add the iter2 example.

Stays as campaign-internal backlog (not durable memory)

B6 — VAAPI ↔ V4L2 SPS field-fidelity gap (low-priority polish): post-iter2 SPS bytes diverge from Baseline B on sps_max_num_reorder_pics (post-fix=0, baseline=2) and sps_max_latency_increase_plus1 (post-fix=0, baseline=4). VAAPI's VAPictureParameterBufferHEVC doesn't expose these; FFmpeg parses them from the bitstream's SPS header. Non-blocking (Criterion 4 byte-identical pixel pass). Phase 8 polish-backlog candidate: add SPS bitstream parsing to h265_fill_sps to extract these fields from the slice OUTPUT buffer when VAAPI doesn't supply them. Probably low ROI — kernel HEVC handler tolerates 0 values for the BBB fixture. Defer until a real-world consumer surfaces a fixture that breaks on this.

B7 — Phase 4 plan body had a sizeof() typo: claimed sizeof(struct v4l2_ctrl_hevc_scaling_matrix) = 1296; empirical sizeof is 1000 = 96 + 384 + 384 + 128 + 6 + 2. Code uses sizeof() symbolically so produces correct bytes; only the plan body's expected-value comment was wrong. Phase 7 byte-compare's structural check caught this (plan-body number wrong, code right). Future polish: state struct sizes via sizeof() references in plan bodies, not hand-computed values; or have Phase 7 byte-compare always validate sizes via runtime sizeof.

B8 — Phase 5 amendment empirically wrong (uniform_spacing_flag): same as L1 above; documented inline in src/h265.c::h265_fill_pps. Already fixed (PPS flag bits 19+20 left zero — VAAPI doesn't expose either). Lesson is durable (L1); the bug is fixed.

Latent bugs surfaced but deferred (carryover)

iter1 B3 — picture.c:287 params.h264.matrix_set = false writes union byte 240 — for HEVC surfaces, byte 240 lands inside h265.picture (Phase 2 Bug 8 verified). RenderPicture's VAPictureParameterBufferHEVC per-frame copy overwrites the corrupted byte. Phase 7 confirmed mpv-vaapi sends VAPictureParameterBufferType per frame for HEVC (no silent filtering like vaapi-copy did for MPEG-2), so the masking holds for iter2 binding cells. Latent for VAAPI clients that reuse a surface without re-sending picture params. iter2+ Phase 4 cross-cutting backlog.

iter1 B4 — src/context.c H.264 device-init log noise on hantro — extended in iter2 Commit B with HEVC device-init in a separate batched call. New behavior on rkvdec: BOTH H.264 and HEVC device-init batches succeed (rkvdec advertises both control families). On hantro: H.264 batch EINVALs (existing noise), HEVC batch ALSO EINVALs (HEVC controls don't exist on hantro). Net: cosmetic log line might fire twice on hantro instead of once. Same intentional (void)v4l2_set_controls(...) swallow pattern; not blocking.

iter1 B5 — vbv_buffer_size 1 MB vs negotiated 1.31 MB: not exercised by HEVC (HEVC's SPS doesn't have an analogous field). MPEG-2-only.

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
iter2	HEVC (rkvdec)	✅ closed (this iteration)
iter3	VP8 (hantro)	open — implement vp8.c
iter4	VP9 (rkvdec)	open — implement vp9.c (largest control surface)
iterN	Phase 4 cross-cutting	open — vaDeriveImage cache-stale fix; V4L2 device-discovery; B3 BeginPicture profile-aware reset; B4 context.c log suppression; B5 vbv_buffer_size; B6 SPS bitstream-parse fidelity polish

Phase 8 doesn't pre-lock iter3; that's the next operator-driven moment. When iter3 opens, its Phase 0 substrate carries forward iter2's findings (especially B6, B7, B8 polish items if convenient to bundle with the VP8 work).

Predicted iter3 difficulty (VP8): smaller than iter2 (VP8 has fewer controls than HEVC). Closer to iter1 MPEG-2 in scope. Reuse the per-frame batched submission pattern; no slice_params dynamic-array (VP8 is frame-mode); no DECODE_PARAMS-equivalent (VP8 control state fits in a single v4l2_ctrl_vp8_frame struct per kernel UAPI).

Memory updates

One extension to an existing memory entry (no new files):

• Extend feedback_review_empirical_over_theoretical.md with iter2's reverse-direction example (reviewer-suggested mapping that proved empirically wrong on test-compile). Same rule, both directions.

Iteration close acknowledgement

Per feedback_dev_process.md's Phase 8: "Loop terminates here." Iteration 2 of fresnel-fourier closes here. The 8-phase loop ran end-to-end with zero Phase 7 → Phase 4 loopbacks — Phase 5 review caught all the would-be loopback triggers in advance (3 Critical UAPI errors). This is the dev-process ideal: review catches the bugs before the implementation lands; verification confirms the contract; close documents both the substrate and the lessons.

Phase 5 review value confirmed empirically. The campaign continues against the corrected memory and the 3-codec-passing scoreboard.