# Phase 0 — substrate for iter11

Opened **2026-05-20** after iter10 effectively closed (the published package stays at iter9 — `mesa-panvk-bifrost-26.0.6.r2-1`; iter10's path-change polish was withdrawn locally).

## Locked research question — iter11

> **Get Brave's GPU process to engage VAAPI hardware video decode on PineTab2 (via libva-v4l2-request-fourier's `v4l2_request` driver), while preserving the iter9 Vulkan compositor path. Verify: `chrome://gpu` reports "Video Decode: Hardware accelerated" for at least one codec; a YouTube H.264 1080p30 video plays smoothly; CPU usage stays low during playback (proving the rkvdec hardware engaged).**

## Why this shape

iter9 closed the Vulkan-compositor-on-Bifrost path. Brave 148 boots, browser UI renders via Vulkan. **Video decode** still falls to software because the GPU process emits:

```
ERROR:media/gpu/vaapi/vaapi_wrapper.cc:1640  vaInitialize failed: unknown libva error
```

every time. The libva stack itself works system-wide (libva-v4l2-request-fourier installed; ffmpeg + mpv both use rkvdec hardware decode on ohm). So the gap is Brave-process-internal: env vars don't reach it, feature flags aren't on, or there's a structural integration issue.

A `strings /opt/brave-bin/brave` grep on 148.1.90.122 shows VAAPI delegates for AV1/H264/VP8/VP9 + the `VaapiVideoDecoder` + `VaapiIgnoreDriverChecks` feature flags — the build is VAAPI-capable. So the goal is runtime config alignment, not patches.

## Hypothesis space

1. **Env vars not propagating to GPU process.** `libva-v4l2-request-fourier` ships `/etc/profile.d/libva-v4l2-request.sh` setting:
   - `LIBVA_DRIVER_NAME=v4l2_request`
   - `LIBVA_V4L2_REQUEST_VIDEO_PATH=/dev/video1`
   - `LIBVA_V4L2_REQUEST_MEDIA_PATH=/dev/media0`
   
   These are inherited by Plasma's session shells but **not** by our SSH-spawned brave-vulkan invocations (no login shell). The current `brave-vulkan` wrapper doesn't set them explicitly. **Fix candidate:** wrapper-level export.

2. **Chromium VAAPI feature flag not enabled.** `--enable-features=VaapiVideoDecoder` is needed in modern Chromium for VAAPI to engage in the GPU process. May also need `VaapiIgnoreDriverChecks` because `v4l2_request` isn't on Chromium's hardcoded driver allowlist (which expects Intel `iHD` / AMD `radeonsi` / Mesa Gallium `va` etc.). **Fix candidate:** flag-level addition.

3. **`--use-gl=disabled` blocks the VAAPI→presentation path.** Chromium's classic VAAPI integration: VAAPI decode → DMA-BUF → GL texture import → compositor uploads the texture. With GL disabled, the texture import step doesn't exist; even if VAAPI succeeds the frame has nowhere to go. **Fix candidate:** either switch to a different `--use-gl` mode that provides texture import (probably `--use-gl=egl`), or rely on Chromium's newer Vulkan VAAPI path (`VK_EXT_external_memory_dma_buf` import — supported by PanVk-Bifrost per iter0 vulkaninfo). The latter requires the right Chromium feature flag (e.g., `EnableVulkanVideoDecode`-style).

4. **Codec profile mismatch.** Chromium asks libva for specific VAProfiles (e.g., `VAProfileH264Main`). libva-v4l2-request-fourier supports certain profiles per hardware. If Chromium's first probed profile isn't supported, `vaCreateContext` (not `vaInitialize`) would fail — but our error is at `vaInitialize` which is earlier. So this is downstream of (1) and (2).

5. **Output format mismatch.** rkvdec emits MM21 (Mali tiled NV12). Chromium expects NV12 (linear) or potentially tiled variants depending on platform. Even if VAAPI engages, the frame format may not be importable. **Diagnostic only at this stage** — wouldn't show up until VAAPI is actually loading.

6. **libva-v4l2-request-fourier API gap.** Chromium may call libva entry points that v4l2_request-fourier doesn't implement (e.g., specific buffer query operations). Need to look at vaapi_wrapper.cc's startup sequence to see exactly which call returns "unknown libva error."

## Phase 1 plan

1. Brave-side env propagation: run brave-vulkan with explicit `LIBVA_DRIVER_NAME` + `LIBVA_V4L2_REQUEST_*` set in the invocation. Did `vaInitialize` succeed?
2. If still failing: add `--enable-features=VaapiVideoDecoder,VaapiIgnoreDriverChecks` to the Brave flags. Re-run.
3. If still failing: try `--use-gl=egl` instead of `--use-gl=disabled`. Risk: re-introduces the GLES3 issue iter9 worked around. If GLES3 path is now OK because patched lib exposes Vulkan-1.2 ANGLE engagement, this might just work.
4. If steps 1-3 give "VAAPI initialized but no codecs available" or similar — drop into the codec profile question (hypothesis 4).
5. Capture `chrome://gpu` content via `--remote-debugging-port=9222` + DevTools protocol scrape (saved as iter11 evidence).
6. Measure: play a known H.264 sample (we have `~/fourier-test/bbb_1080p30_h264.mp4` per libva-multiplanar iter9). Compare CPU usage with VAAPI on vs. off (or against ffmpeg-mpv hardware decode for a known-good baseline).

## In-scope (LOCKED 2026-05-20 for iter11)

- Brave 148.1.90.122 on ohm with mesa-panvk-bifrost iter9 package already installed.
- libva-v4l2-request-fourier system install (no changes).
- Brave wrapper / flag changes only — no Mesa patches, no libva changes.
- Verify via chrome://gpu + a real video playback.

## Out-of-scope (LOCKED 2026-05-20 for iter11)

- Patching Chromium / Brave (build is months; we don't have an aarch64 Chromium-build pipeline).
- Patching libva-v4l2-request-fourier (separate campaign; if iter11 surfaces a real API gap, file an issue against `libva-v4l2-request-fourier#N`).
- VAAPI **encode** (hardware video encode is a rkvenc concern, not rkvdec; out of scope).
- WebGL via ANGLE-GLES3 (iter12+ if it ever happens — needs `VK_EXT_transform_feedback` in PanVk-Bifrost, Bifrost RE work).
- Packaging changes — only modify the brave-vulkan wrapper if a working flag+env combo is found; the iter9 package layout stays.

## Success criteria

1. `chrome://gpu` shows "Video Decode: Hardware accelerated" for at least one codec (likely H.264).
2. Visual playback of `bbb_1080p30_h264.mp4` (or an equivalent local file) shows smooth frame delivery, no software-decode lag.
3. CPU usage during playback comparable to mpv-with-hardware-decode baseline (single-digit % on the 4× Cortex-A55 cluster).
4. iter9 baseline (no GPU process crashes, Vulkan compositor still active) still holds — VAAPI engagement isn't a regression.

If all 4 → iter11 GREEN. Wrapper change deferred to the close phase (we add the right env+flags to brave-vulkan, bump pkgrel=3 if shipping; otherwise note the flags in docs and leave the wrapper alone).

## Reference

- iter9 close: [phase8_iteration9_close.md](phase8_iteration9_close.md).
- libva-multiplanar iter9 substrate (for env-var pattern): `~/src/libva-multiplanar/phase0_findings_iter9.md`.
- Brave 148 VAAPI symbol grep (this session, recent).
- chromium VAAPI integration source: Chromium tree `media/gpu/vaapi/` (not locally cloned; reference only).