Wire TOSA admission and the compiler helper for IDENTITY (#89)

[aravishankar-mp]

Why

Fourth code ticket of the AMD XDNA wayfinder map (#78): TOSA graphs now compile and run on the NPU. Implements the compiler-helper contract (#84) and TOSA admission (#83) for the first tier operator — BF16 IDENTITY — end to end.

Stacked: based on task/xdna-execution-lifecycle (PR #134), which is based on task/xdna-ffi-buffers (PR #127). Review #127 → #134 → this. Rebases onto main as they land.

Highlights:

• src/lower.rs — portable TOSA admission: parse + analyze_for + a strict subset check that turns an artifact into a validated CompilerSpec (integers and enums only) and rejects anything outside the BF16 IDENTITY subset before any subprocess runs. Unit-tested on every host (CI): admits BF16 identity; rejects FP32, non-line-size shapes, and the wrong target.
• compiler/xdna_compile.py — the embedded aiecc helper: an IDENTITY IRON template + spec-driven compile + a toolchain-identity mode, self-configuring the pinned toolchain (NPU_RUNTIME=hrx for the unfolded ABI, Peano/xclbinutil/HRX paths) under a cleared environment.
• src/compiler.rs — the bounded subprocess driver: cleared env + pinned prefix + private workdir, wall-clock timeout, own process group, and a content-addressed artifact cache (spec ‖ toolchain ‖ helper source). Never a Cargo dependency, never in-process.
• src/native.rs load_program — precompiled artifacts load directly; a TOSA artifact is admitted, compiled, and built into an executable (shared build_executable). compile_artifact exposes the admit-then-compile path without a device — the offline / catalog-population use from Decide the compiler-helper subprocess contract #84.
• Tests — CI admission unit tests; a hardware-free golden artifact test (compile IDENTITY, assert xclbin magic + FP32 rejection); and the on-NPU test compiling a TOSA BF16 IDENTITY through the helper and asserting output == input.

Deferred: MATMUL (#90), MAX_POOL2D (#91), full conformance + device-loss tier-2 (#92). The compute tiers add IRON templates to the same helper and dtype/op arms to admission.

Compatibility

• No wire effect. No accepted or emitted protocol bytes change.

Checklist

• Does not alter payload lengths, ownership, reset, error, timeout, or feature-negotiation behavior.
• Authoritative conformance inputs untouched.
• Public Rust API: adds compile_artifact and the portable lower::{admit, CompilerSpec, ...}; the TOSA path in load_program. No core/guest/device/transport changes.
• No dependency/feature/target moves platform behavior into a portable crate — native path and compiler gated behind va_xdna; the compiler is a subprocess, not a linked dependency.
• Unsafe under audit: no new unsafe (the compiler driver is safe code); SAFETY.md notes compiler.rs is safe; the FFI/native audit and release-policy entry stand.
• Deferred features unadvertised: only BF16 IDENTITY compiles; other ops/dtypes and the integer target are rejected at admission.

Verification

On the reference machine (Fedora 44, Krackan NPU, pinned toolchain):

cargo test -p virtio-accel-xdna            # incl. on-NPU TOSA IDENTITY compile+run (output == input)
# placeholder path (no HRX — the CI default): admission unit tests run here
cargo fmt --all -- --check
cargo clippy -p virtio-accel-xdna --all-targets --all-features -- -D warnings
RUSTDOCFLAGS=-D warnings cargo doc -p virtio-accel-xdna --no-deps
python3 ci/check-release-policy.py         # 17 published packages OK
python3 ci/publish-dry-run.py              # ordered dry run passed for all 17 crates

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Wires end-to-end TOSA BF16 IDENTITY support for the AMD XDNA backend by adding a portable TOSA admission layer, a bounded compiler-helper subprocess that produces precompiled artifacts, and native load_program support to admit+compile TOSA artifacts at load time (with new on-hardware tests).

Changes:

• Add portable TOSA admission (lower::admit) that validates a strict BF16 IDENTITY subset and emits a CompilerSpec.
• Add a bounded compiler-helper subprocess driver (src/compiler.rs) plus embedded helper script (compiler/xdna_compile.py) and a content-addressed artifact cache.
• Extend native load_program to accept either precompiled artifacts directly or TOSA artifacts via admit-then-compile; add hardware and compiler tests.

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/release-policy.md	Updates release policy entry to reflect the new tosa-build dev dependency usage.
docs/portability.md	Updates portability docs to describe compilation and on-device testing behavior.
crates/virtio-accel-xdna/tests/hardware.rs	Adds hardware-free compile test and on-NPU BF16 IDENTITY compile+run test.
crates/virtio-accel-xdna/src/native.rs	Extends load_program to accept TOSA artifacts by admitting+compiling them; factors out executable construction.
crates/virtio-accel-xdna/src/lower.rs	Implements portable TOSA admission into CompilerSpec for BF16 IDENTITY subset + unit tests.
crates/virtio-accel-xdna/src/lib.rs	Re-exports admission API/types and adds public compile_artifact entry point (va_xdna).
crates/virtio-accel-xdna/src/compiler.rs	Adds bounded subprocess compiler driver with cache and helper embedding.
crates/virtio-accel-xdna/SAFETY.md	Updates safety scope notes to include the safe compiler driver and compiled path.
crates/virtio-accel-xdna/README.md	Updates crate README to describe new TOSA compilation support and offline compilation path.
crates/virtio-accel-xdna/compiler/xdna_compile.py	Adds the embedded compiler helper script (compile + identity modes).
crates/virtio-accel-xdna/Cargo.toml	Adds virtio-accel-tosa-build as a dev-dependency for test graph construction.
Cargo.lock	Records the new dev-dependency resolution.

Suppressed comments (2)

crates/virtio-accel-xdna/src/compiler.rs:172

• The helper is placed in its own process group (process_group(0)), but on timeout only the immediate child is killed. Any subprocesses spawned by the toolchain may survive, breaking the “bounded subprocess” guarantee. Consider killing the whole process group on timeout (e.g., killpg/SIGKILL) in addition to child.kill().

                    if Instant::now() >= deadline {
                        let _ = child.kill();
                        let _ = child.wait();
                        return Err(external(code::TIMEOUT));

crates/virtio-accel-xdna/src/compiler.rs:125

• cache_key hashes only the toolchain path, not a measured toolchain identity. If the toolchain is updated in-place (same prefix), the cache can serve stale artifacts. Since the helper already has an identity mode, consider incorporating its output (and/or hashes/mtimes of key tool binaries) into the cache key so updates invalidate correctly.

        1u32.hash(&mut hasher); // key schema version
        spec.hash(&mut hasher);
        self.toolchain.hash(&mut hasher);
        HELPER_SOURCE.hash(&mut hasher);
        format!("{:016x}", hasher.finish())

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.