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

> Status: implemented, documented and tested (audit: [docs/27](../../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md); value demos: [docs/25](../../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md)).
> 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. The in-development
> notices were removed on 2026-10-02 after the tool audit, the 194-test green
> suite and the end-to-end value demonstrations; docs 28/29 remain unadmitted
> pilots.

## 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 (`./risc-v-gsp-rm-debugger.sh inject`),
* declarative probe specs, a plugin API, a Ghidra symbol/hit bridge and a
  **Ghidra control bridge** (`./risc-v-gsp-rm-debugger.sh ghidra` + `GreenEyeControl.java`) for
  "execute until here" from the decompiler.

Its stated purpose is **simulating and inspecting the GSP firmware's runtime
memory for `vgsp` 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. `./risc-v-gsp-rm-debugger.sh 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
(`./risc-v-gsp-rm-debugger.sh 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. Development notices removed (2026-10-02)

The in-development notices were removed from this document and from the
developer-tools list on 2026-10-02, after:

1. the v0.1 surface passed the tool audit on a clean checkout
   (`debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md`);
2. the full suite ran green — 194 tests
   (`python3 -m unittest discover -s tests -t .`);
3. the usage recipes and the s01–s10 end-to-end value demonstrations were
   verified (`debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md`);
4. the session format and CLI are the audited v0.1 surfaces.

Open items stay open and are not stability claims: docs/28 porting automation
and docs/29 trial packaging remain unadmitted pilots, the device model (R1)
and custom simulator M2+ (R2) remain roadmap, and RM 610 stays behind the
human gate.