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
131
132
133
134
|
# 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).
> The 2026-10-03 Phase S simulator docs (30–40: cycle model, device model,
> A/B verdict, triage) remain **in development** and are labelled as such.
> Experimental tooling for simulating and inspecting the GSP firmware's
> runtime memory, for `vgsp` 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,
S4 A/B + new-version triage: sim_qemu_line.py, triage.py)
rmharness/ host RM oracle wrappers + read-only capture harness
gpgpu-sim/ Phase G overlay scaffold (configs, patches, scripts; docs/30)
tests/ unit tests + QEMU integration smoke tests
docs/ full documentation set (design, scripting, plugins, accuracy,
portability playbooks, roadmap, service/injection guides,
simulator device model/cycle/A-B/review docs 30-40)
dumps/ recorded sessions (gitignored)
SIMULATOR-WORK-BOUNDARY.txt scope contract for the 2026-10-03 simulator wave
```
## 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) |
| [30-GPGPU-SIM-INTEGRATION](docs/30-GPGPU-SIM-INTEGRATION.md) | GPGPU-Sim overlay: scaffold, build port, admission drafts (Phase G) |
| [31-TURING-TU104-PARAMETERS](docs/31-TURING-TU104-PARAMETERS.md) | Turing TU104 parameter dossier (public sources) |
| [32-GSP-CYCLE-MODEL](docs/32-GSP-CYCLE-MODEL.md) | modeled per-instruction cycle accounting (not silicon timing) |
| [33-AMPERE-PARAMETERS](docs/33-AMPERE-PARAMETERS.md) | Ampere parameter dossier (public sources) |
| [34-BLACKWELL-SOURCES](docs/34-BLACKWELL-SOURCES.md) | Blackwell source classification (public/private leads) |
| [35-GREENEYE-SIMULATOR-DESIGN](docs/35-GREENEYE-SIMULATOR-DESIGN.md) | standalone GSP simulator design; Phase S/G scope and gates |
| [36-GSP-DEVICE-MODEL](docs/36-GSP-DEVICE-MODEL.md) | S1 device model, versioned profiles, boot ladder B0–B2 |
| [37-SIM-QEMU-LINE](docs/37-SIM-QEMU-LINE.md) | simulator-vs-QEMU A/B harness and measured line verdict |
| [38-GSP-EM-API](docs/38-GSP-EM-API.md) | TLV boundary between the GSP emulator and a system simulator (design) |
| [39-RE-WORKFLOW-REVIEW](docs/39-RE-WORKFLOW-REVIEW.md) | reverse-engineering workflow review: time sinks and upgrades |
| [40-NEW-VERSION-TRIAGE](docs/40-NEW-VERSION-TRIAGE.md) | one-command new-version triage (`harness/triage.py`, `./risc-v-gsp-rm-debugger.sh triage`) |
| [41-STABILITY-AND-TIME-TO-VALUE](docs/41-STABILITY-AND-TIME-TO-VALUE.md) | formal stability/value report: phased improvements, proof, adversarial review, conditions |
| [RISC-V-GSP-RM-DEBUGGER-ROADMAP](RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) | the long-term program (H1–H7) |
Scope contract for the current simulator wave:
[`SIMULATOR-WORK-BOUNDARY.txt`](SIMULATOR-WORK-BOUNDARY.txt).
<!-- 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. -->
|
