path: root/debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md

# RISC-V GSP-RM DEBUGGER ROADMAP — long-term program

> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md).
> This is the long-term plan for risc-v-gsp-rm-debugger, the runtime analysis, injection and
> measurement environment for the NVIDIA GPU System Processor (GSP) and its
> adjacent microcontrollers. Near-term, committed work lives in
> [`docs/08-ROADMAP.md`](docs/08-ROADMAP.md); this document is the program.

## 0. Purpose

Open-IOV's hardest long-term problem is not writing the emulation once — it is
**surviving adversarial firmware change**. NVIDIA ships new GSP images, new
device pairings and new architectures on independent schedules, and the
firmware is deliberately opaque (stripped, signed, hardware-coupled, with
non-recoverable boot states). To keep `vgsp` accurate across that
churn, the project needs a toolchain that can:

1. **Run** firmware off-hardware, safely and repeatably.
2. **Observe** it completely — control flow, memory, services, state machines.
3. **Change** it — inject our own services/engines and mutate inputs to learn
   boundaries.
4. **Compare** — hardware vs VFIO vs simulation, old vs new firmware, with a
   metric contract instead of anecdotes.
5. **Reimplement** — turn observed behaviour into reviewed code in
   `vgsp` with evidence attached.

risc-v-gsp-rm-debugger is the vehicle for that program. It is explicitly a **development
environment**, never a shipped component.

## 1. Starting point (H0, done)

v0.1 (2026-10-02) provides: GDB-free QEMU RISC-V transport; hooks,
breakpoints, watchpoints; memory/struct/snapshot tooling; recorded sessions
and symbol-annotated analysis; declarative probes; plugins; a Ghidra symbol
and hit bridge; a Ghidra control bridge; a TCG full-trace plugin; a
position-independent service SDK and `./risc-v-gsp-rm-debugger.sh inject`; and the Frida-like
`Session.call` / `run_until` primitives. Fidelity is L0/L1 (execution and
memory); the device environment (L3) is absent.

## 2. How this roadmap is organised

Five workstreams run through every horizon:

* **F — Fidelity**: how much of the real GSP environment the simulator
  provides (device model, boot chain, timing).
* **I — Injection**: what code we can add to the running system and how.
* **A — Adversarial navigation**: finding and understanding *unexpected*
  firmware behaviour and mapping it to emulation changes.
* **C — Control & tooling**: debugging, Ghidra/agent integration, SDK,
  formats, usability.
* **V — Validation**: metrics, benchmarks, golden sessions, gates that stop a
  claim from landing without evidence.

Horizons are numbered H1..H7 with explicit **entry gates** (what must be true
before starting) and **exit criteria** (what must be demonstrated).

---

## H1 — Injection and control (now → weeks)

**Goal:** make "write a service / change the firmware / prove it" a
first-class loop on the demo uproc and on re-hosted uproc code.

### H1.1 GSP RM firmware service developer guide (deliverable today)
A written guide (docs/11) covering: RM service anatomy, service entry and
message loop, RM-core calls available to a service, allocation/control
surfaces, inter-service messaging, versioning, and the build/inject/debug
loop. On the demo this maps to the handler-table ABI; on real GSP-RM it maps
to the RM object/control model.

### H1.2 Injection SDK v1 (deliverable today, demo-proven)
Specification (docs/12): blob format, PIC requirements, ABI, registration,
capability metadata, error model, observability hooks. Implemented in `sdk/`
and `greeneye/inject.py`, verified by direct call and firmware dispatch.

### H1.3 GSP-RM service injection (needs H2 device model)
Once real GSP-RM runs in the simulator (H2), extend the SDK to:
* build against RM headers or against a risc-v-gsp-rm-debugger shim for
  public work;
* register a service with the simulated RM core instead of a demo handler
  table;
* call RM-core entry points (allocation, control, mapping, scheduling) from
  the injected code, intercepted by the simulator so calls are logged,
  stubbed or forwarded;
* run injected services under the same recording/compare pipeline.
Entry gate: H2.2 (GSP-RM reaches its message loop in the simulator).
Exit: an injected service serves a control end-to-end and its session can be
diffed against hardware.

### H1.4 Ghidra-driven execution (deliverable today, demo-proven)
`./risc-v-gsp-rm-debugger.sh ghidra` + `GreenEyeControl.java` (docs/13): "run until here", set
breakpoints, read memory/registers, remote-call, export hits. Next
increments:
* watchpoints and structure reads from Ghidra;
* a decompiler-side hit heat-map fed by `greeneye_hits.tsv`;
* bidirectional navigation: clicking a hit opens the decompiled function.

### H1.5 Debugger parity
Make the REPL/API cover the common GDB vocabulary for firmware work
(watchpoints, catchpoints for traps, thread/core selection, memory region
metadata) while keeping the scripted API as the primary surface.

---

## H2 — Fidelity: platform device model (months)

**Goal:** move from "executes and faults" to "boots the real GSP image to its
message loop" inside the simulator.

### H2.1 First-touch register map (started)
The `probe` command already reports the first fault (TU104 570.144: load
access fault at firmware vaddr `0x4009014` reading `0x2000000000000A00`).
Systematically harvest first-touch addresses across versions/devices and
build the initial MMIO map from them.

### H2.2 QEMU device model
Model, as a QEMU `-device` (or a small set):
* **falcon/SEC2 windows** (cpuctl, dmactl, fbif, imem/dmem, bootvec) with
  read-back semantics adequate for boot polling;
* **CSB/TRANSCOM** mailbox windows used by the GSP application;
* **WPR2/FWSEC state** registers (so the image believes it was staged);
* **PTIMER** and basic interrupt routing;
* **DMA/IOMMU** address translation for the firmware's descriptors into
  host/FB windows;
* **PMU stub** sufficient for the identity/clock provisioning the GSP app
  reads early.
Entry gate: H0 + first-touch data. Exit: the image reaches `appMain` and
blocks on a host message rather than faulting.

### H2.3 Boot-chain shims
FWSEC/booter/SEC2 are not reasonable to model fully; provide *documented
shims* that place the GSP image in the state the bootloader would have left
it (boot args in a0–a5, MPU/TCM layout, scratch state), so boot behaviour can
be studied without the security chain. Record shim assumptions in session
metadata.

### H2.4 Multi-core and concurrency (approximate first)
GSP-RM is multi-task; adjacent controllers (SEC2/PMU) are separate cores.
Add deterministic scheduling knobs (instruction budget round-robin, timer
injection) so multi-task interleavings can be explored, replayed and
compared — without claiming real-time behaviour.

---

## H3 — Non-QEMU custom simulator (months; explicitly later)

**Why:** QEMU is an execution engine, not a workflow engine. It cannot give
us cheap snapshots, deterministic replay with time-travel, in-process
inspection, per-access callback ABI objects, or a device map expressed as
code + data we can version with the firmware profiles. A custom simulator can,
and can become the substrate for injection, fuzzing and adversarial work.

### H3.1 Requirements
* RV64IMAC(+GC when needed) interpreter, fast enough for firmware bring-up
  (target: ≥10–50 MIPS/core on one host thread; not realtime).
* Pluggable **memory map DSL**: regions (RAM/TCM/MMIO/DMA) with read/write
  callbacks, access logging, and declarative register definitions.
* **Deterministic scheduler**: per-core instruction budgets, timers, event
  queue; replay from an event log.
* **Snapshot/restore** of full machine state (registers, memory, device
  state) for instant checkpointing and time-travel debugging.
* **Event bus** emitting the existing `events.jsonl` schema plus
  `exec`/`access` events.
* **Backend ABI** identical to `Session`'s expectations, so all hooks,
  watchpoints, scripts, probes, plugins, records and comparisons keep working.
* **Injection ABI**: load blobs, register services, intercept RM-core calls.
* **Python-first embedding** (C/C++ core with a Python control plane, or a
  Rust core with PyO3), plus a CLI.

### H3.2 Design sketch
```
+-------------------- risc-v-gsp-rm-debugger Python control plane --------------------+
| Session API, hooks/watchpoints, recorder, plugins, Ghidra/agent bridge |
+---------------------------- Backend interface -------------------------+
        | QEMU-RSP backend (today)            | native simulator backend
        v                                     v
  qemu-system-riscv64                libgreenmachine (C/C++/Rust)
                                      +-- cpu/ (interpreter, decoder)
                                      +-- mem/ (map DSL, snapshots)
                                      +-- dev/ (falcon, csb, pmu, dma)
                                      +-- sched/ (cores, timers, events)
                                      +-- trace/ (event bus, coverage)
```
* The **map DSL** is versioned data (JSON/YAML) with per-device behaviour in
  small plugin modules; new firmware/device profiles are additions, matching
  the project's portability direction.
* **Snapshots** are copy-on-write memory pages + device state, giving cheap
  branch exploration ("what if this reply differed?").
* **Time-travel** is built from snapshot + deterministic event replay.

### H3.3 Implementation plan
1. **M1**: RV64IMAC interpreter + RAM + UART; boots the demo uproc; risc-v-gsp-rm-debugger
   Session works against the native backend (parity with QEMU for the demo).
2. **M2**: memory map DSL + falcon/CSB/PTIMER devices; boots a re-hosted
   uproc build; snapshots/restore.
3. **M3**: deterministic scheduler + event log/replay; multi-task tests.
4. **M4**: device-model parity with H2.2 and boot of the real GSP image under
   shims.
5. **M5**: injection ABI + RM-core interception; fuzzing harness.
6. **M6**: performance and ergonomics hardening; backend selection in the
   CLI (`--backend native`).

### H3.4 Risks
Fidelity divergence from QEMU/hardware (mitigate: differential tests between
backends at H0 demos and H2 boot milestones); effort creep (gate behind H2
success); maintenance of two backends (keep the Backend interface minimal).

---

## H4 — Adversarial firmware navigation (continuous)

**Goal:** when the firmware changes unpredictably — new handlers, opaque
state, deliberate anti-analysis, or shifted resources — navigate and
reimplement quickly.

### H4.1 Semantic diffing
* Import each firmware's Ghidra corpus and risc-v-gsp-rm-debugger symbol DB; diff RPC
  dispatch tables, handler inventory, control sets, message layouts.
* Run the same stimulus harness against each version and use
  `./risc-v-gsp-rm-debugger.sh compare` for hit/watch/write deltas; automatically flag functions
  whose call counts changed but whose static code is unchanged (behaviour
  moved) vs changed code (new logic).
* Produce a "portability delta report" per version (feeds docs/07 playbooks).

### H4.2 Capability inference
Observe what each service reads/writes (watchpoints, TCG trace) and infer
capabilities (which objects, ranges, controls it touches); compare with the
declared/emulated capability model; surface least-privilege and security
findings for `vgsp`.

### H4.3 Mutation and fuzzing
Feed malformed construction/control traffic into re-hosted or simulated
firmware; capture error paths, asserts and panic loops with symbol
annotation; build a corpus that drives the emulation's fail-closed rules
(project security hygiene) and its error replies.

### H4.4 Decoy / anti-analysis handling
Firmware may use timing checks, self-integrity checks, bogus code paths or
hardware-dependent branches. Techniques to build: deterministic replay to
separate data from noise; "two-run differential" with a single input bit
flipped; dead-code identification by coverage; trap-on-read of
anti-analysis registers with recorded responses; and a catalogue of observed
techniques in docs/09.

### H4.5 Reimplementation workflow (accuracy loop)
The canonical loop for any behaviour:
1. Observe on hardware/VFIO (reference capture).
2. Observe in risc-v-gsp-rm-debugger (simulator, replayable).
3. `compare` + metric table M1–M6 (docs/06-ACCURACY.md).
4. Implement in `vgsp` with the session directories attached as
   evidence.
5. Re-run the same stimulus; the metric table must improve or stay equal.
This loop becomes a scripted harness ("consensus harness") so every change
produces comparable evidence.

---

## H5 — Adjacent microcontrollers (months)

**Goal:** treat the GSP as one node in a device-level system.

* **Inventory**: PMU (power/voltage/clock provisioning), SEC2 and ACR/SOE
  (security/boot), the booter, FWSEC/FRTS, and the DMA lines between them
  (from firmware analysis and the RISC-V Story material; see
  docs/09).
* **Models**: per-controller memory maps, mailbox protocols and boot state
  machines as versioned data; SEC2/PMU stubs first (GSP needs them to pass
  early init), full ACR/SOE later.
* **Cross-controller scenarios**: GSP↔PMU identity/clock provisioning,
  GSP↔SEC2 mailbox, boot-order exercises (Init→ACR→RM for the
  confidential-compute partition model).
* **Deliverable**: a device-level session that spans controllers, recorded
  and comparable, so a firmware update's cross-controller interactions are
  visible.

Entry gate: H2.2 (GSP message loop). Exit: at least one cross-controller
exchange reproduced and compared with hardware evidence.

---

## H6 — Verilog soft processor (far later)

**Goal:** an FPGA/ASIC-simulation-grade soft implementation of the GSP core
environment that can run real GSP-RM images with cycle-accuracy options, for
deep timing/security/interoperability work and hardware validation of the
emulation.

### H6.1 Scope
* RV64 core choice/build (existing open cores vs a minimal in-house core),
  matching ISA/extensions used by the firmware; TCM, MPU/PMP, vectored
  interrupts, timers.
* Device fabric: falcon-compatible windows, CSB/TRANSCOM, DMA engine to host
  memory, WPR2/FWSEC state (with an explicit, documented security posture:
  the soft model is a study environment, never a confidentiality boundary).
* Run modes: pure RTL simulation (Verilator) for determinism and coverage;
  FPGA for speed; co-simulation with risc-v-gsp-rm-debugger (JTAG/DPI/a bridge) so the
  same Python hooks, sessions and comparisons apply.

### H6.2 Integration with risc-v-gsp-rm-debugger
* A `Backend` implementation talking to the RTL simulation clock/step and
  memory API; breakpoints become simulation traps; watchpoints become
  signal/page monitors.
* Sessions record cycle counts as a distinct event class (L2 timing becomes
  measurable, with the accuracy caveats of docs/06 revisited).

### H6.3 Gates
Requires: H2/H3 proven, a validated device map, and a funded reason to care
about cycle accuracy (e.g., a customer-facing timing claim). Explicitly
**not** on the critical path; do not start before the baseline goals in the
project roadmap are complete.

---

## H7 — Agentic platform (continuous, gated)

* **MCP plugin (R3)**: expose sessions as MCP tools (list/open sessions,
  symbols, breakpoints, run/run_until, memory, snapshots, compare,
  export_hits). Local stdio; no network by default.
* **AI harness integration**: deterministic run harnesses that an agent can
  drive; sessions as the shared evidence format; guarded write actions with
  an explicit capability manifest.
* **Autonomous analysis loops**: hypothesise → instrument → run → compare →
  report, with human-review gates for anything that changes the product.
* **Safety**: no unattended physical-GPU cycles; no guest modifications; the
  agent runs against the simulator by default.

---

## Cross-cutting workstreams

### V1 — Metrics and golden data
Keep the M1–M6 contract (docs/06) authoritative; maintain golden sessions for
the demo and re-hosted workloads; CI runs the tool tests + golden comparisons.

### V2 — Formats and versioning
`greeneye-session/1` evolves additively with a version bump and migration
notes; symbol DBs carry provenance; injection blobs carry an ABI version and
capability metadata.

### V3 — SDK/ABI evolution
Injection ABI v1 (demo) → v2 (RM-core interception). Breaking changes are
gated by a compatibility shim and a documented migration.

### V4 — Security
Treat the simulator as a study environment: no confidentiality claims; keep
fuzzing and mutation behind explicit harnesses; never ship simulation shims
in the product; never place tooling in a guest.

### V5 — Performance
Simulator performance target (H3.1); TCG trace filtering; snapshot
compression; session size budgets (region-scoped dumps).

### V6 — Documentation and developer experience
Every horizon ships docs with copy-paste workflows, an acceptance script, and
a status/flag criterion (the v0.1 notices came off 2026-10-02); the
Ghidra/agent guides are kept current as first-class deliverables.

## Sequencing summary

| Horizon | Entry gate | Primary deliverable |
|---|---|---|
| H1 | H0 (done) | injection SDK + RM service guide + Ghidra control |
| H2 | H1 | QEMU device model; real GSP image reaches message loop |
| H3 | H2.2 | native simulator with snapshots/replay and injection |
| H4 | H1+H2 | adversarial diffing/capability/fuzzing harness |
| H5 | H2.2 | adjacent-controller models and cross-controller sessions |
| H6 | H3 validation | Verilog soft-core environment (far later) |
| H7 | H1 stable | MCP plugin and agentic harnesses |

## Success criteria (program level)

1. A new GSP version can be triaged (inventory diff + behaviour diff +
   metric table) in **hours**, with recorded evidence.
2. Every new emulation behaviour lands with an A/B session pair and the M1–M6
   table.
3. Injected services prototype RM engine ideas in the simulator before any
   product code is written.
4. The custom simulator reproduces the H2 boot and H4 workloads
   deterministically, with snapshots and replay.
5. No claim of accuracy, portability or security depends on a single run or
   on unstated fidelity assumptions.