From 60f15d5b27731a5e88f9e4e308646fba46a6421e Mon Sep 17 00:00:00 2001 From: paydro Date: Sat, 6 Jun 2026 16:59:29 -0700 Subject: [PATCH 1/3] nix: drop Firefox wrapper outputs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- flake.nix | 12 --- nix/compatibility-report.nix | 7 -- nix/firefox-wrapper.nix | 192 ----------------------------------- 3 files changed, 211 deletions(-) delete mode 100644 nix/firefox-wrapper.nix diff --git a/flake.nix b/flake.nix index a4392b1..ae2809d 100644 --- a/flake.nix +++ b/flake.nix @@ -28,16 +28,6 @@ pkgs = final; inherit nixpkgsRev; }; - - wrapFirefoxVirglVaapiCompat = args: - final.callPackage ./nix/firefox-wrapper.nix ({ - virgl-vaapi-compat = final.virgl-vaapi-compat; - } // args); - - firefox = final.wrapFirefoxVirglVaapiCompat { - firefox = prev.firefox; - aliasName = "firefox"; - }; }; packages = forAllSystems (system: @@ -48,7 +38,6 @@ default = pkgs.virgl-vaapi-compat; virgl-vaapi-compat = pkgs.virgl-vaapi-compat; compatibility-report = pkgs.virgl-vaapi-compat-compatibility-report; - firefox = pkgs.firefox; }); checks = forAllSystems (system: @@ -95,7 +84,6 @@ lib = { libvaAbi = import ./nix/libva-abi.nix; - firefoxWrapper = import ./nix/firefox-wrapper.nix; }; }; } diff --git a/nix/compatibility-report.nix b/nix/compatibility-report.nix index e8dc16f..98a686e 100644 --- a/nix/compatibility-report.nix +++ b/nix/compatibility-report.nix @@ -71,13 +71,6 @@ let version = firstVersion [ [ "cloud-hypervisor" ] ]; sourceRev = firstSourceRev [ [ "cloud-hypervisor" ] ]; }; - firefox = { - stableVersion = firstVersion [ [ "firefox" ] ]; - developerEditionVersion = firstVersion [ - [ "firefox-devedition" ] - [ "firefox-developer-edition" ] - ]; - }; checks = { api = "compile against active libva.dev"; abi = "export exactly ${abi.initSymbol}"; diff --git a/nix/firefox-wrapper.nix b/nix/firefox-wrapper.nix deleted file mode 100644 index 7a82f1b..0000000 --- a/nix/firefox-wrapper.nix +++ /dev/null @@ -1,192 +0,0 @@ -{ lib -, stdenvNoCC -, makeWrapper -, virgl-vaapi-compat -, firefox -, aliasName ? firefoxBinary -, firefoxBinary ? "firefox" -, libvaDriverName ? "virtio_gpu" -, libvaDriversPathExtra ? [ ] -, renderNode ? "/dev/dri/renderD128" -, renderer ? "virgl (virtio-gpu)" -, glVersion ? "4.6 (Compatibility Profile) Mesa" -, extraEnv ? { } -, lockedPreferences ? { } -, extraPolicies ? { } -}: - -let - firefoxName = firefox.pname or (lib.getName firefox); - firefoxVersion = firefox.version or (lib.getVersion firefox); - - libvaDriversPath = lib.concatStringsSep ":" ( - [ "${virgl-vaapi-compat}/lib/dri" ] ++ libvaDriversPathExtra - ); - - defaultEnv = { - LIBVA_DRIVER_NAME = libvaDriverName; - LIBVA_DRIVERS_PATH = libvaDriversPath; - MOZ_ENABLE_WAYLAND = "1"; - }; - - wrapperEnv = defaultEnv // lib.mapAttrs (_: value: toString value) extraEnv; - - makeWrapperArgs = lib.concatStringsSep " " ( - lib.mapAttrsToList - (name: value: "--set ${lib.escapeShellArg name} ${lib.escapeShellArg (toString value)}") - wrapperEnv - ); - - defaultLockedPreferences = { - "gfx.webrender.all" = true; - "gfx.webrender.enabled" = true; - "layers.acceleration.force-enabled" = true; - "media.av1.enabled" = false; - "media.ffmpeg.dmabuf-textures.enabled" = true; - "media.ffmpeg.vaapi.enabled" = true; - "media.ffmpeg.vaapi.force-enabled" = true; - "media.ffmpeg.vaapi.force-surface-zero-copy" = 1; - "media.ffvpx.enabled" = false; - "media.hardware-video-decoding.enabled" = true; - "media.hardware-video-decoding.force-enabled" = true; - "media.mediasource.vp9.enabled" = false; - "media.mediasource.webm.enabled" = false; - "media.rdd-ffmpeg.enabled" = true; - "media.rdd-vpx.enabled" = true; - "media.webm.enabled" = false; - "widget.dmabuf.force-enabled" = true; - }; - - lockedPreferencePolicies = lib.mapAttrs - (_: value: { - Value = value; - Status = "locked"; - }) - (defaultLockedPreferences // lockedPreferences); - - policyDocument = { - policies = lib.recursiveUpdate { - DisableAppUpdate = true; - Preferences = lockedPreferencePolicies; - } extraPolicies; - }; - - policiesJson = builtins.toJSON policyDocument; -in - -stdenvNoCC.mkDerivation { - pname = firefoxName; - version = firefoxVersion; - - nativeBuildInputs = [ makeWrapper ]; - dontUnpack = true; - - installPhase = '' - runHook preInstall - - mkdir -p "$out" - cp -a --no-preserve=ownership ${firefox}/. "$out/" - chmod -R u+w "$out" - - main="$out/bin/${firefoxBinary}" - if [ ! -e "$main" ]; then - main="$(find "$out/bin" -maxdepth 1 -type f -perm -0100 | sort | head -n 1 || true)" - fi - if [ -z "$main" ] || [ ! -e "$main" ]; then - echo "Could not find Firefox executable '${firefoxBinary}' in ${firefox}" >&2 - exit 1 - fi - - main_name="$(basename "$main")" - mv "$main" "$main.virgl-vaapi-original" - makeWrapper "$main.virgl-vaapi-original" "$main" ${makeWrapperArgs} - - if [ "$main_name" != "${aliasName}" ]; then - rm -f "$out/bin/${aliasName}" - ln -s "$main_name" "$out/bin/${aliasName}" - fi - - found_app_dir=0 - for app_dir in "$out"/lib/firefox "$out"/lib/firefox-*; do - [ -e "$app_dir" ] || continue - - if [ -L "$app_dir" ]; then - app_target="$(readlink -f "$app_dir")" - rm "$app_dir" - cp -a --no-preserve=ownership "$app_target" "$app_dir" - chmod -R u+w "$app_dir" - fi - - [ -d "$app_dir" ] || continue - found_app_dir=1 - - mkdir -p "$app_dir/distribution" - cat > "$app_dir/distribution/policies.json" <<'EOF' -${policiesJson} -EOF - - rm -f "$app_dir/glxtest" - cat > "$app_dir/glxtest" <<'SH' -#!/bin/sh -out=/dev/stdout -while [ "$#" -gt 0 ]; do - case "$1" in - -f) - out="/proc/self/fd/$2" - shift 2 - ;; - *) - shift - ;; - esac -done - -cat > "$out" <<'EOF' -DRM_RENDERDEVICE -${renderNode} -DRI_DRIVER -virtio_gpu -VENDOR -Mesa -RENDERER -${renderer} -VERSION -${glVersion} -TFP -TRUE -MESA_ACCELERATED -TRUE -DMABUF_MODIFIERS_XRGB -0 -DMABUF_MODIFIERS_ARGB -0 -DMABUF_MODIFIERS_NV12 -0 -DMABUF_MODIFIERS_P010 -0 -DMABUF_MODIFIERS_YUV420 -0 -TEST_TYPE -EGL -EOF -SH - chmod 0755 "$app_dir/glxtest" - done - - if [ "$found_app_dir" -eq 0 ]; then - echo "Could not find a Firefox application directory under $out/lib" >&2 - exit 1 - fi - - runHook postInstall - ''; - - passthru = { - inherit firefox glVersion policyDocument renderNode renderer virgl-vaapi-compat wrapperEnv; - }; - - meta = (firefox.meta or { }) // { - description = "Firefox wrapped to use virgl-vaapi-compat through scoped LIBVA settings"; - mainProgram = aliasName; - }; -} From e0a566a09f1558540c4ed29212a2d01fb3c6ec5d Mon Sep 17 00:00:00 2001 From: paydro Date: Sat, 6 Jun 2026 17:00:34 -0700 Subject: [PATCH 2/3] docs: split generic repository guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- AGENTS.md | 30 ++++++++++++++--- CHANGELOG.md | 8 +++++ CONTRIBUTING.md | 13 ++++++-- README.md | 14 ++++---- docs/debugging.md | 55 ++++++------------------------ docs/design.md | 10 +++--- docs/firefox.md | 72 ---------------------------------------- docs/nix.md | 16 ++++----- docs/removal-criteria.md | 6 ++-- docs/troubleshooting.md | 10 +++--- 10 files changed, 80 insertions(+), 154 deletions(-) delete mode 100644 docs/firefox.md diff --git a/AGENTS.md b/AGENTS.md index 2e27bb1..c5d2b0f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -86,7 +86,7 @@ deployment glue, unless the maintainer explicitly approves that scope. This repository may document integration points, but it must not silently make host-specific changes for a consumer. -## Nixling-style review panel policy +## 8-reviewer panel sign-off policy Non-trivial plan-driven or multi-phase work requires unanimous 8/8 panel approval at each phase boundary before moving to the next phase. The required @@ -134,7 +134,27 @@ If there is uncertainty about whether a change is trivial, use the panel. ## Branch protection expectation -`main` is intended to be protected once the bootstrap branch lands. Require PRs, -fresh approval after new commits, passing CI jobs, and maintainer bypass only for -emergency repository repair. Non-trivial plan-driven work still requires the 8/8 -panel even if GitHub's branch rule only enforces ordinary PR approval. +After initial repository bootstrap, nobody direct-pushes to `main`. All changes +use this flow: + +1. Create a topic branch. +2. Run the relevant local validation for the changed scope. +3. Open a pull request. +4. Wait for required CI to pass and required conversations to be resolved. +5. Squash-merge the PR after review requirements are met. + +Expected `main` protection settings: + +- block direct pushes for everyone; +- require pull requests before merge; +- require PR review before merge; +- dismiss stale approvals when new commits are pushed; +- require required CI jobs to pass; +- require all conversations to be resolved; +- disallow force-pushes; +- disallow branch deletion; +- restrict maintainer bypass to emergency repository repair and document any + bypass in the PR or follow-up issue. + +Non-trivial plan-driven work still requires the 8/8 panel even if GitHub's +branch rule only enforces ordinary PR approval. diff --git a/CHANGELOG.md b/CHANGELOG.md index d07b238..3bb099d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,14 @@ first stable release. - Governance documentation for contributors, agents, security reporting, and release notes. +### Changed + +- Removed Firefox-specific packaging, wrapper, policy, and logging instructions + from the generic repository docs; client-specific guidance belongs in + downstream client repositories. +- Reframed governance as a generic 8-reviewer panel sign-off policy with + branch-to-PR-to-CI-to-squash-merge expectations after bootstrap. + ## 0.1.0-alpha.1 - TBD ### Added diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 87fa032..e07c92c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -65,6 +65,11 @@ with the command attempted and the failure. ## Pull requests +After initial repository bootstrap, nobody direct-pushes to `main`. Start from a +topic branch, run the relevant local validation, open a pull request, wait for +required CI and conversation resolution, and squash-merge only after review +requirements are satisfied. + Pull requests should include: - A concise summary. @@ -88,8 +93,8 @@ Keep unrelated changes in separate commits. Avoid vague subjects such as ## Review panel expectations -Non-trivial plan-driven or multi-phase work follows the same review-panel style -used by `nixling`. +Non-trivial plan-driven or multi-phase work follows the 8-reviewer panel +sign-off policy. At each phase boundary, work must receive 8/8 sign-off before the next phase starts: @@ -122,11 +127,15 @@ notes, and integration instructions may not. The public `main` branch should be protected after the initial bootstrap push: +- block direct pushes for everyone; - require pull requests before merge; - require at least one approving review for ordinary changes; - require the documented 8/8 panel for non-trivial plan-driven work; - dismiss stale approvals when new commits are pushed; - require the `make test (Ubuntu packages)` and `optional Nix flake checks` workflow jobs to pass; +- require all conversations to be resolved before merge; +- disallow force-pushes; +- disallow branch deletion; - restrict maintainer bypass to emergency repository repair and document any bypass in the PR or follow-up issue. diff --git a/README.md b/README.md index 5135532..c07af27 100644 --- a/README.md +++ b/README.md @@ -72,24 +72,23 @@ Do not overwrite the only copy of the real driver with the shim. The shim must be able to `dlopen()` the real `virtio_gpu_drv_video.so`, preferably through an absolute path compiled with `REAL_DRIVER=...`. -## Nix and Firefox +## Nix Nix/NixOS users can package the shim by setting `REAL_DRIVER` to the real Mesa virtio-gpu VA driver path in the target graphics closure and exposing the shim -through a higher-priority `LIBVA_DRIVERS_PATH`. The flake exposes: +through a higher-priority `LIBVA_DRIVERS_PATH`. The public generic flake +documents the shim package, checks, compatibility report, and overlay: ```bash nix build github:vicondoa/virgl-vaapi-compat#virgl-vaapi-compat -nix build github:vicondoa/virgl-vaapi-compat#firefox nix build github:vicondoa/virgl-vaapi-compat#compatibility-report ``` See [`docs/nix.md`](docs/nix.md). -Firefox users should treat this as one possible workaround for a VA-API DMABUF -format-descriptor mismatch, not as a general Firefox acceleration switch. You -still need a working VA-API virtio-gpu stack and Firefox VA-API enabled. See -[`docs/firefox.md`](docs/firefox.md) and [`docs/debugging.md`](docs/debugging.md). +Client-specific packaging, browser policies, wrapper packages, and application +logging recipes belong in downstream client repositories. This generic repo only +documents the libva shim boundary. ## Safety and scope @@ -122,7 +121,6 @@ clients accept the existing virgl I420 descriptor path. See - [`docs/design.md`](docs/design.md) - design goals, non-goals, and constraints - [`docs/debugging.md`](docs/debugging.md) - reproducing and diagnosing the motivating failure mode -- [`docs/firefox.md`](docs/firefox.md) - Firefox-specific VA-API notes - [`docs/nix.md`](docs/nix.md) - Nix/NixOS integration notes - [`docs/troubleshooting.md`](docs/troubleshooting.md) - common symptoms and fixes diff --git a/docs/debugging.md b/docs/debugging.md index 192080e..1820074 100644 --- a/docs/debugging.md +++ b/docs/debugging.md @@ -8,18 +8,17 @@ DMABUF fails because the client rejects the exported DRM PRIME descriptor shape. A prior debugging session (`f15bd57d-e724-47f2-9d2e-012652265f5e`) found: -- Firefox cannot use the `virtio_media` `/dev/video0` V4L2 M2M path directly; - Firefox Linux hardware decode uses VA-API. +- The original motivating browser client used VA-API for this hardware decode + path rather than the `virtio_media` `/dev/video0` V4L2 M2M path directly. - Enabling `graphics.virglVideo = true` made the guest virtio-gpu VA-API driver expose H.264 profiles. -- Firefox selected H.264 VA-API decode (`hw: "true"`, `VAAPI_VLD`) but failed - with messages such as `CreateImageVAAPI(): failed to get VideoFrameSurface` - and `VAAPI dmabuf allocation error`, then fell back to software decode. +- The client selected H.264 VA-API decode but rejected the exported DMABUF + descriptor, then fell back to software decode. - The root cause was virgl exporting `DRM_PRIME_2` `VA_FOURCC_I420` descriptors - while Firefox rejected that descriptor before reaching its lower DMABUF YUV + while the client rejected that descriptor before reaching its lower DMABUF YUV import path. -- A first workaround patched Firefox's I420 allowlist. This project is the - preferred wrapper/shim approach because it leaves Firefox unpatched. +- A first workaround patched the client allowlist. This project is the preferred + wrapper/shim approach because it leaves clients unpatched. Known stack versions from that investigation: @@ -31,9 +30,6 @@ Known stack versions from that investigation: | virglrenderer | `1.3.0` | | crosvm | `4c80bf3523cf84114054209d88a7af3eefd8423f` | | Cloud Hypervisor | `52.0` | -| Firefox | `151.0.2` | -| Firefox Developer Edition | `152.0b1` | - ## Establish what path the client uses First separate three different acceleration paths: @@ -42,9 +38,9 @@ First separate three different acceleration paths: 2. **VA-API** through libva and `virtio_gpu_drv_video.so` 3. **Software decode** -For Firefox on Linux, the relevant hardware decode path is VA-API. Seeing a -`virtio_media` node is not enough; Firefox will not directly use that V4L2 M2M -path for this class of decode. +For the motivating browser client, the relevant hardware decode path was VA-API. +Seeing a `virtio_media` node was not enough because that client did not directly +use the V4L2 M2M path for this class of decode. ## Check VA-API visibility @@ -85,35 +81,6 @@ If libva cannot initialize the shim, confirm that the build-time libva headers and runtime libva agree. Rebuild with the target system's `pkg-config` and libva headers when in doubt. -## Firefox VA-API logging - -Firefox logging can show whether VA-API decode is selected and where it fails. -Useful environment variables include: - -```bash -MOZ_LOG="PlatformDecoderModule:5,FFmpegVideo:5,DMABUF:5,WidgetDMABuf:5,VAAPI:5" -MOZ_LOG_FILE=firefox-vaapi.log -LIBVA_MESSAGING_LEVEL=2 -LIBVA_DRIVER_NAME=virtio_gpu -``` - -Run Firefox from a terminal with those variables, reproduce playback, then check -for evidence that the VA-API decoder was selected: - -- `hw: "true"` -- `VAAPI_VLD` -- H.264 profile selection - -Then look for the failure signatures: - -- `CreateImageVAAPI(): failed to get VideoFrameSurface` -- `VAAPI dmabuf allocation error` -- fallback from hardware to software decode - -The exact log module names can change between Firefox releases. If a module is -silent, keep `PlatformDecoderModule`, `DMABUF`, and `WidgetDMABuf` enabled and -consult the Firefox version's current logging names. - ## DMABUF and I420 failure signature The failure this shim targets has a specific shape: @@ -140,7 +107,7 @@ LIBVA_DRIVERS_PATH=/path/to/shim/lib/dri${LIBVA_DRIVERS_PATH:+:$LIBVA_DRIVERS_PA vainfo ``` -For a client such as Firefox, include the same shim variables in the launch +For an affected client, include the same shim variables in the launch environment. When the hook is installed and a matching export occurs, stderr may include lines like: diff --git a/docs/design.md b/docs/design.md index f118217..b5aea0c 100644 --- a/docs/design.md +++ b/docs/design.md @@ -26,7 +26,7 @@ accepted by affected clients. - a color management tool - a DMABUF allocator - a GPU synchronization layer -- a Mesa, virglrenderer, crosvm, or Firefox fork +- a Mesa, virglrenderer, crosvm, browser, or client fork - a generic workaround for all virtio-gpu graphics problems If a client fails before VA-API decode is selected, if H.264 profiles are not @@ -36,10 +36,10 @@ use virtio-gpu video at all, this shim is not the primary fix. ## Why a shim The motivating failure was not that H.264 decode was unavailable. The guest -virtio-gpu VA driver advertised H.264 decode and Firefox selected VA-API, but -surface export failed at a descriptor compatibility boundary: virgl exported a -`DRM_PRIME_2` I420 descriptor, and Firefox rejected that descriptor before -falling through to its lower DMABUF YUV import path. +virtio-gpu VA driver advertised H.264 decode and the affected client selected +VA-API, but surface export failed at a descriptor compatibility boundary: virgl +exported a `DRM_PRIME_2` I420 descriptor, and the client rejected that descriptor +before falling through to its lower DMABUF YUV import path. A client patch that allowed that I420 descriptor can work, but it ties the workaround to one client. A VA driver shim keeps clients unpatched and confines diff --git a/docs/firefox.md b/docs/firefox.md deleted file mode 100644 index a9d8388..0000000 --- a/docs/firefox.md +++ /dev/null @@ -1,72 +0,0 @@ -# Firefox notes - -Firefox is the original motivating client for this project, but -`virgl-vaapi-compat` is not Firefox-specific. The shim sits at the libva driver -boundary and can be used by any VA-API client that loads the virtio-gpu VA -driver. - -## What Firefox needs first - -Before testing the shim, confirm the guest already has a working VA-API path: - -```bash -LIBVA_DRIVER_NAME=virtio_gpu vainfo -``` - -The output should show H.264 decode profiles and `VAEntrypointVLD`. If those are -missing, fix the VM/guest graphics stack first. In the motivating environment, -turning on virgl video support exposed H.264 profiles; the shim did not create -those capabilities. - -Firefox on Linux uses VA-API for this class of hardware decode. A -`virtio_media` `/dev/video0` V4L2 M2M device is not the path Firefox used in the -investigation that led to this shim. - -## Launching Firefox with the shim - -Example launch: - -```bash -VIRGL_VAAPI_COMPAT_DEBUG=1 \ -LIBVA_DRIVER_NAME=virtio_gpu \ -LIBVA_DRIVERS_PATH=/path/to/shim/lib/dri${LIBVA_DRIVERS_PATH:+:$LIBVA_DRIVERS_PATH} \ -MOZ_LOG="PlatformDecoderModule:5,FFmpegVideo:5,DMABUF:5,WidgetDMABuf:5,VAAPI:5" \ -MOZ_LOG_FILE=firefox-vaapi.log \ -firefox -``` - -Depending on the distribution and Firefox build, other Firefox preferences or -feature flags may be required for VA-API. This repository does not try to be a -complete Firefox acceleration guide; it addresses the narrower descriptor export -compatibility problem after VA-API decode is already being selected. - -## Expected evidence - -In Firefox logs, look for evidence that H.264 VA-API decode was selected, such -as: - -- `hw: "true"` -- `VAAPI_VLD` - -In failing baseline logs for the motivating bug, relevant messages included: - -- `CreateImageVAAPI(): failed to get VideoFrameSurface` -- `VAAPI dmabuf allocation error` - -With the shim and `VIRGL_VAAPI_COMPAT_DEBUG=1`, stderr should show the shim hook -being installed and, during playback, matching I420 `DRM_PRIME_2` exports being -rewritten to YV12 with a U/V layer swap. - -## What this does not fix - -The shim will not help if: - -- Firefox is using software decode from the start -- Firefox is blocked by sandbox, Wayland, EGL, or GPU process issues unrelated - to VA-API surface export -- `vainfo` does not show the needed decode profile -- the VM has no working virgl/virtio-gpu video path -- the failure is for a different fourcc, memory type, or descriptor layout - -When in doubt, follow [`debugging.md`](debugging.md) and compare logs with and -without the shim. diff --git a/docs/nix.md b/docs/nix.md index 21a9ab7..955f06c 100644 --- a/docs/nix.md +++ b/docs/nix.md @@ -7,21 +7,19 @@ and the shim `dlopen()`s the real driver. ## Flake outputs -The public flake exposes: +The generic shim integration points are: | Output | Purpose | | --- | --- | | `.#virgl-vaapi-compat` / `.#default` | The generic `virtio_gpu_drv_video.so` shim package. | -| `.#firefox` | Optional Firefox package wrapper with scoped `LIBVA_*` environment, locked VA-API policies, and a virgl `glxtest` stub. Its executable is `bin/firefox`, so all Firefox launches through that package use the wrapper. | -| `.#compatibility-report` | JSON report of the evaluated nixpkgs/libva/Mesa/virglrenderer/crosvm/Cloud Hypervisor/Firefox versions and derived libva init symbol. | +| `.#compatibility-report` | JSON report of the evaluated generic graphics stack versions and derived libva init symbol. | | `.#checks..default` | Build-time drift gate: compiles the shim, checks the exported libva ABI symbol, and runs the fake-driver behavior harness. | -| `overlays.default` | Adds `virgl-vaapi-compat`, `wrapFirefoxVirglVaapiCompat`, and the compatibility report to `pkgs`, and replaces `pkgs.firefox` with the wrapped Firefox built from the unwrapped upstream `prev.firefox`. | +| `overlays.default` | Adds the generic shim package and compatibility report to `pkgs` for downstream consumers. | Examples: ```bash nix build github:vicondoa/virgl-vaapi-compat#virgl-vaapi-compat -nix build github:vicondoa/virgl-vaapi-compat#firefox nix build github:vicondoa/virgl-vaapi-compat#compatibility-report cat result/compatibility-report.json ``` @@ -81,10 +79,10 @@ A conservative integration is to wrap only the affected application with `LIBVA_DRIVERS_PATH` and `LIBVA_DRIVER_NAME` rather than replacing the global VA driver search path for the whole system. -If you apply the overlay in a NixOS guest, `pkgs.firefox` becomes the wrapped -Firefox and still installs `bin/firefox`. Do not also install stock Firefox from -the pre-overlay package set, or both packages will try to provide the same -`bin/firefox` path. +Downstream clients should wrap only their affected application with +`LIBVA_DRIVERS_PATH` and `LIBVA_DRIVER_NAME`. Application-specific packages, +browser policies, and launch wrappers belong outside this generic shim +repository. ## Updating and garbage collection diff --git a/docs/removal-criteria.md b/docs/removal-criteria.md index b677619..4e11d8f 100644 --- a/docs/removal-criteria.md +++ b/docs/removal-criteria.md @@ -25,9 +25,9 @@ Compare the same workload with and without the shim: 4. Confirm playback continues without DMABUF/image allocation failures. 5. Confirm there are no regressions in color, stability, or fallback behavior. -For Firefox, useful evidence includes VA-API decode logs showing hardware decode -selected and no recurrence of `CreateImageVAAPI(): failed to get -VideoFrameSurface` or `VAAPI dmabuf allocation error`. +Useful evidence includes client logs showing hardware decode selected, no +recurrence of the original DMABUF/image allocation failure, and no shim debug +messages indicating descriptor rewrites during normal playback. ## Keep the test harness diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 45a97fd..14c91bf 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -50,16 +50,14 @@ The shim cannot add decoder support. Fix the underlying virtio-gpu/virgl video configuration first. In the motivating environment, enabling virgl video support made the guest VA-API driver advertise H.264 decode profiles. -## Firefox still falls back to software +## The client still falls back to software Confirm all of the following: -- Firefox selected VA-API decode (`hw: "true"`, `VAAPI_VLD`, or equivalent logs) -- the baseline failure resembles `CreateImageVAAPI(): failed to get - VideoFrameSurface` or `VAAPI dmabuf allocation error` +- the client selected VA-API decode according to its own logs or telemetry +- the baseline failure is a DMABUF/image allocation failure at surface export - shim debug logs show an I420 `DRM_PRIME_2` descriptor rewrite -- the issue is not a separate sandbox, Wayland/EGL, codec, or GPU-process - problem +- the issue is not a separate sandbox, display, codec, or GPU-process problem If the shim never sees a matching export, it is not addressing the active failure. From 052493f0f798184deff97928e596442233a81ec3 Mon Sep 17 00:00:00 2001 From: paydro Date: Sat, 6 Jun 2026 17:04:05 -0700 Subject: [PATCH 3/3] docs: close generic split review findings Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/debugging.md | 2 +- docs/nix.md | 21 +++++++++++++++++++++ 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/debugging.md b/docs/debugging.md index 1820074..ccee15a 100644 --- a/docs/debugging.md +++ b/docs/debugging.md @@ -6,7 +6,7 @@ DMABUF fails because the client rejects the exported DRM PRIME descriptor shape. ## Known motivating investigation -A prior debugging session (`f15bd57d-e724-47f2-9d2e-012652265f5e`) found: +A prior investigation found: - The original motivating browser client used VA-API for this hardware decode path rather than the `virtio_media` `/dev/video0` V4L2 M2M path directly. diff --git a/docs/nix.md b/docs/nix.md index 955f06c..b9b6eea 100644 --- a/docs/nix.md +++ b/docs/nix.md @@ -15,6 +15,7 @@ The generic shim integration points are: | `.#compatibility-report` | JSON report of the evaluated generic graphics stack versions and derived libva init symbol. | | `.#checks..default` | Build-time drift gate: compiles the shim, checks the exported libva ABI symbol, and runs the fake-driver behavior harness. | | `overlays.default` | Adds the generic shim package and compatibility report to `pkgs` for downstream consumers. | +| `lib.libvaAbi` | Helper function for downstream flakes that need to derive the libva driver init ABI from a libva package version. | Examples: @@ -68,6 +69,26 @@ allowed when the active headers compile, the expected init symbol is exported, and the fake-driver harness passes. Actual API or behavior drift fails the package/check instead of relying on a fixed allowlist of exact versions. +## `lib.libvaAbi` + +`lib.libvaAbi` is a small helper for downstream flakes that need to derive the +libva driver entry point from a package version without importing this package +derivation. Call it with a nixpkgs `lib` and a libva package version: + +```nix +let + abi = virgl-vaapi-compat.lib.libvaAbi { + inherit (pkgs) lib; + libvaVersion = pkgs.libva.version; + }; +in abi.initSymbol +``` + +The returned attribute set includes `initMajor`, `initMinor`, `initAbi`, +`initSymbol`, and `expectedPkgConfigVersionPrefix`. It is intentionally limited +to libva ABI derivation; it does not imply that a full graphics stack is known +good without the package checks. + ## VM integration In a NixOS guest, this shim is usually most useful when the guest already has a