From 31e27d455969d33190d28917ef98f034888d217b Mon Sep 17 00:00:00 2001
From: Arthur Hanson Rasmusson <arthur@vgpu.io>
Date: Fri, 2 Oct 2026 08:36:35 -0400
Subject: 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.
---
 .../risc-v-gsp-rm-vm/ghidra/ExportForGreenEye.java | 46 ++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 debug/risc-v-gsp-rm-vm/ghidra/ExportForGreenEye.java

(limited to 'debug/risc-v-gsp-rm-vm/ghidra/ExportForGreenEye.java')

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());
+    }
+}
-- 
cgit v1.2.3