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.
---
 .../examples/probes/demo_probes.json               | 25 ++++++++++++++++++++++
 1 file changed, 25 insertions(+)
 create mode 100644 debug/risc-v-gsp-rm-vm/examples/probes/demo_probes.json

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

diff --git a/debug/risc-v-gsp-rm-vm/examples/probes/demo_probes.json b/debug/risc-v-gsp-rm-vm/examples/probes/demo_probes.json
new file mode 100644
index 0000000..db623f1
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/examples/probes/demo_probes.json
@@ -0,0 +1,25 @@
+{
+  "probes": [
+    {
+      "name": "sum-nonzero",
+      "symbol": "rpc_sum",
+      "when": "a1 > 0",
+      "on_enter": {
+        "log": ["a0", "a1"],
+        "dump": [{"reg": "a0", "len": 32, "label": "sum-input"}],
+        "note": "rpc_sum with a non-zero length"
+      },
+      "on_leave": {"log": ["retval"]}
+    },
+    {
+      "name": "state-machine",
+      "symbol": "rpc_state",
+      "on_leave": {"log": ["retval"], "note": "state transition"}
+    },
+    {
+      "name": "trap",
+      "symbol": "rpc_fault",
+      "on_enter": {"note": "rpc_fault entered; the ebreak trap follows"}
+    }
+  ]
+}
-- 
cgit v1.2.3