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
|
# risc-v-gsp-rm-debugger — GSP runtime analysis in a RISC-V QEMU VM
> 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 `gsp-rm-vfio` accuracy measurements and GSP/uproc
> reverse engineering. It is a development-only, out-of-tree tool: never a
> dependency of the shipped driver and never present in a guest.
risc-v-gsp-rm-debugger boots GSP/uproc firmware in `qemu-system-riscv64`, attaches over
QEMU's gdbstub with a GDB-free Python client, and exposes Frida-like
instrumentation: hooks, breakpoints, watchpoints, memory dumping, structure
decoding, snapshot diffing, session recording, plugins and a Ghidra bridge.
An optional deterministic native RV64IMAC backend (M1) runs the same Session
in-process: `--backend native` or `ge.launch(..., backend="native")`, with an
in-process exec/access trace (M1.5/R4) written as a session blob and rendered
by `analyze` (`--trace`, `--trace-start/--trace-end`, `--trace-exec on|off`).
Start with [`docs/00-OVERVIEW.md`](docs/00-OVERVIEW.md).
## Quick start
```bash
cd open-iov/debug/risc-v-gsp-rm-vm
make demo # build the bundled RV64 uproc demo (clang + lld)
./risc-v-gsp-rm-debugger.sh demo # boot it, hook handlers, watch counters, record + analyze
./risc-v-gsp-rm-debugger.sh demo --backend native # same run on the deterministic native sim
./risc-v-gsp-rm-debugger.sh record --backend native --trace --duration 0.5 # exec/access trace
./risc-v-gsp-rm-debugger.sh info # environment / tooling check
```
Interactively instrument a session:
```bash
./risc-v-gsp-rm-debugger.sh attach --kernel firmware/uproc_demo/build/uproc_demo.elf
risc-v-gsp-rm-debugger> bp rpc_sum
risc-v-gsp-rm-debugger> watch gsp_ctrl+0x10 8 w
risc-v-gsp-rm-debugger> x 0x80000840 64
risc-v-gsp-rm-debugger> c 2
```
Or launch a target separately and attach to it by port:
```bash
./risc-v-gsp-rm-debugger.sh launch --kernel <elf> # prints the gdbstub port, keeps QEMU alive
./risc-v-gsp-rm-debugger.sh attach --port <port> --kernel <elf>
```
Requirements: QEMU (`qemu-system-misc` on Ubuntu gives
`qemu-system-riscv64`), Python 3.10+, clang + lld for the demo firmware.
Everything else is Python stdlib.
## Layout
```
greeneye/ Python package: RSP client, session, memory, symbols,
structures, recording, analysis, probes, plugins, Ghidra bridge
sim/ deterministic native RV64IMAC simulator (M1: decode, RAM,
UART; M1.5: exec/access trace in sim/trace.py)
firmware/uproc_demo/RV64 bare-metal demo "uproc" (mailbox RPC, state machine, trap)
sdk/ injected-service SDK (position-independent RV64 blobs)
qemu/ launch helper + optional TCG plugin for full memory tracing
ghidra/ Ghidra scripts (export symbols, annotate hits, control bridge)
plugins/ example plugin, MCP server, RM-harness plugin + authoring guide
examples/ Python instrumentation scripts and declarative probe specs
harness/ automation harness (mutation, portability, version diff,
control discovery/reachability, value-validation demos)
rmharness/ host RM oracle wrappers + read-only capture harness
tests/ unit tests + QEMU integration smoke tests
docs/ full documentation set (design, scripting, plugins, accuracy,
portability playbooks, roadmap, service/injection guides)
dumps/ recorded sessions (gitignored)
```
## Documentation map
| Doc | Content |
|---|---|
| [00-OVERVIEW](docs/00-OVERVIEW.md) | purpose, status, quickstart |
| [01-DESIGN](docs/01-DESIGN.md) | architecture and data model |
| [02-USAGE](docs/02-USAGE.md) | CLI and REPL recipes |
| [03-SCRIPTING](docs/03-SCRIPTING.md) | Python API + probe specs |
| [04-PLUGINS](docs/04-PLUGINS.md) | writing risc-v-gsp-rm-debugger plugins |
| [05-GHIDRA-BRIDGE](docs/05-GHIDRA-BRIDGE.md) | static/dynamic address join |
| [06-ACCURACY](docs/06-ACCURACY.md) | simulation fidelity and measurement |
| [07-PORTABILITY-PLAYBOOKS](docs/07-PORTABILITY-PLAYBOOKS.md) | new GSP/device/arch runs |
| [08-ROADMAP](docs/08-ROADMAP.md) | MCP, custom simulator, device model |
| [09-GSP-FIRMWARE-NOTES](docs/09-GSP-FIRMWARE-NOTES.md) | uproc/falcon/NV-RISCV facts |
| [10-RELATED-WORK](docs/10-RELATED-WORK.md) | Frida/GDB/QEMU-plugin comparison |
| [11-GSP-RM-SERVICE-DEVELOPER-GUIDE](docs/11-GSP-RM-SERVICE-DEVELOPER-GUIDE.md) | writing, injecting and debugging firmware services |
| [12-INJECTION-SDK](docs/12-INJECTION-SDK.md) | injection blob/ABI specification |
| [13-GHIDRA-CONTROL](docs/13-GHIDRA-CONTROL.md) | driving risc-v-gsp-rm-debugger from GhidraScripts |
| [14-ADVERSARIAL-INTEROP-GUIDE](docs/14-ADVERSARIAL-INTEROP-GUIDE.md) | navigating unpredictable/adversarial firmware change |
| [15-AGENTIC-GSP-IDE](docs/15-AGENTIC-GSP-IDE.md) | agentic workflows and runbooks |
| [16-CUSTOM-SIMULATOR](docs/16-CUSTOM-SIMULATOR.md) | non-QEMU simulator design; M1 native backend + M1.5 trace status/usage |
| [17-RM-HARNESS](docs/17-RM-HARNESS.md) | host RM oracle harness (`rmharness`, wrappers, capture) |
| [18-HARNESS-AUTOMATION](docs/18-HARNESS-AUTOMATION.md) | mutation/portability automation harness |
| [19-CONTROL-DISCOVERY](docs/19-CONTROL-DISCOVERY.md) | unknown-call discovery and reachability |
| [20-MCP-SERVER](docs/20-MCP-SERVER.md) | bundled MCP server plugin |
| [21-CI-RELEASE-PIPELINE](docs/21-CI-RELEASE-PIPELINE.md) | release triage pipeline (`harness/ci_release.py`) |
| [22-PORTING-CUDA-AND-DEVICES](docs/22-PORTING-CUDA-AND-DEVICES.md) | portability playbook for new CUDA/devices |
| [23-RM610-READINESS](docs/23-RM610-READINESS.md) | RM 610 readiness checklist |
| [24-DEVICE-MAP](docs/24-DEVICE-MAP.md) | versioned first-touch MMIO device map |
| [25-VALUE-VALIDATION](docs/25-VALUE-VALIDATION.md) | value-validation demos (s01–s10) |
| [26-ARCHITECTURE](docs/26-ARCHITECTURE.md) | full architecture/API surface map |
| [27-TOOL-AUDIT](docs/27-TOOL-AUDIT.md) | tool audit: purpose, tests, usage, status |
| [28-PORTING-AUTOMATION](docs/28-PORTING-AUTOMATION.md) | driver-version sweep and new-device scaffolds (pilot, dry-run default) |
| [29-PACKAGING-AND-TRIALING](docs/29-PACKAGING-AND-TRIALING.md) | trial simulation packages (pilot) |
| [RISC-V-GSP-RM-DEBUGGER-ROADMAP](RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) | the long-term program (H1–H7) |
<!-- change (2026-10-02): add docs 28/29 to the documentation map; scope: doc
map only; benefit: new tool-tree documents are linked from the tree front
door. -->
|
