ipu-stack

ipu-stack is a small collection of runtime, packaging, code-generation, and early graph-lowering components for Graphcore IPU21 devices. It does not yet contain the allocator or complete graph-to-device compiler.

Components

• ipu-exchange generates and encodes device and host exchange programs.
• ipu-codegen emits straight-line supervisor code from caller-resolved tile programs.
• ipu-elf compiles Graphcore tile sources and links Colossus ELF objects.
• ipu-package reads, writes, and validates .ipuexe application packages and cycle profiles.
• ipu-profile queries cycle profiles.
• ipu-driver initializes hardware, loads packages, and drives host exchange.
• ipu-runtime is a thin device/load/session wrapper.
• ipu-tests builds and runs the explicit hardware diagnostic package.
• ipu-cli exposes generic compile, link, inspect, profile, load, and host-run operations.

The device/ directory retains the static runtime support and generic FP16 and FP32 GEMM kernels. Workload-specific kernels and planners are intentionally out of scope.

Design boundary

ipu-codegen::build_package accepts a ComputeGraph and PackageConfig. The graph is shaped structured SSA. Its separate mid-level lowering selects precision and layout with a toy cost model and inserts explicit casts and rearrangements. Mid-to-low lowering then produces logical per-tile shard work, kernel runs, synchronized exchanges, and structured repeats. Package construction produces completion-only tile programs until SRAM placement, exchange encoding, and kernel-symbol selection are implemented. The config uses one shared PipelineConfig for target, tile count, input formats, operator catalog, scheduling, and profiling. PackageConfig adds the toolchain, static runtime source, and build directory.

TileProgram remains the finalized lower representation. Its exchange rows, addresses, kernel symbols, operands, arguments, and profile destinations are all explicit rather than inferred by codegen.

Build

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

The hardware test builds and round-trips its own package before loading it:

IPU_CONFIG=config.bin \
POPLAR_SDK_ENABLED=/path/to/poplar \
scripts/hardware-e2e.sh

The test checks that every supervisor and worker context halts after the

CLI

ipu-stack kernel-compile device/static_runtime.S /tmp/runtime \
  --sdk "$POPLAR_SDK_ENABLED"
ipu-stack object-inspect kernel.o
ipu-stack package-inspect application.ipuexe --bindings
ipu-stack profile-render profile.capnp -o profile.html
ipu-stack profile-query profile.capnp --group-by kernel
ipu-stack host-run application.ipuexe bootloader.elf config.bin graph

The CLI intentionally excludes graph construction, allocation, model commands, diagnostic workload generation, and format-conversion experiments.