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

diff --git a/debug/risc-v-gsp-rm-vm/ghidra/README.md b/debug/risc-v-gsp-rm-vm/ghidra/README.md
new file mode 100644
index 0000000..e0bb2c0
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/ghidra/README.md
@@ -0,0 +1,39 @@
+# Ghidra bridge scripts
+
+Two Java scripts run inside Ghidra (GUI or headless):
+
+| Script | Direction | Purpose |
+|---|---|---|
+| `ExportForGreenEye.java` | Ghidra → green-eye | write `addr<TAB>name<TAB>size` for every function |
+| `MarkGreenEyeHits.java` | green-eye → Ghidra | annotate functions with runtime hit counts + bookmarks |
+
+Typical loop:
+
+```bash
+# 1. Export the decompiler's view of the firmware.
+$GHIDRA/support/analyzeHeadless <proj_dir> <project> -process <program> -noanalysis \
+    -scriptPath debug/risc-v-gsp-rm-vm/ghidra \
+    -postScript ExportForGreenEye.java /tmp/ghidra-symbols.tsv
+
+# 2. Build a green-eye symbol DB from it.
+./greeneye.sh symbols export --index /tmp/ghidra-symbols.tsv -o symbols.json
+
+# 3. Run a session, then export its hits.
+python3 - <<'PY'
+from greeneye.ghidra import export_hits
+from greeneye.symbols import SymbolDB
+db = SymbolDB(); db.load_json("symbols.json")
+print(export_hits("dumps/<run>", "/tmp/greeneye_hits.tsv", symbols=db))
+PY
+
+# 4. Annotate the project.
+$GHIDRA/support/analyzeHeadless <proj_dir> <project> -process <program> -noanalysis \
+    -scriptPath debug/risc-v-gsp-rm-vm/ghidra \
+    -postScript MarkGreenEyeHits.java /tmp/greeneye_hits.tsv
+```
+
+Address convention: the exported `addr` is the **program address** (what
+Ghidra shows). `greeneye symbols export --index` understands the 3-column
+form and keeps file/program addresses separate when present (4/7-column
+project indexes). Pass `--bias` only when the exported TSV does not already
+carry runtime addresses.