[rocjitsu] Translate gfx1250 lane-banked and kernarg-supplied indirect calls

.github/workflows/rocjitsu-corpus-tests.yml

@@ -360,7 +360,7 @@ jobs:
           ROCM_PATH="$(rocm-sdk path --root)"
           export ROCM_PATH
           LAUNCHER="${ROCJITSU_BUILD_DIR}/tools/rocjitsu/rocjitsu"
-          CONFIG="${ROCJITSU_SOURCE_DIR}/configs/gfx1250.json"
+          CONFIG="${ROCJITSU_SOURCE_DIR}/configs/gfx1250_mi455x.json"
           HOTSWAP="${ROCJITSU_BUILD_DIR}/lib/rocjitsu/src/rocjitsu/hooks/libhsa_hotswap_rocjitsu.so"
           test -f "${HOTSWAP}"
           # Disable ROCr's built-in mechanism in both legs. Load the branch-built
@@ -442,7 +442,7 @@ jobs:
           DBT_TRANSLATOR="${DBT_TRANSLATOR_BINARY}"
           if [[ "${{ matrix.verify_dbt_idempotence }}" == "1" ]]; then
             DBT_TRANSLATOR="${RUNNER_TEMP}/rj_dbt_translate-verify-idempotence"
-            printf '#!/usr/bin/env bash\nexec %q --verify-idempotence "$@"\n' \
+            printf '#!/usr/bin/env bash\nexec %q --verify-idempotence --verify-rewrite-discharge "$@"\n' \
               "${DBT_TRANSLATOR_BINARY}" \
               > "${DBT_TRANSLATOR}"
             chmod +x "${DBT_TRANSLATOR}"

emulation/README.md

@@ -12,7 +12,7 @@
     - [DBT](emulation/rocjitsu/lib/rocjitsu/src/rocjitsu/code/dbt/) — Dynamic binary translation: encoding and semantic translation.
     - [Patch / DBI](emulation/rocjitsu/lib/rocjitsu/src/rocjitsu/code/patch/) — Patch points and (planned) instrumentation, spill/restore.
   - [Analysis Layer](emulation/rocjitsu/lib/rocjitsu/src/rocjitsu/analysis/) — Register liveness, def-use chains, hazard scheduling, lane permutation. See [liveness.cpp](emulation/rocjitsu/lib/rocjitsu/src/rocjitsu/analysis/liveness.cpp) and [def_use_chain.cpp](emulation/rocjitsu/lib/rocjitsu/src/rocjitsu/analysis/def_use_chain.cpp).
-  - [ISA Layer](emulation/rocjitsu/lib/rocjitsu/src/rocjitsu/isa/) — Per-ISA decoders, operand types, machine instruction structs, encoding formats (CDNA1–4, RDNA1–4, RDNA3.5). Entry points: [decoder.cpp](emulation/rocjitsu/lib/rocjitsu/src/rocjitsu/isa/decoder.cpp), [rj_decode.cpp](emulation/rocjitsu/lib/rocjitsu/src/rocjitsu/isa/rj_decode.cpp); per-arch tables in [arch/](emulation/rocjitsu/lib/rocjitsu/src/rocjitsu/isa/arch/).
+  - [ISA Layer](emulation/rocjitsu/lib/rocjitsu/src/rocjitsu/isa/) — Per-ISA decoders, operand types, machine instruction structs, encoding formats (CDNA1–5, RDNA1–4). Entry points: [decoder.cpp](emulation/rocjitsu/lib/rocjitsu/src/rocjitsu/isa/decoder.cpp), [rj_decode.cpp](emulation/rocjitsu/lib/rocjitsu/src/rocjitsu/isa/rj_decode.cpp); per-arch tables in [arch/](emulation/rocjitsu/lib/rocjitsu/src/rocjitsu/isa/arch/).
   - [simdojo](emulation/rocjitsu/lib/simdojo/) — Decoupled parallel discrete-event simulation engine that orchestrates composable models. See [DESIGN.md](emulation/rocjitsu/lib/simdojo/DESIGN.md) and [src/](emulation/rocjitsu/lib/simdojo/src/) ([simulation.cpp](emulation/rocjitsu/lib/simdojo/src/simulation.cpp), [topology.cpp](emulation/rocjitsu/lib/simdojo/src/topology.cpp), [component.cpp](emulation/rocjitsu/lib/simdojo/src/component.cpp)).
   - [amdisa](emulation/rocjitsu/lib/python/amdisa/) — Python codegen that consumes AMD machine-readable ISA specs to auto-generate decoders, semantics, encoding/legalization tables, and cross-ISA translators. Key modules: [parser.py](emulation/rocjitsu/lib/python/amdisa/parser.py), [semantics.py](emulation/rocjitsu/lib/python/amdisa/semantics.py), [encoding_translator_codegen.py](emulation/rocjitsu/lib/python/amdisa/encoding_translator_codegen.py), [legalization_codegen.py](emulation/rocjitsu/lib/python/amdisa/legalization_codegen.py), [cross_isa.py](emulation/rocjitsu/lib/python/amdisa/cross_isa.py), [codegen/](emulation/rocjitsu/lib/python/amdisa/codegen/).
   - [rocjitsu_vllm](emulation/rocjitsu/lib/python/rocjitsu_vllm/) — Python integration glue for running vLLM on top of rocjitsu.
@@ -106,7 +106,7 @@ flowchart TB
                 CODEAPI --> DBI --> ANA
             end
             subgraph ISA["ISA Layer"]
-                I1["Per-ISA: decoders, execution, operand types, machine instr structs, encoding formats<br/>9 ISAs: CDNA1–4, RDNA1–4, RDNA3.5"]
+                I1["Per-ISA: decoders, execution, operand types, machine instr structs, encoding formats<br/>CDNA1–5, RDNA1–4"]
                 subgraph AMDISA["amdisa (Python codegen)"]
                     AM1["Leverages the AMD machine-readable ISA specs to auto-generate<br/>ISA description and semantics for simulation, instrumentation, and translation"]
                 end

emulation/mirage/builtin/src/agents.rs

@@ -2,7 +2,7 @@
 //!
 //! Each agent mirrors one of the rocjitsu `configs/*.json` files:
 //! `MI300X` follows `gfx942_cdna3.json`, `MI350X` follows
-//! `gfx950_cdna4.json`, and `MI450X` follows `gfx1250.json`.
+//! `gfx950_mi355x.json`, and `MI450X` follows `gfx1250_mi455x.json`.
 //! All three share the same `soc -> {vram, iod, xcd -> {l2, cp,
 //! se -> cu}}` component tree and six link patterns; they differ
 //! only in their device identity, the IOD fan-out, and the per-CU
@@ -77,7 +77,7 @@ pub fn mi300x() -> AgentDef {
 }
 
 /// `MI350X` builtin agent (registry key `MI350X`), mirroring the
-/// rocjitsu `gfx950_cdna4.json` config: `arch = cdna4`, marketing
+/// rocjitsu `gfx950_mi355x.json` config: `arch = cdna4`, marketing
 /// name "AMD Instinct MI350X", and an 8-XCD / 4-SE / 8-CU shader
 /// fabric over a 2-IOD memory tier.
 pub fn mi350x() -> AgentDef {
@@ -127,12 +127,12 @@ pub fn mi350x() -> AgentDef {
 }
 
 /// `MI450X` builtin agent (registry key `MI450X`), mirroring the
-/// rocjitsu `gfx1250.json` config: `arch = gfx1250`, an
+/// rocjitsu `gfx1250_mi455x.json` config: `arch = cdna5`, an
 /// 8-XCD / 4-SE / 8-CU shader fabric and a 2-IOD memory tier.
 pub fn mi450x() -> AgentDef {
     AgentDef {
         vm: VirtualMachineConfig {
-            arch: "gfx1250".to_string(),
+            arch: "cdna5".to_string(),
             gpu: AmdgpuConfig {
                 num_xcds: 0,
                 num_iods: 0,
@@ -336,7 +336,7 @@ mod tests {
     #[test]
     fn mi450x_identity() {
         let a = mi450x();
-        assert_eq!(a.vm.arch, "gfx1250");
+        assert_eq!(a.vm.arch, "cdna5");
         assert_eq!(a.vm.gpu.device.marketing_name, "gfx1250");
         assert_eq!(a.vm.gpu.device.gfx_target_version, 120500);
         assert_eq!(a.topology.links.len(), 6);

emulation/mirage/ctl/src/lib.rs

@@ -603,6 +603,18 @@ pub struct RunArgs {
     /// daemon (the default).
     #[arg(long = "in-process")]
     in_process: bool,
+    /// Debug the workload interactively under ROCgdb: the command is
+    /// wrapped as `rocgdb --args <command...>`, with kernel breakpoints
+    /// made pending so `break <kernel>` works before the GPU code object
+    /// loads at launch. Requires a profile whose container ships ROCgdb.
+    #[arg(long)]
+    gdb: bool,
+    /// Extra ROCgdb command to run before the program, injected as
+    /// `-ex <CMD>` (repeatable, applied in order). Implies `--gdb`.
+    /// Useful for scripted/batch debugging, e.g.
+    /// `--gdb-ex 'break add_one' --gdb-ex run --gdb-ex continue`.
+    #[arg(long = "gdb-ex", value_name = "CMD")]
+    gdb_ex: Vec<String>,
     /// The command and its arguments.
     #[arg(trailing_var_arg = true, required = true, allow_hyphen_values = true)]
     argv: Vec<String>,
@@ -1765,6 +1777,32 @@ fn split_argv(argv: &[String]) -> (String, Vec<String>) {
     (cmd, it.collect())
 }
 
+/// Wrap a workload argv so it runs under ROCgdb for GPU kernel debugging
+/// (`mirage run --gdb`). `["./add_one", "5"]` becomes
+/// `rocgdb -ex "set breakpoint pending on" [-ex EX]... --args ./add_one 5`.
+///
+/// Kernel breakpoints are made pending because GPU code objects load lazily at
+/// dispatch: a `break <kernel>` set before launch would otherwise be rejected.
+/// Extra `-ex` commands (`--gdb-ex`) are injected in order, before `--args`, so
+/// a run can be fully scripted. When any `-ex` command is present the session is
+/// non-interactive, so `--batch` is added: ROCgdb runs the commands and exits
+/// (a bare `--gdb`, with no `-ex`, stays interactive and reads the terminal).
+fn gdb_wrap_argv(argv: &[String], gdb_ex: &[String]) -> Vec<String> {
+    let mut wrapped = vec!["rocgdb".to_string()];
+    if !gdb_ex.is_empty() {
+        wrapped.push("--batch".to_string());
+    }
+    wrapped.push("-ex".to_string());
+    wrapped.push("set breakpoint pending on".to_string());
+    for ex in gdb_ex {
+        wrapped.push("-ex".to_string());
+        wrapped.push(ex.clone());
+    }
+    wrapped.push("--args".to_string());
+    wrapped.extend_from_slice(argv);
+    wrapped
+}
+
 /// Parse repeated `KEY=VALUE` pairs from the CLI into the env map
 /// used by [`ExecArgs`]. Rejects entries without an `=` so a typo
 /// surfaces immediately instead of silently being dropped.
@@ -2013,7 +2051,14 @@ async fn run_cmd<C: MirageCtl + 'static>(ctl: Arc<C>, a: RunArgs) -> anyhow::Res
             (def.id, true)
         }
     };
-    let (cmd, args) = split_argv(&a.argv);
+    // `--gdb` / `--gdb-ex` wrap the workload under ROCgdb for interactive GPU
+    // kernel debugging. `--gdb-ex` implies `--gdb`.
+    let effective_argv = if a.gdb || !a.gdb_ex.is_empty() {
+        gdb_wrap_argv(&a.argv, &a.gdb_ex)
+    } else {
+        a.argv.clone()
+    };
+    let (cmd, args) = split_argv(&effective_argv);
     let env = parse_envs(&a.envs)?;
     let def = ExecDef {
         timestamp: chrono::Utc::now(),
@@ -2234,6 +2279,45 @@ mod tests {
         assert!(parse_option("=value").is_err());
     }
 
+    #[test]
+    fn gdb_wrap_prepends_rocgdb_with_pending_breakpoints() {
+        let got = gdb_wrap_argv(&["./add_one".to_string(), "5".to_string()], &[]);
+        assert_eq!(
+            got,
+            vec![
+                "rocgdb",
+                "-ex",
+                "set breakpoint pending on",
+                "--args",
+                "./add_one",
+                "5",
+            ]
+        );
+    }
+
+    #[test]
+    fn gdb_wrap_injects_extra_ex_commands_in_order() {
+        let got = gdb_wrap_argv(
+            &["./add_one".to_string()],
+            &["break add_one".to_string(), "run".to_string()],
+        );
+        assert_eq!(
+            got,
+            vec![
+                "rocgdb",
+                "--batch",
+                "-ex",
+                "set breakpoint pending on",
+                "-ex",
+                "break add_one",
+                "-ex",
+                "run",
+                "--args",
+                "./add_one",
+            ]
+        );
+    }
+
     #[test]
     fn no_overrides_keeps_by_name_ref() {
         let mut p = sample_profile();

emulation/mirage/rocjitsu_sys/src/lib.rs

@@ -115,6 +115,10 @@ pub struct RjVmCmd {
     /// In daemon mode the VM substitutes it into DBG_TRAP ENABLE and, on
     /// adoption, clears it to -1 so the caller does not close it.
     pub in_handle: RjHandle,
+    /// `[in/out]` Debugger-authorized target `/proc/pid/mem` fd, or -1.
+    pub in_mem_handle: RjHandle,
+    /// `[in]` Pinned target `/proc/pid` directory fd, or -1.
+    pub in_proc_handle: RjHandle,
 }
 
 /// Device memory mapping descriptor (`rj_vm_map_t`).
@@ -610,7 +614,7 @@ mod tests {
         assert_eq!(std::mem::size_of::<RjVmUnmap>(), 16);
         // rj_vm_cmd_t: u32 + (pad) + ptr + usize + i32 + i32 + i32 + (pad)
         // on 64-bit.
-        assert_eq!(std::mem::size_of::<RjVmCmd>(), 40);
+        assert_eq!(std::mem::size_of::<RjVmCmd>(), 48);
         assert_eq!(RjVmMode::Daemon as i32, 2);
         // rj_vm_gpu_info_t — must match the 312-byte RpcGpuInfo the
         // daemon handshake embeds (static_assert in rpc.h).

emulation/mirage/scripts/record_demo.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+#
+# Copyright (c) 2026 Advanced Micro Devices, Inc.
+# SPDX-License-Identifier: MIT
+#
+# Record an asciinema demo of a mirage/rocjitsu workflow.
+#
+# WHY: the emulation demos under `emulation/rocjitsu/demos/` each ship three
+# files — `<demo>.md` (what it shows), `<demo>.sh` (the exact commands), and
+# `<demo>.cast` (the recording). This helper is the single, reproducible way to
+# (re)generate the `.cast`: it builds a portable mirage + rocjitsu with
+# `mirage-docker-build.sh`, puts that `mirage` on `PATH`, and records the demo
+# script with asciinema, overwriting the `.cast` next to the `.sh` by default.
+#
+# Usage:
+#   scripts/record_demo.sh [options] <demo.sh> [output.cast]
+#
+# Examples:
+#   # Build mirage+rocjitsu, record emulation/rocjitsu/demos/rocgdb-quickstart.cast
+#   scripts/record_demo.sh ../rocjitsu/demos/rocgdb-quickstart.sh
+#
+#   # Reuse an already-built prefix (skip the ~minutes-long docker build)
+#   scripts/record_demo.sh --no-build --prefix ./build/manylinux \
+#       ../rocjitsu/demos/rocgdb-quickstart.sh
+#
+# Options:
+#   --no-build            Skip the docker build; reuse --prefix / $MIRAGE_BIN.
+#   --prefix DIR          Build into / read the mirage prefix here
+#                         (default: mirage/build/manylinux; also $MIRAGE_PREFIX).
+#   --title STR           asciinema recording title (default: the demo name).
+#   -h, --help            Show this help.
+#
+# Environment:
+#   MIRAGE_BIN            Explicit `mirage` binary to use (implies --no-build).
+#   MIRAGE_PREFIX         Same as --prefix.
+#   CARGO_PROFILE         Passed to mirage-docker-build.sh (default: release).
+#   ASCIINEMA_COLS/ROWS   Terminal size for the recording (default 100x30).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MIRAGE_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+no_build=0
+prefix="${MIRAGE_PREFIX:-$MIRAGE_DIR/build/manylinux}"
+title=""
+demo=""
+out=""
+
+usage() { sed -n '2,40p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --no-build) no_build=1; shift ;;
+    --prefix) prefix="$2"; shift 2 ;;
+    --title) title="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    --) shift; break ;;
+    -*) echo "record_demo: unknown option: $1" >&2; usage >&2; exit 2 ;;
+    *) if [[ -z "$demo" ]]; then demo="$1"; elif [[ -z "$out" ]]; then out="$1"; else
+         echo "record_demo: unexpected argument: $1" >&2; exit 2; fi; shift ;;
+  esac
+done
+
+[[ -n "$demo" ]] || { echo "record_demo: missing <demo.sh>" >&2; usage >&2; exit 2; }
+[[ -f "$demo" ]] || { echo "record_demo: no such demo script: $demo" >&2; exit 1; }
+demo="$(cd "$(dirname "$demo")" && pwd)/$(basename "$demo")"
+# Default output: <demo>.cast next to the .sh, overwritten.
+[[ -n "$out" ]] || out="${demo%.sh}.cast"
+[[ -n "$title" ]] || title="$(basename "${demo%.sh}")"
+
+# --- Require asciinema ------------------------------------------------------
+# Recording a demo is a developer convenience, which is not a good enough reason
+# to mutate the machine it runs on. Provision the tool in the build or container
+# environment instead; this script only reports what is missing.
+command -v asciinema >/dev/null 2>&1 || {
+  echo "record_demo: asciinema not found. Install it and re-run, e.g." >&2
+  echo "  apt-get install asciinema  |  dnf install asciinema" >&2
+  echo "  pipx install asciinema     |  pip install --user asciinema" >&2
+  exit 1
+}
+
+# --- Build mirage + rocjitsu (portable) -------------------------------------
+mirage_bin="${MIRAGE_BIN:-}"
+if [[ -z "$mirage_bin" && "$no_build" -eq 0 ]]; then
+  echo "record_demo: building mirage + rocjitsu into $prefix" >&2
+  "$SCRIPT_DIR/mirage-docker-build.sh" "$prefix" >&2
+fi
+if [[ -z "$mirage_bin" ]]; then
+  mirage_bin="$prefix/bin/mirage"
+fi
+[[ -x "$mirage_bin" ]] || {
+  echo "record_demo: mirage binary not found at $mirage_bin" >&2
+  echo "  build it first (drop --no-build) or set \$MIRAGE_BIN." >&2
+  exit 1
+}
+mirage_bin="$(cd "$(dirname "$mirage_bin")" && pwd)/$(basename "$mirage_bin")"
+echo "record_demo: using mirage: $mirage_bin" >&2
+
+# --- Record -----------------------------------------------------------------
+# The demo script finds `mirage` on PATH (built above) and may read $MIRAGE_BIN.
+# asciinema replays the exact stdout of `bash <demo.sh>`; --overwrite keeps the
+# `.cast` regenerable in place.
+echo "record_demo: recording $demo -> $out" >&2
+env \
+  PATH="$(dirname "$mirage_bin"):$PATH" \
+  MIRAGE_BIN="$mirage_bin" \
+  asciinema rec \
+    --overwrite \
+    --title "$title" \
+    --cols "${ASCIINEMA_COLS:-100}" \
+    --rows "${ASCIINEMA_ROWS:-30}" \
+    --command "bash '$demo'" \
+    "$out"
+
+echo "record_demo: wrote $out" >&2

emulation/rocjitsu/CMakeLists.txt

@@ -405,7 +405,6 @@ add_subdirectory(fuzz/decode)
 if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
     add_subdirectory(tools/rocjitsu)
 endif()
-# Tests and scaling tools.
 if(BUILD_TESTING)
     add_subdirectory(tests)
 endif()

emulation/rocjitsu/CONTRIBUTING.md

@@ -49,8 +49,11 @@ Before writing new infrastructure, check these existing libraries:
 - **Intrusive list** — `util/intrusive_list.h` for linked data structures
   that need O(1) insert/erase without heap allocation per node.
 - **Arena allocator** — `util/arena_alloc.h` for fixed-size block pools.
-- **Exceptions** — `util/except.h` for `InvalidInst`, `UnimplementedInst`,
-  `ConfigError`.
+- **Expected failures** — Return `Result` or `FailureOr<T>` and accept a
+  `DiagnosticEmitter` when the caller needs a reason. Its sink is non-owning
+  and must not outlive its callable.
+- **Exceptions** — `util/except.h` for unrecoverable initialization,
+  configuration, and execution failures.
 - **Register sets** — `isa/register_set.h` for ISA-independent register
   file modeling (SGPR/VGPR/AccVGPR bitsets).
 - **Spill manager** — `code/patch/spill_manager.h` for scratch layout
@@ -88,16 +91,13 @@ Before writing new infrastructure, check these existing libraries:
   `stderr` — it runs inside another runtime's `OnLoad`, its messages must
   survive a log-groups-OFF build, and its signal-backtrace path must stay
   async-signal-safe (`rj_hsa_dbt_hooks.cpp` uses raw `::write`).
-- **Exceptions.** Exceptions are used only for unrecoverable errors
-  during initialization and configuration (`ConfigError`) or when
-  encountering invalid/unimplemented instructions during code object
-  parsing (`InvalidInst`, `UnimplementedInst`). All exception types
-  live in `util/except.h`. Do not throw exceptions in simulation hot
-  paths (event handlers, instruction execution, cache lookups). Do not
-  add `try`/`catch` blocks unless you are at a boundary that must
-  translate an error (e.g., the C API layer). There is no general
-  exception safety guarantee — assume code is not exception-safe
-  unless explicitly documented.
+- **Errors.** Expected failures such as a rejected instruction encoding return
+  `Result` or `FailureOr<T>` and optionally emit a diagnostic. Exceptions are
+  reserved for unrecoverable initialization, configuration, or execution
+  failures. Do not throw exceptions in simulation hot paths (event handlers,
+  instruction execution, cache lookups). Do not add `try`/`catch` blocks unless
+  you are at a boundary that must translate an error (e.g., the C API layer).
+  There is no general exception safety guarantee unless explicitly documented.
 
 ## ISA codegen workflow