Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
32 changes: 21 additions & 11 deletions docs/zero-copy.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
64 changes: 64 additions & 0 deletions tests/fixtures/import_profile_foreign_api.c
Original file line number Diff line number Diff line change
@@ -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;
}
64 changes: 64 additions & 0 deletions tests/fixtures/import_profile_narrowed.c
Original file line number Diff line number Diff line change
@@ -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;
}
84 changes: 70 additions & 14 deletions tests/npu_import_contract.sh
Original file line number Diff line number Diff line change
Expand Up @@ -45,10 +45,55 @@
# so public CI neither runs nor fails it:
# ONEBIT_LIBAMDF_CTS_DIR=<build>/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 <repo root> [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 <repo root>}
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 <repo root> | --self-test}
cts=${ONEBIT_LIBAMDF_CTS_DIR:-}
gfx=${AMDF_GPU_TARGET:-gfx1151}
strict=${ONEBIT_IMPORT_CONTRACT:-table}
Expand All @@ -60,19 +105,14 @@ 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; }

# The advertisement, read from the pinned UMD at the branch that describes the import class.
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"

Expand Down Expand Up @@ -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"
Expand All @@ -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)"
Expand Down
Loading