siligent 0.1.0__py3-none-any.whl

siligent/__init__.py

@@ -0,0 +1,3 @@
+"""Siligent: safe, measured access to real hardware for AI agents."""
+
+__version__ = "0.1.0"

siligent/api.py

@@ -0,0 +1,127 @@
+"""Plain functions shared by the CLI and the MCP server. Each returns a JSON-ready dict."""
+
+from __future__ import annotations
+
+from .bench import Bench, BenchConfig
+from .detect import scan_meters, scan_usb
+from .errors import SiligentError, SafetyRefusal
+from .image import load_image
+from .rules import load_rules
+from .runner import run_tests as _run_tests
+from .safety import BenchState, SafetyGate
+
+
+def _guard(fn):
+    """Turn refusals and errors into structured results an agent can act on."""
+
+    def wrapper(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except SafetyRefusal as e:
+            return e.to_dict()
+        except SiligentError as e:
+            return {"ok": False, "error": str(e)}
+        except Exception as e:  # hardware and library errors: report, don't crash the agent's tool call
+            return {"ok": False, "error": f"{type(e).__name__}: {e}"}
+
+    wrapper.__name__ = fn.__name__
+    wrapper.__doc__ = fn.__doc__
+    return wrapper
+
+
+@_guard
+def detect(config: BenchConfig | None = None, connect: bool = True) -> dict:
+    """List debug probes and, for supported ones, identify the board and its rules."""
+    probes = [p.to_dict() for p in scan_usb()]
+    result: dict = {"ok": True, "probes": probes, "meters": scan_meters()}
+    if connect and any(p["supported"] for p in probes):
+        try:
+            with Bench(config) as bench:
+                result["board"] = {
+                    "name": bench.rules.name,
+                    "chip": bench.rules.chip,
+                    "dev_id": hex(bench.probe.device_id()),
+                    "probe_uid": bench.probe.backend.unique_id,
+                    "rules": bench.rules.source,
+                }
+        except SafetyRefusal as e:
+            result["board"] = e.to_dict()
+    return result
+
+
+@_guard
+def rules(board: str = "stm32l476rg") -> dict:
+    """Show the safety rules for a board."""
+    return {"ok": True, **load_rules(board).summary()}
+
+
+@_guard
+def check_image(path: str, board: str = "stm32l476rg", config: BenchConfig | None = None) -> dict:
+    """Check a firmware image against a board's rules without touching hardware."""
+    cfg = config or BenchConfig.load()
+    image = load_image(path)
+    gate = SafetyGate(load_rules(cfg.board or board), BenchState(cfg.flash_allowed))
+    gate.check_image(image)
+    return {"ok": True, "image": path, "sha256": image.sha256, "bytes": image.size, "detail": "passes image checks"}
+
+
+@_guard
+def flash(path: str, config: BenchConfig | None = None) -> dict:
+    """Flash a firmware image through the safety gate."""
+    with Bench(config) as bench:
+        return bench.probe.flash(load_image(path))
+
+
+@_guard
+def restore(path: str, config: BenchConfig | None = None) -> dict:
+    """Put a saved full-flash snapshot (raw .bin from the start of flash) back on the chip.
+
+    The same safety checks apply as for any flash. Trailing erased bytes are skipped.
+    """
+    from pathlib import Path
+
+    from .image import Image, Segment
+
+    raw = Path(path).read_bytes().rstrip(b"\xff")
+    raw += b"\xff" * (-len(raw) % 8)  # flash programs in 8-byte double words
+    with Bench(config) as bench:
+        image = Image(path, [Segment(bench.rules.flash.start, raw)])
+        return bench.probe.flash(image)
+
+
+@_guard
+def run_tests(path: str, timeout_s: float = 10.0, config: BenchConfig | None = None) -> dict:
+    """Flash test firmware, run it, and return pass/fail, cycles and energy."""
+    with Bench(config) as bench:
+        return _run_tests(bench.probe, load_image(path), meter=bench.meter, timeout_s=timeout_s)
+
+
+@_guard
+def read_memory(address: int, length: int, config: BenchConfig | None = None) -> dict:
+    """Read memory from the chip."""
+    if not 0 < length <= 4096:
+        raise SiligentError("length must be between 1 and 4096 bytes")
+    with Bench(config) as bench:
+        data, halted = bench.probe.read_memory_checked(address, length)
+    out = {"ok": True, "address": hex(address), "length": length, "hex": data.hex()}
+    if halted:
+        out["note"] = "the core was asleep, so it was halted briefly for this read and then resumed"
+    return out
+
+
+@_guard
+def write_memory(address: int, data_hex: str, config: BenchConfig | None = None) -> dict:
+    """Write bytes to RAM or a peripheral register, subject to the board's rules."""
+    data = bytes.fromhex(data_hex)
+    with Bench(config) as bench:
+        bench.probe.write_memory(address, data)
+    return {"ok": True, "address": hex(address), "length": len(data)}
+
+
+@_guard
+def action_log(n: int = 20, config: BenchConfig | None = None) -> dict:
+    """The most recent bench actions, allowed and refused."""
+    cfg = config or BenchConfig.load()
+    from .log import ActionLog
+
+    return {"ok": True, "entries": ActionLog(cfg.log_path).tail(n)}

siligent/bench.py

@@ -0,0 +1,180 @@
+"""The bench: configuration plus the pieces wired together (probe, rules, meter, log)."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .errors import SiligentError, SafetyRefusal
+from .log import ActionLog
+from .meters.base import PowerMeter
+from .probes.guarded import GuardedProbe
+from .rules import BoardRules, load_rules, rules_for_dev_id
+from .safety import BenchState, SafetyGate
+
+DATA_DIR = Path(os.environ.get("SILIGENT_HOME", "~/.local/share/siligent")).expanduser()
+CONFIG_PATHS = [
+    *([Path(os.environ["SILIGENT_CONFIG"]).expanduser()] if os.environ.get("SILIGENT_CONFIG") else []),
+    Path("bench.toml"),
+    Path("~/.config/siligent/bench.toml").expanduser(),
+]
+
+
+@dataclass
+class BenchConfig:
+    flash_allowed: bool | None = None
+    probe_uid: str | None = None
+    board: str | None = None  # rules name or path; None = detect from the chip
+    meter: dict = field(default_factory=lambda: {"type": "none"})
+    log_path: Path = DATA_DIR / "actions.jsonl"
+    snapshot_dir: Path = DATA_DIR / "snapshots"
+    virtual: bool = False  # use a Renode virtual board instead of real hardware
+    renode_path: str | None = None
+    source: str = "defaults"
+
+    @classmethod
+    def load(cls, path: str | Path | None = None) -> BenchConfig:
+        candidates = [Path(path)] if path else CONFIG_PATHS
+        for p in candidates:
+            if p.is_file():
+                d = tomllib.loads(p.read_text())
+                bench = d.get("bench", {})
+                return cls(
+                    flash_allowed=bench.get("flash_allowed"),
+                    probe_uid=bench.get("probe_uid"),
+                    board=bench.get("board"),
+                    meter=d.get("meter", {"type": "none"}),
+                    log_path=Path(bench.get("log_path", DATA_DIR / "actions.jsonl")).expanduser(),
+                    snapshot_dir=Path(bench.get("snapshot_dir", DATA_DIR / "snapshots")).expanduser(),
+                    virtual=bool(bench.get("virtual", False)),
+                    renode_path=bench.get("renode_path"),
+                    source=str(p),
+                )
+        if path:
+            raise SiligentError(f"no bench config at {path}")
+        return cls()
+
+
+METER_PLUGIN_GROUP = "siligent.meters"
+
+
+def meter_plugins() -> dict:
+    from importlib.metadata import entry_points
+
+    return {ep.name: ep for ep in entry_points(group=METER_PLUGIN_GROUP)}
+
+
+def make_meter(cfg: dict, gate: SafetyGate | None) -> PowerMeter | None:
+    """Build the configured meter. A meter that powers the board ("mode = source")
+    is checked against the board's supply range here, before any plugin code runs."""
+    kind = cfg.get("type", "none").lower()
+    if kind == "none":
+        return None
+    if cfg.get("mode") == "source":
+        if gate is None:
+            raise SiligentError("connect to the board first: its rules decide the allowed supply voltage")
+        if "voltage_mv" not in cfg:
+            raise SiligentError("a meter in source mode needs voltage_mv in bench.toml")
+        gate.check_supply_voltage(int(cfg["voltage_mv"]))
+    if kind == "ina219":
+        from .meters.ina219 import INA219, LinuxI2CBus
+
+        return INA219(
+            LinuxI2CBus(int(cfg["i2c_bus"])),
+            address=int(cfg.get("address", 0x40)),
+            shunt_ohms=float(cfg.get("shunt_ohms", 0.1)),
+        )
+    plugins = meter_plugins()
+    if kind in plugins:
+        return plugins[kind].load()(cfg)
+    available = ", ".join(["none", "ina219", *sorted(plugins)])
+    raise SiligentError(f"unknown meter type '{kind}' (available: {available})")
+
+
+class Bench:
+    """Open a probe, work out which board it is on, and apply that board's rules."""
+
+    def __init__(self, config: BenchConfig | None = None) -> None:
+        self.config = config or BenchConfig.load()
+        self.log = ActionLog(self.config.log_path)
+        self.probe: GuardedProbe | None = None
+        self.rules: BoardRules | None = None
+        self._backend = None
+        self._meter: PowerMeter | None = None
+        self._meter_made = False
+
+    @property
+    def meter(self) -> PowerMeter | None:
+        if self.config.virtual:
+            return None  # a physical meter cannot measure a simulated chip
+        if not self._meter_made:
+            self._meter = make_meter(self.config.meter, self.probe.gate if self.probe else None)
+            self._meter_made = True
+        return self._meter
+
+    def connect(self) -> GuardedProbe:
+        if self.config.virtual:
+            return self._connect_virtual()
+        from .probes.pyocd_backend import PyOCDBackend
+
+        # Read the chip ID with a generic Cortex-M connection, then load the matching rules.
+        hint = load_rules(self.config.board) if self.config.board else None
+        backend = PyOCDBackend(
+            target=hint.pyocd_target if hint else "cortex_m", unique_id=self.config.probe_uid
+        )
+        backend.open()
+        try:
+            rules = hint
+            if rules is None:
+                # DBGMCU_IDCODE lives at 0xE0042000 on STM32 F4/L4; other families add their own rules.
+                dev_id = backend.read32(0xE0042000) & 0xFFF
+                rules = rules_for_dev_id(dev_id)
+                if rules is None:
+                    raise SafetyRefusal(
+                        "board.unknown",
+                        f"No safety rules for this chip (device ID {hex(dev_id)}), so only reads are allowed.",
+                        dev_id=hex(dev_id),
+                    )
+                backend.close()
+                backend = PyOCDBackend(target=rules.pyocd_target, unique_id=backend.unique_id)
+                backend.open()
+        except Exception:
+            backend.close()
+            raise
+        gate = SafetyGate(rules, BenchState(flash_allowed=self.config.flash_allowed))
+        self._backend = backend
+        self.rules = rules
+        self.probe = GuardedProbe(backend, rules, gate, self.log, self.config.snapshot_dir)
+        self.log.record("connect", "ok", probe=backend.unique_id, board=rules.name)
+        return self.probe
+
+    def _connect_virtual(self) -> GuardedProbe:
+        from .probes.renode_backend import RenodeBackend
+
+        board = self.config.board or "stm32l476rg"
+        rules = load_rules(board)
+        backend = RenodeBackend(board=Path(board).stem, renode=self.config.renode_path)
+        backend.open()
+        # Every rule applies as on real hardware, except the bench check:
+        # nothing physical is flashed, so no equipment can be harmed.
+        gate = SafetyGate(rules, BenchState(flash_allowed=True))
+        self._backend = backend
+        self.rules = rules
+        self.probe = GuardedProbe(backend, rules, gate, self.log, self.config.snapshot_dir)
+        self.log.record("connect", "ok", probe=backend.unique_id, board=rules.name, virtual=True)
+        return self.probe
+
+    def close(self) -> None:
+        if self._backend is not None:
+            self._backend.close()
+            self._backend = None
+            self.probe = None
+
+    def __enter__(self) -> Bench:
+        self.connect()
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()

siligent/boards/renode/stm32l476rg.repl

@@ -0,0 +1,41 @@
+// Virtual STM32L476RG for Renode. Renode ships no STM32L4 model, so this
+// describes just enough of the chip to run Siligent test firmware:
+// the Cortex-M4F core, NVIC, cycle counter, flash, SRAM and the ID registers.
+// Peripherals (GPIO, UART, timers, RCC) are not modelled yet.
+//
+// Cycle counts here come from simulated time, not from timing real
+// instructions, so they are not the same as on the real chip.
+
+cpu: CPU.CortexM @ sysbus
+    cpuType: "cortex-m4f"
+    nvic: nvic
+
+nvic: IRQControllers.NVIC @ sysbus 0xE000E000
+    priorityMask: 0xF0
+    systickFrequency: 4000000
+    IRQ -> cpu@0
+
+// The real chip starts on its 4 MHz MSI clock.
+dwt: Miscellaneous.DWT @ sysbus 0xE0001000
+    frequency: 4000000
+
+// At boot the real chip mirrors flash at address 0, where the core fetches its vector table.
+flash: Memory.MappedMemory @ {
+        sysbus 0x08000000;
+        sysbus 0x00000000
+    }
+    size: 0x100000
+
+sram1: Memory.MappedMemory @ sysbus 0x20000000
+    size: 0x18000
+
+sram2: Memory.MappedMemory @ sysbus 0x10000000
+    size: 0x8000
+
+sysbus:
+    init:
+        // DBGMCU_IDCODE: revision 0x1007, device ID 0x415 (as read from the real board)
+        Tag <0xE0042000, 0xE0042003> "DBGMCU_IDCODE" 0x10076415
+        Tag <0xE0042004, 0xE0042007> "DBGMCU_CR" 0x0
+        // FLASH_OPTR with read protection at level 0, as on the real board
+        Tag <0x40022020, 0x40022023> "FLASH_OPTR" 0xFFEFF8AA

siligent/boards/stm32l476rg.toml

@@ -0,0 +1,92 @@
+# Safety rules for the NUCLEO-L476RG (STM32L476RG).
+# Addresses from the STM32L4x6 reference manual (RM0351).
+
+[board]
+name = "NUCLEO-L476RG"
+chip = "STM32L476RG"
+dev_id = 0x415                # DBGMCU_IDCODE[11:0]
+idcode_address = 0xE0042000   # DBGMCU_IDCODE
+pyocd_target = "stm32l476rgtx"
+
+[memory]
+flash = { start = 0x08000000, size = 0x100000 }   # 1 MB
+ram = [
+    { name = "SRAM1", start = 0x20000000, size = 0x18000 },  # 96 KB
+    { name = "SRAM2", start = 0x10000000, size = 0x8000 },   # 32 KB
+]
+
+# Supply voltage a power meter may apply when it powers the chip (VDD, datasheet range).
+[power]
+vdd_min_mv = 1710
+vdd_max_mv = 3600
+
+# Flashing is refused unless read protection is at level 0 (RDP byte 0xAA).
+# This is the lesson from the locked F401RE.
+[protection]
+optr_address = 0x40022020     # FLASH_OPTR
+rdp_mask = 0xFF
+rdp_level0 = 0xAA
+
+# Host writes (from an agent, the CLI or the Python API) are allowed only here.
+[[allow_write]]
+name = "SRAM1"
+start = 0x20000000
+size = 0x18000
+
+[[allow_write]]
+name = "SRAM2"
+start = 0x10000000
+size = 0x8000
+
+[[allow_write]]
+name = "Peripherals"
+start = 0x40000000
+size = 0x20000000
+
+[[allow_write]]
+name = "Core debug (cycle counter, breakpoints)"
+start = 0xE0000000
+size = 0x100000
+
+# Forbidden ranges win over allowed ranges.
+[[forbid_write]]
+name = "FLASH registers"
+start = 0x40022000
+size = 0x400
+reason = "Flash control, option bytes, write and read protection. Only the flash tool may program flash, and it never touches option bytes."
+
+[[forbid_write]]
+name = "System memory, OTP and option bytes"
+start = 0x1FFF0000
+size = 0x10000
+reason = "OTP writes are permanent and option bytes can lock the chip."
+
+# Firmware containing these words is refused. It is a heuristic: it catches
+# firmware that would unlock the option bytes at run time, which no address
+# check can see. A compiler can split a constant across two instructions,
+# so the read-protection check before every flash is the real backstop.
+[[forbid_image_word]]
+value = 0x08192A3B
+reason = "Option-byte unlock key 1 (FLASH_OPTKEYR). Firmware that unlocks option bytes can set read protection and lock the chip."
+
+[[forbid_image_word]]
+value = 0x4C5D6E7F
+reason = "Option-byte unlock key 2 (FLASH_OPTKEYR). Firmware that unlocks option bytes can set read protection and lock the chip."
+
+# Pins whose mode a host write may not change. Mode 2 = alternate function.
+[gpio]
+base = 0x48000000
+stride = 0x400
+ports = "ABCDEFGH"
+
+[[protected_pin]]
+port = "A"
+pin = 13
+required_mode = 2
+reason = "SWDIO. Changing its mode cuts the debug link."
+
+[[protected_pin]]
+port = "A"
+pin = 14
+required_mode = 2
+reason = "SWCLK. Changing its mode cuts the debug link."

siligent/cli.py

@@ -0,0 +1,73 @@
+"""Command line: `siligent <command>`. Every command prints JSON."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import api
+from .bench import BenchConfig
+
+
+def _int(s: str) -> int:
+    return int(s, 0)
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="siligent", description="Safe, measured access to real hardware.")
+    p.add_argument("--config", help="path to bench.toml (default: ./bench.toml or ~/.config/siligent/bench.toml)")
+    p.add_argument("--virtual", action="store_true", help="use a Renode virtual board instead of real hardware")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    d = sub.add_parser("detect", help="find probes and identify the board")
+    d.add_argument("--no-connect", action="store_true", help="only scan USB; do not open the probe")
+    r = sub.add_parser("rules", help="show a board's safety rules")
+    r.add_argument("board", nargs="?", default="stm32l476rg")
+    c = sub.add_parser("check", help="check a firmware image against the rules, without hardware")
+    c.add_argument("image")
+    f = sub.add_parser("flash", help="flash a firmware image")
+    f.add_argument("image")
+    rs = sub.add_parser("restore", help="put a full-flash snapshot (.bin) back on the chip")
+    rs.add_argument("snapshot")
+    t = sub.add_parser("test",help="flash test firmware, run it, report pass/fail and cycles (plus energy if a power meter is set up)")
+    t.add_argument("image")
+    t.add_argument("--timeout", type=float, default=10.0)
+    rd = sub.add_parser("read", help="read memory")
+    rd.add_argument("address", type=_int)
+    rd.add_argument("length", type=_int)
+    w = sub.add_parser("write", help="write bytes (hex) to RAM or a peripheral")
+    w.add_argument("address", type=_int)
+    w.add_argument("data_hex")
+    lg = sub.add_parser("log", help="show recent bench actions")
+    lg.add_argument("-n", type=int, default=20)
+
+    a = p.parse_args(argv)
+    cfg = BenchConfig.load(a.config)
+    if a.virtual:
+        cfg.virtual = True
+    if a.cmd == "detect":
+        out = api.detect(cfg, connect=not a.no_connect)
+    elif a.cmd == "rules":
+        out = api.rules(a.board)
+    elif a.cmd == "check":
+        out = api.check_image(a.image, config=cfg)
+    elif a.cmd == "flash":
+        out = api.flash(a.image, config=cfg)
+    elif a.cmd == "restore":
+        out = api.restore(a.snapshot, config=cfg)
+    elif a.cmd == "test":
+        out = api.run_tests(a.image, timeout_s=a.timeout, config=cfg)
+    elif a.cmd == "read":
+        out = api.read_memory(a.address, a.length, config=cfg)
+    elif a.cmd == "write":
+        out = api.write_memory(a.address, a.data_hex, config=cfg)
+    else:
+        out = api.action_log(a.n, config=cfg)
+    json.dump(out, sys.stdout, indent=2)
+    print()
+    return 0 if out.get("ok") else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

siligent/detect.py

@@ -0,0 +1,84 @@
+"""Find debug probes from their USB IDs, without opening them."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+# (vendor ID, product ID) -> probe kind. A product ID of None matches any product.
+KNOWN_PROBES: dict[tuple[int, int | None], str] = {
+    (0x0483, 0x3748): "ST-LINK/V2",
+    (0x0483, 0x374B): "ST-LINK/V2-1",
+    (0x0483, 0x374E): "STLINK-V3",
+    (0x0483, 0x374F): "STLINK-V3",
+    (0x0483, 0x3753): "STLINK-V3",
+    (0x0483, 0x3754): "STLINK-V3",
+    (0x1366, None): "SEGGER J-Link",
+    (0x0D28, 0x0204): "CMSIS-DAP (DAPLink)",
+    (0x2E8A, 0x000C): "Raspberry Pi Debug Probe (CMSIS-DAP)",
+}
+
+# Families Siligent can drive today. Others are reported but not opened.
+SUPPORTED_KINDS = {"ST-LINK/V2", "ST-LINK/V2-1", "STLINK-V3"}
+
+
+@dataclass(frozen=True)
+class UsbProbe:
+    kind: str
+    vendor_id: str
+    product_id: str
+    serial: str
+    product: str
+    supported: bool
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def _read(path: Path) -> str:
+    try:
+        return path.read_text().strip()
+    except OSError:
+        return ""
+
+
+def scan_meters(sysfs_root: str | Path = "/sys/bus/usb/devices") -> list[dict]:
+    """List USB power meters Siligent knows, by their USB product name."""
+    root = Path(sysfs_root)
+    if not root.is_dir():
+        return []
+    known = {"PPK2": "Nordic Power Profiler Kit II (plugin: siligent-ppk2)"}
+    return [
+        {"kind": known[product], "serial": _read(dev / "serial")}
+        for dev in sorted(root.iterdir())
+        if (product := _read(dev / "product")) in known
+    ]
+
+
+def probe_kind(vid: int, pid: int) -> str | None:
+    return KNOWN_PROBES.get((vid, pid)) or KNOWN_PROBES.get((vid, None))
+
+
+def scan_usb(sysfs_root: str | Path = "/sys/bus/usb/devices") -> list[UsbProbe]:
+    """List known debug probes by reading Linux sysfs. Opens no device."""
+    found = []
+    root = Path(sysfs_root)
+    if not root.is_dir():
+        return found
+    for dev in sorted(root.iterdir()):
+        vid_s, pid_s = _read(dev / "idVendor"), _read(dev / "idProduct")
+        if not vid_s or not pid_s:
+            continue
+        kind = probe_kind(int(vid_s, 16), int(pid_s, 16))
+        if kind:
+            found.append(
+                UsbProbe(
+                    kind=kind,
+                    vendor_id=vid_s,
+                    product_id=pid_s,
+                    serial=_read(dev / "serial"),
+                    product=_read(dev / "product"),
+                    supported=kind in SUPPORTED_KINDS,
+                )
+            )
+    return found

siligent/errors.py

@@ -0,0 +1,32 @@
+"""Errors raised by Siligent."""
+
+from __future__ import annotations
+
+
+class SiligentError(Exception):
+    """Base class for Siligent errors."""
+
+
+class SafetyRefusal(SiligentError):
+    """An action was refused by the safety gate before it reached the hardware.
+
+    `rule` names the rule that fired, so an agent can tell refusals apart and
+    explain them, instead of retrying blindly.
+    """
+
+    def __init__(self, rule: str, reason: str, **detail: object) -> None:
+        super().__init__(f"refused by rule '{rule}': {reason}")
+        self.rule = rule
+        self.reason = reason
+        self.detail = detail
+
+    def to_dict(self) -> dict:
+        return {"ok": False, "refused": True, "rule": self.rule, "reason": self.reason, "detail": self.detail}
+
+
+class HardwareError(SiligentError):
+    """The hardware did not respond as expected."""
+
+
+class ImageError(SiligentError):
+    """A firmware image could not be read."""