ampere-fourier/phase1_goal.md

Phase 1 — Goal formulation (iter1)

Locked 2026-05-16. Phase 0 finished 30 min earlier; substrate confirms 3 codecs decode-capable on the clean kernel and 3 are blocked behind external work. This iteration locks the scope to the kernel-supported subset — chasing the 3 blockers would conflate three different debugging problems with three different teams (kernel oops fix, kernel feature add, backend iter39) into one iteration loop, which is exactly the failure mode the 8-phase process is designed to avoid.

Iter1 goal (one sentence)

Establish a rigorous, instrumented baseline that the 3 currently-kernel-supported codecs (H.264 via rkvdec, VP8 + MPEG-2 via hantro) decode end-to-end through the libva-v4l2-request-fourier (iter38b, hand-built) backend on ampere, with measurable evidence of byte-correctness and HW path engagement — so subsequent iterations chasing the 3 blocker codecs have a known-stable floor to regress against.

Resolved Phase 0 open questions

• Q1 scope: 3 codecs (H.264 + VP8 + MPEG-2). The other 3 are tracked as separate iterations (each becomes its own 8-phase loop once the kernel-agent experiment / backend iter39 produces something to test). Locking iter1 to "all 6 work" makes the iteration unclosable.
• Q2 bit-exact anchor: libva-HW vs ffmpeg -i clip … -f rawvideo nv12 SW decode of the SAME input clip. kdirect (the fresnel-side V4L2 stateless test rig) is RK3399-specific and not yet ported to RK3588's mainline rkvdec; porting it is a separate piece of work, not iter1. The SW-compare anchor is weaker than libva==kdirect (it conflates "libva backend bug" with "kernel V4L2 stateless ABI deviation from SW reference"), but it is measurable against a stable reference, which is what Phase 1 needs.
• Q3 HEVC OOPS sandboxing: deferred to the HEVC-fix iteration. Iter1 avoids HEVC entirely.
• Q4 firefox-fourier vendor defaults: in scope for iter1 as the consumer validation step — install firefox-fourier 150.0.1-5 on ampere, sweep H.264 / VP8 / MPEG-2 (skip HEVC, skip VP9, MPEG-2 expected n/a in Gecko per fresnel iter1 finding) with the empty-profile-vendor-defaults test method validated on fresnel.
• Q5 AV1 source clip: deferred — iter1 doesn't touch AV1.

Success criteria (measurable, with the Phase 3 instrument named for each)

For each of {H.264, VP8, MPEG-2}:

#	Criterion	Phase 3 instrument
C1	libva HW decode runs to completion, exit 0, frame count = clip frame count (1440 frames for 60 s @ 24 fps)	ffmpeg -hide_banner -benchmark -hwaccel vaapi -hwaccel_output_format vaapi -i $clip -vf hwdownload,format=nv12 -f rawvideo /tmp/out.nv12 ; frame= count from stderr, ls -la /tmp/out.nv12 size check (= frame_count × 1280×720 × 1.5)
C2	HW path is actually engaged, not a silent SW fallback	lsof -p $PID during decode shows /dev/video* and /dev/media* opened by the ffmpeg PID; AND strace -e trace=ioctl -p $PID shows VIDIOC_QUERYCAP / VIDIOC_S_EXT_CTRLS / MEDIA_REQUEST_IOC_QUEUE calls
C3	Decoded byte output matches SW reference at frame 0	cmp of first 1 382 400 bytes (one yuv420p 720p frame) between libva-HW /tmp/hw.nv12 and SW ffmpeg -i $clip -f rawvideo -pix_fmt nv12 -frames:v 1 /tmp/sw.nv12
C4	At frame 30 s, SSIM Y ≥ 0.99 vs SW reference (acknowledges H.264 cumulative drift per fresnel iter1)	ffmpeg -lavfi "[0:v][1:v]ssim" -f null - between the two clips at frame 720
C5	Per-codec decode FPS reported at N=3 with mean and σ. No "should be fast" — actual numbers, no recall from training or fresnel cross-host.	wall-time measurement around timeout … ffmpeg …; mean and standard deviation of 3 runs
C6	dmesg clean across the full sweep — no new oops, no new warning, no rkvdec/hantro error lines	dmesg --time-format=ctime before/after the sweep, diff'd

Plus one campaign-level criterion:

| C7 | firefox-fourier 150.0.1-5 engages HW for {H.264, VP8} via empty-profile vendor defaults (MPEG-2 expected n/a — Gecko doesn't play video/mp2t) | Empty ~/.mozilla/firefox-test/profile, autoplay page, count Got VA-API DMABufSurface and Requesting pixel format VAAPI_VLD MOZ_LOG entries |

Hypothesis

With backend 7ac934e (hand-built 0c9a7efaab…) over kernel 7.0.0-rc3-devices+, all 3 codecs satisfy C1-C6 and {H.264, VP8} satisfy C7. The basis for this prediction is fresnel iter38 close which certified the same backend on RK3399 with the same V4L2 stateless ABI surface; RK3588's mainline rkvdec + generic hantro present a similar enough surface that the libva-side code path should function identically.

The hypothesis is wrong if:

• (a) Any of the 3 codecs fails C1 (decode crash / hang / wrong frame count). Loop back to Phase 0: substrate was wrong, the codec isn't actually viable on this kernel.
• (b) Decode completes but C3 fails at frame 0 (libva-HW first-frame bytes differ from SW first-frame bytes). Loop back to Phase 2: surface a kernel-V4L2-ABI deviation on RK3588 that didn't show on RK3399 / RK3568, and characterize it before chasing per-codec tuning.
• (c) MPEG-2 C3 fails per IDCT precision tolerance (per memory feedback_mpeg2_hw_sw_idct_precision, hantro MPEG-2 is intrinsically ≤3 LSB off SW per IEEE 1180). Phase 4 must relax C3 for MPEG-2 to "SSIM Y ≥ 0.9997" instead of "byte-identical." This is a plan refinement, not a substrate failure.

Out of iter1, tracked as separate iterations

• iter2 (planned): HEVC kernel OOPS fix. Substrate-mode work; needs marfrit/kernel-agent experiment with a candidate patch for rkvdec_hevc_prepare_hw_st_rps. Open a follow-up issue against kernel-agent before iter1 closes.
• iter3 (planned): VP9 kernel enablement on RK3588 rkvdec. Substrate-mode; kernel-agent experiment with the upstream patch chain (VDPU381/383 family, per memory feedback_rkvdec_patch_reachability).
• iter4 (planned): AV1 via libva backend iter39 — third-fd probe in request.c. Pure backend work, not kernel.

Each will be Phase 0 → Phase 8 in its own right, anchored to this iter1 baseline as its reference floor.

Phase 1 close

Goal is one sentence, success is six criteria each named to a specific instrument, hypothesis is falsifiable in three named ways. Ready for Phase 2 situation analysis.