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, 204 insertions, 2 deletions

diff --git a/debug/risc-v-gsp-rm-vm/tests/test_bridge.py b/debug/risc-v-gsp-rm-vm/tests/test_bridge.py
new file mode 100644
index 0000000..472bc49
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/tests/test_bridge.py
@@ -0,0 +1,81 @@
+"""Integration tests for the Ghidra JSON-lines control bridge."""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import socket
+import unittest
+
+import greeneye as ge
+from greeneye.gdbridge import GhidraBridge
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+DEMO_ELF = os.path.join(HERE, "..", "firmware", "uproc_demo", "build", "uproc_demo.elf")
+
+
+def qemu_available() -> bool:
+    return bool(os.environ.get("GREENEYE_QEMU") or shutil.which("qemu-system-riscv64"))
+
+
+@unittest.skipUnless(qemu_available(), "qemu-system-riscv64 not installed")
+@unittest.skipUnless(os.path.exists(DEMO_ELF), "demo firmware not built")
+class BridgeTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.session = ge.launch(kernel=DEMO_ELF, record=True, name="unittest-bridge")
+        cls.bridge = GhidraBridge(cls.session, port=0)
+        cls.port = cls.bridge.start()
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.bridge.stop()
+        cls.session.close()
+
+    def call(self, cmd, args=None):
+        with socket.create_connection(("127.0.0.1", self.port), timeout=10) as sock:
+            stream = sock.makefile("rwb")
+            stream.write((json.dumps({"id": 1, "cmd": cmd, "args": args or {}}) + "\n").encode())
+            stream.flush()
+            response = json.loads(stream.readline())
+        self.assertTrue(response["ok"], response)
+        return response["result"]
+
+    def test_info_and_resolve(self):
+        info = self.call("info")
+        self.assertEqual(info["name"], "unittest-bridge")
+        addr = self.call("resolve", {"name": "rpc_sum"})
+        self.assertEqual(addr, self.session.symbols.lookup("rpc_sum"))
+
+    def test_run_until_and_hits(self):
+        result = self.call("run_until", {"target": "rpc_sum", "timeout": 5.0})
+        self.assertEqual(result["addr"], self.session.symbols.lookup("rpc_sum"))
+        hits = self.call("hits")
+        self.assertTrue(any(entry["addr"] == result["addr"] for entry in hits), hits)
+
+    def test_memory_and_registers(self):
+        ctrl = self.session.symbols.lookup("gsp_ctrl")
+        hexdata = self.call("read_mem", {"addr": ctrl, "size": 8})
+        self.assertEqual(len(bytes.fromhex(hexdata)), 8)
+        self.call("write_reg", {"name": "t3", "value": 0x1234})
+        self.assertEqual(self.call("read_reg", {"name": "t3"}), 0x1234)
+
+    def test_breakpoints_and_call(self):
+        addr = self.call("bp_set", {"target": "rpc_fill"})
+        self.assertEqual(addr, self.session.symbols.lookup("rpc_fill"))
+        self.call("bp_clear", {"addr": addr})
+        result = self.call("call", {"target": "rpc_ping", "args": [0x1111]})
+        self.assertEqual(result, 0x1111 ^ 0xBEEF)
+
+    def test_unknown_command(self):
+        with socket.create_connection(("127.0.0.1", self.port), timeout=10) as sock:
+            stream = sock.makefile("rwb")
+            stream.write((json.dumps({"id": 2, "cmd": "nope", "args": {}}) + "\n").encode())
+            stream.flush()
+            response = json.loads(stream.readline())
+        self.assertFalse(response["ok"])
+        self.assertIn("unknown bridge command", response["error"])
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/debug/risc-v-gsp-rm-vm/tests/test_core.py b/debug/risc-v-gsp-rm-vm/tests/test_core.py
index ab27451..907a2eb 100644
--- a/debug/risc-v-gsp-rm-vm/tests/test_core.py
+++ b/debug/risc-v-gsp-rm-vm/tests/test_core.py
@@ -27,8 +27,8 @@ class ElfTests(unittest.TestCase):
         self.assertIn("rpc_ping", names)
         self.assertIn("gsp_ctrl", names)
         ctrl = next(s for s in image.symbols if s.name == "gsp_ctrl")
-        self.assertEqual(ctrl.value, 0x80000840)
-        self.assertEqual(ctrl.size, 0x188)
+        self.assertGreaterEqual(ctrl.value, 0x80000000)
+        self.assertEqual(ctrl.size, 0x190)
         plan = image.flat_load_plan()
         self.assertTrue(plan and plan[0][0] == 0x80000000)
 
diff --git a/debug/risc-v-gsp-rm-vm/tests/test_injection.py b/debug/risc-v-gsp-rm-vm/tests/test_injection.py
new file mode 100644
index 0000000..5dca9cb
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/tests/test_injection.py
@@ -0,0 +1,121 @@
+"""Integration tests for Frida-like remote calls, run-until and service injection.
+
+Skipped cleanly when QEMU, the demo firmware, clang/lld or the SDK are absent.
+"""
+from __future__ import annotations
+
+import io
+import contextlib
+import os
+import shutil
+import subprocess
+import unittest
+
+import greeneye as ge
+from greeneye.errors import RspTimeout
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+TOOL_ROOT = os.path.join(HERE, "..")
+DEMO_ELF = os.path.join(TOOL_ROOT, "firmware", "uproc_demo", "build", "uproc_demo.elf")
+SERVICE_ELF = os.path.join(TOOL_ROOT, "sdk", "build", "injected_demo.elf")
+
+
+def qemu_available() -> bool:
+    return bool(os.environ.get("GREENEYE_QEMU") or shutil.which("qemu-system-riscv64"))
+
+
+def toolchain_available() -> bool:
+    return bool(shutil.which("clang")) and (
+        shutil.which("ld.lld") or os.path.exists("/usr/lib/llvm-18/bin/ld.lld")
+    )
+
+
+@unittest.skipUnless(qemu_available(), "qemu-system-riscv64 not installed")
+@unittest.skipUnless(os.path.exists(DEMO_ELF), "demo firmware not built (make demo)")
+class CallTests(unittest.TestCase):
+    def test_remote_call(self):
+        session = ge.launch(kernel=DEMO_ELF, name="unittest-call")
+        try:
+            result = session.call("rpc_ping", (0x1111,))
+            self.assertEqual(result, 0x1111 ^ 0xBEEF)
+            # registers must be restored around the call
+            self.assertEqual(session.pc, 0x1000)
+        finally:
+            session.close()
+
+    def test_run_until(self):
+        session = ge.launch(kernel=DEMO_ELF, name="unittest-rununtil")
+        try:
+            hit = session.run_until("rpc_sum", timeout=5.0)
+            self.assertEqual(hit.addr, session.symbols.lookup("rpc_sum"))
+            self.assertEqual(hit.kind, "breakpoint")
+        finally:
+            session.close()
+
+    def test_run_until_timeout(self):
+        session = ge.launch(kernel=DEMO_ELF, name="unittest-rununtil-timeout")
+        try:
+            with self.assertRaises(RspTimeout):
+                session.run_until("rpc_fault", timeout=0.2)  # self-test never calls it
+        finally:
+            session.close()
+
+
+@unittest.skipUnless(qemu_available(), "qemu-system-riscv64 not installed")
+@unittest.skipUnless(os.path.exists(DEMO_ELF), "demo firmware not built (make demo)")
+class ReplTests(unittest.TestCase):
+    def test_repl_commands(self):
+        from greeneye.cli import GreenEyeRepl
+        from greeneye.plugins import PluginManager
+
+        session = ge.launch(kernel=DEMO_ELF, record=True, name="unittest-repl")
+        output = io.StringIO()
+        try:
+            ctrl = session.symbols.lookup("gsp_ctrl")
+            repl = GreenEyeRepl(session, PluginManager(session))
+            with contextlib.redirect_stdout(output):
+                repl.onecmd("bp rpc_sum")
+                repl.onecmd("watch gsp_ctrl+0x10 8 w")
+                repl.onecmd(f"x {ctrl:#x} 16")
+                repl.onecmd("sym rpc_ping")
+                repl.onecmd("c 0.6")
+                repl.onecmd("events 5")
+            text = output.getvalue()
+            self.assertIn("rpc_sum", text)
+            self.assertIn(f"{ctrl:08x}", text)
+            self.assertIn(f"watch w@{ctrl + 0x10:#x}", text)
+        finally:
+            session.close()
+
+
+@unittest.skipUnless(qemu_available(), "qemu-system-riscv64 not installed")
+@unittest.skipUnless(os.path.exists(DEMO_ELF), "demo firmware not built")
+@unittest.skipUnless(toolchain_available(), "clang/lld not available")
+class InjectionTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        result = subprocess.run(
+            ["make", "-C", os.path.join(TOOL_ROOT, "sdk")],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0 or not os.path.exists(SERVICE_ELF):
+            raise unittest.SkipTest(f"SDK build failed: {result.stderr[-200:]}")
+
+    def test_direct_and_firmware_invocation(self):
+        from greeneye.inject import invoke_remote, invoke_via_firmware, load_service
+
+        session = ge.launch(kernel=DEMO_ELF, record=True, name="unittest-inject")
+        try:
+            service = load_service(session, SERVICE_ELF, slot=6)
+            self.assertEqual(invoke_remote(session, service, 1, 0x41), 0x41 ^ 0xBEEF)
+            self.assertEqual(invoke_remote(session, service, 2, 0x10, 0x20), 0x30)
+            session.run(duration=0.3)
+            self.assertEqual(invoke_via_firmware(session, service, 1, 0x41), 0x41 ^ 0xBEEF)
+            self.assertEqual(invoke_via_firmware(session, service, 2, 0x10, 0x20), 0x30)
+        finally:
+            session.close()
+
+
+if __name__ == "__main__":
+    unittest.main()