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
|
# GSP in a RISC-V VM — green-eye (experimental)
> **# TOOL IN DEVELOPMENT - NOT READY YET!**
> 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. When it reaches a
> minimum stable level, the flags will be removed from this document and from
> the developer-tools list.
## 1. What it is
**green-eye** 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`),
* declarative probe specs, a plugin API and a Ghidra symbol/hit bridge.
Its stated purpose is **simulating and inspecting the GSP firmware's runtime
memory for `gsp-rm-vfio` 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. `greeneye 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*; green-eye 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)** | **green-eye** | **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 green-eye, and compare the recorded sessions
(`greeneye 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
./greeneye.sh info # environment check (QEMU, toolchain)
make demo # build the bundled RV64 uproc demo
./greeneye.sh demo # canned instrumentation pass; records a session
./greeneye.sh analyze dumps/<session>
./greeneye.sh probe # real GSP image: report the first divergence
```
Requirements: `qemu-system-riscv64` (Ubuntu `qemu-system-misc`), Python 3.10+
(stdlib only), `clang` + `lld` for the demo firmware. 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, the Ghidra bridge, and
the real-firmware first-fault probe. The TCG full-memory trace plugin builds
and records. Not implemented: device model (R1), custom simulator (R2), MCP
plugin (R3) — all roadmap.
## 6. When the development flag can be removed
The marker comes off this document and the developer-tools list when:
1. the v0.1 acceptance list in `debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md`
passes on a clean checkout;
2. the usage recipes in `docs/02-USAGE.md` are verified end-to-end;
3. a second person or agent can run the quickstart unaided;
4. the session format and CLI are declared stable.
Until then, treat everything here as in development.
|
