path: root/debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md

# 00 — risc-v-gsp-rm-debugger overview

> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md).
> Experimental tooling for simulating and inspecting the GSP firmware's
> runtime memory, for `vgsp` accuracy measurements and GSP/uproc
> reverse engineering. Interfaces and file formats may change without notice.
> It is development-only: never shipped, never a dependency of the emulation,
> never present in a guest.

## What problem it solves

Open-IOV emulates the GSP interface and (in the physical backend) boots the
real GSP firmware. Both efforts need the same missing capability: to *watch
the firmware do things* — which handler runs, what it reads and writes, what
it returns, how its state machine evolves — without a physical GPU, without
WPR2/hazard exposure, and repeatably.

risc-v-gsp-rm-debugger runs uproc/GSP firmware in `qemu-system-riscv64` and gives the
developer Frida-like instrumentation over its memory and execution:

* breakpoints and enter/leave **hooks** (RV64 ABI aware),
* **watchpoints** on firmware variables,
* **memory** read/write/hexdump/search/scan,
* **structure decoding** from schemas,
* **snapshot + diff** of memory regions,
* **sessions**: a recorded, replayable dump of runtime memory activity,
* **post-run analysis** with symbol annotation,
* **plugins** for new tools, harnesses and virtualization updates,
* a **Ghidra bridge** joining static addresses to runtime hits,
* A/B tooling for **bare-metal vs vfio-mdev** result comparison.

It is deliberately not a GDB wrapper: a pure-Python RSP client makes the
whole stack scriptable, and QEMU is just the first execution backend.

## Status (v0.1 + 2026-10-03 simulator wave)

| Capability | State |
|---|---|
| RV64 QEMU boot + gdbstub transport (no GDB) | working, live-verified |
| Hooks / breakpoints / watchpoints / step / continue | working, live-verified |
| Memory tools + struct decode + snapshot diff | working, live-verified |
| Session recording + `analyze` report | working, live-verified |
| Declarative probe specs | working, live-verified |
| Plugin loader + example plugin | working |
| Native RV64IMAC simulator (M1, `--backend native`) | working; QEMU-parity differential test |
| Native exec/access trace (M1.5, R4): `--trace`, analyzer coverage | working; trace blob + determinism test |
| Test suite | full suite green on the 2026-10-03 review host (298 tests incl. live QEMU + native differential; count varies with local prerequisites) |
| Ghidra bridge | scripts + docs |
| Real GSP `.fwimage` probe (first-fault report) | working (first fault + lenient continuation) |
| GSP device model + versioned profiles (S1) | in development: `sim/devices/`, `sim/profiles/`, `sim/gsp_boot.py`; B0–B2 on the real 570.144 image with 0 unknown MMIO (36) |
| Modeled cycle accounting | increment 0: `sim/cycles.py`; modeled defaults, not silicon timing (32) |
| Simulator-vs-QEMU A/B + new-version triage | working: frozen thresholds, verdict `above` on the S1 path per docs/37 §4.3; `harness/triage.py` (37, 40) |
| GPGPU-Sim overlay | Phase 0 scaffold + CUDA-12 build port record; Phase G gated (30) |
| TCG full-memory tracing plugin | source + optional build (verified live) |
| Automation harness (mutation/portability/version diff) + value demos | working (18/19/21/25) |
| Host RM oracle harness (`rmharness`) | wrappers + capture working; device tables depend on driver permissions (17) |
| First-touch device map + lenient native MMIO | working (24) |
| MCP server (`plugins/mcp_server.py`) | working (20); stdlib-only, read-only by default |
| Porting automation + trial packaging (28/29) | scaffolds + tests present; unadmitted pilots (dry-run default) |

The in-development notices were removed on 2026-10-02 after the tool audit
([27-TOOL-AUDIT](27-TOOL-AUDIT.md)), the 194-test green suite, and the
end-to-end s01–s10 value demonstrations
([25-VALUE-VALIDATION](25-VALUE-VALIDATION.md)). Open items stay listed as
open: docs 28/29 are unadmitted pilots, the device model is partial (S1,
B0–B2; docs/36) and custom-simulator M2+ remains roadmap, and nothing here is
a stability guarantee beyond the audited v0.1 surface.

## Quick start

```bash
cd open-iov/debug/risc-v-gsp-rm-vm
make demo                 # build the bundled RV64 uproc demo
./risc-v-gsp-rm-debugger.sh demo        # canned instrumentation pass, records a session
./risc-v-gsp-rm-debugger.sh info        # environment check
./risc-v-gsp-rm-debugger.sh probe       # run the real GSP fwimage and report first divergence
```

Interactively:

```bash
./risc-v-gsp-rm-debugger.sh demo --no-build --duration 0   # launches; prints the gdbstub port
./risc-v-gsp-rm-debugger.sh attach --port <port> --kernel firmware/uproc_demo/build/uproc_demo.elf
```

## Document map

| Doc | Read it for |
|---|---|
| [01-DESIGN](01-DESIGN.md) | how the pieces fit, transport, data model, limits |
| [02-USAGE](02-USAGE.md) | CLI and REPL recipes |
| [03-SCRIPTING](03-SCRIPTING.md) | writing programs against the API |
| [04-PLUGINS](04-PLUGINS.md) | extending risc-v-gsp-rm-debugger |
| [05-GHIDRA-BRIDGE](05-GHIDRA-BRIDGE.md) | static/dynamic address join |
| [06-ACCURACY](06-ACCURACY.md) | what the simulation does and does not prove |
| [07-PORTABILITY-PLAYBOOKS](07-PORTABILITY-PLAYBOOKS.md) | new GSP / device / architecture |
| [08-ROADMAP](08-ROADMAP.md) | MCP, custom simulator, device model |
| [09-GSP-FIRMWARE-NOTES](09-GSP-FIRMWARE-NOTES.md) | uproc/falcon/NV-RISCV facts used here |
| [10-RELATED-WORK](10-RELATED-WORK.md) | Frida/GDB/QEMU-plugin comparison |
| [11-GSP-RM-SERVICE-DEVELOPER-GUIDE](11-GSP-RM-SERVICE-DEVELOPER-GUIDE.md) | writing/injecting/debugging RM services |
| [12-INJECTION-SDK](12-INJECTION-SDK.md) | injection blob/ABI specification |
| [13-GHIDRA-CONTROL](13-GHIDRA-CONTROL.md) | driving risc-v-gsp-rm-debugger from Ghidra |
| [14-ADVERSARIAL-INTEROP-GUIDE](14-ADVERSARIAL-INTEROP-GUIDE.md) | adversarial firmware navigation |
| [15-AGENTIC-GSP-IDE](15-AGENTIC-GSP-IDE.md) | agentic workflows and runbooks |
| [16-CUSTOM-SIMULATOR](16-CUSTOM-SIMULATOR.md) | native simulator (M1/M1.5 implemented; M2+ design) |
| [17-RM-HARNESS](17-RM-HARNESS.md) | host RM oracle harness (`rmharness`) |
| [18-HARNESS-AUTOMATION](18-HARNESS-AUTOMATION.md) | mutation/portability automation |
| [19-CONTROL-DISCOVERY](19-CONTROL-DISCOVERY.md) | unknown-call discovery and reachability |
| [20-MCP-SERVER](20-MCP-SERVER.md) | bundled MCP server plugin |
| [21-CI-RELEASE-PIPELINE](21-CI-RELEASE-PIPELINE.md) | release triage pipeline |
| [22-PORTING-CUDA-AND-DEVICES](22-PORTING-CUDA-AND-DEVICES.md) | porting playbook |
| [23-RM610-READINESS](23-RM610-READINESS.md) | RM 610 readiness checklist |
| [24-DEVICE-MAP](24-DEVICE-MAP.md) | first-touch MMIO device map |
| [25-VALUE-VALIDATION](25-VALUE-VALIDATION.md) | value-validation demos s01–s10 |
| [26-ARCHITECTURE](26-ARCHITECTURE.md) | full architecture and API surface map |
| [27-TOOL-AUDIT](27-TOOL-AUDIT.md) | tool audit: purpose, tests, usage, status |
| [28-PORTING-AUTOMATION](28-PORTING-AUTOMATION.md) | driver-version sweep and new-device scaffolds (pilot) |
| [29-PACKAGING-AND-TRIALING](29-PACKAGING-AND-TRIALING.md) | trial simulation packages (pilot) |
| [30-GPGPU-SIM-INTEGRATION](30-GPGPU-SIM-INTEGRATION.md) | GPGPU-Sim overlay scaffold and build port (Phase G) |
| [31-TURING-TU104-PARAMETERS](31-TURING-TU104-PARAMETERS.md) | Turing TU104 parameter dossier |
| [32-GSP-CYCLE-MODEL](32-GSP-CYCLE-MODEL.md) | modeled cycle accounting (not silicon timing) |
| [33-AMPERE-PARAMETERS](33-AMPERE-PARAMETERS.md) | Ampere parameter dossier |
| [34-BLACKWELL-SOURCES](34-BLACKWELL-SOURCES.md) | Blackwell source classification |
| [35-GREENEYE-SIMULATOR-DESIGN](35-GREENEYE-SIMULATOR-DESIGN.md) | standalone GSP simulator design and gates |
| [36-GSP-DEVICE-MODEL](36-GSP-DEVICE-MODEL.md) | S1 device model, profiles, boot ladder |
| [37-SIM-QEMU-LINE](37-SIM-QEMU-LINE.md) | simulator-vs-QEMU A/B and measured verdict |
| [38-GSP-EM-API](38-GSP-EM-API.md) | GSP-emulator/system-simulator TLV boundary (design) |
| [39-RE-WORKFLOW-REVIEW](39-RE-WORKFLOW-REVIEW.md) | reverse-engineering workflow review |
| [40-NEW-VERSION-TRIAGE](40-NEW-VERSION-TRIAGE.md) | one-command new-version triage |
| [RISC-V-GSP-RM-DEBUGGER-ROADMAP](../RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) | long-term program H1–H7 |

## Where this fits in the Open-IOV workflow

risc-v-gsp-rm-debugger is a **development and research** tool, alongside the Ghidra corpus
and the guest diagnostics. It does not replace either:

* **Ghidra** answers *what is the code*; risc-v-gsp-rm-debugger answers *what did it do*.
* **Guest diagnostics** (`tools/guest-diag`) answer *what did the guest
  driver do*; risc-v-gsp-rm-debugger answers *what did the firmware server do*.
* **The physical backend** (PLAN B) answers *what does real silicon do*;
  risc-v-gsp-rm-debugger provides a safe place to repeat, mutate and single-step the same
  firmware when the hardware path is hazardous or unavailable.

The intended accuracy loop is: run the same workload against the real
GSP-RM (hardware or mdev), record its RPC/state behaviour, then run the
firmware in risc-v-gsp-rm-debugger, record the same events, and compare with `compare`
(see 06 and 07).

<!-- change (2026-10-02): add docs 28/29 to the status table and document map
and mark their scripts as unadmitted pilots; scope: status table and document
map only; benefit: the newest tool tree docs are discoverable and not mistaken
for admitted tooling. -->