debug: green-eye wave 2 - injection SDK, Frida-like calls, Ghidra control bridge, long-term docs

Adds to debug/risc-v-gsp-rm-vm/:
- Session.call / run_until: Frida-like remote function calls and run-to-cursor,
  with register restoration; verified live (rpc_ping -> 0xaffe).
- symbol+offset target resolution (gsp_ctrl+0x10) across all APIs and the REPL.
- Injection SDK (sdk/) and 'greeneye inject': position-independent RV64 service
  blobs (verified zero relocations), loaded into RAM, registered in the demo
  handler table, and invoked either directly or through the firmware mailbox
  dispatcher. Demo ABI extended: mailbox 16..23 selects slots, arg0 carries the
  service command, arg2 added (struct now 0x190; schema updated).
- Ghidra control bridge (greeneye ghidra + GreenEyeControl.java): run-until-here,
  breakpoints, memory/register access, remote calls, hit export; verified
  end-to-end with Ghidra headless (run_until reached rpc_sum from a GhidraScript).
- MarkGreenEyeHits.java fixed for the Ghidra 12 createBookmark API; verified
  headless together with ExportForGreenEye.java.
- Analyzer renders a QEMU first-fault table for probe sessions (fault count,
  epc with firmware vaddr translation, access address/size, reason).
- Tests now 35 green, including injection, Ghidra bridge, remote call, run-until
  and REPL command smoke tests.
- Documentation: docs/11-16 (GSP RM service developer guide, injection SDK
  specification, Ghidra control, adversarial interoperability guide, agentic
  GSP IDE, custom simulator design) and GREEN-EYE-ROADMAP.md (long-term H1-H7
  program); doc maps and the project RISC-V VM doc updated.

3 files changed, 110 insertions, 0 deletions

diff --git a/debug/risc-v-gsp-rm-vm/sdk/Makefile b/debug/risc-v-gsp-rm-vm/sdk/Makefile
new file mode 100644
index 0000000..8cccc66
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/sdk/Makefile
@@ -0,0 +1,32 @@
+# green-eye injected-service SDK: builds a position-independent RV64 blob.
+#
+# The service ELF is linked at address 0 and loaded by the injector at a
+# runtime address; all code is PC-relative (medany + PIC, no globals), so no
+# dynamic relocations are required.  Verify with: llvm-readelf-18 -r build/*.elf
+
+CC  := clang
+LLD ?= $(shell command -v ld.lld 2>/dev/null || echo /usr/lib/llvm-18/bin/ld.lld)
+BUILD := build
+TARGET := $(BUILD)/injected_demo.elf
+
+CFLAGS := --target=riscv64-unknown-elf -march=rv64imac -mabi=lp64 \
+          -mcmodel=medany -mno-relax -fPIC -ffreestanding -nostdlib \
+          -fno-builtin -fno-stack-protector -fno-asynchronous-unwind-tables \
+          -O2 -Wall -Wextra -I.
+
+.PHONY: all clean relocs
+
+all: $(TARGET)
+
+$(TARGET): injected_demo.c greeneye_service.h
+	@mkdir -p $(BUILD)
+	$(CC) $(CFLAGS) -c injected_demo.c -o $(BUILD)/injected_demo.o
+	$(LLD) -m elf64lriscv --no-relax -e ge_demo_service_dispatch \
+	    -o $@ $(BUILD)/injected_demo.o
+	@echo "built $@"
+
+relocs: $(TARGET)
+	@llvm-readelf-18 -r $(TARGET) 2>/dev/null || readelf -r $(TARGET)
+
+clean:
+	rm -rf $(BUILD)
diff --git a/debug/risc-v-gsp-rm-vm/sdk/greeneye_service.h b/debug/risc-v-gsp-rm-vm/sdk/greeneye_service.h
new file mode 100644
index 0000000..d5218cc
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/sdk/greeneye_service.h
@@ -0,0 +1,37 @@
+/* green-eye injected-service SDK header.
+ *
+ * A green-eye service is position-independent RV64 code loaded into the
+ * target's RAM by the debugger.  Nothing in the firmware links against it,
+ * so it must not reference globals, absolute addresses or libc: every
+ * function it calls must be one it brings with it (or a function whose
+ * address the injector passes in).
+ *
+ * On the demo uproc, the injector stores the service entry in the control
+ * block's handler table and the firmware dispatches commands 16..23 to it.
+ * On a future GSP-RM simulator the same shape becomes an RM engine entry
+ * registered with the simulated RM core.
+ */
+#ifndef GREENEYE_SERVICE_H
+#define GREENEYE_SERVICE_H
+
+typedef unsigned long ge_u64;
+typedef long ge_i64;
+
+#define GE_SERVICE_MAGIC 0x47455356u /* "GESV" */
+#define GE_SERVICE_VERSION 1u
+
+/* Command range the demo firmware routes to injected handlers. */
+#define GE_INJECT_CMD_BASE 16
+
+/* Dispatch prototype: cmd plus two arguments, one result. */
+typedef ge_u64 (*ge_service_fn)(ge_u64 cmd, ge_u64 a0, ge_u64 a1);
+
+/* Optional metadata block an injector can locate by symbol name. */
+typedef struct {
+    unsigned int magic;
+    unsigned int version;
+    const char *name;
+    ge_u64 (*dispatch)(ge_u64, ge_u64, ge_u64);
+} ge_service_t;
+
+#endif /* GREENEYE_SERVICE_H */
diff --git a/debug/risc-v-gsp-rm-vm/sdk/injected_demo.c b/debug/risc-v-gsp-rm-vm/sdk/injected_demo.c
new file mode 100644
index 0000000..8d836fe
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/sdk/injected_demo.c
@@ -0,0 +1,41 @@
+/* Example green-eye injected service.
+ *
+ * Position-independent, no globals, no libc: safe to load at any address.
+ * Commands (matching the demo firmware's injected command range):
+ *   1: xor a0 with 0xbeef
+ *   2: a0 + a1
+ *   3: rotate a0 left by (a1 & 63)
+ *   4: a0 * 3 + 7
+ *   5: min(a0, a1)
+ *   6: max(a0, a1)
+ * default: ~cmd
+ */
+#include "greeneye_service.h"
+
+__attribute__((noinline)) ge_u64 ge_demo_service_dispatch(ge_u64 cmd, ge_u64 a0, ge_u64 a1)
+{
+    switch (cmd) {
+    case 1:
+        return a0 ^ 0xbeefu;
+    case 2:
+        return a0 + a1;
+    case 3: {
+        unsigned int shift = (unsigned int)(a1 & 63u);
+        return shift ? ((a0 << shift) | (a0 >> (64u - shift))) : a0;
+    }
+    case 4:
+        return a0 * 3u + 7u;
+    case 5:
+        return a0 < a1 ? a0 : a1;
+    case 6:
+        return a0 > a1 ? a0 : a1;
+    default:
+        return ~cmd;
+    }
+}
+
+/* A second entry point, to demonstrate multi-function services. */
+__attribute__((noinline)) ge_u64 ge_demo_service_answer(void)
+{
+    return 42;
+}