From 31e27d455969d33190d28917ef98f034888d217b Mon Sep 17 00:00:00 2001 From: Arthur Hanson Rasmusson 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 ++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 debug/risc-v-gsp-rm-vm/plugins/README.md (limited to 'debug/risc-v-gsp-rm-vm/plugins/README.md') 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`. -- cgit v1.2.3