TheRock/rocm-systems/emulation/mirage/README.md

mirage

mirage is the user-facing UX — a command-line tool and an optional web dashboard — for the rocjitsu GPU emulator and other emulator backends. It lets you run real ROCm applications on top of an emulated GPU without changing the application, and inspect, script, and recover from the emulation as easily as you read a file.

$ mirage profile create cdna4 --emulator rocjitsu --agent MI350X
$ mirage run --profile cdna4 -- ./my-rocm-app --flag

Why mirage

• All state lives on disk in standard XDG locations. There is no required background daemon to keep state alive: the CLI and the per-session host processes coordinate exclusively through well-defined files. You can inspect everything with ls, cat, and tail -f.
• Easy to script. Every list/show command accepts --json for machine-readable output, and exit codes are predictable.
• Crash-resilient. Because state is on disk, a crashed CLI or host can be restarted and pick up where it left off.
• A drop-in for rocjitsu. mirage --config cfg.json -- ./app works just like the upstream rocjitsu CLI, so existing scripts keep running.

Core concepts

Concept	What it is
Emulator	A backend that runs GPU code (rocjitsu, rocjitsu-dbt, hotswap, noop).
Agent	A hardware GPU definition (e.g. MI300X, MI350X, MI450X).
Topology	A rack/node/GPU layout that references an agent.
Profile	A reusable preset binding an emulator + topology + options.
Session	A long-lived context (one host process) that hosts an emulator and runs execs.
Exec	A single command invocation inside a session, with fully redirected stdio.

A typical flow is: pick or create a profile, start a session from it, and run one or more execs in that session. The mirage run shortcut does all three (create → run → clean up) in a single command.

Quick start

# See which emulator backends are available on this machine.
mirage emulators

# Create a profile targeting an MI350X with the rocjitsu emulator.
mirage profile create cdna4 --emulator rocjitsu --agent MI350X

# One-shot: create a transient session, run a command, attach, clean up.
mirage run --profile cdna4 -- ./my-rocm-app --flag

# Or manage the lifecycle yourself:
sid=$(mirage session start --profile cdna4)
mirage exec start "$sid" -- ./my-rocm-app
mirage session stop "$sid"

If you have no GPU and just want to exercise the tooling, use the noop emulator, which runs commands directly with no emulation:

mirage profile create local --emulator noop
mirage run --profile local -- echo "hello from mirage"

Building

mirage is a single Cargo workspace. One build produces the unified mirage binary:

cd emulation/mirage
cargo build --workspace          # debug build -> target/debug/mirage
./target/debug/mirage --help

By default the rocjitsu backend is compiled in. Backends are selected with Cargo features, and the optional web dashboard needs Node.js 20.19+. See docs/building.md for the full guide, including building rocjitsu and the dashboard.

Testing

cargo test --workspace

The end-to-end tests in tests/ drive the full lifecycle (create session → start exec → attach → signal → stop) through the public CLI and HTTP surfaces. The rocjitsu-backed e2e tests require a working rocjitsu runtime; without it they are expected to fail with a "KMD preload library not found" message.

Web dashboard (optional)

mirage ships an optional cross-session HTTP/WebSocket dashboard:

cargo build --workspace --features webui
mirage webui                     # serve on 127.0.0.1:5174 by default
mirage webui install             # register it as a systemd user service

Documentation

• docs/cli.md — complete CLI reference.
• docs/architecture.md — design and crate overview.
• docs/building.md — building mirage, the dashboard, and rocjitsu.
• docs/host.md — what the per-session host does and how to extend it.
• docs/state-layout.md — authoritative on-disk layout reference.