marfrit-packages/arch/chromium-fourier/STUDY.md

chromium-fourier — Chromium with V4L2-stateless / VAAPI HW decode on mainline-kernel ARM Linux

Goal

Patch upstream Chromium so it can do hardware video decode through VaapiVideoDecoder on a plain Linux Wayland system on Rockchip (RK3566 / RK3588), via our marfrit/libva-v4l2-request-fourier libva backend. Target consumers: Brave (rebuilt from the same patched Chromium), upstream Chromium itself for Arch Linux ARM, and any other Blink-based browser that picks up the patches.

This fills a niche no shipping fork currently fills — every existing ARM-Linux Chromium with HW decode (7Ji's chromium-mpp, Ubuntu's liujianfeng1994/rockchip-multimedia PPA, JeffyCN's recipe, etc.) goes through the vendor MPP path on **5.10 BSP kernel + X11 + Mali blob

• panfork**. We're going for mainline kernel + V4L2 stateless + Wayland + panfrost / panthor, the direction Fourier is heading anyway.

What's actually broken in stock Chromium 147+

1. media/gpu/chromeos/video_decoder_pipeline.cc is selected on Linux when it shouldn't be. It then tries to initialize a V4L2 ImageProcessor (a ChromeOS-specific m2m chip block for color conversion / scaling) that doesn't exist on a plain Linux Wayland system. Failure surface:

   PickDecoderOutputFormat(): Initializing ImageProcessor; max buffers: 16
   ERROR: failed Initialize()ing the frame pool
   

2. VaapiVideoDecoder is compiled into stock Chromium / brave-bin (verified: strings /opt/brave-bin/brave | grep VaapiVideoDecoder), but the chromeos pipeline preempts it. Once the pipeline fails, the decoder selection bails — it never falls back to direct VaapiVideoDecoder.

3. V4L2VideoDecoder factory is BUILDFLAG(IS_CHROMEOS)-gated. Feature flags UseChromeOSDirectVideoDecoder / V4L2FlatStatelessVideoDecoder are no-ops on a non-ChromeOS build — their flag strings don't even appear in the binary.

The patch shape (sketch)

Patch 1 — bypass the chromeos pipeline on Linux

media/gpu/chromeos/video_decoder_pipeline.cc is reached from media/gpu/vaapi/vaapi_video_decoder.cc somewhere in ApplyResolutionChangeWithScreenSizes. Either:

• Skip the chromeos pipeline entirely on Linux non-ChromeOS, going straight to VaapiVideoDecoder::CreateContextAndScopedVASurfaces for frame allocation, OR
• Replace PickDecoderOutputFormat's ImageProcessor probing with a no-op that just trusts the VAAPI surface format (since on real ChromeOS the IP does color conversion that we don't need in our dmabuf-passthrough path).

Reference: [crbug 40192819] "VaapiVideoDecoder on linux" (https://issues.chromium.org/issues/40192819).

Patch 2 — un-gate V4L2VideoDecoder factory for non-ChromeOS Linux

Optional but useful as a fallback. The class is compiled in; only the factory registration is IS_CHROMEOS-gated. The igel-oss/meta-browser-hwdecode patch https://github.com/igel-oss/meta-browser-hwdecode/blob/master/recipes-chromium/chromium/files/0001-Add-support-for-V4L2VDA-on-Linux.patch shows the historical pattern for the V4L2VDA factory; the modern factory is in media/gpu/v4l2/v4l2_video_decoder.{h,cc}.

This is plan B if Patch 1 turns out harder than expected — V4L2VDA talks to /dev/videoN directly without going through libva, which means we don't depend on the libva-v4l2-request-fourier decode-submission path either. Shorter end-to-end critical path, but a more invasive factory change.

Patch 3 — point libva at our backend (build-time)

Already configurable at runtime via LIBVA_DRIVER_NAME=v4l2_request, but a Brave/Chromium binary that defaults to it would be cleaner. Could patch the GPU process startup to set the env var if not already set. Cosmetic, optional.

Reference forks (read these side-by-side with our patch)

• JeffyCN/meta-rockchip chromium recipe — the upstream of the V4L2VDA factory un-gating and libv4l-rkmpp shim that every shipping fork uses. https://github.com/JeffyCN/meta-rockchip/tree/master/dynamic-layers/recipes-browser/chromium Caveat: targets the V4L2VDA path (Plan B), not the modern VaapiVideoDecoder (Plan A) we want.
• igel-oss/meta-browser-hwdecode — Yocto layer with the original 0001-Add-support-for-V4L2VDA-on-Linux.patch. 2017-vintage but the pattern still applies. https://github.com/igel-oss/meta-browser-hwdecode
• 7Ji-PKGBUILDs/chromium-mpp — the most recent ALARM-shipping variant, Chromium 132 with MPP. Useful for the PKGBUILD shape and the patch-set list, even though we're not using MPP. https://github.com/7Ji-PKGBUILDs/chromium-mpp
• amazingfate/chromium-debian-build — Debian flavour of the same approach, for reference. https://github.com/amazingfate/chromium-debian-build

Build environment

• Source tree: gn / depot_tools, hosted on fermi (Arch ARM aarch64 LXC on hertz). Fetch is ~30 GB; full chromium tree is ~100 GB with build artifacts. Fermi's storage budget needs checking — may need to bind-mount a hertz path with more headroom.
• Build acceleration: distcc-avahi is already deployed. Wire the chromium build to use distcc through CT108 + tesla as compile workers. Pump mode can shave further; chromium's ninja will accept distcc'd cc/c++ via wrappers.
• First build wall time estimate: 6–10 hours initial on fermi alone; 3–5 hours with distcc-avahi if the network throughput holds. After the first build, incrementals on small patches are ~10–15 min.
• Configure flags: gn args — start from Arch's chromium PKGBUILD, add use_vaapi=true use_v4l2_codec=true is_official_build=false.
• Output: chromium-fourier-<chromium-ver>-1-aarch64.pkg.tar.zst shipping /usr/bin/chromium. provides=(chromium) conflicts=(chromium) shape, same as ffmpeg-v4l2-request-git's replacement of stock ffmpeg.

Validation path

Once a patched binary builds:

1. Launch with the same env we use for mpv-vaapi: LIBVA_DRIVER_NAME=v4l2_request LIBVA_V4L2_REQUEST_VIDEO_PATH=/dev/video0
2. Open chrome://gpu — should show "Video Decode: Hardware accelerated" (not "Disabled" or "Software only").
3. Open a 1080p H.264 file:// URL, watch CPU on /dev/video0 openers, measure Brave's GPU process CPU% during playback.
4. Cross-reference with mpv --hwdec=vaapi numbers once the libva-v4l2-request-fourier decode-submission path also lands.

Order of operations

Phase A (this session): workspace + STUDY.md (this file). Done.

Phase B: build environment — install depot_tools on fermi, run fetch chromium, get a baseline (unpatched) build to confirm fermi can build chromium at all. ~one full day.

Phase C: identify the exact line to flip for Patch 1 by reading media/gpu/chromeos/video_decoder_pipeline.cc + media/gpu/vaapi/vaapi_video_decoder.cc against current Chromium master. Iterate the patch on a real build.

Phase D: package as chromium-fourier PKGBUILD, hook into marfrit-packages CI on fermi (already has the pattern from ffmpeg-v4l2-request-git).

Phase E: rebase Patch 1 (and Patch 2 if needed) onto Brave's source tree, ship as brave-fourier next to chromium-fourier. Brave's tree adds ~50 patches on top of upstream Chromium; the chromeos-pipeline seam should be unchanged across that delta, so this should be a mechanical rebase.

Out of scope

• HW video encode (cameras, webcam streams). RK3566 has a separate encoder block on /dev/video2; not a Fourier priority.
• HEVC / VP9 / AV1 — RK3566 has no HW for these. RK3588 has VDPU381 but our libva backend doesn't speak HEVC yet.
• WebGL / WebGPU performance — separate concern, not part of video decode.
• Brave-specific features (Shields, Wallet, etc.) — they all live in Brave's source tree on top of Chromium and are unaffected by our decode patches.