debug: green-eye wave 3 - RM harness, local simulator, device map, MCP plugin, value-validation demos, CI pipeline, toolchain docs; add host RM tools rmtool/rmtop

1 files changed, 13 insertions, 4 deletions

diff --git a/debug/risc-v-gsp-rm-vm/greeneye/symbols.py b/debug/risc-v-gsp-rm-vm/greeneye/symbols.py
index 7b2e9dd..cb11f7f 100644
--- a/debug/risc-v-gsp-rm-vm/greeneye/symbols.py
+++ b/debug/risc-v-gsp-rm-vm/greeneye/symbols.py
@@ -25,7 +25,7 @@ import json
 import os
 from dataclasses import dataclass, field as _field
 
-from .errors import SymbolNotFound
+from .errors import GreenEyeError, SymbolNotFound
 
 
 @dataclass
@@ -193,9 +193,15 @@ class SymbolDB:
         return count
 
     def load_json(self, path: str) -> int:
-        with open(path, "r", encoding="utf-8") as fh:
-            payload = json.load(fh)
-        symbols = payload.get("symbols", payload if isinstance(payload, list) else [])
+        """Load a green-eye JSON symbol DB; raise GreenEyeError on bad input."""
+        try:
+            with open(path, "r", encoding="utf-8") as fh:
+                payload = json.load(fh)
+        except (OSError, json.JSONDecodeError) as exc:
+            raise GreenEyeError(f"cannot load symbol DB {path!r}: {exc}") from exc
+        if not isinstance(payload, (dict, list)):
+            raise GreenEyeError(f"symbol DB {path!r} must be a JSON object or list")
+        symbols = payload.get("symbols", []) if isinstance(payload, dict) else payload
         count = 0
         for item in symbols:
             try:
@@ -276,12 +282,15 @@ class SymbolDB:
         return f"{addr:#x} {sym.label(addr)}"
 
     def nearest(self, addr: int, max_delta: int = 0x10000) -> Symbol | None:
+        """Alias of :meth:`resolve` kept for call sites that read better as
+        "nearest symbol" (same containing/preceding/max-delta rules)."""
         return self.resolve(addr, max_delta=max_delta)
 
     def names(self) -> list[str]:
         return sorted(self._by_name)
 
     def by_subsystem(self, subsystem: str) -> list[Symbol]:
+        """Return all symbols tagged with ``subsystem`` (loaders set it when known)."""
         return [s for s in self._symbols if s.subsystem == subsystem]