rustriton

Imported from zetanumbers/rustriton (AGENTS.md). Install upstream with npx skills add zetanumbers/rustriton. Copyright stays with the author.

Rustriton agent guidelines

Repository and scope

Rustriton is an independent Rust workspace. Its local checkout is ~/bisheng/rustriton; AscendNPU-IR is a separate sibling repository. The initial standalone snapshot has its own history. Do not import private repositories, their git history, metadata, source files, or build artifacts. Do not recreate the removed project symlinks in AscendNPU-IR.

The goal is a Rust kernel language whose examples closely resemble Triton. Continue porting existing Triton tutorials and language tests, using the public upstream implementation as the reference. Do not assume all Triton kernels or features have already been ported. Current blocks are one-dimensional f32; multidimensional tensors, dot/matmul, and autotuning still need further work.

Proceed with authorized implementation and routine choices. Ask when a real semantic or architectural ambiguity needs the user's decision. Keep the prototype clean: avoid convenience aliases, duplicate graph construction, and unnecessary public compiler implementation APIs.

Workspace layout

• src/: the public ascend_tile facade; keep existing crate names stable.
• frontend/: shared signature, grammar, and generic surface handling.
• compiler/: semantic checking, AST-to-graph lowering, module handling, specialization, diagnostics, MLIR construction, and the rustritonc CLI.
• macros/: procedural macro adapter calling the compiler library.
• core/: graph representation, textual TTIR export, CPU reference execution, artifact/ABI validation, typed kernels, and the CANN launcher.
• examples/, tests/, compiler/tests/: demonstrations and regression tests.
• docs/: technical investigations.

Accepted language and API decisions

• Compilation belongs to build-time procedural macros or rustritonc. AOT is enabled by default. Do not restore runtime compilation.
• Use proc_macro2/syn for the shared compiler path. Both file compilation and macros must retain source spans in diagnostics.
• #[kernel] mod is a compilation unit. Device helpers are checked and inlined within that unit. Nested modules and helpers imported from other kernel modules/crates have not been adopted.
• Named specializations use instantiate!(pub name = function::<values>); inside the kernel module. Do not restore an instantiate attribute. Validate generic grammar/types independently of specialization values; specialization must not be used to hide type errors.
• Keep BLOCK and compatible device indices/scalars as i32. Detect type mismatches rather than silently accepting usize/i32 combinations.
• Dependent buffer arguments such as n: i32, x: &[f32; n] are DSL syntax. Array lengths may contain integer literals, preceding integer arguments, and supported integer arithmetic. They are checked and erased for emitted host Rust; they do not imply Rust dependent types or proven memory safety.
• Rust ranges such as 0..BLOCK may represent lane indices. Use Triton-like tl::load/tl::store, masks, and explicit tl::select. Do not restore lane-wise if or memory indexing as load/store syntax. Scalar device loops use the existing checked loop syntax; ordinary if is not yet supported.
• Floating unary negation follows the accepted Triton semantics 0.0 - x, including its signed-zero behavior.
• Preserve supported public operations that have Triton counterparts. Compiler/expansion-only helpers belong in hidden implementation support.
• Kernels have typed Kernel<(ArgTy1, ArgTy2, ...)> interfaces and return no device value. run and run_device remain unsafe: arbitrary masks, buffer bounds, aliasing, and writes are not fully proven by the compiler. Keep the launch interface transparent and document concrete caller duties.

Compiler backend

compiler/src/mlir/lower.rs constructs TTIR operations, SSA operands, blocks, function arguments, and loop/reduction/scan regions directly through MLIR C API. Do not restore whole-module textual TTIR parsing in the production path. Small type/attribute parsers remain in use. Textual TTIR is still useful for inspection, CPU graph examples, and reference equivalence tests.

The backend is libBiShengIRCompileCAPI.so, built by the sibling AscendNPU-IR repository. Both Cargo macro compilation and the CLI use BISHENGIR_LIBRARY. The older BISHENGIR_COMPILE setting only locates the sibling shared library; Rustriton does not launch bishengir-compile.

Use opaque handles from the same loaded MLIR library. Keep that library loaded for the process lifetime, serialize compilation, and destroy owned modules, contexts, and diagnostic handlers on success and failure. Preserve binary, metadata, and compiler-added argument validation before embedding artifacts. Changes to the C++ bridge/pipeline belong in AscendNPU-IR, not this workspace. Follow that repository's own AGENTS.md and formatting rules when modifying it.

Final code generation still invokes CANN tools (bisheng, with linking tools where needed) and uses temporary files. Do not claim compilation is entirely in-process. CANN 9.2.0-beta.2 libasrtc was tested: it rejects -x ir, parses LLVM IR as CCE source, and spawns ccec/ld.lld. It is not a replacement for our LLVM IR backend; see docs/asrtc-investigation.md.

Build and verification

Use stable Rust. For CPU/frontend/compiler work without the native backend:

cargo +stable test --workspace --no-default-features
cargo +stable clippy -p rustriton_compiler --all-targets -- -D warnings
cargo +stable fmt --all -- --check

For AOT compilation, build the matching AscendNPU-IR BiShengIRCompileCAPI target and configure the library:

export BISHENGIR_LIBRARY="$HOME/bisheng/AscendNPU-IR/build/lib/libBiShengIRCompileCAPI.so"
cargo +stable build --features npu --example mandelbrot_manual

Native compilation also requires the matching CANN environment, including bisheng in PATH or BISHENG_INSTALL_PATH pointing to its binary directory. The current compile bridge targets Ascend950PR_9589, pure SIMT, four warps, 32 threads per warp, and 122880 bytes of dynamic UB. Do not silently change these defaults or infer physical hardware compatibility from simulator tests.

The tested simulator environment is Docker image bluesim-dev:9.2 containing CANN 9.2.0-beta.2. The wrapper mounts this standalone project, the compiler build, and cached Rust dependencies. Its run directory must not exist yet:

ASCEND_TILE_EXAMPLE=vector_add_manual \
  bash examples/run_simulator_container.sh /tmp/rustriton-manual-new-run

Other useful example choices include mandelbrot_manual, block_reductions, block_scans, seeded_dropout, and vector_add_instances. Require the script's success marker and checked CPU/guard-tail results, not just a generated ELF. For native MLIR equivalence and failure-path tests, run the ignored compiler library tests inside the matching CANN environment:

cargo +stable test -p rustriton_compiler --lib -- --ignored

Run tests appropriate to a change. For lowering/runtime changes, check masked and empty tails, guard regions, reduction neutral values, multiple instances, and repeated calls/failures as relevant. Compare numerical tolerances and special-value semantics to the actual Triton implementation. The CPU reference interpreter is a checker, not an NPU launch or proof of device correctness. The standalone migration passed 159 normal tests and the manual-launch simulator example; the native lowering equivalence test covers 47 cases.

Git workflow

Keep work in this standalone repository and commit completed changes. Do not publish or add a remote unless requested. Preserve unrelated user changes. Use codex/ for new working branches. Commit messages use this format:

[Triton] feat: concise imperative description

Motivation: Why the change is needed.
Design: The approach and significant choices.
Risks: Known risks, or None.

Assisted-by: AI

Use feat, fix, doc, refactor, or chore; a useful component may be added as a second bracket, for example [Triton][Launcher]. Never commit target/, compiler intermediates, generated kernel binaries, machine-specific caches, or private repository metadata. Keep source and documentation in sync.