From ba58dcdc5ad6ca021c723d279f33e3f14e1184df 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.
---
 debug/risc-v-gsp-rm-vm/plugins/README.md         | 34 ++++++++++++++++++
 debug/risc-v-gsp-rm-vm/plugins/example_plugin.py | 45 ++++++++++++++++++++++++
 2 files changed, 79 insertions(+)
 create mode 100644 debug/risc-v-gsp-rm-vm/plugins/README.md
 create mode 100644 debug/risc-v-gsp-rm-vm/plugins/example_plugin.py

(limited to 'debug/risc-v-gsp-rm-vm/plugins')

diff --git a/debug/risc-v-gsp-rm-vm/plugins/README.md b/debug/risc-v-gsp-rm-vm/plugins/README.md
new file mode 100644
index 0000000..aa9bc72
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/plugins/README.md
@@ -0,0 +1,34 @@
+# green-eye plugins
+
+A plugin is a Python module exposing `register(ge)`:
+
+```python
+def register(ge):
+    ge.log("my plugin loaded")
+    ge.add_command("mycmd", mycmd, help="does a thing")
+    ge.hook("rpc_sum", on_enter=lambda hit: ge.log(f"sum a0={hit.arg(0):#x}"))
+```
+
+`ge` provides:
+* `session`, `memory`, `symbols`, `recorder` — the live objects;
+* `hook(target, on_enter=, on_leave=)` / `watch(target, size=, kind=, callback=)`;
+* `on_event(kind, callback)` — react to every stop of a kind;
+* `add_command(name, fn, help=)` — new REPL commands (`fn(session, args) -> int`);
+* `log(message, **fields)` — recorded plugin notes.
+
+Discovery: `--plugin PATH` (file or directory), then `GREENEYE_PLUGINS`
+(colon-separated), then the bundled `plugins/` directory. A plugin that raises
+is recorded as `plugin_error` and never breaks the session.
+
+Types of plugins that fit green-eye:
+1. **Runtime RE tools** — new watchpoint strategies, coverage collectors,
+   structure probes, heap/allocator graphs.
+2. **Harnesses** — stimulus drivers that poke mailboxes/rings and assert on
+   recorded events.
+3. **Virtualization-environment updates** — replay/record wrappers, QEMU
+   argument tweaks, device-model shims.
+4. **AI/harness integration** — export sessions to analysis services;
+   **MCP servers are planned as a plugin** (see `docs/08-ROADMAP.md`), not
+   part of v0.1.
+
+The example plugin is `example_plugin.py`.
diff --git a/debug/risc-v-gsp-rm-vm/plugins/example_plugin.py b/debug/risc-v-gsp-rm-vm/plugins/example_plugin.py
new file mode 100644
index 0000000..0bd382e
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/plugins/example_plugin.py
@@ -0,0 +1,45 @@
+"""Example green-eye plugin.
+
+Load it explicitly with ``--plugin plugins/example_plugin.py`` (the bundled
+``plugins/`` directory is discovered automatically), or set
+``GREENEYE_PLUGINS=/path/to/plugins``.
+
+It demonstrates the three plugin extension points:
+  * a CLI command (``gehits``),
+  * runtime instrumentation (a hook on ``rpc_state`` logging transitions),
+  * session notes / event stream contributions.
+"""
+from __future__ import annotations
+
+
+def register(ge):
+    ge.log("example plugin loaded")
+
+    state_seen: list[int] = []
+
+    def on_state(hit):
+        state_seen.append(hit.retval or 0)
+        ge.recorder.event(
+            "plugin_state_transition",
+            plugin="example",
+            step=len(state_seen),
+            result=hit.retval,
+            a0=hit.arg(0),
+        )
+
+    sym = ge.symbols.get("rpc_state")
+    if sym is not None:
+        ge.hook("rpc_state", on_leave=on_state)
+        ge.log("hooked rpc_state for transition logging")
+    else:
+        ge.log("rpc_state not in symbol DB; hook skipped")
+
+    def cmd_gehits(session, args):
+        """gehits -- print plugin-observed state transitions."""
+        print(f"  observed {len(state_seen)} rpc_state transitions: {state_seen}")
+        directory = getattr(session.recorder, "dir", None)
+        if directory:
+            print(f"  session: {directory}")
+        return 0
+
+    ge.add_command("gehits", cmd_gehits, help="print plugin-observed rpc_state transitions")
-- 
cgit v1.2.3