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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
# 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`.
When the question is an accept/refuse predicate on a control or entry (e.g. a
promote/shape the firmware keeps refusing), run the firmware's own validation
branch offline first with `harness/valprobe.py` (crafted state, labelled
outcome addresses, deterministic; `docs/47-VALIDATION-PREDICATE-PROBE.md`) —
it answers in seconds what would otherwise cost a static guess or a supervised
cycle. Use `harness/rehost.py` (`docs/46-SURGICAL-REHOST.md`) for a whole
handler/function whose first missing state is itself the finding.
## 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.
Standalone simulator increments (2026-10-06): the native RV64 machine with a
GSP device model and a deterministic real-firmware boot ladder to **B3**
(570.144 image, ~474k instructions, two-run identical), one-command release
triage, GMMU/FBIF observe-only windows and the PTE/PDE decoder, the RM RPC
capture decode/compare/stimulus tooling (`harness/rm_capture.py`, docs/45),
surgical rehost (`harness/rehost.py`, docs/46) and the validation-predicate
probe (`harness/valprobe.py`, docs/47). The predicate probe executes the
shipped firmware's own accept/refuse branch offline with crafted state and
labelled outcomes (seconds, deterministic) — the intended first stop for
control/entry-shape questions before any supervised cycle. The functional
GMMU page-table walker and launch memory-contract auditor
(`sim/gmmu_walk.py`, `harness/launch_audit.py`, docs/48) resolve every
engine-visible address of a submission (ring, inline-QMD destination,
parameter/program pages, release slot) against captured page tables and
classify mismatches, so "where would the engine read/write this VA?" is an
offline question. The suite is at 489 tests.
Limits: fidelity is instruction/memory semantics (L0/L1) — no timing (L2) and
no device environment (L3); host message traffic (B4/B5) is not yet served,
so sessions stay boot-state/predicate level; the GR engine and other GPU
execution units are **not** modelled, so engine/silicon behaviour remains a
hardware question. Not implemented: custom simulator (R2), MCP plugin (R3) —
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.
|
