From daaceac9a9b7cb5d69fdcfb9b78dcd8993440b7d Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Fri, 6 Nov 2026 22:18:16 -0400 Subject: [PATCH] npu_import_contract: bound the advertisement read to the import branch, and test it The review of #1283 is right and the defect was in the test: the advertisement read was a whole-file awk search for FOREIGN_API, so a pin that narrows the import class still read as advertising it. Two bounds, both load-bearing -- the ordinal-0 class advertises the same flag, and the import class clears it on the opaque-fd entry it clones, which a plain search reads as an advertisement. pinned file old=yes new=yes pinned file, import flag dropped (review) old=yes new=(nothing) fixture: advertising import class old=yes new=yes fixture: narrowed import class old=yes new=(nothing) The negative case now has a test, and it needs no device: CTest npu_import_advert reads the two fixtures and requires advertised on one and not the other, plus the pinned file when the submodule is present. The fixtures are synthetic (the original's shapes, not its text) so no third-party notice is dragged in. Also the two wording points: the dma-buf-fd and opaque-fd transports are counted and asserted apart, since only the first carries FOREIGN_API; and the 8-arm floor is named as the pinned CTS's count, additive on purpose. docs/zero-copy.md says the same in prose. Refs #812 #753 --- CMakeLists.txt | 5 ++ docs/zero-copy.md | 32 +++++--- tests/fixtures/import_profile_foreign_api.c | 64 ++++++++++++++++ tests/fixtures/import_profile_narrowed.c | 64 ++++++++++++++++ tests/npu_import_contract.sh | 84 +++++++++++++++++---- 5 files changed, 224 insertions(+), 25 deletions(-) create mode 100644 tests/fixtures/import_profile_foreign_api.c create mode 100644 tests/fixtures/import_profile_narrowed.c diff --git a/CMakeLists.txt b/CMakeLists.txt index 0fbb74e28..bcf913af0 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -215,6 +215,11 @@ set_tests_properties(npu_repack_path PROPERTIES SKIP_RETURN_CODE 77) add_test(NAME npu_import_contract COMMAND ${CMAKE_SOURCE_DIR}/tests/npu_import_contract.sh ${CMAKE_SOURCE_DIR}) set_tests_properties(npu_import_contract PROPERTIES SKIP_RETURN_CODE 77) +# The advertisement half of that test is a parse of the pinned libamdf, so it is tested device-free here: the +# two fixtures are an advertising import profile and the same profile with the flag dropped from its dma-buf +# entry. Runs everywhere, needs no array, no GPU and no submodule (the pinned file is read only if present). +add_test(NAME npu_import_advert + COMMAND ${CMAKE_SOURCE_DIR}/tests/npu_import_contract.sh --self-test) # engine#876: the gate row for a folded (pb16i/t2s) container. Its device half needs the array, but its # assertion does not: these are the accept/refuse cases of `scripts/npu-window11.sh --compare` on hand-written # logs -- folded against folded passes, one differing rotated activation fails, a folded log against a plain one diff --git a/docs/zero-copy.md b/docs/zero-copy.md index 6d6770f11..81a04a151 100644 --- a/docs/zero-copy.md +++ b/docs/zero-copy.md @@ -160,17 +160,27 @@ engine#1134); until the owner authorises loading it, the exporter-mapping route That is also a contract question, and `tests/npu_import_contract.sh` (CTest `npu_import_contract`) is where it is checked instead of remembered. The pinned `libamdf` advertises -`AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_FOREIGN_API` with device read/write on its import memory profile -(ordinal 1, `libamdf/src/xdna/umd/drm/memory_profile.c`), i.e. "import a foreign dma-buf and execute on -it". `libamdf`'s import path takes host access through an amdxdna `mmap` of the import, which is the -poisoning path in the table above, so on the shipping module that capability is advertised and refused. The -test reads the advertisement from the pin, measures the behaviour with `libamdf`'s own CTS (GPU export -> NPU -import -> NPU executes on the imported range, plus registered caller pages as the control), and keys the -expected pairing on the loaded module's `srcversion` against the fingerprint table in -`third_party/patches/amdxdna/README.md`. Run it with `ONEBIT_IMPORT_CONTRACT=advertised` for the acceptance -form: it is red while a module without `0006`/`0007` is loaded, and green when one that carries them is -(measured 2026-11-06 on `EE1F36A2B9BA294CE11AD80`, the c26 driver: binding 7/7 pass, the array executes -registered caller pages, and 8 of 8 imported-backing arms fail at `kernel_queue_create`). +`AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_FOREIGN_API` with device read/write on the **dma-buf-fd entry** of its +import memory profile (ordinal 1, `libamdf/src/xdna/umd/drm/memory_profile.c`), i.e. "import a foreign +dma-buf and execute on it". The **opaque-fd entry** in the same profile is cloned from that one and then has +the flag cleared, carrying the direct-host provenance instead -- a different advertisement for the same +execution, which is why the acceptance below covers both transports and reports them apart. `libamdf`'s +import path takes host access through an amdxdna `mmap` of the import, which is the poisoning path in the +table above, so on the shipping module that capability is advertised and refused. The test reads the +advertisement from the pin, measures the behaviour with `libamdf`'s own CTS (GPU export -> NPU import -> NPU +executes on the imported range, plus registered caller pages as the control), and keys the expected pairing on +the loaded module's `srcversion` against the fingerprint table in `third_party/patches/amdxdna/README.md`. +Run it with `ONEBIT_IMPORT_CONTRACT=advertised` for the acceptance form: it is red while a module without +`0006`/`0007` is loaded, and green when one that carries them is (measured 2026-11-06 on +`EE1F36A2B9BA294CE11AD80`, the c26 driver: binding 7/7 pass, the array executes registered caller pages, and +8 of 8 imported-backing arms fail at `kernel_queue_create`). + +The advertisement half is a parse of the pin, so it has a device-free test of its own: CTest +`npu_import_advert` (`tests/npu_import_contract.sh --self-test`) reads two fixtures — an advertising pin and +the same pin with the flag dropped from the import class' dma-buf entry — and requires `advertised` on the +first and *not* on the second. Both bounds it needs are load-bearing and were both wrong in the first +version: the ordinal-0 class advertises the same flag, and the import class clears it on the opaque-fd entry +it clones, so a whole-file search reports a narrowed pin as advertising (engine#1283's review). The NPU BO to dma-buf direction still does not exist: the export `PRIME_HANDLE_TO_FD` returns ENOENT for the handle the runtime produces, so an NPU-owned buffer cannot yet be handed to the GPU. Nothing on the serving diff --git a/tests/fixtures/import_profile_foreign_api.c b/tests/fixtures/import_profile_foreign_api.c new file mode 100644 index 000000000..3f4f5ec46 --- /dev/null +++ b/tests/fixtures/import_profile_foreign_api.c @@ -0,0 +1,64 @@ +// Copyright 2026 bong-water-water-bong +// SPDX-License-Identifier: Apache-2.0 +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// The shape of libamdf's XDNA memory profile that tests/npu_import_contract.sh has to read, reduced to the +// lines that decide it (the pinned source is third_party/hrx-system, memory_profile.c). This is the +// advertising pin: the ordinal-1 (import) branch sets FOREIGN_API on its dma-buf-fd entry. +// +// Three shapes here are the whole reason the scan is not a grep: the ordinal-0 branch advertises the flag +// too (so a whole-file search cannot tell a narrowed import class from a create class), and the ordinal-1 +// branch CLEARS the flag on the opaque-fd entry it clones (so a scan that ignores negated uses reads that +// clear as an advertisement -- engine#1283's review). +// +// Synthetic on purpose: a copy of the third-party file would drag its notice and its licence into this tree +// for a four-line question. The indentation and the two-entry clone are the original's. + if (memory_profile_ordinal == 0) { + profile.external_memory_support_count = 2; + profile.external_memory_support[0] = (amdf_external_memory_support_t){ + .type = AMDF_EXTERNAL_MEMORY_TYPE_DMA_BUF_FD, + .flags = AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_EXPORT | + AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_CROSS_PROCESS | + AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_FOREIGN_API, + }; + profile.external_memory_support[1] = profile.external_memory_support[0]; + profile.external_memory_support[1].type = + AMDF_EXTERNAL_MEMORY_TYPE_OPAQUE_FD; + profile.external_memory_support[1].flags &= + ~AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_FOREIGN_API; + } else if (memory_profile_ordinal == 1) { + profile.roles = + AMDF_MEMORY_PROFILE_ROLE_IMPORT | AMDF_MEMORY_PROFILE_ROLE_HOST_MAP; + profile.external_memory_support_count = 2; + profile.external_memory_support[0] = (amdf_external_memory_support_t){ + .type = AMDF_EXTERNAL_MEMORY_TYPE_DMA_BUF_FD, + .flags = AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_IMPORT | + AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_SOURCE_OFFSET | + AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_CROSS_PROCESS | + AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_FOREIGN_API, + .source_offset_alignment = 1, + .byte_length_alignment = 1, + }; + profile.external_memory_support[1] = profile.external_memory_support[0]; + profile.external_memory_support[1].type = + AMDF_EXTERNAL_MEMORY_TYPE_OPAQUE_FD; + profile.external_memory_support[1].provenance = + (amdf_external_memory_provenance_t) + AMDF_LINUX_DMA_BUF_DIRECT_HOST_PROVENANCE; + profile.external_memory_support[1].flags &= + ~AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_FOREIGN_API; + } else { + profile.roles = + AMDF_MEMORY_PROFILE_ROLE_REGISTER | AMDF_MEMORY_PROFILE_ROLE_HOST_MAP; + } diff --git a/tests/fixtures/import_profile_narrowed.c b/tests/fixtures/import_profile_narrowed.c new file mode 100644 index 000000000..2edd8a4a5 --- /dev/null +++ b/tests/fixtures/import_profile_narrowed.c @@ -0,0 +1,64 @@ +// Copyright 2026 bong-water-water-bong +// SPDX-License-Identifier: Apache-2.0 +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// The same profile as import_profile_foreign_api.c with ONE change: the ordinal-1 (import) branch no longer +// sets FOREIGN_API on its dma-buf-fd entry. That is the narrowing the contract test exists to notice -- and +// the case that used to read as `advertised=yes`, because the ordinal-0 branch still advertises the flag and +// the ordinal-1 branch still mentions it in the opaque-fd clear (engine#812 option 2, engine#1283 review). +// +// Three shapes here are the whole reason the scan is not a grep: the ordinal-0 branch advertises the flag +// too (so a whole-file search cannot tell a narrowed import class from a create class), and the ordinal-1 +// branch CLEARS the flag on the opaque-fd entry it clones (so a scan that ignores negated uses reads that +// clear as an advertisement -- engine#1283's review). +// +// Synthetic on purpose: a copy of the third-party file would drag its notice and its licence into this tree +// for a four-line question. The indentation and the two-entry clone are the original's. + if (memory_profile_ordinal == 0) { + profile.external_memory_support_count = 2; + profile.external_memory_support[0] = (amdf_external_memory_support_t){ + .type = AMDF_EXTERNAL_MEMORY_TYPE_DMA_BUF_FD, + .flags = AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_EXPORT | + AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_CROSS_PROCESS | + AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_FOREIGN_API, + }; + profile.external_memory_support[1] = profile.external_memory_support[0]; + profile.external_memory_support[1].type = + AMDF_EXTERNAL_MEMORY_TYPE_OPAQUE_FD; + profile.external_memory_support[1].flags &= + ~AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_FOREIGN_API; + } else if (memory_profile_ordinal == 1) { + profile.roles = + AMDF_MEMORY_PROFILE_ROLE_IMPORT | AMDF_MEMORY_PROFILE_ROLE_HOST_MAP; + profile.external_memory_support_count = 2; + profile.external_memory_support[0] = (amdf_external_memory_support_t){ + .type = AMDF_EXTERNAL_MEMORY_TYPE_DMA_BUF_FD, + .flags = AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_IMPORT | + AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_SOURCE_OFFSET | + AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_CROSS_PROCESS, + .source_offset_alignment = 1, + .byte_length_alignment = 1, + }; + profile.external_memory_support[1] = profile.external_memory_support[0]; + profile.external_memory_support[1].type = + AMDF_EXTERNAL_MEMORY_TYPE_OPAQUE_FD; + profile.external_memory_support[1].provenance = + (amdf_external_memory_provenance_t) + AMDF_LINUX_DMA_BUF_DIRECT_HOST_PROVENANCE; + profile.external_memory_support[1].flags &= + ~AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_FOREIGN_API; + } else { + profile.roles = + AMDF_MEMORY_PROFILE_ROLE_REGISTER | AMDF_MEMORY_PROFILE_ROLE_HOST_MAP; + } diff --git a/tests/npu_import_contract.sh b/tests/npu_import_contract.sh index 46047663d..fa86873c6 100755 --- a/tests/npu_import_contract.sh +++ b/tests/npu_import_contract.sh @@ -45,10 +45,55 @@ # so public CI neither runs nor fails it: # ONEBIT_LIBAMDF_CTS_DIR=/libamdf ctest -R npu_import_contract # +# The advertisement read is a parse of the pin, so it has its own device-free test: +# tests/npu_import_contract.sh --self-test (CTest `npu_import_advert`) +# whose fixtures are the two shapes that decide it: the advertising pin, and the same pin with the flag +# dropped from the import class' dma-buf entry -- the narrowing this test is supposed to notice, and the +# case that read as `advertised=yes` while the scan was a whole-file search (engine#1283's review). +# # usage: tests/npu_import_contract.sh [env: ONEBIT_LIBAMDF_CTS_DIR, AMDF_GPU_TARGET] +# tests/npu_import_contract.sh --self-test set -uo pipefail -root=${1:?usage: npu_import_contract.sh } +fail=0 +check() { if eval "$2"; then echo "ok $1"; else echo "FAIL $1"; [ -n "${3:-}" ] && echo " $3"; fail=1; fi; } + +# The advertisement: AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_FOREIGN_API *set* on an entry of the ordinal-1 +# (import) branch of libamdf's XDNA memory profile. Two bounds, and both are load-bearing: +# - the branch, because the ordinal-0 (create) class advertises the same flag, so a whole-file search +# cannot tell a pin that narrowed the import class from one that did not; +# - negated uses, because the import branch clears the flag on the opaque-fd entry it clones from the +# dma-buf one (`flags &= ~AMDF_..._FOREIGN_API`), which a plain grep reads as an advertisement. +advertises_foreign_api() { + awk ' + /memory_profile_ordinal == 1/ { in_branch = 1; next } + in_branch && /^ } else/ { exit } + in_branch && /FOREIGN_API/ && !/~[[:space:]]*AMDF_EXTERNAL_MEMORY_SUPPORT_FLAG_FOREIGN_API/ { + print "yes"; exit + } + ' "$1" +} + +if [ "${1:-}" = --self-test ]; then + here=$(cd "$(dirname "$0")" && pwd) + check "an advertising pin reads as advertised" \ + "[ -n \"\$(advertises_foreign_api '$here/fixtures/import_profile_foreign_api.c')\" ]" \ + "the fixture that sets FOREIGN_API on the import class' dma-buf entry read as not advertised" + check "a pin that drops it from the import class reads as narrowed" \ + "[ -z \"\$(advertises_foreign_api '$here/fixtures/import_profile_narrowed.c')\" ]" \ + "the flag was still found: the scan is reading the ordinal-0 class or the opaque-fd clear" + pinned=$here/../third_party/hrx-system/libamdf/src/xdna/umd/drm/memory_profile.c + if [ -f "$pinned" ]; then + check "the pinned libamdf advertises it today" \ + "[ -n \"\$(advertises_foreign_api '$pinned')\" ]" \ + "$pinned no longer sets FOREIGN_API on the import class: re-read docs/zero-copy.md's contract" + else + echo "note: $pinned is not checked out (submodule), so only the fixtures were read" + fi + exit $((fail)) +fi + +root=${1:?usage: npu_import_contract.sh | --self-test} cts=${ONEBIT_LIBAMDF_CTS_DIR:-} gfx=${AMDF_GPU_TARGET:-gfx1151} strict=${ONEBIT_IMPORT_CONTRACT:-table} @@ -60,9 +105,6 @@ if [ -z "$cts" ] || [ ! -x "$cts/libamdf_cts_interop_gpu_xdna_recipes_execution_ exit 77 fi -fail=0 -check() { if eval "$2"; then echo "ok $1"; else echo "FAIL $1"; [ -n "${3:-}" ] && echo " $3"; fail=1; fi; } - loaded=$(cat /sys/module/amdxdna/srcversion 2>/dev/null) [ -n "$loaded" ] || { echo "skip: amdxdna is not loaded"; exit 77; } @@ -70,9 +112,7 @@ loaded=$(cat /sys/module/amdxdna/srcversion 2>/dev/null) profile=$root/third_party/hrx-system/libamdf/src/xdna/umd/drm/memory_profile.c [ -f "$profile" ] || { echo "skip: $profile is not checked out (submodule)"; exit 77; } advertised=no -if awk '/memory_profile_ordinal == 1/{f=1} f&&/FOREIGN_API/{print "yes"; exit}' "$profile" | grep -q yes; then - advertised=yes -fi +[ -n "$(advertises_foreign_api "$profile")" ] && advertised=yes check "the pinned libamdf advertises FOREIGN_API on the import class" "[ '$advertised' = yes ]" \ "no FOREIGN_API in $profile's ordinal-1 branch: the contract below is the narrowed one" @@ -106,14 +146,28 @@ check "control: the array executes (registered caller pages)" \ "$(grep -A2 'RUN.*RegisteredCausalRoundTrip' "$log/exec.txt" | head -3)" imported=$(grep -cE '^\[ RUN \] ImportedBacking/' "$log/exec.txt") imported_ok=$(grep -cE '^\[ OK \] ImportedBacking/' "$log/exec.txt") +# 8 is the count at the pinned hrx-system (7f4236924a): four arms per transport. Additive on purpose -- +# a pin that grows the CTS raises this floor rather than failing the test. check "the run covered the imported-backing cases" "[ '$imported' -ge 8 ]" "only $imported arm(s) ran" +# The two transports are advertised differently and the review of #1283 is right that the labels have to +# say so: the dma-buf-fd entry carries FOREIGN_API, the opaque-fd entry is cloned from it and then has the +# flag cleared, carrying the direct-host provenance instead. Both are required here -- they are two +# descriptors for the same execution -- but they are counted and reported apart. +dma_buf=$(grep -cE '^\[ RUN \] ImportedBacking/.*/DmaBuf' "$log/exec.txt") +opaque=$(grep -cE '^\[ RUN \] ImportedBacking/.*/Opaque' "$log/exec.txt") +dma_buf_ok=$(grep -cE '^\[ OK \] ImportedBacking/.*/DmaBuf' "$log/exec.txt") +opaque_ok=$(grep -cE '^\[ OK \] ImportedBacking/.*/Opaque' "$log/exec.txt") + if [ "$carrier" = yes ] && [ "$advertised" = yes ]; then - # The pair is loaded: the advertisement must be true, arm by arm. - check "execution on an imported dma-buf ($imported arms, the advertised capability)" \ - "[ '$imported_ok' = '$imported' ]" \ - "$(grep -E '^\[ FAILED \] ImportedBacking/' "$log/exec.txt" | head -3)" - verdict="delivers what it advertises" + # The pair is loaded: the advertised capability must hold, and both transports must execute. + check "the dma-buf fd transport executes ($dma_buf arms: what FOREIGN_API advertises)" \ + "[ '$dma_buf_ok' = '$dma_buf' ] && [ '$dma_buf' -ge 1 ]" \ + "$(grep -E '^\[ FAILED \] ImportedBacking/.*/DmaBuf' "$log/exec.txt" | head -3)" + check "the opaque fd transport executes ($opaque arms: direct-host provenance)" \ + "[ '$opaque_ok' = '$opaque' ] && [ '$opaque' -ge 1 ]" \ + "$(grep -E '^\[ FAILED \] ImportedBacking/.*/Opaque' "$log/exec.txt" | head -3)" + verdict="delivers what it advertises (both transports)" elif [ "$carrier" = yes ]; then # Loaded and no longer advertised (the pin narrowed it): either result is honest, so only record it. echo "note: $imported_ok of $imported imported arms pass and the pin no longer advertises execution" @@ -122,14 +176,16 @@ elif [ "$strict" = advertised ] && [ "$advertised" = yes ]; then # The acceptance form: this is engine#812 itself -- a capability advertised and not delivered. echo "FAIL the pinned libamdf advertises FOREIGN_API dma-buf execution and amdxdna $loaded" echo " refuses it: $((imported - imported_ok)) of $imported imported arms failed" + echo " ($dma_buf_ok/$dma_buf dma-buf fd arms, $opaque_ok/$opaque opaque fd arms)" grep -m1 -A3 'kernel_queue_create' "$log/exec.txt" | sed 's/^/ /' fail=1 verdict="advertises execution it does not deliver (#812)" else # Documented state of a driver without the pair: imported execution is refused, and it must be # refused at the same place every time -- a different failure would be a different bug. - check "execution on an imported dma-buf is refused (module has no 0006/0007)" \ - "[ '$imported_ok' = 0 ]" "$imported_ok of $imported arms passed on a module without the pair" + check "execution on an imported range is refused (module has no 0006/0007)" \ + "[ '$imported_ok' = 0 ]" \ + "$imported_ok of $imported arms passed on a module without the pair ($dma_buf_ok/$dma_buf dma-buf, $opaque_ok/$opaque opaque)" check "the refusal is the import's, at kernel_queue_create" \ "grep -q 'kernel_queue_create' '$log/exec.txt'" \ "$(grep -E '^\[ PASSED \]|Failure' "$log/exec.txt" | head -3)"