T

claude-noether 3e996d09e2 iter1 Phase 4: plan — contract clauses, diff scope, Phase 7 harness

Phase 4 plan for the iter1 MPEG-2 fix, structured per the
feedback_dev_process.md Phase 6 contract-before-code worked example
(0012-h264-omit-scaling-matrix-frame-based.patch shape):
contract clauses with citations first, then code changes mapping
1:1 to clauses.

Phase 1 criterion #3 re-locked per Phase 3 → Phase 1 loopback:

  Original: "mpv --hwdec=vaapi-copy ... engages backend"
  Adjusted: "ffmpeg -hwaccel vaapi ... engages backend"

  Phase 3 Baseline A established mpv silently filters MPEG-2 out
  before libva is loaded; the original wording was unfalsifiable.
  ffmpeg-direct exercises the path. mpv-driven testing → separate
  follow-up task.

Other 4 criteria unchanged (vainfo regression, vaCreateConfig
SUCCESS, DMA-BUF GL pixel verify HW=SW at +02s, T4 H.264
regression).

Six contract clauses cited from authoritative sources:

  Clause 1 — Three split controls in one batched VIDIOC_S_EXT_CTRLS
    Authority: linux/v4l2-controls.h:1988-2105
    Reference impl: FFmpeg libavcodec/v4l2_request_mpeg2.c:130-155
    Empirical anchor: Phase 3 Baseline C verbatim payload

  Clause 2 — v4l2_ctrl_mpeg2_sequence layout (12 bytes)
    Authority: linux/v4l2-controls.h:2009-2017
    Field-by-field VAAPI source mapping table
    Note: progressive_frame is used as proxy for progressive_sequence
          (VAAPI doesn't expose the latter; same bit for BBB).

  Clause 3 — v4l2_ctrl_mpeg2_picture layout (32 bytes)
    Authority: linux/v4l2-controls.h:2056-2065
    reserved[5] MUST be zeroed (kernel doc 2052)
    8 picture flags decoded; field-by-field VAAPI mapping

  Clause 4 — v4l2_ctrl_mpeg2_quantisation layout (256 bytes)
    Authority: linux/v4l2-controls.h:2089-2096
    Matrices in zigzag scanning order; no permutation in libva backend
    (kernel hantro_mpeg2_dec_copy_qtable handles zigzag-to-raster)
    Decision: when iqmatrix_set is false, populate from MPEG-2 spec
    defaults (ISO/IEC 13818-2 Table 7-3) to avoid kernel rejecting
    a batch missing the QUANTISATION control.

  Clause 5 — Per-frame submission via v4l2_set_controls
    Authority: existing src/h264.c:986 pattern
    surface_object->request_fd binds controls to per-surface request

  Clause 6 — config.c MPEG-2 case must break;
    Authority: C semantics; H.264 case shape at config.c:62-63
    Empirical anchor: Phase 3 Baseline B confirmed scratch-fix shape.

Diff scope:

  src/config.c    — 3 lines added (break for MPEG-2 cases) + drop
                    stale #include <mpeg2-ctrls.h>
  src/mpeg2.c     — full rewrite of mpeg2_set_controls against new
                    split API; ~120 lines replaced; switches from
                    2× v4l2_set_control(single) to 1× batched
                    v4l2_set_controls(3-control array)
  include/mpeg2-ctrls.h — DELETE (staging-era, masks kernel UAPI)
  src/picture.c, src/context.c, meson.build — no changes
                    (verified Phase 2 + Phase 3)

Phase 6 implementation order (3 logical commits):

  Commit A: config.c break — substrate fix in isolation
  Commit B: mpeg2.c rewrite + drop mpeg2-ctrls.h includes
  Commit C: delete include/mpeg2-ctrls.h

Phase 7 verification harness (full Bash incantations included in
plan body):

  Criterion 1: vainfo MPEG-2 enumeration regression check
  Criterion 2: vaCreateConfig SUCCESS via libva trace
  Criterion 3: ffmpeg -hwaccel vaapi exit 0, no Failed-to-create
  Criterion 4: mpv --hwdec=vaapi --vo=image at +02s seek; HW=SW
               byte-identical hashes for 2 distinct frames
               (fallback to ffmpeg hwdownload if mpv-vaapi also
               filters MPEG-2; criterion holds, harness adapts)
  Criterion 5: T4 H.264 hashes still f623d5f7... and 7d7bc6f2...
  Bonus: byte-compare post-fix S_EXT_CTRLS payload vs Baseline C

Pre-identified Phase 7 → Phase 4 loopback triggers:

  1. S_EXT_CTRLS EINVAL post-fix → check pic.reserved[5] memset,
     struct sizes, flag value collisions
  2. Pixel hash mismatch → check f_code packing, field/frame
     interpretation, ref timestamps, IQ matrix order
  3. mpv-vaapi filters MPEG-2 out (same as -copy) → fall-forward
     to ffmpeg hwdownload pixel verify (criterion holds, harness
     adapts; do not redefine criterion)
  4. H.264 regression → re-locate the offending change in Bug 1
  5. Header deletion breaks unaudited consumer → git grep audit

Out of scope (LOCKED): HEVC/VP9/VP8 (later iterations); vaDerive
Image cache-stale fix; chromium-fourier 149 install; perf metrics;
long-duration stress; other MPEG-2 containers; mpv-hwdec follow-up;
context.c H.264 device-init EINVAL (auxiliary, intentional);
profile/chroma/progressive_sequence refinement; upstream engagement.

Phase 5 entry: artifacts handover (no summary, raw bundle) per
feedback_dev_process.md — phase0_findings_iter1.md,
phase2_iter1_situation.md, phase3_iter1_baseline.md,
phase4_iter1_plan.md, plus phase0_evidence/2026-05-07/iter1_phase3/.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-08 04:38:53 +00:00

phase0_evidence/2026-05-07

iter1 Phase 3: baseline measurements — Phase 2 confirmed empirically

2026-05-08 04:04:25 +00:00

.gitignore

iter1 Phase 3: baseline measurements — Phase 2 confirmed empirically

2026-05-08 04:04:25 +00:00

phase0_findings_iter1.md

iter1 Phase 0 + Phase 1 lock: MPEG-2 boolean correctness on hantro

2026-05-07 22:04:52 +00:00

phase0_findings.md

phase 0 corrections: hantro RK3399 has no H.264; substrate is iter8 master

2026-05-07 20:57:40 +00:00

phase0_recovery_2026-05-07.md

phase 0 deliverables 1-3: SDDM watchpoint, V4L2 inventory, iter8 fork smoke

2026-05-07 20:54:38 +00:00

phase2_iter1_situation.md

iter1 Phase 2: situation analysis — three bugs in MPEG-2 path

2026-05-07 22:24:50 +00:00

phase3_iter1_baseline.md

iter1 Phase 3: baseline measurements — Phase 2 confirmed empirically

2026-05-08 04:04:25 +00:00

phase4_iter1_plan.md

iter1 Phase 4: plan — contract clauses, diff scope, Phase 7 harness

2026-05-08 04:38:53 +00:00

README.md

phase 0 corrections: hantro RK3399 has no H.264; substrate is iter8 master

2026-05-07 20:57:40 +00:00

README.md

fresnel-fourier

TL;DR

Peer campaign to libva-multiplanar, targeting fresnel (Pinebook Pro / Rockchip RK3399) instead of ohm (PineTab2 / RK3566). Same deliverable shape — make libva-v4l2-request-fourier work end-to-end, for production VA-API consumers — but on a different SoC with a different (and broader) V4L2 decoder surface.

The libva backend fork itself (libva-v4l2-request-fourier) is shared: it lives at ../libva-multiplanar/libva-v4l2-request-fourier/. This campaign does not nest a second copy. Code-side work that turns out to be RK3399-specific lands either as #ifdef/runtime-detected paths inside that fork's master or, if scope diverges sharply, on a feature branch — Phase 2 source-read of each iteration decides.

Origin

libva-multiplanar reached iter5-close on 2026-05-05 with the ohm path solid: hantro (rk3568-vpu DT compatible) decodes H.264 to NV12 dmabufs end-to-end, three iterations of bugs fixed, mpv --hwdec=vaapi smooth, firefox-fourier RDD-sandboxed Firefox engages the backend without MOZ_DISABLE_RDD_SANDBOX=1, chromium-fourier 149 confirmed as the regression-check consumer.

That campaign's README explicitly names fresnel (RK3399) and ampere/boltzmann (RK3588) as "future iterations after ohm path is solid" (libva-multiplanar/README.md:87). fresnel-fourier is the formal peer campaign for the RK3399 leg of that promise.

Topology choice (LOCKED 2026-05-07): peer campaign, not child of libva-multiplanar. Each runs its own 8(+1) phase loop. Cross-link only — fresnel-fourier results do not gate libva-multiplanar's Phase 8 close (which already happened iteration-by-iteration on ohm).

Hardware target

fresnel — Pinebook Pro laptop. See reference_fresnel_kernel_constraints.md for the custom-OC-kernel discipline (don't let pacman -Syu clobber the OC DTB) and project_fresnel.md for fleet placement.

Property	Value
SoC	Rockchip RK3399 (2× Cortex-A72 + 4× Cortex-A53)
GPU	Mali-T860 MP4 (Midgard, panfrost)
Decoder block 1	rkvdec (`/dev/video3`) — H.264 + HEVC + VP9
Decoder block 2	hantro-vpu-dec (`rk3399-vpu-dec`, `/dev/video5`) — MPEG-2 + VP8 (RK3399 hantro does not advertise H.264; corrected 2026-05-07 from empirical V4L2 enumeration — see `phase0_evidence/2026-05-07/v4l2_inventory_findings.md`)
Encoder block	hantro-vpu-enc (`/dev/video4`) — JPEG only
OS	EndeavourOS-ARM (Arch derivative; same pacman + marfrit-packages mechanism as ohm)
Kernel	`linux-eos-arm 6.19.9-99` — CONFIG_FTRACE=y, CONFIG_FUNCTION_TRACER=y, CONFIG_DYNAMIC_FTRACE=y, CONFIG_TRACING=y verified 2026-05-07. No rebuild needed for trace work.

The decode-side surface area is genuinely broader than ohm. ohm has hantro (H.264 + MPEG-2 + VP8) and an rkvdec block whose mainline rkvdec2/vdpu346 driver isn't merged. fresnel has hantro (MPEG-2 + VP8 only — empirical, see correction note in the table above) plus a fully-driven mainline rkvdec covering H.264 + HEVC + VP9. So this campaign exercises codecs (HEVC, VP9) the libva-v4l2-request-fourier fork has never run on real hardware to date, and there is exactly one decoder bind for H.264 (rkvdec) — no two-block routing decision.

GPU side: panfrost on Mali-T860 (Midgard) is a different generation than ohm's Mali-G52 (Bifrost). KWin / Mesa / panfrost stack regressions or wins on T860 are not assumed to track G52 — the kwin-fourier verdict from fourier_attribution doesn't transfer for free.

Scope (LOCKED 2026-05-07 in phase0_findings.md)

In scope:

libva-v4l2-request-fourier backend exercised on fresnel V4L2 decode nodes (rkvdec + hantro-vpu-dec).
Codecs: everything decode-capable — H.264 + HEVC + VP9 (via rkvdec) + MPEG-2 + VP8 (via hantro-vpu-dec). This is the explicit broadening from libva-multiplanar's H.264-first locked scope.
Test consumers: vainfo, mpv --hwdec=vaapi, Firefox via media.ffmpeg.vaapi.enabled, chromium-fourier 149 (regression check).
Phase 1 success criterion (matching libva-multiplanar): boolean correctness — "libva accepted + providing access to hardware decoder for each codec." Performance metrics deferred.
Phase 0 task 1: recover fresnel from the SDDM greeter crash-loop (per ~/.claude/plans/dynamic-forging-piglet.md). Recovery is bookkept as substrate work inside this campaign, not as a separate prereq.

Out of scope:

Front-end libva (API library). Backend only.
Other hardware (ohm + ampere/boltzmann are libva-multiplanar's iterations).
AV1 (no decoder block on RK3399 supports it).
Performance metrics — fresnel CPU/GPU benchmarking is a separate iteration after correctness lands.
cros-codecs Rust replacement (per user_stance_rust.md).
Bootlin / Collabora upstreaming default-deferred (per feedback_no_upstream.md). Same discipline as libva-multiplanar.
KWin / panfrost / Mali-T860 work — orthogonal until proven otherwise; a parallel kwin-fourier-fresnel campaign would be a separate decision.

Process

8(+1) phase loop per feedback_dev_process.md. Phase 0 substrate is in phase0_findings.md. Phase 5 review uses the sonnet-architect subagent pattern (Plan with model: sonnet).

In-session-acquired data discipline per feedback_replicate_baseline_first.md: libva-multiplanar's ohm-side measurements are reference history, not threshold sources for fresnel-fourier cells.

Predecessor work this campaign builds on

../libva-multiplanar/ — five closed iterations on ohm. Read in order:
- README.md — current state, codec scope, file map.
- phase8_iteration5_close.md — most recent close. The iter5-end backend is the substrate fresnel-fourier starts from.
- phase0_findings.md (and phase0_findings_iter[2-5].md) — locked-scope precedent for codec breadth and consumer matrix on ohm; useful frame-of-reference when locking fresnel-side scope.
- phase8_iteration1_close.md — iter1 surface-export DMA-BUF lifecycle race + multi-resolution cache + 64-pitch alignment bugs. Likely re-surface candidates on RK3399.
../libva-multiplanar/libva-v4l2-request-fourier/ — the fork itself. 12 commits ahead of bootlin tip plus iter1..iter5 work. git log for the actual landing record.
~/.claude/plans/dynamic-forging-piglet.md — fresnel SDDM greeter crash diagnosis + recovery plan. Phase 0 task 1 picks up from here.
~/src/fourier_attribution/ — ohm-only attribution matrix. The chromium-fourier WHEAT-but-fragile verdict and Cell E (vanilla Chromium 149 control) item are ohm-side context, not fresnel data.

External reference (carry-over from libva-multiplanar):

Mozilla bug 1833354 / 1965646 (Firefox HW decode on RK35xx via libva-v4l2-request).
Bootlin upstream bootlin/libva-v4l2-request — dormant since 2021.
Linux kernel drivers/staging/media/rkvdec/ — RK3399 rkvdec H.264/HEVC/VP9 control protocol reference.
Linux kernel drivers/media/platform/verisilicon/hantro_* — RK3399-vpu-dec MPEG-2/H.264/VP8 control protocol reference.

Repository layout

~/src/fresnel-fourier/                     <- this campaign (its own git repo)
├── README.md                              <- this file
├── phase0_findings.md                     <- locked research question + Phase 0 work list
├── (worklist.md, phase[2-8]*.md as phases land)
└── (the libva fork is NOT here — see ../libva-multiplanar/libva-v4l2-request-fourier/)

The campaign repo and the fork repo stay separate. fresnel-fourier commits its findings here; code changes to the backend land on the fork's master (or a branch named per the iteration if scope diverges from libva-multiplanar's ohm-side master).

Operator-facing repo URL: git.reauktion.de/marfrit/fresnel-fourier — created empty during scaffolding, no push until first iteration finds something worth publishing.

Non-upstreaming default

Inherited from libva-multiplanar / feedback_no_upstream.md. Patches must be aligned to upstream in syntax and semantics; PR/MR/bug-report only on explicit operator instruction.

Build infrastructure

distcc/cross-build path is the existing fleet: aarch64crosscompiler LXD on data, tesla LXD on hertz, dcc1 on dcw3. See reference_distcc_kernel_builds.md for invocation. Per the locked Phase 0 answer for libva-multiplanar (item 9), no distcc for libva builds — libva is small and links fast, hand-build on fresnel directly. Same default applies here unless a specific reason emerges.

For chromium-fourier 149 / firefox-fourier rebuilds against fresnel-side findings, the boltzmann LXD container path from libva-multiplanar iter3 is reusable.

README.md Unescape Escape

fresnel-fourier

TL;DR

Origin

Hardware target

Scope (LOCKED 2026-05-07 in phase0_findings.md)

Process

Predecessor work this campaign builds on

Repository layout

Non-upstreaming default

Build infrastructure

README.md