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.

1 files changed, 98 insertions, 0 deletions

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