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

diff --git a/debug/risc-v-gsp-rm-vm/README.md b/debug/risc-v-gsp-rm-vm/README.md
new file mode 100644
index 0000000..66f53fa
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/README.md
@@ -0,0 +1,77 @@
+# green-eye — GSP runtime analysis in a RISC-V QEMU VM
+
+> **# 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. It is a development-only, out-of-tree tool: never a
+> dependency of the shipped driver and never present in a guest.
+
+green-eye boots GSP/uproc firmware in `qemu-system-riscv64`, attaches over
+QEMU's gdbstub with a GDB-free Python client, and exposes Frida-like
+instrumentation: hooks, breakpoints, watchpoints, memory dumping, structure
+decoding, snapshot diffing, session recording, plugins and a Ghidra bridge.
+
+Start with [`docs/00-OVERVIEW.md`](docs/00-OVERVIEW.md).
+
+## Quick start
+
+```bash
+cd open-iov/debug/risc-v-gsp-rm-vm
+
+make demo            # build the bundled RV64 uproc demo (clang + lld)
+./greeneye.sh demo   # boot it, hook handlers, watch counters, record + analyze
+./greeneye.sh info   # environment / tooling check
+```
+
+Interactively instrument a session:
+
+```bash
+./greeneye.sh attach --kernel firmware/uproc_demo/build/uproc_demo.elf
+greeneye> bp rpc_sum
+greeneye> watch gsp_ctrl+0x10 8 w
+greeneye> x 0x80000840 64
+greeneye> c 2
+```
+
+Or launch a target separately and attach to it by port:
+
+```bash
+./greeneye.sh launch --kernel <elf>      # prints the gdbstub port, keeps QEMU alive
+./greeneye.sh attach --port <port> --kernel <elf>
+```
+
+Requirements: QEMU (`qemu-system-misc` on Ubuntu gives
+`qemu-system-riscv64`), Python 3.10+, clang + lld for the demo firmware.
+Everything else is Python stdlib.
+
+## Layout
+
+```
+greeneye/           Python package: RSP client, session, memory, symbols,
+                    structures, recording, analysis, probes, plugins, Ghidra bridge
+firmware/uproc_demo/RV64 bare-metal demo "uproc" (mailbox RPC, state machine, trap)
+qemu/               launch helper + optional TCG plugin for full memory tracing
+ghidra/             Ghidra scripts (export symbols, annotate hit addresses)
+plugins/            example plugin + authoring guide
+examples/           Python instrumentation scripts and declarative probe specs
+tests/              unit tests + QEMU integration smoke test
+docs/               full documentation set (design, scripting, plugins, accuracy,
+                    portability playbooks, roadmap, GSP firmware notes)
+dumps/              recorded sessions (gitignored)
+```
+
+## Documentation map
+
+| Doc | Content |
+|---|---|
+| [00-OVERVIEW](docs/00-OVERVIEW.md) | purpose, status, quickstart |
+| [01-DESIGN](docs/01-DESIGN.md) | architecture and data model |
+| [02-USAGE](docs/02-USAGE.md) | CLI and REPL recipes |
+| [03-SCRIPTING](docs/03-SCRIPTING.md) | Python API + probe specs |
+| [04-PLUGINS](docs/04-PLUGINS.md) | writing green-eye plugins |
+| [05-GHIDRA-BRIDGE](docs/05-GHIDRA-BRIDGE.md) | static/dynamic address join |
+| [06-ACCURACY](docs/06-ACCURACY.md) | simulation fidelity and measurement |
+| [07-PORTABILITY-PLAYBOOKS](docs/07-PORTABILITY-PLAYBOOKS.md) | new GSP/device/arch runs |
+| [08-ROADMAP](docs/08-ROADMAP.md) | MCP, custom simulator, device model |
+| [09-GSP-FIRMWARE-NOTES](docs/09-GSP-FIRMWARE-NOTES.md) | uproc/falcon/NV-RISCV facts |
+| [10-RELATED-WORK](docs/10-RELATED-WORK.md) | Frida/GDB/QEMU-plugin comparison |