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
|
# 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.
|
