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.

3 files changed, 165 insertions, 0 deletions

diff --git a/debug/risc-v-gsp-rm-vm/ghidra/ExportForGreenEye.java b/debug/risc-v-gsp-rm-vm/ghidra/ExportForGreenEye.java
new file mode 100644
index 0000000..29cc1cd
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/ghidra/ExportForGreenEye.java
@@ -0,0 +1,46 @@
+// Export functions as a green-eye-compatible symbol TSV.
+//
+// Usage (Ghidra headless):
+//   analyzeHeadless <proj> <name> -process <program> -noanalysis \
+//       -scriptPath debug/risc-v-gsp-rm-vm/ghidra \
+//       -postScript ExportForGreenEye.java /abs/path/ghidra-symbols.tsv
+//
+// Columns: addr (program address) <TAB> name <TAB> size.
+// green-eye's `symbols export --index` accepts this form directly.
+//
+//@category OpenIOV
+//@menupath Tools.OpenIOV.Export for green-eye
+
+import java.io.File;
+import java.io.PrintWriter;
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.listing.Function;
+import ghidra.program.model.listing.FunctionIterator;
+
+public class ExportForGreenEye extends GhidraScript {
+
+    @Override
+    public void run() throws Exception {
+        String[] args = getScriptArgs();
+        if (args.length < 1) {
+            println("usage: ExportForGreenEye.java <out.tsv>");
+            return;
+        }
+        File out = new File(args[0]);
+        int count = 0;
+        try (PrintWriter pw = new PrintWriter(out, "UTF-8")) {
+            pw.println("addr\tname\tsize");
+            FunctionIterator functions =
+                currentProgram.getFunctionManager().getFunctions(true);
+            while (functions.hasNext()) {
+                Function function = functions.next();
+                long addr = function.getEntryPoint().getOffset();
+                long size = function.getBody().getNumAddresses();
+                pw.printf("0x%08x\t%s\t%d%n", addr, function.getName(), size);
+                count++;
+            }
+        }
+        println("green-eye: exported " + count + " functions to " + out.getAbsolutePath());
+    }
+}
diff --git a/debug/risc-v-gsp-rm-vm/ghidra/MarkGreenEyeHits.java b/debug/risc-v-gsp-rm-vm/ghidra/MarkGreenEyeHits.java
new file mode 100644
index 0000000..c99c3e1
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/ghidra/MarkGreenEyeHits.java
@@ -0,0 +1,80 @@
+// Annotate green-eye runtime hits in the current Ghidra program.
+//
+// Input: the TSV produced by greeneye.ghidra.export_hits():
+//   addr <TAB> hits <TAB> symbol <TAB> annotation
+//
+// Usage (Ghidra headless):
+//   analyzeHeadless <proj> <name> -process <program> -noanalysis \
+//       -scriptPath debug/risc-v-gsp-rm-vm/ghidra \
+//       -postScript MarkGreenEyeHits.java /abs/path/greeneye_hits.tsv
+//
+// For each address it adds a plate comment on the containing function
+// ("green-eye: N hits") and a bookmark at the exact address.
+//
+//@category OpenIOV
+//@menupath Tools.OpenIOV.Mark green-eye hits
+
+import java.io.BufferedReader;
+import java.io.File;
+import java.io.FileReader;
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.Function;
+
+public class MarkGreenEyeHits extends GhidraScript {
+
+    @Override
+    public void run() throws Exception {
+        String[] args = getScriptArgs();
+        if (args.length < 1) {
+            println("usage: MarkGreenEyeHits.java <greeneye_hits.tsv>");
+            return;
+        }
+        File in = new File(args[0]);
+        int marked = 0;
+        int missed = 0;
+        try (BufferedReader reader = new BufferedReader(new FileReader(in))) {
+            String line;
+            boolean header = true;
+            while ((line = reader.readLine()) != null) {
+                if (header) {
+                    header = false;
+                    if (line.startsWith("addr")) {
+                        continue;
+                    }
+                }
+                if (line.isBlank()) {
+                    continue;
+                }
+                String[] cols = line.split("\t");
+                if (cols.length < 2) {
+                    continue;
+                }
+                long addrValue;
+                try {
+                    addrValue = Long.parseUnsignedLong(cols[0].replace("0x", ""), 16);
+                } catch (NumberFormatException e) {
+                    continue;
+                }
+                String hits = cols[1];
+                String symbol = cols.length > 2 ? cols[2] : "";
+                Address address = toAddr(addrValue);
+                Function function = getFunctionContaining(address);
+                if (function != null) {
+                    String note = "green-eye: " + hits + " hit(s)"
+                        + (symbol.isEmpty() ? "" : " (" + symbol + ")");
+                    String existing = function.getComment();
+                    function.setComment(existing == null ? note : existing + "\n" + note);
+                    marked++;
+                } else {
+                    missed++;
+                }
+                createBookmark(address, "Note", "green-eye",
+                    hits + " runtime hit(s)" + (symbol.isEmpty() ? "" : " " + symbol));
+            }
+        }
+        println("green-eye: annotated " + marked + " functions (" + missed
+            + " addresses outside any function) from " + in.getAbsolutePath());
+    }
+}
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.