libva-multiplanar/phase0_findings_iter7.md

# Phase 0 — iteration 7 substrate (libva-multiplanar campaign)

Opened 2026-05-06 immediately after iter6 close. iter6 closed GREEN with a single architectural fix (per-OUTPUT-slot request_fd binding via REINIT, fork commit `a09c03c`) that resolved the merged A∪I scope. Both candidate I (Firefox VIDIOC_QBUF EINVAL) and candidate A (cap_pool resolution-change race) closed in the same fix; the resolution-change race was organically exercised by YouTube's quality-renegotiation `cap_pool_init` events (4 events on a ~95s YT avc1 run, all clean).

Operator's primary goal — Firefox HW decode of YouTube avc1 on PineTab2 — is now MET end-to-end. Remaining campaign work is polish, formal verification, and upstream-prep.

## Predecessor close-out summary (iteration 6 → iteration 7)

iter6 landed a single fork commit:

- `a09c03c` — per-OUTPUT-slot request_fd binding via `MEDIA_REQUEST_IOC_REINIT`. Replaces iter4's `385dee1` close+`media_request_alloc`-per-frame model. Pool size 4 → 16. Slot owns the fd, surface borrows. iter4's case-against-REINIT was confirmed to be a DPB-payload confounder (since fixed in `74d8dd1`).

iter6 dropped MPEG-2 from the carry list (CPU handles it fine on RK3568).

iter6 carried into iter7:
- **msync pixel-correctness verification** (carry from iter5 Phase 5 sonnet C3)
- **Slot-leak error recovery** (iter6 internal carry — `request_pool_force_release` for the rare case where REINIT or DQBUF fails mid-cycle)
- **Probe-pattern test harness for cap_pool race** (carry from iter5 sonnet C4 — race is organically exercised by YT but a synthetic test would anchor the claim formally)
- **WiFi-IRQ frame drops** (out-of-campaign system concern; flagged but not on iter7 scope)

## Iteration 7 candidate research questions

### A. msync removal pixel-correctness verification (carried from iter5 Phase 5 sonnet C3)

> Confirm decoded frames are byte-identical (or visually-correct-and-deterministic) post-iter5-sweep, after `msync(MS_SYNC | MS_INVALIDATE)` was removed alongside the iter1 patch-0010 hex-dump diagnostic.

**Plan**: 100-frame `vaapi-copy` run on `bbb_1080p30_h264.mp4`, capture md5/sha of each decoded YUV plane, compare against (a) iter1 baseline (msync-present), (b) FFmpeg software decode reference, (c) iter5-end baseline.

**Risk**: low. If frames diverge, msync goes back in. If frames match, formally close iter5 sonnet C3.

**Effort**: 1-2 hours including writing the frame-hash harness.

### B. Slot-leak error recovery (iter6 internal carry)

> Add `request_pool_force_release(pool, slot_index)` that REINITs the slot's fd and clears `busy=true`, callable from RequestSyncSurface error paths.

Currently when REINIT or DQBUF fails mid-cycle, the slot stays busy=true until `RequestTerminate`. With pool=16 and rare errors this is bounded, but it's a slow leak that sould eventually starve acquire under sustained-error scenarios.

**Plan**: add `request_pool_force_release` to request_pool.{c,h}. Call from surface.c error paths. Verify with a fault-injection harness (return `-EBUSY` from REINIT in some test scenario).

**Risk**: low — additive function, doesn't change happy path.

**Effort**: 1 hour code + smoke test.

### C. Probe-pattern test harness for cap_pool race (iter5 sonnet C4 / iter6 candidate A formal-anchor)

> Write a synthetic test program that exercises the `vaCreateSurfaces(small) → vaCreateSurfaces(big)` resolution-change pattern that originally triggered REQBUFS-EBUSY. Confirms iter6's REINIT discipline holds the cap_pool race closed in a deterministic-repro form, not just organically via YT.

**Plan**: 50-line C program using libva: open device, create context, create 4 surfaces at 128×128, vaPutSurface noop, destroy, create 4 surfaces at 1920×1080, decode bbb's first I-frame, sha256 the output. No EBUSY events expected in driver stderr.

**Risk**: low. Test harness only; doesn't change driver.

**Effort**: 2-3 hours including writing test, fixturing bbb's first I-frame as raw H.264 NAL.

### D. Bootlin / Mozilla upstreaming prep (carried from iter3 candidate G + iter4 + iter5 + iter6)

> File the firefox-fourier patch with Mozilla Bugzilla (bug 1833354 / 1965646 reference for V4L2 stateless analogue). File libva-v4l2-request fork's iter1-iter6 patch series with bootlin's libva-v4l2-request maintainer (Paul Kocialkowski) as a coherent series.

**Plan (Mozilla)**: Bugzilla account, write up "V4L2 stateless decoders blocked by RDD+Utility sandbox" with reproducer, attach combined 160-line patch.

**Plan (bootlin)**: structure the iter1-iter6 commits as a clean patch series. Possibly squash some of iter5's instrumentation-removal commits with their original patch landings. Address upstream concerns about per-call diagnostics that survived as `request_log` lines.

**Risk**: socially-mediated. Maintainer may push back on architectural decisions; per `feedback_no_upstream.md` no PR/MR happens without explicit operator instruction.

**Effort**: bug filing 2-4 hours; patch-series prep 4-8 hours.

### E. Performance binding cell (carried from iter1+2+3+4+5+6)

> Anchor measured numbers for the four primary consumer paths: mpv-vaapi DMA-BUF, mpv-vaapi-copy, Firefox-fourier HW, SW baseline. Drop count, CPU%, frame timing, GPU freq, on bbb_1080p30. Reproducible from a documented script.

**Plan**: shell script that runs each consumer for 30s, captures `pidstat -u -p <PID>`, reads `/sys/class/devfreq/fde60000.gpu/cur_freq`, parses mpv stats / Firefox `about:processes`. Generate a markdown table. Carried five iterations now.

**Risk**: low. Measurement only.

**Effort**: 3-4 hours including script + run + table.

### F. V4L2_MEMORY_DMABUF (carried from iter2+3+4+5+6)

> Replace V4L2_MEMORY_MMAP with userspace dma-buf allocation for the OUTPUT pool. Architectural fix for the iter2 cap_pool race (statistical / LRU mitigation now superseded by iter6's REINIT discipline, but DMABUF is structurally cleaner).

**Risk**: highest unknown of any candidate. Possibly requires kernel work. Hantro on this kernel may not accept DMABUF on OUTPUT.

**Effort**: 1-3 days, possibly more.

### G. WiFi-IRQ frame drops (NEW from iter6, out-of-campaign-scope flagged)

> ohm shows visible frame drops during YouTube playback whenever the brcm/iwlwifi driver does heavy IRQ work. Decode pipeline is fine; presentation schedule slips.

**Stance**: out of campaign scope (system-level concern, not a libva-multiplanar bug). Listed here because operator surfaced it during iter6 verification. If desired, separate investigation into IRQ affinity, GRO offload, network-stack buffer settings.

### H. fourier-fresnel campaign (carried from iter5 followon-campaigns memory)

> Open the `fourier-fresnel` campaign — port `libva-v4l2-request-fourier` from ohm RK3568 to fresnel RK3399 (Pinebook Pro). Validates generality of iter1-iter6 fixes on a second hardware target.

**Stance**: separate top-level campaign, not an iter7 candidate. Charter at `~/src/fourier-fresnel/` once opened. iter5 memory entry `project_followon_campaigns.md` records sequencing: fourier-fresnel before panvk-bifrost.

### I. panvk-bifrost campaign (carried from iter5 followon-campaigns memory)

> Charter at `~/src/panvk-bifrost/` already exists as document-only. Sequenced after fourier-fresnel.

**Stance**: separate top-level campaign.

### Recommended pairings

- **A + B** (msync verify + slot-leak fix) — both small, both formally close iter6's carry items. Tightest scope.
- **A + C** (msync verify + cap_pool race harness) — formally closes the two iter5 sonnet caveats. Mid scope.
- **A + B + C** — closes all three internal carry items in one iteration. Reasonable upper bound.
- **D alone** — gated on operator instruction. Big effort but the campaign's culmination.
- **E alone** — anchors campaign-wide claims to numbers. Carried six iterations now.
- **F alone** — high-risk architectural.

**Recommended primary**: **A + B + C** — closes all three internal carry items, leaves D/E/F for iter8+ depending on whether operator wants the upstream-filing iteration first or the perf-anchor iteration first.

**Alternative**: **D alone** if operator wants to make iter7 the upstream-prep / external-filing iteration. Carries political weight (Mozilla + bootlin) but minimal new code.

## State that carries (re-verified iter6 close)

- **Hardware**: ohm RK3568 hantro G1/G2, kernel 6.19.10. Access: `ohm` (LAN). VPN currently flaky.
- **Userspace**: firefox 150.0.1-1.1 (iter5 amendment), libva 2.23.0, mesa 26.0.5, libdrm 2.4.131, mpv 0.41.0-3.
- **Driver installed**: `/usr/lib/dri/v4l2_request_drv_video.so` sha256 `ebe396d55104dbfedfa1065232d7f1959c519b4afe6fe33f46c1b9af13465ed6` (iter6-end, REINIT discipline + pool=16).
- **Test fixture**: bbb_1080p30_h264.mp4 sha256 `dcf8a7170fbd...`.
- **Build container**: firefox-fourier LXD on boltzmann, persistent.
- **Diagnostic instrument**: `/home/mfritsche/iter6-fork-dx/` on ohm — full fork tree with ITER6_DX log instrumentation, can be reactivated for iter7 candidate B fault-injection or candidate C harness wiring.

## State that does NOT carry

- iter6 telemetry logs are tmpfs-volatile.
- Original iter6-DX driver binary backed up at `/home/mfritsche/v4l2_request_drv_video.so.iter5end.bak` (iter5-end pre-iter6); the iter6-DX with diagnostics is at `/home/mfritsche/iter6-fork-dx/build/src/v4l2_request_drv_video.so` if needed for re-instrumentation.

## Tooling and measurement-instrument inventory

Same as iter6. Plus for new candidates:

- For A (msync verify): `vaapi-copy` already produces NV12 output to mpv's vo=null path. Add an mpv `--frames=N --o=output.yuv` script to capture raw YUV; sha256 each frame. FFmpeg's `ffmpeg -i bbb -vframes N output_%d.yuv` provides the SW reference.
- For B (slot-leak): synthesize a fault-inject by adding a debug toggle in surface.c that returns `-EBUSY` from REINIT after N frames; observe pool starvation, then add force_release and verify recovery.
- For C (cap_pool harness): write a 50-line libva test program. Reuse driver_data inspection from iter5 Track E test pattern.
- For D (upstream): no new tooling; existing patch series live in `firefox-fourier/` and the fork's git log iter1-iter6.
- For E (perf): `pidstat -u`, `/sys/class/devfreq/fde60000.gpu`, mpv stats overlay, Firefox `about:processes`.
- For F (DMABUF): kernel docs `Documentation/userspace-api/media/v4l/buffer.rst`, hantro driver source `drivers/staging/media/hantro/`.

## In-scope (LOCKING DEFERRED — Phase 1 user input)

To be locked at Phase 1 from candidates A..F above. G is out-of-campaign-scope. H, I are separate top-level campaign decisions, not iter7 candidates.

## Out-of-scope (LOCKED 2026-05-06 for iteration 7)

- iter6-completed work (per-slot REINIT discipline) — done.
- iter5-completed work (Track A sweep, Track G PGO rebuild, Track E multi-context, Track B mpv libplacebo) — done.
- iter5 amendment (Utility seccomp / Firefox-fourier sandbox) — done.
- iter4-completed work (Track A frame-11 EINVAL fix) — done.
- iter3-completed work (Track F sandbox patch) — done in firefox-fourier; upstream filing is iter7 candidate D.
- New codecs OUTSIDE H.264 (VP8/VP9/AV1/HEVC out per iter1 lock; MPEG-2 dropped at iter6 close).
- New target hardware (fresnel, ampere) — separate campaigns (H, I above).
- WiFi-IRQ frame drops — system-level, not libva-multiplanar.

## Phase 1 success criterion (will lock after user picks candidate)

Pre-lock template:
- For candidate A: "100-frame `vaapi-copy` produces frame hashes matching either FFmpeg SW baseline (preferred) or iter1 baseline (if msync-removal causes any divergence). If divergence, msync restored and verified."
- For candidate B: "Synthetic fault-injection (REINIT returns -EBUSY after N frames) demonstrates pool starvation pre-fix; post-fix demonstrates `request_pool_force_release` reclaims the slot and decode resumes."
- For candidate C: "Synthetic test program issues `vaCreateSurfaces(small)` then `vaCreateSurfaces(big)` then decodes bbb's first I-frame; driver stderr has zero REQBUFS-EBUSY events; output frame sha matches FFmpeg SW reference for that I-frame."
- For candidate D: "Mozilla Bugzilla bug filed with combined 160-line patch attached, references bug 1833354/1965646. Bootlin patch series prepared as a clean iter1-iter6 sequence on a separate branch, ready to send (no PR until operator OK)."
- For candidate E: "Anchored perf table for {mpv vaapi DMA-BUF, mpv vaapi-copy, Firefox-fourier HW, SW baseline} across drop count + CPU% + frame timing + GPU freq on bbb_1080p30. Reproducible from documented script."
- For candidate F: "vaapi-copy + vaapi --vo=null still produce real frames with V4L2_MEMORY_DMABUF-backed OUTPUT buffers; race window architecturally closed."

## Stop point

**Phase 1 lock requires user input** — pick from A..F (and any pairing).

Recommended primary: **A + B + C** — closes all three internal carry items, leaves D/E/F for iter8+ depending on whether operator wants upstream-filing or perf-anchor next.

Alternative leans:
- **D alone** if operator wants the upstream-prep iteration now
- **E alone** if perf measurement matters more than carryover-closure
- **F alone** if architectural cleanliness drives the next iteration

After lock, iter7 phases 2..8 proceed autonomously per "Stop only if user is needed."