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. --- debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md | 98 ++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md (limited to 'debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md') diff --git a/debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md b/debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md new file mode 100644 index 0000000..a9f4251 --- /dev/null +++ b/debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md @@ -0,0 +1,98 @@ +# 00 — green-eye overview + +> **# TOOL IN DEVELOPMENT - NOT READY YET!** +> Experimental tooling for simulating and inspecting the GSP firmware's +> runtime memory, for `gsp-rm-vfio` accuracy measurements and GSP/uproc +> reverse engineering. Interfaces and file formats may change without notice. +> It is development-only: never shipped, never a dependency of the emulation, +> never present in a guest. + +## What problem it solves + +Open-IOV emulates the GSP interface and (in the physical backend) boots the +real GSP firmware. Both efforts need the same missing capability: to *watch +the firmware do things* — which handler runs, what it reads and writes, what +it returns, how its state machine evolves — without a physical GPU, without +WPR2/hazard exposure, and repeatably. + +green-eye runs uproc/GSP firmware in `qemu-system-riscv64` and gives the +developer Frida-like instrumentation over its memory and execution: + +* breakpoints and enter/leave **hooks** (RV64 ABI aware), +* **watchpoints** on firmware variables, +* **memory** read/write/hexdump/search/scan, +* **structure decoding** from schemas, +* **snapshot + diff** of memory regions, +* **sessions**: a recorded, replayable dump of runtime memory activity, +* **post-run analysis** with symbol annotation, +* **plugins** for new tools, harnesses and virtualization updates, +* a **Ghidra bridge** joining static addresses to runtime hits, +* A/B tooling for **bare-metal vs vfio-mdev** result comparison. + +It is deliberately not a GDB wrapper: a pure-Python RSP client makes the +whole stack scriptable, and QEMU is just the first execution backend. + +## Status (v0.1, 2026-10-02) + +| Capability | State | +|---|---| +| RV64 QEMU boot + gdbstub transport (no GDB) | working, live-verified | +| Hooks / breakpoints / watchpoints / step / continue | working, live-verified | +| Memory tools + struct decode + snapshot diff | working, live-verified | +| Session recording + `analyze` report | working, live-verified | +| Declarative probe specs | working, live-verified | +| Plugin loader + example plugin | working | +| Test suite | 22 tests green (live QEMU smoke included) | +| Ghidra bridge | scripts + docs | +| Real GSP `.fwimage` probe (first-fault report) | working (honest: it does not boot without a TU104 model — see 06) | +| TCG full-memory tracing plugin | source + optional build | +| MCP server / custom simulator / full device model | roadmap only (08) | + +## Quick start + +```bash +cd open-iov/debug/risc-v-gsp-rm-vm +make demo # build the bundled RV64 uproc demo +./greeneye.sh demo # canned instrumentation pass, records a session +./greeneye.sh info # environment check +./greeneye.sh probe # run the real GSP fwimage and report first divergence +``` + +Interactively: + +```bash +./greeneye.sh demo --no-build --duration 0 # launches; prints the gdbstub port +./greeneye.sh attach --port --kernel firmware/uproc_demo/build/uproc_demo.elf +``` + +## Document map + +| Doc | Read it for | +|---|---| +| [01-DESIGN](01-DESIGN.md) | how the pieces fit, transport, data model, limits | +| [02-USAGE](02-USAGE.md) | CLI and REPL recipes | +| [03-SCRIPTING](03-SCRIPTING.md) | writing programs against the API | +| [04-PLUGINS](04-PLUGINS.md) | extending green-eye | +| [05-GHIDRA-BRIDGE](05-GHIDRA-BRIDGE.md) | static/dynamic address join | +| [06-ACCURACY](06-ACCURACY.md) | what the simulation does and does not prove | +| [07-PORTABILITY-PLAYBOOKS](07-PORTABILITY-PLAYBOOKS.md) | new GSP / device / architecture | +| [08-ROADMAP](08-ROADMAP.md) | MCP, custom simulator, device model | +| [09-GSP-FIRMWARE-NOTES](09-GSP-FIRMWARE-NOTES.md) | uproc/falcon/NV-RISCV facts used here | +| [10-RELATED-WORK](10-RELATED-WORK.md) | Frida/GDB/QEMU-plugin comparison | + +## Where this fits in the Open-IOV workflow + +green-eye is a **development and research** tool, alongside the Ghidra corpus +and the guest diagnostics. It does not replace either: + +* **Ghidra** answers *what is the code*; green-eye answers *what did it do*. +* **Guest diagnostics** (`tools/guest-diag`) answer *what did the guest + driver do*; green-eye answers *what did the firmware server do*. +* **The physical backend** (PLAN B) answers *what does real silicon do*; + green-eye provides a safe place to repeat, mutate and single-step the same + firmware when the hardware path is hazardous or unavailable. + +The intended accuracy loop is: run the same workload against the real +GSP-RM (hardware or mdev), record its RPC/state behaviour, then run the +firmware in green-eye, record the same events, and compare with `compare` +(see 06 and 07). -- cgit v1.2.3