siligent 0.1.0__py3-none-any.whl

siligent/image.py

@@ -0,0 +1,93 @@
+"""Read firmware images (ELF or raw binary) into loadable segments and symbols."""
+
+from __future__ import annotations
+
+import hashlib
+import struct
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .errors import ImageError
+
+PT_LOAD = 1
+SHT_SYMTAB = 2
+
+
+@dataclass(frozen=True)
+class Segment:
+    address: int
+    data: bytes
+
+    @property
+    def end(self) -> int:
+        return self.address + len(self.data)
+
+
+@dataclass
+class Image:
+    path: str
+    segments: list[Segment]
+    symbols: dict[str, tuple[int, int]] = field(default_factory=dict)  # name -> (address, size)
+
+    @property
+    def sha256(self) -> str:
+        h = hashlib.sha256()
+        for s in sorted(self.segments, key=lambda s: s.address):
+            h.update(s.address.to_bytes(4, "little"))
+            h.update(s.data)
+        return h.hexdigest()
+
+    @property
+    def size(self) -> int:
+        return sum(len(s.data) for s in self.segments)
+
+    def word_at(self, address: int) -> int | None:
+        for s in self.segments:
+            if s.address <= address and address + 4 <= s.end:
+                off = address - s.address
+                return int.from_bytes(s.data[off : off + 4], "little")
+        return None
+
+
+def load_image(path: str | Path, base_address: int | None = None) -> Image:
+    """Load an .elf, or a raw .bin placed at `base_address`."""
+    path = Path(path)
+    if not path.is_file():
+        raise ImageError(f"no such file: {path}")
+    raw = path.read_bytes()
+    if raw[:4] == b"\x7fELF":
+        return _load_elf(raw, str(path))
+    if base_address is None:
+        raise ImageError("a raw binary needs a base address (for example the start of flash)")
+    return Image(str(path), [Segment(base_address, raw)])
+
+
+def _load_elf(raw: bytes, path: str) -> Image:
+    if raw[4] != 1 or raw[5] != 1:
+        raise ImageError("only 32-bit little-endian ELF files are supported")
+    (e_phoff, e_shoff) = struct.unpack_from("<II", raw, 0x1C)
+    (e_phentsize, e_phnum, e_shentsize, e_shnum) = struct.unpack_from("<HHHH", raw, 0x2A)
+
+    segments = []
+    for i in range(e_phnum):
+        p_type, p_offset, _vaddr, p_paddr, p_filesz = struct.unpack_from("<IIIII", raw, e_phoff + i * e_phentsize)
+        if p_type == PT_LOAD and p_filesz:
+            # The physical (load) address is where the bytes live in flash.
+            segments.append(Segment(p_paddr, raw[p_offset : p_offset + p_filesz]))
+
+    symbols: dict[str, tuple[int, int]] = {}
+    sections = [struct.unpack_from("<IIIIIIIIII", raw, e_shoff + i * e_shentsize) for i in range(e_shnum)]
+    for sh in sections:
+        if sh[1] != SHT_SYMTAB:
+            continue
+        sym_off, sym_size, link, entsize = sh[4], sh[5], sh[6], sh[9] or 16
+        str_off = sections[link][4]
+        for j in range(sym_size // entsize):
+            st_name, st_value, st_size = struct.unpack_from("<III", raw, sym_off + j * entsize)
+            if st_name:
+                end = raw.index(b"\0", str_off + st_name)
+                symbols[raw[str_off + st_name : end].decode(errors="replace")] = (st_value, st_size)
+
+    if not segments:
+        raise ImageError("the ELF file has no loadable segments")
+    return Image(path, segments, symbols)

siligent/log.py

@@ -0,0 +1,25 @@
+"""An append-only log of every action taken on the bench, refused or not."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+
+class ActionLog:
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path).expanduser()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def record(self, action: str, outcome: str, **fields: object) -> dict:
+        entry = {"time": time.strftime("%Y-%m-%dT%H:%M:%S%z"), "action": action, "outcome": outcome, **fields}
+        with self.path.open("a") as f:
+            f.write(json.dumps(entry, default=str) + "\n")
+        return entry
+
+    def tail(self, n: int = 20) -> list[dict]:
+        if not self.path.exists():
+            return []
+        lines = self.path.read_text().splitlines()[-n:]
+        return [json.loads(line) for line in lines if line.strip()]

siligent/mcp_server.py

@@ -0,0 +1,89 @@
+"""MCP server: exposes the bench to AI agents (Claude Code, Cursor, others) over stdio.
+
+Refusals come back as normal results with "refused": true, the rule that fired
+and the reason, so the agent can explain or change course instead of retrying.
+"""
+
+from __future__ import annotations
+
+from mcp.server.mcpserver import MCPServer
+
+from . import api
+from .bench import BenchConfig
+
+INSTRUCTIONS = """\
+Siligent controls a real hardware bench. Every write and flash passes a safety gate.
+If a result has "refused": true, do not retry the same action: read "rule" and "reason",
+then explain it to the user or choose a different approach. Reads are always allowed.
+Start with detect_hardware, then board_rules to see what is allowed on this board.
+Use check_image before flash or run_tests to catch problems without touching hardware.
+"""
+
+server = MCPServer("siligent", instructions=INSTRUCTIONS)
+
+
+def _cfg(virtual: bool = False) -> BenchConfig:
+    cfg = BenchConfig.load()
+    if virtual:
+        cfg.virtual = True
+    return cfg
+
+
+@server.tool()
+def detect_hardware() -> dict:
+    """List connected debug probes and identify the board and the safety rules that apply."""
+    return api.detect(_cfg())
+
+
+@server.tool()
+def board_rules(board: str = "stm32l476rg") -> dict:
+    """Show what is allowed and forbidden on a board: memory regions, protected pins, flash preconditions."""
+    return api.rules(board)
+
+
+@server.tool()
+def check_image(path: str) -> dict:
+    """Check a firmware file (.elf) against the board's rules without touching hardware."""
+    return api.check_image(path, config=_cfg())
+
+
+@server.tool()
+def flash(path: str, virtual: bool = False) -> dict:
+    """Flash a firmware file (.elf) to the board. The flash pages are backed up first.
+    virtual=true uses a Renode virtual board instead of real hardware."""
+    return api.flash(path, config=_cfg(virtual))
+
+
+@server.tool()
+def run_tests(path: str, timeout_s: float = 10.0, virtual: bool = False) -> dict:
+    """Flash test firmware built with the Siligent harness, run it, and return
+    pass/fail and CPU cycles per test, plus energy if a power meter is configured.
+    virtual=true runs it on a Renode virtual board (no hardware needed; cycle counts
+    are simulated, and there is no energy)."""
+    return api.run_tests(path, timeout_s=timeout_s, config=_cfg(virtual))
+
+
+@server.tool()
+def read_memory(address: int, length: int, virtual: bool = False) -> dict:
+    """Read up to 4096 bytes of chip memory. Returns hex."""
+    return api.read_memory(address, length, config=_cfg(virtual))
+
+
+@server.tool()
+def write_memory(address: int, data_hex: str, virtual: bool = False) -> dict:
+    """Write bytes to RAM or a peripheral register. Flash, option bytes and protected pins are refused."""
+    return api.write_memory(address, data_hex, config=_cfg(virtual))
+
+
+@server.tool()
+def action_log(n: int = 20) -> dict:
+    """The most recent bench actions, including refused ones."""
+    return api.action_log(n, config=_cfg())
+
+
+def main() -> None:
+    server.run("stdio")
+
+
+if __name__ == "__main__":
+    main()

siligent/meters/__init__.py

@@ -0,0 +1,5 @@
+"""Power meters: anything that can sample current and voltage over a time window."""
+
+from .base import MeterReading, PowerMeter, integrate
+
+__all__ = ["MeterReading", "PowerMeter", "integrate"]

siligent/meters/base.py

@@ -0,0 +1,58 @@
+"""The power-meter interface and the energy maths shared by every meter."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class MeterReading:
+    meter: str
+    duration_s: float
+    samples: int
+    energy_uj: float
+    avg_current_a: float
+    min_current_a: float
+    max_current_a: float
+    avg_voltage_v: float
+    resolution_a: float  # smallest current step the meter can see
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        # Say plainly when the meter is too coarse for what it measured.
+        d["below_resolution"] = self.avg_current_a < 10 * self.resolution_a
+        return d
+
+
+class PowerMeter(Protocol):
+    name: str
+    resolution_a: float
+
+    def start(self) -> None:
+        """Begin sampling in the background."""
+
+    def stop(self) -> MeterReading:
+        """Stop sampling and return the totals for the window."""
+
+
+def integrate(meter: str, resolution_a: float, samples: list[tuple[float, float, float]]) -> MeterReading:
+    """Totals from (time_s, current_a, voltage_v) samples, by the trapezoid rule."""
+    if not samples:
+        return MeterReading(meter, 0.0, 0, 0.0, 0.0, 0.0, 0.0, 0.0, resolution_a)
+    energy_j = 0.0
+    for (t0, i0, v0), (t1, i1, v1) in zip(samples, samples[1:]):
+        energy_j += (i0 * v0 + i1 * v1) / 2 * (t1 - t0)
+    duration = samples[-1][0] - samples[0][0]
+    currents = [s[1] for s in samples]
+    return MeterReading(
+        meter=meter,
+        duration_s=duration,
+        samples=len(samples),
+        energy_uj=energy_j * 1e6,
+        avg_current_a=sum(currents) / len(currents),
+        min_current_a=min(currents),
+        max_current_a=max(currents),
+        avg_voltage_v=sum(s[2] for s in samples) / len(samples),
+        resolution_a=resolution_a,
+    )

siligent/meters/ina219.py

@@ -0,0 +1,88 @@
+"""TI INA219 current/voltage sensor over I2C.
+
+Good for active current. With a 0.1 ohm shunt it reads in 100 uA steps, so it
+cannot see microcontroller sleep currents (around 1 uA). Use a uA-capable
+meter for those.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Protocol
+
+from .base import MeterReading, integrate
+
+REG_CONFIG = 0x00
+REG_SHUNT = 0x01
+REG_BUS = 0x02
+SHUNT_LSB_V = 10e-6
+BUS_LSB_V = 4e-3
+# 32 V range, PGA /8 (+-320 mV), 12-bit, shunt and bus continuous: the reset default.
+CONFIG_DEFAULT = 0x399F
+
+
+class I2CBus(Protocol):
+    def read_word(self, address: int, register: int) -> int:
+        """Read a 16-bit register, most significant byte first (as the INA219 sends it)."""
+
+    def write_word(self, address: int, register: int, value: int) -> None:
+        """Write a 16-bit register, most significant byte first."""
+
+
+class LinuxI2CBus:
+    """A Linux /dev/i2c-N bus via smbus2 (pip install siligent[ina219])."""
+
+    def __init__(self, bus: int) -> None:
+        from smbus2 import SMBus  # imported here so the dependency stays optional
+
+        self._bus = SMBus(bus)
+
+    def read_word(self, address: int, register: int) -> int:
+        w = self._bus.read_word_data(address, register)
+        return ((w & 0xFF) << 8) | (w >> 8)  # SMBus words arrive low byte first
+
+    def write_word(self, address: int, register: int, value: int) -> None:
+        self._bus.write_word_data(address, register, ((value & 0xFF) << 8) | (value >> 8))
+
+
+class INA219:
+    name = "INA219"
+
+    def __init__(self, bus: I2CBus, address: int = 0x40, shunt_ohms: float = 0.1, sample_hz: float = 500) -> None:
+        self.bus = bus
+        self.address = address
+        self.shunt_ohms = shunt_ohms
+        self.period = 1.0 / sample_hz
+        self.resolution_a = SHUNT_LSB_V / shunt_ohms
+        self._samples: list[tuple[float, float, float]] = []
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self.bus.write_word(self.address, REG_CONFIG, CONFIG_DEFAULT)
+
+    def read_once(self) -> tuple[float, float]:
+        """One (current_a, bus_voltage_v) reading."""
+        raw = self.bus.read_word(self.address, REG_SHUNT)
+        if raw & 0x8000:
+            raw -= 0x10000
+        bus = self.bus.read_word(self.address, REG_BUS)
+        return raw * SHUNT_LSB_V / self.shunt_ohms, (bus >> 3) * BUS_LSB_V
+
+    def _run(self) -> None:
+        t0 = time.monotonic()
+        while not self._stop.is_set():
+            i, v = self.read_once()
+            self._samples.append((time.monotonic() - t0, i, v))
+            time.sleep(self.period)
+
+    def start(self) -> None:
+        self._samples = []
+        self._stop.clear()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> MeterReading:
+        self._stop.set()
+        if self._thread:
+            self._thread.join()
+        return integrate(self.name, self.resolution_a, self._samples)

siligent/probes/__init__.py

@@ -0,0 +1,6 @@
+"""Debug probes. Every probe is used through GuardedProbe, which applies the safety gate."""
+
+from .base import ProbeBackend
+from .guarded import GuardedProbe
+
+__all__ = ["ProbeBackend", "GuardedProbe"]

siligent/probes/base.py

@@ -0,0 +1,35 @@
+"""The interface a probe plugin implements. Plugins never apply safety rules themselves."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from ..image import Segment
+
+
+class ProbeBackend(Protocol):
+    unique_id: str
+    description: str
+
+    def open(self) -> None: ...
+
+    def close(self) -> None: ...
+
+    def read32(self, address: int) -> int: ...
+
+    def read_memory(self, address: int, length: int) -> bytes: ...
+
+    def write_memory(self, address: int, data: bytes) -> None: ...
+
+    def program(self, segments: list[Segment]) -> None:
+        """Halt the core with a reset, then erase the sectors these segments cover and program
+        them. Never a whole-chip erase."""
+
+    def reset(self, halt: bool = False) -> None: ...
+
+    def halt(self) -> None: ...
+
+    def resume(self) -> None: ...
+
+    def state(self) -> str:
+        """'running', 'halted', 'sleeping', 'lockup' or 'reset'."""

siligent/probes/guarded.py

@@ -0,0 +1,143 @@
+"""GuardedProbe: the only way Siligent touches a probe.
+
+Every write and flash passes the safety gate here, and every action (allowed
+or refused) is written to the action log. The CLI, the Python API and the
+MCP server all go through this class, so none of them can get around the rules.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from ..errors import SafetyRefusal
+from ..image import Image, Segment
+from ..log import ActionLog
+from ..rules import BoardRules
+from ..safety import SafetyGate
+from .base import ProbeBackend
+
+FLASH_PAGE = 2048
+
+
+class GuardedProbe:
+    def __init__(
+        self,
+        backend: ProbeBackend,
+        rules: BoardRules,
+        gate: SafetyGate,
+        log: ActionLog,
+        snapshot_dir: str | Path,
+    ) -> None:
+        self.backend = backend
+        self.rules = rules
+        self.gate = gate
+        self.log = log
+        self.snapshot_dir = Path(snapshot_dir).expanduser()
+
+    # Reads are allowed anywhere. Some peripheral registers clear flags when read,
+    # so reads are still logged.
+    def read_memory(self, address: int, length: int) -> bytes:
+        data, _ = self.read_memory_checked(address, length)
+        return data
+
+    def read_memory_checked(self, address: int, length: int) -> tuple[bytes, bool]:
+        """Read memory; returns (data, halted_to_read).
+
+        While the core sleeps, the ST-LINK returns zeros for RAM and flash with no
+        error. So a sleeping core is halted for the read, then resumed.
+        """
+        halted = self.backend.state() == "sleeping"
+        if halted:
+            self.backend.halt()
+        try:
+            data = self.backend.read_memory(address, length)
+        finally:
+            if halted:
+                self.backend.resume()
+        self.log.record("read_memory", "ok", address=hex(address), length=length, halted_to_read=halted)
+        return data, halted
+
+    def read32(self, address: int) -> int:
+        return self.backend.read32(address)
+
+    def device_id(self) -> int:
+        return self.backend.read32(self.rules.idcode_address) & 0xFFF
+
+    def write_memory(self, address: int, data: bytes) -> None:
+        try:
+            self.gate.check_host_write(address, data)
+        except SafetyRefusal as e:
+            self.log.record("write_memory", "refused", rule=e.rule, address=hex(address), length=len(data))
+            raise
+        self.backend.write_memory(address, data)
+        self.log.record("write_memory", "ok", address=hex(address), length=len(data))
+
+    def flash(self, image: Image) -> dict:
+        """Check, snapshot, then program an image. Returns what was done."""
+        halted = False
+        try:
+            self.gate.check_bench_for_flash()
+            self.gate.check_image(image)
+            # Halt first: while the core sleeps, register reads come back as zeros.
+            self.backend.halt()
+            halted = True
+            dev_id = self.device_id()
+            if dev_id != self.rules.dev_id:
+                raise SafetyRefusal(
+                    "chip.mismatch",
+                    f"The connected chip (device ID {hex(dev_id)}) is not a {self.rules.chip} "
+                    f"({hex(self.rules.dev_id)}); these rules do not apply to it.",
+                )
+            self.gate.check_read_protection(self.backend.read32(self.rules.optr_address))
+        except SafetyRefusal as e:
+            if halted:
+                self.backend.resume()  # a refusal leaves the board as it was
+            self.log.record("flash", "refused", rule=e.rule, image=image.path, sha256=image.sha256)
+            raise
+
+        # A virtual board starts fresh each time, so there is nothing to back up.
+        snapshot = self._snapshot(image.segments) if getattr(self.backend, "persistent", True) else None
+        self.backend.program(image.segments)
+        result = {
+            "ok": True,
+            "image": image.path,
+            "sha256": image.sha256,
+            "bytes": image.size,
+            "snapshot": str(snapshot) if snapshot else None,
+        }
+        self.log.record("flash", "ok", **result)
+        return result
+
+    def reset(self, halt: bool = False) -> None:
+        self.backend.reset(halt=halt)
+        self.log.record("reset", "ok", halt=halt)
+
+    def resume(self) -> None:
+        self.backend.resume()
+
+    def halt(self) -> None:
+        self.backend.halt()
+
+    def _snapshot(self, segments: list[Segment]) -> Path:
+        """Save the flash pages about to be overwritten, so they can be put back.
+
+        The first flash on a device also saves the whole flash as a baseline.
+        """
+        uid = self.backend.unique_id or "unknown"
+        folder = self.snapshot_dir / uid
+        folder.mkdir(parents=True, exist_ok=True)
+        baseline = folder / "baseline-full-flash.bin"
+        if not baseline.exists():
+            baseline.write_bytes(self.backend.read_memory(self.rules.flash.start, self.rules.flash.size))
+            self.log.record("snapshot", "ok", kind="baseline", path=str(baseline))
+
+        stamp = time.strftime("%Y%m%d-%H%M%S")
+        path = folder / f"pages-{stamp}.bin"
+        with path.open("wb") as f:
+            for seg in segments:
+                start = seg.address - (seg.address % FLASH_PAGE)
+                end = -(-seg.end // FLASH_PAGE) * FLASH_PAGE
+                f.write(start.to_bytes(4, "little") + (end - start).to_bytes(4, "little"))
+                f.write(self.backend.read_memory(start, end - start))
+        return path

siligent/probes/pyocd_backend.py

@@ -0,0 +1,91 @@
+"""ST-LINK (and other CMSIS-DAP style probes) through pyOCD."""
+
+from __future__ import annotations
+
+import logging
+
+from ..errors import HardwareError
+from ..image import Segment
+
+
+class PyOCDBackend:
+    def __init__(self, target: str, unique_id: str | None = None, frequency_hz: int = 4_000_000) -> None:
+        self.target_name = target
+        self.unique_id = unique_id or ""
+        self.description = ""
+        self.frequency_hz = frequency_hz
+        self._session = None
+        self._target = None
+
+    def open(self) -> None:
+        from pyocd.core.helpers import ConnectHelper
+
+        logging.getLogger("pyocd").setLevel(logging.WARNING)
+        session = ConnectHelper.session_with_chosen_probe(
+            blocking=False,
+            unique_id=self.unique_id or None,
+            options={
+                "target_override": self.target_name,
+                # Attach without halting, so reading never disturbs running firmware.
+                "connect_mode": "attach",
+                "frequency": self.frequency_hz,
+                "hide_programming_progress": True,
+            },
+        )
+        if session is None:
+            raise HardwareError("no debug probe found (is the board plugged in?)")
+        try:
+            session.open()
+        except Exception as e:
+            raise HardwareError(f"could not connect to the chip through the probe: {e}") from e
+        self._session = session
+        self._target = session.board.target
+        self.unique_id = session.probe.unique_id
+        self.description = session.probe.description
+
+    def close(self) -> None:
+        if self._session is not None:
+            self._session.close()
+            self._session = None
+            self._target = None
+
+    def _t(self):
+        if self._target is None:
+            raise HardwareError("probe is not open")
+        return self._target
+
+    def read32(self, address: int) -> int:
+        return self._t().read32(address)
+
+    def read_memory(self, address: int, length: int) -> bytes:
+        return bytes(self._t().read_memory_block8(address, length))
+
+    def write_memory(self, address: int, data: bytes) -> None:
+        self._t().write_memory_block8(address, list(data))
+
+    def program(self, segments: list[Segment]) -> None:
+        from pyocd.flash.loader import MemoryLoader
+
+        # Stop whatever firmware is running first. Erasing flash under running code
+        # locks the core up and makes the erase time out (seen on the real L476).
+        self._t().reset_and_halt()
+        # Sector erase only: a chip erase would wipe more than the image covers.
+        loader = MemoryLoader(self._session, chip_erase="sector", smart_flash=True, keep_unwritten=True)
+        for seg in segments:
+            loader.add_data(seg.address, seg.data)
+        loader.commit()
+
+    def reset(self, halt: bool = False) -> None:
+        if halt:
+            self._t().reset_and_halt()
+        else:
+            self._t().reset()
+
+    def halt(self) -> None:
+        self._t().halt()
+
+    def resume(self) -> None:
+        self._t().resume()
+
+    def state(self) -> str:
+        return self._t().get_state().name.lower()