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.

4 files changed, 124 insertions, 4 deletions

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/<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.
diff --git a/docs/07-developers/onboarding-and-standards.md b/docs/07-developers/onboarding-and-standards.md
index 241e03f..e62ec28 100644
--- a/docs/07-developers/onboarding-and-standards.md
+++ b/docs/07-developers/onboarding-and-standards.md
@@ -158,6 +158,7 @@ The following rules each come from a real bug and are enforced in review:
 | `tools/firmware_analyzer.py` + Ghidra scripts | firmware analysis pipeline |
 | module debug parameters | guest-memory scanning/poking, VRAM inspection |
 | QEMU gdbstub workflow | guest virtual-memory inspection/writing |
+| `debug/risc-v-gsp-rm-vm/` (green-eye) | **# TOOL IN DEVELOPMENT - NOT READY YET!** — RISC-V GSP/uproc VM runtime inspection, session recording and `gsp-rm-vfio` accuracy measurement (see [`../05-operations/03-risc-v-gsp-rm-vm.md`](../05-operations/03-risc-v-gsp-rm-vm.md)) |
 | `wiki/` documents | protocol and firmware deep dives |
 
 ## 5. Landing a change
diff --git a/docs/README.md b/docs/README.md
index c74c59a..61aa529 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -169,10 +169,11 @@ Read in order if you are new. Jump directly if you know what you need.
 | 17 | [Practical challenges and adversarial interoperability](04-implementation/02-practical-challenges-and-adversarial-interop.md) | developers, stakeholders | 20 min |
 | 18 | [Performance, correctness, security](05-operations/01-performance-correctness-security.md) | developers, auditors | 25 min |
 | 19 | [Debugging and maintenance workflows](05-operations/02-debugging-and-maintenance-workflows.md) | developers, maintainers | 25 min |
-| 20 | [Hardware and software matrix](06-portability/hardware-software-matrix.md) | developers, integrators | 20 min |
-| 21 | [Developer onboarding and standards](07-developers/onboarding-and-standards.md) | contributors | 20 min |
-| 22 | [HAAEEP and collaboration](08-ecosystem/haaeep-and-collaboration.md) | stakeholders, partners | 20 min |
-| 23 | [Glossary and FAQ](09-reference/glossary-and-faq.md) | everyone | reference |
+| 20 | [GSP in a RISC-V VM (green-eye, experimental)](05-operations/03-risc-v-gsp-rm-vm.md) — **# TOOL IN DEVELOPMENT - NOT READY YET!** | developers, analysts | 15 min |
+| 21 | [Hardware and software matrix](06-portability/hardware-software-matrix.md) | developers, integrators | 20 min |
+| 22 | [Developer onboarding and standards](07-developers/onboarding-and-standards.md) | contributors | 20 min |
+| 23 | [HAAEEP and collaboration](08-ecosystem/haaeep-and-collaboration.md) | stakeholders, partners | 20 min |
+| 24 | [Glossary and FAQ](09-reference/glossary-and-faq.md) | everyone | reference |
 
 Row 15 is a **deferred future goal**: host NVIDIA-driver acceleration over a
 virtual function. The feasibility verdict and a first design sketch are
@@ -190,6 +191,11 @@ The pre-reboot flat documents have been merged into this tree and removed
 * debugging: gdbstub/NMI workflows, the EPT-livelock case study and the
   failure taxonomy →
   [`05-operations/02-debugging-and-maintenance-workflows.md`](05-operations/02-debugging-and-maintenance-workflows.md)
+* firmware runtime analysis (experimental): running GSP/uproc firmware in a
+  RISC-V QEMU VM with hooks, watchpoints, memory dumps and `gsp-rm-vfio`
+  accuracy measurement — **# TOOL IN DEVELOPMENT - NOT READY YET!** →
+  [`05-operations/03-risc-v-gsp-rm-vm.md`](05-operations/03-risc-v-gsp-rm-vm.md)
+  (tooling in [`../debug/risc-v-gsp-rm-vm/`](../debug/risc-v-gsp-rm-vm/README.md))
 * performance: the microbenchmark list and the A/B methodology →
   [`05-operations/01-performance-correctness-security.md`](05-operations/01-performance-correctness-security.md)
 * version upgrades: the firmware/driver upgrade runbook (with the corrected