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.

6 files changed, 377 insertions, 0 deletions

diff --git a/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/Makefile b/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/Makefile
new file mode 100644
index 0000000..f406a52
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/Makefile
@@ -0,0 +1,34 @@
+# green-eye uproc demo firmware (RISC-V 64, bare metal)
+#
+# Uses clang + lld (no riscv64 GCC required):
+#   CC=clang, LD=ld.lld (absolute path to llvm-18 lld by default).
+# Override with: make CC=... LLD=...
+
+# `?=` does not override make's built-in CC=cc, so choose clang explicitly;
+# a command-line `make CC=...` still wins.
+CC      := clang
+LLD     ?= $(shell command -v ld.lld 2>/dev/null || echo /usr/lib/llvm-18/bin/ld.lld)
+BUILD   := build
+TARGET  := $(BUILD)/uproc_demo.elf
+
+CFLAGS  := --target=riscv64-unknown-elf -march=rv64imac -mabi=lp64 \
+           -mcmodel=medany -mno-relax -ffreestanding -nostdlib -fno-builtin \
+           -fno-stack-protector -O2 -Wall -Wextra -I.
+LDFLAGS := --ld-path=$(LLD) -nostdlib -static -Wl,-T,linker.ld -Wl,--no-relax
+SRCS    := start.S main.c
+
+.PHONY: all clean dump
+
+all: $(TARGET)
+
+$(TARGET): $(SRCS) linker.ld ge_uart.h
+	@mkdir -p $(BUILD)
+	$(CC) $(CFLAGS) $(SRCS) $(LDFLAGS) -o $@
+	@echo "built $@"
+
+dump: $(TARGET)
+	@llvm-objdump-18 -d --no-show-raw-insn $(TARGET) | head -80 2>/dev/null || \
+	  objdump -d $(TARGET) | head -80
+
+clean:
+	rm -rf $(BUILD)
diff --git a/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/ge_uart.h b/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/ge_uart.h
new file mode 100644
index 0000000..4bd2f53
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/ge_uart.h
@@ -0,0 +1,38 @@
+/* Minimal NS16550A UART helpers for the QEMU virt machine. */
+#ifndef GE_UART_H
+#define GE_UART_H
+
+typedef unsigned char u8;
+typedef unsigned int u32;
+typedef unsigned long u64;
+typedef long i64;
+
+#define UART0_BASE 0x10000000UL
+#define UART_THR   (UART0_BASE + 0x00)
+#define UART_LSR   (UART0_BASE + 0x05)
+
+static inline void uart_putc(char c)
+{
+    volatile u8 *lsr = (volatile u8 *)UART_LSR;
+    while ((*lsr & 0x20) == 0) {
+        /* wait for THR empty */
+    }
+    *(volatile u8 *)UART_THR = (u8)c;
+}
+
+static inline void uart_puts(const char *s)
+{
+    while (*s) {
+        uart_putc(*s++);
+    }
+}
+
+static inline void uart_hex(u64 value, int digits)
+{
+    static const char hex[] = "0123456789abcdef";
+    for (int i = (digits - 1) * 4; i >= 0; i -= 4) {
+        uart_putc(hex[(value >> i) & 0xf]);
+    }
+}
+
+#endif /* GE_UART_H */
diff --git a/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/gsp_ctrl.schema.json b/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/gsp_ctrl.schema.json
new file mode 100644
index 0000000..ca18f81
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/gsp_ctrl.schema.json
@@ -0,0 +1,19 @@
+{
+  "name": "gsp_ctrl",
+  "size": 392,
+  "fields": [
+    {"name": "magic",         "offset": 0,   "fmt": "u32", "note": "GSP-like control block magic 0x47535031"},
+    {"name": "version",       "offset": 4,   "fmt": "u32"},
+    {"name": "state",         "offset": 8,   "fmt": "u32", "enum": {"0": "S0", "1": "S1", "2": "S2", "3": "S3"}},
+    {"name": "heartbeat",     "offset": 12,  "fmt": "u32"},
+    {"name": "rpc_count",     "offset": 16,  "fmt": "u64"},
+    {"name": "last_rpc",      "offset": 24,  "fmt": "u64"},
+    {"name": "mailbox",       "offset": 32,  "fmt": "u64", "enum": {"0": "idle", "1": "PING", "2": "ECHO", "3": "FILL", "4": "SUM", "5": "STATE", "6": "FAULT"}},
+    {"name": "arg0",          "offset": 40,  "fmt": "u64"},
+    {"name": "arg1",          "offset": 48,  "fmt": "u64"},
+    {"name": "result",        "offset": 56,  "fmt": "u64"},
+    {"name": "buf",           "offset": 64,  "fmt": "bytes", "size": 256},
+    {"name": "handler_count", "offset": 320, "fmt": "u64"},
+    {"name": "handlers",      "offset": 328, "fmt": "u64", "count": 8}
+  ]
+}
diff --git a/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/linker.ld b/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/linker.ld
new file mode 100644
index 0000000..7ad7af8
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/linker.ld
@@ -0,0 +1,54 @@
+/* green-eye uproc demo firmware - RISC-V 64 bare-metal test target.
+ *
+ * Mimics the shape of a GSP-side micro-service: a global control block with a
+ * magic, a handler table and counters; a mailbox-driven RPC dispatcher; a
+ * multi-stage state machine handler; and an intentional trap handler so
+ * green-eye can demonstrate breakpoint/hook/watchpoint/trap workflows.
+ *
+ * Build: make -C firmware/uproc_demo
+ */
+OUTPUT_ARCH(riscv)
+ENTRY(_start)
+
+MEMORY
+{
+    RAM (rwxa) : ORIGIN = 0x80000000, LENGTH = 32M
+}
+
+SECTIONS
+{
+    . = 0x80000000;
+
+    .text : ALIGN(4) {
+        KEEP(*(.text.start))
+        *(.text .text.*)
+    } > RAM
+
+    .rodata : ALIGN(8) {
+        *(.rodata .rodata.*)
+    } > RAM
+
+    .data : ALIGN(8) {
+        *(.data .data.*)
+    } > RAM
+
+    /* The control block gets its own section so its address is predictable. */
+    .gsp_data : ALIGN(64) {
+        KEEP(*(.gsp_data))
+    } > RAM
+
+    .bss : ALIGN(8) {
+        *(.bss .bss.*)
+        *(COMMON)
+    } > RAM
+
+    . = ALIGN(16);
+    . += 0x4000;                /* 16 KiB stack */
+    _stack_top = .;
+
+    /DISCARD/ : {
+        *(.comment)
+        *(.note .note.*)
+        *(.riscv.attributes)
+    }
+}
diff --git a/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/main.c b/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/main.c
new file mode 100644
index 0000000..d23b00c
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/main.c
@@ -0,0 +1,222 @@
+/* green-eye uproc demo firmware.
+ *
+ * A small, deterministic "GSP-like" service:
+ *   - gsp_ctrl global control block (magic 0x47535031) in .gsp_data;
+ *   - mailbox-driven RPC dispatcher with a handler table;
+ *   - handlers: PING, ECHO, FILL, SUM, STATE (4-stage machine), FAULT (ebreak);
+ *   - a self-test sequence at boot so a freshly attached debugger sees events;
+ *   - a free-running heartbeat so memory activity is always present.
+ *
+ * No libc: memcpy/memset are provided for the compiler.
+ */
+#include "ge_uart.h"
+
+#define GSP_MAGIC 0x47535031u
+
+typedef struct {
+    u32 magic;              /* +0x00 */
+    u32 version;            /* +0x04 */
+    u32 state;              /* +0x08 */
+    u32 heartbeat;          /* +0x0c */
+    u64 rpc_count;          /* +0x10 */
+    u64 last_rpc;           /* +0x18 */
+    u64 mailbox;            /* +0x20 */
+    u64 arg0;               /* +0x28 */
+    u64 arg1;               /* +0x30 */
+    u64 result;             /* +0x38 */
+    char buf[256];          /* +0x40 */
+    u64 handler_count;      /* +0x140 */
+    u64 handlers[8];        /* +0x148 */
+} gsp_ctrl_t;
+
+volatile gsp_ctrl_t gsp_ctrl __attribute__((section(".gsp_data"), aligned(64)));
+
+/* ---- compiler support (freestanding) ---- */
+
+void *memcpy(void *dst, const void *src, u64 n)
+{
+    u8 *d = (u8 *)dst;
+    const u8 *s = (const u8 *)src;
+    while (n--) {
+        *d++ = *s++;
+    }
+    return dst;
+}
+
+void *memset(void *dst, int value, u64 n)
+{
+    u8 *d = (u8 *)dst;
+    while (n--) {
+        *d++ = (u8)value;
+    }
+    return dst;
+}
+
+static u64 strlen_local(const char *s)
+{
+    u64 n = 0;
+    while (s[n]) {
+        n++;
+    }
+    return n;
+}
+
+/* ---- RPC handlers (kept as symbols for green-eye hooks) ---- */
+
+__attribute__((noinline)) u64 rpc_ping(u64 a0, u64 a1)
+{
+    (void)a1;
+    return a0 ^ 0xbeefu;
+}
+
+__attribute__((noinline)) u64 rpc_echo(u64 a0, u64 a1)
+{
+    (void)a1;
+    const char *src = (const char *)a0;
+    u64 n = strlen_local(src);
+    if (n > sizeof(gsp_ctrl.buf) - 1) {
+        n = sizeof(gsp_ctrl.buf) - 1;
+    }
+    memcpy((void *)gsp_ctrl.buf, src, n);
+    gsp_ctrl.buf[n] = '\0';
+    return n;
+}
+
+__attribute__((noinline)) u64 rpc_fill(u64 a0, u64 a1)
+{
+    u64 n = a1 > sizeof(gsp_ctrl.buf) ? sizeof(gsp_ctrl.buf) : a1;
+    memset((void *)gsp_ctrl.buf, (int)(a0 & 0xff), n);
+    return n;
+}
+
+__attribute__((noinline)) u64 rpc_sum(u64 a0, u64 a1)
+{
+    const u8 *p = (const u8 *)a0;
+    u64 total = 0;
+    for (u64 i = 0; i < a1; i++) {
+        total += p[i];
+    }
+    return total;
+}
+
+__attribute__((noinline)) u64 rpc_state(u64 a0, u64 a1)
+{
+    (void)a0;
+    (void)a1;
+    u64 stage = gsp_ctrl.state & 3u;
+    u64 out = 0;
+    switch (stage) {
+    case 0:
+        out = 0x10;
+        break;
+    case 1:
+        out = 0x20;
+        break;
+    case 2:
+        out = 0x30;
+        break;
+    default:
+        out = 0x40;
+        break;
+    }
+    gsp_ctrl.state = (u32)((stage + 1) & 3u);
+    return out;
+}
+
+__attribute__((noinline)) u64 rpc_fault(u64 a0, u64 a1)
+{
+    (void)a0;
+    (void)a1;
+    __asm__ volatile("ebreak"); /* debugger trap: green-eye stops here */
+    return 0xdead;
+}
+
+/* ---- dispatcher ---- */
+
+typedef u64 (*rpc_fn)(u64, u64);
+
+void rpc_dispatch(u64 cmd, u64 a0, u64 a1)
+{
+    u64 result;
+    switch (cmd) {
+    case 1:
+        result = rpc_ping(a0, a1);
+        break;
+    case 2:
+        result = rpc_echo(a0, a1);
+        break;
+    case 3:
+        result = rpc_fill(a0, a1);
+        break;
+    case 4:
+        result = rpc_sum(a0, a1);
+        break;
+    case 5:
+        result = rpc_state(a0, a1);
+        break;
+    case 6:
+        result = rpc_fault(a0, a1);
+        break;
+    default:
+        result = ~cmd;
+        break;
+    }
+    gsp_ctrl.result = result;
+    gsp_ctrl.last_rpc = cmd;
+    gsp_ctrl.rpc_count = gsp_ctrl.rpc_count + 1; /* after the handler */
+}
+
+static void install_handlers(void)
+{
+    gsp_ctrl.handlers[0] = (u64)(unsigned long)rpc_ping;
+    gsp_ctrl.handlers[1] = (u64)(unsigned long)rpc_echo;
+    gsp_ctrl.handlers[2] = (u64)(unsigned long)rpc_fill;
+    gsp_ctrl.handlers[3] = (u64)(unsigned long)rpc_sum;
+    gsp_ctrl.handlers[4] = (u64)(unsigned long)rpc_state;
+    gsp_ctrl.handlers[5] = (u64)(unsigned long)rpc_fault;
+    gsp_ctrl.handler_count = 6;
+}
+
+int main(void)
+{
+    volatile gsp_ctrl_t *ctl = &gsp_ctrl;
+    ctl->magic = GSP_MAGIC;
+    ctl->version = 1;
+    ctl->state = 0;
+    ctl->heartbeat = 0;
+    ctl->rpc_count = 0;
+    ctl->last_rpc = 0;
+    ctl->mailbox = 0;
+    ctl->result = 0;
+    ctl->buf[0] = '\0';
+    install_handlers();
+
+    uart_puts("GREEN-EYE UPROC DEMO v1\n");
+    uart_puts("MAGIC ");
+    uart_hex(ctl->magic, 8);
+    uart_puts(" CTRL@");
+    uart_hex((u64)(unsigned long)ctl, 8);
+    uart_puts("\n");
+
+    /* Deterministic self-test so freshly attached instrumentation sees events. */
+    rpc_dispatch(1, 0x1111, 0);
+    rpc_dispatch(2, (u64)(unsigned long)"hello-green-eye", 0);
+    rpc_dispatch(3, 0x5a, 32);
+    rpc_dispatch(4, (u64)(unsigned long)ctl->buf, 16);
+    rpc_dispatch(5, 0, 0);
+    rpc_dispatch(5, 0, 0);
+    rpc_dispatch(5, 0, 0);
+    uart_puts("SELFTEST DONE\n");
+
+    for (;;) {
+        ctl->heartbeat = ctl->heartbeat + 1;
+        u64 cmd = ctl->mailbox;
+        if (cmd != 0) {
+            ctl->mailbox = 0;
+            rpc_dispatch(cmd, ctl->arg0, ctl->arg1);
+        }
+        for (volatile int i = 0; i < 2000; i++) {
+            __asm__ volatile("");
+        }
+    }
+}
diff --git a/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/start.S b/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/start.S
new file mode 100644
index 0000000..1341461
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/firmware/uproc_demo/start.S
@@ -0,0 +1,10 @@
+/* green-eye uproc demo firmware - reset/entry. */
+    .section .text.start, "ax", @progbits
+    .global _start
+    .type _start, @function
+_start:
+    la      sp, _stack_top
+    call    main
+1:  wfi
+    j       1b
+    .size _start, . - _start