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

diff --git a/debug/risc-v-gsp-rm-vm/docs/10-RELATED-WORK.md b/debug/risc-v-gsp-rm-vm/docs/10-RELATED-WORK.md
new file mode 100644
index 0000000..a2a45db
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/docs/10-RELATED-WORK.md
@@ -0,0 +1,76 @@
+# 10 — related work: why not Frida, and what each tool is for
+
+> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status.
+
+## 1. Frida
+
+**Verdict for the firmware VM: not applicable.** Upstream Frida ships no
+RISC-V target (checked against the 17.20 release assets: x86/x86_64,
+arm/arm64, mips, macOS/Windows/QNX/Prospero — no `linux-riscv64`), and
+frida-agent requires a hosted OS process. The GSP image is bare-metal RV64
+with its own libos; there is nothing to inject into, and even a hypothetical
+RISC-V port would need an OS layer the firmware does not have.
+
+**Where the Frida *idea* lives in green-eye:** the scripting model. `Session`
+offers `hook`/`watch`/`memory`/`events` with Python callbacks, which is the
+part of Frida that matters for this workflow. The difference is transport:
+RSP to QEMU instead of an injected agent.
+
+**Where Frida is applicable in the project:** host- or guest-userland x86_64
+work (e.g. the CUDA userspace layer) if a dynamic tracer is ever wanted there.
+That is outside this tool's scope; the existing ptrace tracer covers the
+guest today.
+
+## 2. GDB / gdbstub
+
+QEMU's gdbstub is the transport both tools share. GDB itself is still useful
+for *debugging green-eye* (stub behaviour, protocol traces), and `gdb
+-multiarch` can inspect the same target interactively. It is not the
+instrumentation layer here because:
+
+* every operation becomes a subprocess/parse problem instead of an API call;
+* recording, symbol annotation, structure decoding and session diffing would
+  have to be rebuilt around GDB/MI anyway;
+* the project already uses GDB Python scripts for the CUDA corpus; green-eye
+  is the equivalent for firmware, with a stronger data model.
+
+## 3. QEMU TCG plugins
+
+The correct complement, not a competitor: plugins execute inside QEMU and can
+observe **every** instruction and memory access, which gdbstub breakpoints
+cannot. green-eye's `qemu/greeneye_trace.c` emits a JSONL access trace for
+exactly this; integrating it into the session format is R4 on the roadmap.
+Rule of thumb: use green-eye hooks for semantics ("handler X ran with these
+args") and TCG plugins for coverage/heatmaps ("every write to this window").
+
+## 4. Unicorn / emulator libraries
+
+Unicorn (and similar CPU emulators) can execute RV64 code faster to set up
+than QEMU and embed cleanly in Python, but they model no board at all and
+have weaker debug infrastructure. They are candidates for the **custom
+simulator** (R2) once the required device semantics are known — the same
+reason the roadmap defers that work.
+
+## 5. `rr` / record-replay
+
+`rr` does not support RISC-V guests and records at the host-process level.
+QEMU's own record/replay (`-icount`) can provide deterministic reruns later;
+green-eye's session recording occupies a different niche (semantic events,
+not full replay) and can coexist.
+
+## 6. Comparison table
+
+| Tool | Layer | RISC-V firmware | green-eye relationship |
+|---|---|---|---|
+| Frida | userland process injection | no | conceptual model only |
+| GDB + gdbstub | execution control | yes (transport) | debugging green-eye; same stub |
+| QEMU TCG plugin | full instruction/memory trace | yes | complement (R4) |
+| green-eye | semantic instrumentation + recording + analysis | yes | this tool |
+| Unicorn/rv8/etc. | CPU emulation library | yes | R2 candidate |
+| Ghidra | static decompilation | yes | symbol/hit bridge (05) |
+
+## 7. Reading list
+
+* `docs/01-DESIGN.md` — where each layer sits.
+* `docs/05-GHIDRA-BRIDGE.md` — the static/dynamic join.
+* `docs/08-ROADMAP.md` — R1 device model, R2 custom simulator, R3 MCP.