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/greeneye/ghidra.py b/debug/risc-v-gsp-rm-vm/greeneye/ghidra.py
new file mode 100644
index 0000000..6986d74
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/greeneye/ghidra.py
@@ -0,0 +1,80 @@
+"""Ghidra bridge: symbols in, hit annotations out.
+
+Two flows:
+
+*out of Ghidra*: export function names/addresses/sizes to a green-eye JSON
+symbol database (from ``names.tsv``, ``decompiled_index.tsv``, exports or ELF);
+*hits*: turn a recorded session into ``greeneye_hits.tsv``
+(``addr<TAB>hits<TAB>symbol``) that ``MarkGreenEyeHits.java`` can annotate in
+the Ghidra project.
+
+This is the static/dynamic join: Ghidra owns the address space and
+decompilation, green-eye owns what actually executed.
+"""
+from __future__ import annotations
+
+import os
+from collections import Counter
+
+from .record import load_events
+from .symbols import SymbolDB
+
+
+def build_symbol_db(
+    *,
+    names_tsv: str | None = None,
+    index_tsv: str | None = None,
+    exports_tsv: str | None = None,
+    callgraph_tsv: str | None = None,
+    elf: str | None = None,
+    bias: int = 0,
+) -> SymbolDB:
+    db = SymbolDB()
+    if elf:
+        db.load_elf(elf, bias=0)  # ELF symbol values are already runtime addresses
+    if names_tsv:
+        db.load_names_tsv(names_tsv, bias=bias)
+    if index_tsv:
+        db.load_index_tsv(index_tsv, bias=bias)
+    if exports_tsv:
+        db.load_index_tsv(exports_tsv, bias=bias)
+    if callgraph_tsv:
+        db.load_callgraph(callgraph_tsv)
+    return db
+
+
+def export_hits(session_dir: str, out_tsv: str, symbols: SymbolDB | None = None) -> str:
+    events = load_events(session_dir)
+    hits: Counter = Counter()
+    for event in events:
+        if event.get("type") == "bp_hit":
+            hits[event.get("pc")] += 1
+        elif event.get("type") == "watch_hit":
+            hits[event.get("addr")] += 1
+    with open(out_tsv, "w", encoding="utf-8") as fh:
+        fh.write("addr\thits\tsymbol\tannotation\n")
+        for addr, count in sorted(hits.items(), key=lambda kv: -kv[1]):
+            if not isinstance(addr, int):
+                continue
+            sym = symbols.resolve(addr) if symbols else None
+            name = sym.name if sym else ""
+            annotation = symbols.annotate(addr) if symbols else f"{addr:#x}"
+            fh.write(f"{addr:#x}\t{count}\t{name}\t{annotation}\n")
+    return os.path.abspath(out_tsv)
+
+
+def corpus_location(symbol, corpus_root: str) -> str | None:
+    """Return ``<bucket>:<line>`` for a symbol with Ghidra index extras."""
+    bucket = symbol.extras.get("bucket")
+    line = symbol.extras.get("line")
+    if not bucket:
+        return None
+    return os.path.join(corpus_root, bucket) + (f":{line}" if line else "")
+
+
+def render_ghidra_command(project_dir: str, project_name: str, program: str, hits_tsv: str) -> str:
+    return (
+        "analyzeHeadless {proj} {name} -process {program} -noanalysis "
+        "-scriptPath <open-iov>/debug/risc-v-gsp-rm-vm/ghidra "
+        "-postScript MarkGreenEyeHits.java {hits}"
+    ).format(proj=project_dir, name=project_name, program=program, hits=hits_tsv)