From ba58dcdc5ad6ca021c723d279f33e3f14e1184df Mon Sep 17 00:00:00 2001 From: Arthur Hanson Rasmusson Date: Fri, 2 Oct 2026 08:36:35 -0400 Subject: debug: add green-eye GSP/uproc RISC-V VM runtime analysis tooling Adds open-iov/debug/risc-v-gsp-rm-vm: a GDB-free instrumentation stack that boots uproc/GSP firmware in qemu-system-riscv64 and provides Frida-like hooks, breakpoints, watchpoints, memory dumps, structure decoding, snapshot diffs, recorded sessions, declarative probes, a plugin API and a Ghidra symbol/hit bridge. Verified: 25 tests green (including a live QEMU smoke test); the demo uproc boots with correct hook/leave/watch/schema/snapshot/fault evidence; the optional TCG trace plugin builds and recorded 15M trace lines in 3 s; the TU104 570.144 fwimage probe reports its first exception (load access fault at firmware vaddr 0x4009014 reading 0x2000000000000A00). Documentation: lean tool docs under debug/risc-v-gsp-rm-vm/docs/00-10, a new docs/05-operations/03-risc-v-gsp-rm-vm.md debugging document, and '# TOOL IN DEVELOPMENT - NOT READY YET!' markers in docs/README.md, the onboarding tooling table and the debugging workflows doc. Vendors qemu-plugin.h from QEMU v8.2.2 (GPL-2.0-or-later), with its license header intact, so the optional TCG plugin builds without a QEMU source tree. --- .../02-debugging-and-maintenance-workflows.md | 15 ++++ docs/05-operations/03-risc-v-gsp-rm-vm.md | 98 ++++++++++++++++++++++ 2 files changed, 113 insertions(+) create mode 100644 docs/05-operations/03-risc-v-gsp-rm-vm.md (limited to 'docs/05-operations') diff --git a/docs/05-operations/02-debugging-and-maintenance-workflows.md b/docs/05-operations/02-debugging-and-maintenance-workflows.md index 801cda6..8d711c6 100644 --- a/docs/05-operations/02-debugging-and-maintenance-workflows.md +++ b/docs/05-operations/02-debugging-and-maintenance-workflows.md @@ -192,6 +192,21 @@ Watch the serial log afterwards for backtraces. A truly hard-wedged vCPU (spinning on a faulting MMIO instruction) may print nothing — use the gdbstub instead. +### 3.9 Firmware runtime analysis — green-eye (experimental) + +> **# TOOL IN DEVELOPMENT - NOT READY YET!** + +For firmware-side questions (what does the GSP/uproc server do at runtime, +what does it read/write, how do its state machines evolve), the experimental +green-eye tooling runs uproc/GSP firmware in a `qemu-system-riscv64` VM with +hooks, watchpoints, memory dumps and session recording, without a physical +GPU, WPR2 risk or a reboot. See +[`03-risc-v-gsp-rm-vm.md`](03-risc-v-gsp-rm-vm.md) for purpose, status and +limits; tooling and full documentation live in +[`../../debug/risc-v-gsp-rm-vm/`](../../debug/risc-v-gsp-rm-vm/README.md). +It is development-only: never shipped, never in a guest, and not a +substitute for the physical backend when silicon truth is required. + ## 4. Workflows for new inputs ### 4.1 New firmware / driver version (upgrade runbook) diff --git a/docs/05-operations/03-risc-v-gsp-rm-vm.md b/docs/05-operations/03-risc-v-gsp-rm-vm.md new file mode 100644 index 0000000..8d3cf7c --- /dev/null +++ b/docs/05-operations/03-risc-v-gsp-rm-vm.md @@ -0,0 +1,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/ +./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. -- cgit v1.2.3