fix(sycl): harden the luma-only zero-copy path: immediate primary queue, twin routing, synchronous upload (ADR-1763, ADR-1764)

[Tualua]

Summary

Depends on the hybrid-toolchain PR (build(container): GCC for CPU C, icpx for SYCL, and a Containerfile.vmafx ..., head Tualua:pr/hybrid-toolchain-containerfile). Review and merge it first; this branch is stacked on it. Until it merges, the diff here also shows its 24 commits; this PR's own commits are the last 11. It is stacked rather than based on master because it closes T-SYCL-ORDERED-SUM-MALLOC-PERTURB-2026-10-03, the docs/state.md row that PR opens, and its new tests follow that PR's test_link_kwargs rule.

SYCL zero-copy hardening for the luma-only path of ADR-1688, ported from the Tualua fork without its chroma import (that is post-1.0, ADR-1685, and comes as a separate draft):

• ADR-1763 — the primary SYCL queue runs on immediate command lists. Under batched command lists (UR_L0_USE_IMMEDIATE_COMMANDLISTS=0) an Arc A380 silently dropped the per-frame VA import from a random frame on; zero-copy cambi differed from host upload in 3 to 7 of 10 runs. Only the primary queue's mode matters (an import-only immediate queue still fails 8 of 12).
• vmaf_sycl_upload_plane() is synchronous: it waits on the copy queue before it returns, so the D3D11 import may unmap its staging texture at once and the plane is in place before the next read. Closes T-SYCL-UPLOAD-PLANE-NO-COMPUTE-FENCE-2026-10-05.
• test_sycl_ordered_sum probe keeps its host copy sources alive until the wait (it read freed memory under deferred command lists; fails on master under meson test's MALLOC_PERTURB_).
• ADR-1764 — patch 0005 routes feature= names to SYCL twins through vmaf_feature_backend_twin(), as the CLI does: on QSV zero-copy input a feature without a usable twin fails at configuration naming the reason; on software input the filter warns and uses the CPU. QSV zero-copy accepts NV12 / P010 only.
• [vmaf-sycl] timing: follows the log level (vmaf_log at INFO instead of fprintf(stderr)); libvmaf_sycl no longer prints it at -loglevel error.
• e2e harness (scripts/test/zerocopy-e2e.sh, comparator, sycl-dev-container.sh) and make sycl-zerocopy-contract in the FFmpeg Patch Stack job and pre-commit. Stage 1 is ADR-1688's admitted set and must equal host upload exactly; stage-2/3 cases need chroma and must be refused by name.
• Extra scored frame with -frames:v / -t: not a fork bug. FFmpeg n9.0.2 applies output limits after the filtergraph, so any libvmaf* filter (CPU included) can score one more pair (-frames:v 20: 7 of 12 runs with libvmaf, 4 of 12 with libvmaf_sycl; -t 1: 12 of 12 both). Documented with trim=end_frame=N on both inputs (Score exactly N frames); docs/state.md Confirmed not-affected row; the zero-copy docs example now trims.

What the fork had that this PR leaves to master (Research-1763 has the table): the CPU-extractor pre-pass and per-extractor -ENOTSUP guards (ADR-1688's admission check covers both), and the fatal VA import (#2110 decides it: retry, then fail naming the frame). Patch 0005's import-failure branch is unchanged here.

ADR numbers: the fork's ADR-1596 becomes ADR-1763; ADR-1764 holds what is left of the fork's ADR-1595. Both are above the numbers VMAFx/vmafx branches claim (up to 1762).

Type

• fix — bug fix
• test — test-only
• sycl / cuda / simd — backend-specific

Checklist

• Commits follow Conventional Commits (the commit-msg hook enforces this).
• make format && make lint is green locally. (pre-commit over the branch diff; clang-tidy on core/src/sycl/common.cpp and test_sycl_ordered_sum_probe.cpp reports no finding that master does not have; the 17 old ones in common.cpp are the subject of refactor(sycl): bring the SYCL host file, psnr_hvs host and SYCL tests to the lint and HISS standard (ADR-1142) #2092.)
• Unit tests pass: --suite fast and --suite sycl on the Arc A380 (below).
• If I touched any SIMD/GPU code path, I ran /cross-backend-diff and the worst ULP is ≤ 2. (No kernel arithmetic changed; the e2e harness compares host upload with the CPU and zero-copy with host upload at %.17g: 0 ULP.)
• If I touched a feature extractor with SIMD/GPU twins, I either updated every twin or listed the gap under "Known follow-ups" below. (No extractor changed.)
• If I added a new .c / .cpp / .cu / .h / .hpp, it has the appropriate license header (see CONTRIBUTING.md). (None added; new scripts carry SPDX headers.)
• If this is a breaking change, the commit message uses ! or BREAKING CHANGE: and the migration path is documented below. (Not breaking: vmaf_sycl_upload_plane()'s contract only gets stricter; the timing line keeps its text with the libvmaf INFO prefix.)
• If this PR adds an ADR, the ADR row lives in docs/adr/_index_fragments/<NNNN-slug>.md and the slug is appended to docs/adr/_index_fragments/_order.txt.

Bug-status hygiene (ADR-0165)

• docs/state.md updated: Recently closed T-SYCL-UPLOAD-PLANE-NO-COMPUTE-FENCE-2026-10-05 (moved from Open, removed from the RC3 list), T-SYCL-ORDERED-SUM-MALLOC-PERTURB-2026-10-03 (moved from Open), T-SYCL-ZEROCOPY-IMPORT-DROPPED-2026-10-02, T-SYCL-TIMING-LINE-IGNORES-LOGLEVEL-2026-10-05, T-SYCL-FILTER-FEATURE-NAMES-NOT-ROUTED-2026-10-02; Confirmed not-affected T-FFMPEG-OUTPUT-LIMIT-EXTRA-SCORED-FRAME-2026-10-05 (with the evidence).

Netflix golden-data gate (ADR-0024)

• I did not modify any assertAlmostEqual(...) score in the Netflix golden Python tests.
• If I believe a golden value must change, I have explained why below AND pinged @lusoris for a CODEOWNERS exception. (No golden value changes.)

Cross-backend numerical results

zerocopy-e2e.sh --stage 1 --repeat 3, Arc A380, src01 576x324 + checkerboard 1920x1080, at %.17g
8 bit : pass=50 fail=0 nonexact=0  (18 stage-1 cases zc == host == cpu, 3 of 3 runs; 32 stage-2/3 cases refused by name)
10 bit: pass=50 fail=0 nonexact=0

Deep-dive deliverables (ADR-0108)

• Research digest — docs/research/1763-sycl-zerocopy-hardening.md (reconciliation with ADR-1688 / fix(ffmpeg): retry a failed libvmaf_sycl VA import, then stop naming the frame, and import each input with its own VA display #2110, command-list measurements, the frame-count evidence table, validation).
• Decision matrix — ADR-1763 and ADR-1764 ## Alternatives considered; the frame-count options in Research-1763.
• AGENTS.md invariant note — core/src/sycl/AGENTS.md (immediate primary queue, synchronous upload_plane, timing through vmaf_log), core/src/AGENTS.d/logging-and-diagnostics.md.
• Reproducer / smoke-test command — pasted below under "Reproducer".
• CHANGELOG fragment — changelog.d/fixed/sycl-zerocopy-import-immediate-cmdlist.md, sycl-upload-plane-synchronous.md, sycl-timing-line-follows-log-level.md, sycl-filter-feature-twin-routing.md, changelog.d/changed/ffmpeg-score-exactly-n-frames.md.
• Rebase note — docs/rebase-notes.md: "ADR-1763 — SYCL primary queue on immediate command lists" and "SYCL zero-copy hardening: twin routing, synchronous upload, timing log, e2e harness".

User docs: docs/usage/ffmpeg.md (twin routing and its messages; Score exactly N frames), docs/backends/sycl/zero-copy.md, docs/backends/sycl/bundling.md, docs/api/gpu.md, docs/development/sycl-zerocopy-testing.md. FFmpeg patch 0005 changes in this PR (rule 14); the series replays on n9.0.2, 20 of 20.

Reproducer

HOST_REPO=<host checkout> scripts/test/sycl-dev-container.sh libvmaf
HOST_REPO=<host checkout> scripts/test/sycl-dev-container.sh ffmpeg
scripts/test/sycl-dev-container.sh test --suite sycl
scripts/test/sycl-dev-container.sh test --suite fast
scripts/test/sycl-dev-container.sh exec bash scripts/test/zerocopy-e2e.sh --stage 1 --out /work/.cache/sycl-dev/e2e-8 --depths 8 --repeat 3
scripts/test/sycl-dev-container.sh exec bash scripts/test/zerocopy-e2e.sh --stage 1 --out /work/.cache/sycl-dev/e2e-10 --depths 10 --repeat 3
make sycl-zerocopy-contract

Results (Arc A380, i915/iHD, localhost/vmafx:build-ocloc, fresh cache, measured on base 52e265fc0 with PR 1 underneath; since rebased onto 2f95aa87f, whose 8 newer commits change CUDA/HIP ADM, Python, arm64 SIMD, the vendored interop and CPU SpEED registration, not the SYCL host code or patch 0005):

• --suite sycl 69 OK / 0 fail; --suite fast 397 OK / 0 fail / 1 skipped (test_sycl_ordered_sum passes; it fails on master).
• e2e stage 1 --repeat 3: 8 bit and 10 bit each pass=50 fail=0 nonexact=0.
• make sycl-zerocopy-contract: routing check passes, comparator 26 of 26.
• FFmpeg series on n9.0.2: 20 of 20 with git am --3way; FFmpeg builds with --enable-libvmaf-sycl.
• Probes: feature=name=psnr on QSV → feature 'psnr' -> psnr_sycl, refused at frame 0 naming psnr_sycl; feature=name=niqe → configuration error on QSV, CPU fallback with a warning on software input; [vmaf-sycl] timing absent at -loglevel error, present at info; trim=end_frame=20 on both QSV inputs → 20 frames.
• pre-commit, make docs-fragments-check, ADR link / numbering / source-citation checks, check-state-md-rows, assertion density, the mypy gate, and standardsctl audit --base VMAFx/master (43 within 43 baselined on 9aee0bc9e, touched files clean, no baseline growth) pass.

Known follow-ups

• Chroma import, the shared-plane twins and float_motion motion_add_uv on zero-copy (post-1.0, ADR-1685): prepared as a separate draft on top of this branch.
• fix(ffmpeg): retry a failed libvmaf_sycl VA import, then stop naming the frame, and import each input with its own VA display #2110 also edits patch 0005 (import retry); whichever lands second rebases the patch.
• refactor(sycl): bring the SYCL host file, psnr_hvs host and SYCL tests to the lint and HISS standard (ADR-1142) #2092 (SYCL host lint) overlaps core/src/sycl/common.cpp.

🤖 Generated with Claude Code

[lusoris]

Thanks. See my comment on #2216: both get a full review right after the rc.3 tag, as RC4 scope. The immediate-command-list finding (ADR-1763 in this branch) is the part we most want to take.

[lusoris]

Thanks for this hardening. Here is how it relates to the RC4 import work, so it doesn't get lost.

#2342 (RC4 WP3) replaces the SYCL import layer around this code, but it leaves the luma-only VA path of ADR-1688 unchanged. That is the path this PR hardens, so the PR is still relevant. It overlaps #2342 in 17 files (core/src/sycl/common.*, the meson files, docs and docs/state.md among them). Once #2342 has landed, could you rebase onto master? We will then review the hardening on its own merits.

[lusoris]

Thank you for this hardening work. #2342 has landed, so here is the review on its own merits, run on 2026-10-10 at your head 23c060d5d on an Arc A380. One thing to know up front: our A380 runs on the xe kernel driver, not i915.

What works (measured)

• --suite sycl: 69 passed, 0 failed. --suite fast: 400 passed, 0 failed. The scratch check audits 131 kernels and finds none using scratch memory.
• Netflix golden gate against this build: 280 passed, 3 skipped.
• The ordered-sum probe fix is confirmed. With UR_L0_USE_IMMEDIATE_COMMANDLISTS=0, test_sycl_ordered_sum fails on its first run at the build(container): GCC for CPU C, icpx for SYCL, and a Containerfile.vmafx SYCL + FFmpeg image (ADR-1714, ADR-1715) #2216 head and passes 12 of 12 at this head.
• The twin-routing contract is a real check. make sycl-zerocopy-contract passes (8 patch assertions, 26 comparator tests), and the same script fails all 8 assertions against patch 0005 as it is at the build(container): GCC for CPU C, icpx for SYCL, and a Containerfile.vmafx SYCL + FFmpeg image (ADR-1714, ADR-1715) #2216 head, before your change. The series replays on FFmpeg n9.0.2 (20 patches).
• Your e2e harness, stage 1, under batched command lists (the harness sets that itself):
  • 10 bit, --repeat 3: pass=50 fail=0 nonexact=0.
  • 8 bit, --repeat 3: pass=49 fail=1. The one failure is a zero-copy run of psnr_luma on src01 that ended with SIGSEGV (rc 139) right after the import line was logged. It did not recur: psnr_luma 20 of 20, then all nine stage-1 cases on both clips with --repeat 10, 180 of 180.

What we could not confirm

ADR-1763's dropped import did not show on our host. I removed the immediate property from the primary queue locally and re-ran the nine stage-1 cases on both clips with --repeat 10: 180 zero-copy runs, none different from host upload (pass=18 fail=0 nonexact=0). So on xe the change does no harm, but we cannot say it is needed there; your measurements were on i915.

What the project's rules need before it can land

1. Rebase onto master, and off build(container): GCC for CPU C, icpx for SYCL, and a Containerfile.vmafx SYCL + FFmpeg image (ADR-1714, ADR-1715) #2216. The branch conflicts with master in 32 files (5 under core/, 11 FFmpeg patches, 15 docs pages and the citation map). Your 11 commits touch none of build(container): GCC for CPU C, icpx for SYCL, and a Containerfile.vmafx SYCL + FFmpeg image (ADR-1714, ADR-1715) #2216's toolchain files, so this PR does not have to wait for it: the docs/state.md row for the probe can be opened and closed here.
2. Drop what master already has. vmaf_sycl_upload_plane() waits for its copy on master since fix(sycl): return from vmaf_sycl_upload_plane only after its copy has completed #2102 (core/src/sycl/common.cpp:957). Still new on master: the immediate primary queue, the timing line through vmaf_log, the probe fix, the twin routing in patch 0005, and the harness. Master's series has 22 patches now.
3. The harness on other hosts. To run it here I needed three local changes:
   • scripts/test/zerocopy-e2e.sh:55 hard-codes /dev/dri/renderD128; on a host with several GPUs the Intel one can be elsewhere (here renderD130), so the node has to be a parameter.
   • With every GPU passed in, hevc_qsv opened the first render node and failed; the encode step has to name its device as the decode legs do.
   • QSV encode fails on our xe stack (Invalid FrameType:0) while QSV decode works. A way to feed pre-encoded clips, or a software encoder as fallback, lets the harness run where only decode is available.
4. Smaller points. scripts/test/sycl-dev-container.sh:108 ends in || true. The builds inside it use every core (ninja, make -j"$(nproc)"); a jobs parameter helps on shared hosts.

Our offer

You do not have to do this rework. We can do it on top of your 11 commits, with your authorship kept, and show you the result before it lands:

• the rebase onto master without build(container): GCC for CPU C, icpx for SYCL, and a Containerfile.vmafx SYCL + FFmpeg image (ADR-1714, ADR-1715) #2216, leaving out what master already has,
• the harness changes of point 3 (render node as a parameter, the encode device, pre-encoded clips or a software encoder),
• the smaller points of point 4.

Is that fine with you? Say if you would rather do some or all of it yourself.

What only you can answer or do

• The SIGSEGV. One crash in 254 eight-bit zero-copy runs is too rare for us to say where it comes from, and we have no backtrace. Have you seen rc 139 in your runs on i915? If you have a log, please attach it.
• ADR-1763. Which kernel driver and which compute-runtime version did your measurements run on? With that the record says where the failure was seen; we can add the line once you tell us.
• The sign-off. The project asks for a Signed-off-by line on every commit since 2026-10-09 (this PR is older, so the check does not stop it). The line is the Developer Certificate of Origin: with it the author states that they wrote the change or have the right to submit it under the project's licence. Our commits carry our own; nobody but you can add yours, and we need it before your code lands through our rework: on your commits, or as an explicit statement in this thread. To add it: git rebase --signoff 2f95aa87f, then git push --force-with-lease to your branch (DCO sign-off).