# GSP in a RISC-V VM — risc-v-gsp-rm-debugger (experimental)

> **# TOOL IN DEVELOPMENT - NOT READY YET!**
> This is experimental developer tooling. It is not part of the shipped
> emulation, never runs in a guest, and its interfaces, file formats and
> documented workflows may change without notice. Do not depend on it in
> production paths or cite it as a supported feature. When it reaches a
> minimum stable level, the flags will be removed from this document and from
> the developer-tools list.

## 1. What it is

**risc-v-gsp-rm-debugger** runs GSP/uproc firmware in a `qemu-system-riscv64` VM and makes
its runtime behaviour inspectable with Frida-like primitives:

* breakpoints and enter/leave hooks (RV64 ABI aware),
* watchpoints on firmware variables,
* memory read/write/hexdump/search, structure decoding, snapshot diffing,
* recorded sessions: a replayable event stream plus memory dumps
  (`events.jsonl`, snapshots, `summary.md`),
* Frida-like remote calls (`Session.call`) and run-to-cursor
  (`Session.run_until`),
* **code injection**: build a position-independent RV64 service with the
  `sdk/`, load it into the running firmware and register it so the firmware
  dispatches to it (`greeneye inject`),
* declarative probe specs, a plugin API, a Ghidra symbol/hit bridge and a
  **Ghidra control bridge** (`greeneye ghidra` + `GreenEyeControl.java`) for
  "execute until here" from the decompiler.

Its stated purpose is **simulating and inspecting the GSP firmware's runtime
memory for `gsp-rm-vfio` accuracy measurements**: capture how the firmware
behaves, compare that with the emulation and with the physical backend, and
survive GSP version/device/architecture churn with repeatable evidence.

The tooling lives in
[`../../debug/risc-v-gsp-rm-vm/`](../../debug/risc-v-gsp-rm-vm/README.md);
its full documentation set (design, usage, scripting, plugins, Ghidra bridge,
accuracy, portability playbooks, roadmap) is under
`debug/risc-v-gsp-rm-vm/docs/`.

## 2. What it is not

* **Not a GSP boot environment.** QEMU `virt` has no falcon windows, WPR2,
  CSB/TRANSCOM, PMU, timers or FB DMA. `greeneye probe` shows exactly where
  the real image first diverges (for the TU104 570.144 image: a load-access
  fault at firmware vaddr `0x4009014` reading `0x2000000000000A00`); it does
  not boot it. A device model is a roadmap item, not a claim.
* **Not a timing model.** Do not infer latency or concurrency behaviour from
  it; its in-scope conclusions are execution flow and memory side effects.
* **Not a replacement for Ghidra or the guest diagnostics.** Ghidra answers
  *what is the code*; risc-v-gsp-rm-debugger answers *what did it do*. The guest driver
  remains the oracle for guest-side behaviour.

## 3. Where it fits

| Layer | Tool | Question answered |
|---|---|---|
| Static | Ghidra corpus (`userspace/cuda`, `tools/ghidra`) | what is the code? |
| Guest driver | `tools/guest-diag/`, ptrace tracer | what did the driver request? |
| Physical backend | supervised physical cycles, module logs | what did real silicon/the real GSP-RM do? |
| **Firmware runtime (this)** | **risc-v-gsp-rm-debugger** | **what does the firmware server do, repeatably and safely?** |

The intended measurement loop is: capture the real backend's RPC behaviour,
run the same stimulus in risc-v-gsp-rm-debugger, and compare the recorded sessions
(`greeneye compare`) with the accuracy metrics defined in the tool's
`docs/06-ACCURACY.md`. Portability runs (new GSP, new device, GB10-class
architecture) are described in `docs/07-PORTABILITY-PLAYBOOKS.md`.

## 4. Quick start

From the repository root:

```bash
cd debug/risc-v-gsp-rm-vm
./risc-v-gsp-rm-debugger.sh info                 # environment check (QEMU, toolchain)
make demo sdk                      # build the demo uproc and the injection SDK
./risc-v-gsp-rm-debugger.sh demo                 # canned instrumentation pass; records a session
./risc-v-gsp-rm-debugger.sh analyze dumps/<session>
./risc-v-gsp-rm-debugger.sh probe                # real GSP image: report the first divergence
./risc-v-gsp-rm-debugger.sh inject               # load and invoke an injected service
./risc-v-gsp-rm-debugger.sh ghidra               # serve the session to GhidraScripts
```

Requirements: `qemu-system-riscv64` (Ubuntu `qemu-system-misc`), Python 3.10+
(stdlib only), `clang` + `lld` for the demo firmware and the SDK. The tool
touches no GPU, no mdev, no kernel module and no host driver.

## 5. Status and limits (v0.1)

Working and live-verified: QEMU boot and gdbstub transport without GDB,
hooks/breakpoints/watchpoints, memory tools, structure decoding, session
recording and analysis, declarative probes, plugins, remote calls and
run-to-cursor, the injection SDK with direct and firmware-dispatched service
invocation, the Ghidra symbol/hit bridge and Ghidra control bridge, the
real-firmware first-fault probe, and the TCG full-memory trace plugin. Not
implemented: device model (R1), custom simulator (R2), MCP plugin (R3) — all
roadmap. The long-term program (adversarial navigation, adjacent
microcontrollers, custom simulator, Verilog soft-core, agentic platform) is
documented in `debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`.

## 6. When the development flag can be removed

The marker comes off this document and the developer-tools list when:

1. the v0.1 acceptance list in `debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md`
   passes on a clean checkout;
2. the usage recipes in `docs/02-USAGE.md` are verified end-to-end;
3. a second person or agent can run the quickstart unaided;
4. the session format and CLI are declared stable.

Until then, treat everything here as in development.