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 306608b06..03d9a6902 100644 --- a/docs/zero-copy.md +++ b/docs/zero-copy.md @@ -171,17 +171,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)"