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, 34 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)