Iron

Curated map of the Iron docs. The top-level README is the project landing page. Start with the path that matches your task instead of reading the design archive in filename order.

Recommended reading paths

Understand Iron in an inference engine

1. Architecture for the Butter/Iron boundary, crate ownership, source-to-shader path, dispatch, and evidence lifecycle.
2. Testing for the layered correctness model and backend-specific hardware gates.
3. Qwen3.8 kernel architecture and TDD for a worked mixed-precision, hybrid, and speculative kernel boundary.

Write or optimize a kernel

1. Getting started.
2. Rapid Software Testing for risk, oracle, coverage, reachability, mutation, and evidence rules.
3. Developing, especially the dispatch hazards.
4. Kernel style guide.
5. Testing, then the relevant backend specification.
6. Rust efficiency before changing compiler, runtime, or generated-kernel performance.

Add or change a backend

1. Architecture.
2. CUDA backend, which defines the shared seam.
3. The target delta: AMD/HIP or Vulkan/SPIR-V.
4. Testing for the target inventory and promotion boundary.

Getting started

• Getting started — toolchain, clone, first build, first kernel.

Local development

• Developing — repo layout, the make dev loop, branching, commits, debugging, and the kernel-authoring hazards (⚠️) that cause silent or catastrophic failure. Required reading before writing a kernel.
• Kernel engineering guide — the guide to how Iron kernels are built, analysed, tested, measured, and improved, end to end: architecture, occupancy and DSL memory paths, the optimization loop, correctness/testing layers, the honest A/B measurement protocol, gates, a gotchas catalogue, and where a new contributor should start.
• Kernel style guide — the authority on how to write one kernel/bench/test: file shape, naming, #[kernel(variants(...))], shared primitives, the CPU oracle, the bench. The target style the library is migrating toward.
• Testing — the test layers, what runs in CI vs locally, how to write a test, coverage targets, and the gaps in the test infrastructure that let bugs through silently.
• Test inventory — the reproducible per-file audit queue for Rust, declarative GPU, ignored, and benchmark declarations.
• Rapid Software Testing — the Iron-specific session method for test and code reachability, named oracles, known-bad mutations, backend evidence, and honest handoffs.
• Rust efficiency — project rules for compiler/runtime allocations, deterministic codegen, kernel fusion, occupancy, numerical boundaries, and production receipts.
• Publishing — the dev → main release flow.

Reference

• Architecture — how a #[kernel] becomes a compiled shader, and how the bench runner, test runner, and kernel profiling work end-to-end (current in-process vs planned-subprocess execution model).
• CLI — the iron binary: bench, build, emit, inspect, device, snap, diff.
• Kernel audit — per-op coverage table: which MLX / Iron kernels are ported, partial, or still missing, with the gaps and open PRs called out.
• TensorOps primitive — extending the cooperative-tile (MPP matmul2d) family so Butter’s 15 hand-written MPP / simdgroup-matrix kernels become emitted kernels: inventory, the missing DSL surface, the header-skew / live-compile manifest fix, and the phased migration.
• Qwen3.8 kernel architecture and TDD: current dense and Flash-Next tracks, Butter/Iron ownership, kernel map, precision contracts, and test tiers.
• GDN prefill contract: recurrent-state math, chunking, and state-publication rules.

Design & planning

Long-form specs and design docs live in specs/.

• Bench metrics spec — planned iron bench measurement additions (latency, GFLOP/s, roofline/utilization, bottleneck) so kernels can actually be optimized and precisions compared; includes the precision-support roadmap (nvfp4/mxfp4/mxfp8) and M5 Neural Accelerator context.
• Kernel consolidation plan — the singular roadmap for restructuring wh-iron-std’s kernels: the kernels/<family>/ target layout, the three LOC-reduction tools, the proven conv/ exemplar, and the family-by-family migration order. (Authoring style lives in the style guide.)
• Hy3 MoE prep — kernel-layer readiness for Tencent Hy3 (hy_v3): router path choice, 192/top-8 shapes, oQ2 int2 expert path, local checkpoint notes.
• Toolchain design — the #[kernel] / #[bench] / #[test_kernel] macro surface and how the IR lowers to MSL.
• Proposed optimizations — hot-path patterns that need codegen-layer support, with rationale and implementation sketches.

Backend ports

Codegen-backend specs for taking the DSL beyond Metal. Each is a delta on the CUDA spec, which defines the shared backend seam.

• CUDA / NVIDIA — the backend-seam design (DSL → C++/PTX) the other ports build on.
• AMD / ROCm — HIP/ROCm delta on the CUDA seam.
• Vulkan / SPIR-V — portable compute via SPIR-V.
• Apple ANE — the Neural Engine: why it’s not directly programmable and what a port would entail.

See also

• Top-level README — project landing page.
• CONTRIBUTING — issue / PR process, agentic-contribution disclosure, code of conduct.