1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
# 00 — risc-v-gsp-rm-debugger overview
> **# TOOL IN DEVELOPMENT - NOT READY YET!**
> Experimental tooling for simulating and inspecting the GSP firmware's
> runtime memory, for `gsp-rm-vfio` 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-02)
| 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 | 155 tests green (live QEMU + native differential included) |
| Ghidra bridge | scripts + docs |
| Real GSP `.fwimage` probe (first-fault report) | working (honest: it does not boot without a TU104 model — see 06) |
| 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) |
| Native M2+ device model | roadmap only (08, 16) |
## 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) |
| [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. -->
|
