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, 116 insertions, 0 deletions

diff --git a/debug/risc-v-gsp-rm-vm/docs/08-ROADMAP.md b/debug/risc-v-gsp-rm-vm/docs/08-ROADMAP.md
new file mode 100644
index 0000000..c8b4638
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/docs/08-ROADMAP.md
@@ -0,0 +1,116 @@
+# 08 — green-eye roadmap
+
+> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status.
+> Items here are **not** v0.1. Do not start them ad hoc; each has a gate.
+
+## R0. Product principles
+
+* green-eye stays a **development tool**: no shipped dependencies, no guest
+  presence, no kernel-module coupling.
+* Fidelity improvements must be *measurable* (metrics table in 06) and must
+  not slow the fast path (demo + probe) below usefulness.
+* Every new backend must satisfy the same `Session` contract so scripts,
+  probes, plugins and recordings survive.
+
+## R1. Platform device model (raise L3)
+
+**Why:** a bare `qemu virt` cannot boot the real fwimage; the probe shows the
+first unmapped access and stops.
+
+**Scope:** model the minimum GSP environment:
+falcon windows (FALCON/CSB/TRANSCOM registers), WPR2/FWSEC state registers
+with read-back semantics, PTIMER, PMU/SEC2 mailbox stubs, FB DMA/IOMMU
+address translation for the firmware's DMA descriptors, and interrupt
+routing. QEMU `qemu-system-riscv64` with a custom device (`-device`) is the
+preferred vehicle; TCG plugins provide the observation points.
+
+**Gate:** R1 starts only when a portability task (P2/P3) or an accuracy
+measurement (P1.6) requires booting real firmware in-simulator. Until then,
+use the probe + rehosted uproc paths.
+
+**Exit criteria:** `greeneye probe <fwimage>` reaches a stable address and
+reports "waiting for host message" rather than a fault; the first host↔GSP
+RPC records are captured in a session; M3 ordering can be measured against
+the physical backend.
+
+## R2. Custom simulator (explicitly requested; not first version)
+
+**Why:** QEMU is an excellent execution engine but a poor *workflow* engine
+for this project: no in-process API, RSP serialisation for every access,
+limited snapshotting, and a device model designed for whole boards rather
+than firmware servers. A custom simulator can be deterministic, replayable
+and scriptable at native speed.
+
+**Shape (to build later, not now):**
+* an RV64IMAC interpreter/JIT with a **pluggable memory map** (RAM, MMIO
+  hooks, DMA windows) and a **deterministic scheduler** (no realtime claim);
+* native `Session` integration — replace the RSP transport with a
+  `Backend` interface, keep hooks/watchpoints/memory/recording identical;
+* first-class **snapshot/restore** of full machine state (time-travel
+  debugging, branch-flip experiments);
+* an **event bus** feeding the existing `events.jsonl` schema;
+* a **stub DSL** for device registers (read/write scripts with state), so a
+  new GPU generation is configuration, matching the project's portability
+  direction.
+
+**Candidates to evaluate at that time:** extending QEMU TCG with a thin
+in-process backdoor, `libriscv`, `rv8`, or a from-scratch interpreter.
+Realtime is explicitly *not* a requirement; determinism and introspection are.
+
+**Gate:** R1 must have stabilised the device semantics (otherwise the custom
+simulator inherits an unvalidated model). Estimated multi-week work; schedule
+only after the guest-bridge work (PLAN B) no longer depends on it.
+
+## R3. MCP server plugin
+
+**Why:** expose green-eye sessions to AI harnesses and other agents under the
+plugin model the user requested.
+
+**Shape:** a plugin (`plugins/mcp_server.py` when built) that wraps the
+session/analysis API as MCP tools: `list_sessions`, `open_session`,
+`symbols_resolve`, `set_breakpoint`, `run`, `memory_read`, `memory_hexdump`,
+`snapshot`, `compare_sessions`, `export_hits`. Transport local stdio first;
+no network exposure by default. The plugin depends on an MCP library only at
+plugin load time; the core stays stdlib-only.
+
+**Gate:** v0.1 must be stable (acceptance list in 00) and the session format
+frozen. Explicitly deferred by the owner; do not add MCP code before then.
+
+## R4. Full-memory trace (TCG plugin integration)
+
+The optional `qemu/greeneye_trace.c` plugin records instruction execution and
+memory accesses. Roadmap: build it against the vendored QEMU headers, stream
+its JSONL into the session format as `exec`/`access` events, and teach
+`analyze` to render coverage/heatmaps and written-page timelines. This is the
+"complete map" upgrade from stop-based observation to full access tracing.
+
+**Gate:** available once the QEMU plugin headers are vendored (or the build
+environment provides them). Does not block v0.1 — watchpoint recording plus
+step traces already cover the common cases.
+
+## R5. Fuzzing and mutation harness
+
+Use AFL++ QEMU mode (or a custom mutator) against the rehosted firmware's
+RPC input surface, with green-eye recording crash/trap paths and symbol
+annotation. Requires R1/R2 for stable input plumbing. Output: a corpus of
+malformed controls and the firmware's error paths, feeding the emulation's
+fail-closed rules (project security hygiene).
+
+## R6. Multi-version orchestration
+
+Scripts that, given a set of firmware images and device profiles, run the
+probe + rehost + compare pipeline for the whole matrix and emit the M1–M6
+tables. This automates `07-PORTABILITY-PLAYBOOKS` P1–P3.
+
+## R7. Ghidra two-way console
+
+A Ghidra script/plugin that talks to a live green-eye session (via the CLI or
+a local socket) to toggle breakpoints/watchpoints from the decompiler and to
+highlight hit addresses. Until then, the hit-TSV + `MarkGreenEyeHits.java`
+flow is the supported path.
+
+## Not on the green-eye roadmap
+
+* Graphics/display emulation, Windows guest internals, multi-tenant policy —
+  these belong to the main project roadmap, not to this analysis tool.
+* Replacing Ghidra: green-eye is the dynamic complement, never a decompiler.