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

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());
+    }
+}