siligent 0.1.0__py3-none-any.whl

siligent/probes/renode_backend.py

@@ -0,0 +1,190 @@
+"""A virtual board in Renode, driven through Renode's monitor port.
+
+It implements the same interface as a real probe, so the safety gate, the
+test runner, the CLI and the MCP tools work on it unchanged.
+"""
+
+from __future__ import annotations
+
+import glob
+import os
+import re
+import shutil
+import socket
+import subprocess
+import tempfile
+import time
+from importlib import resources
+from pathlib import Path
+
+from ..errors import HardwareError
+from ..image import Segment
+
+PROMPT = re.compile(r"\((?:monitor|machine-\d+)\) $")
+TELNET_IAC = re.compile(rb"\xff[\xfb-\xfe].|\xff[\xf0-\xfa]")
+
+
+def find_renode(explicit: str | None = None) -> str:
+    candidates = [explicit, os.environ.get("RENODE"), shutil.which("renode")]
+    candidates += sorted(glob.glob(os.path.expanduser("~/.local/opt/renode-*/renode")), reverse=True)
+    for c in candidates:
+        if c and Path(c).is_file():
+            return c
+    raise HardwareError(
+        "Renode not found. Install it (https://github.com/renode/renode/releases) "
+        "or set RENODE=/path/to/renode."
+    )
+
+
+def platform_file(board: str) -> Path:
+    res = resources.files("siligent.boards") / "renode" / f"{board}.repl"
+    if not res.is_file():
+        raise HardwareError(f"no Renode platform for '{board}' yet")
+    return Path(str(res))
+
+
+def _free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+class RenodeBackend:
+    persistent = False  # nothing to back up: the virtual board starts fresh each time
+
+    def __init__(self, board: str = "stm32l476rg", renode: str | None = None, mips: int = 4):
+        self.board = board
+        self.mips = mips
+        self.renode = find_renode(renode)
+        self.unique_id = f"renode-virtual-{board}"
+        self.description = f"Renode virtual {board}"
+        self._proc: subprocess.Popen | None = None
+        self._sock: socket.socket | None = None
+        self._running = False
+        self._tmp = tempfile.TemporaryDirectory(prefix="siligent-renode-")
+
+    # Monitor connection ---------------------------------------------------------
+
+    def open(self) -> None:
+        port = _free_port()
+        self._proc = subprocess.Popen(
+            [self.renode, "--disable-gui", "--plain", "--hide-log", "--port", str(port)],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        deadline = time.monotonic() + 60
+        while True:
+            try:
+                self._sock = socket.create_connection(("127.0.0.1", port), timeout=1)
+                break
+            except OSError:
+                if self._proc.poll() is not None or time.monotonic() > deadline:
+                    self.close()
+                    raise HardwareError("Renode did not start")
+                time.sleep(0.2)
+        self._read_until_prompt(timeout=60)
+        self.command("mach create")
+        self.command(f"machine LoadPlatformDescription @{platform_file(self.board)}", timeout=60)
+        # One instruction per clock at the chip's 4 MHz start-up clock, so the cycle
+        # counter lands near the real chip's (Renode's default is 100 MIPS).
+        self.command(f"cpu PerformanceInMips {self.mips}")
+
+    def close(self) -> None:
+        if self._sock is not None:
+            try:
+                self._sock.sendall(b"quit\n")
+            except OSError:
+                pass
+            self._sock.close()
+            self._sock = None
+        if self._proc is not None:
+            try:
+                self._proc.wait(timeout=20)
+            except subprocess.TimeoutExpired:
+                self._proc.kill()
+            self._proc = None
+        self._tmp.cleanup()
+
+    def _read_until_prompt(self, timeout: float = 30) -> str:
+        assert self._sock is not None
+        buf = b""
+        deadline = time.monotonic() + timeout
+        self._sock.settimeout(0.5)
+        while time.monotonic() < deadline:
+            try:
+                chunk = self._sock.recv(65536)
+            except socket.timeout:
+                continue
+            if not chunk:
+                raise HardwareError("Renode closed the monitor connection")
+            buf += chunk
+            text = TELNET_IAC.sub(b"", buf).decode(errors="replace")
+            if PROMPT.search(text):
+                return text
+        raise HardwareError("Renode did not answer in time")
+
+    def command(self, line: str, timeout: float = 30) -> str:
+        """Run one monitor command and return its output (without the echo and prompt)."""
+        if self._sock is None:
+            raise HardwareError("virtual board is not open")
+        self._sock.sendall(line.encode() + b"\n")
+        text = self._read_until_prompt(timeout)
+        body = PROMPT.sub("", text).replace("\r", "")
+        lines = [ln for ln in body.split("\n") if ln.strip() and ln.strip() != line]
+        out = "\n".join(lines).strip()
+        if out.startswith("There was an error") or "Could not find" in out:
+            raise HardwareError(f"Renode: {out}")
+        return out
+
+    # Probe interface --------------------------------------------------------------
+
+    def read32(self, address: int) -> int:
+        return int(self.command(f"sysbus ReadDoubleWord {address:#x}"), 16)
+
+    def read_memory(self, address: int, length: int) -> bytes:
+        out = self.command(f"sysbus ReadBytes {address:#x} {length}")
+        values = re.findall(r"0x([0-9A-Fa-f]{1,2})", out)
+        if len(values) != length:
+            raise HardwareError(f"Renode returned {len(values)} bytes, expected {length}")
+        return bytes(int(v, 16) for v in values)
+
+    def write_memory(self, address: int, data: bytes) -> None:
+        i = 0
+        while i < len(data):
+            a = address + i
+            if a % 4 == 0 and i + 4 <= len(data):
+                word = int.from_bytes(data[i : i + 4], "little")
+                self.command(f"sysbus WriteDoubleWord {a:#x} {word:#x}")
+                i += 4
+            else:
+                self.command(f"sysbus WriteByte {a:#x} {data[i]:#x}")
+                i += 1
+
+    def program(self, segments: list[Segment]) -> None:
+        self.halt()
+        for n, seg in enumerate(segments):
+            path = Path(self._tmp.name) / f"segment{n}.bin"
+            path.write_bytes(seg.data)
+            self.command(f"sysbus LoadBinary @{path} {seg.address:#x}")
+        self.reset(halt=True)
+
+    def reset(self, halt: bool = False) -> None:
+        # The platform mirrors flash at address 0, so the core boots from the
+        # vector table there, as the real chip does.
+        self.halt()
+        self.command("machine Reset")
+        if not halt:
+            self.resume()
+
+    def halt(self) -> None:
+        if self._running:
+            self.command("pause")
+            self._running = False
+
+    def resume(self) -> None:
+        if not self._running:
+            self.command("start")
+            self._running = True
+
+    def state(self) -> str:
+        return "running" if self._running else "halted"

siligent/rules.py

@@ -0,0 +1,150 @@
+"""Board safety rules, loaded from TOML files in siligent/boards/."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from importlib import resources
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Region:
+    name: str
+    start: int
+    size: int
+    reason: str = ""
+
+    @property
+    def end(self) -> int:
+        return self.start + self.size
+
+    def contains(self, addr: int, length: int = 1) -> bool:
+        return self.start <= addr and addr + length <= self.end
+
+    def overlaps(self, addr: int, length: int) -> bool:
+        return addr < self.end and self.start < addr + length
+
+
+@dataclass(frozen=True)
+class ForbiddenWord:
+    value: int
+    reason: str
+
+
+@dataclass(frozen=True)
+class ProtectedPin:
+    port: str
+    pin: int
+    required_mode: int
+    reason: str
+
+
+@dataclass(frozen=True)
+class BoardRules:
+    name: str
+    chip: str
+    dev_id: int
+    idcode_address: int
+    pyocd_target: str
+    flash: Region
+    ram: tuple[Region, ...]
+    allow_write: tuple[Region, ...]
+    forbid_write: tuple[Region, ...]
+    forbid_image_words: tuple[ForbiddenWord, ...]
+    optr_address: int
+    rdp_mask: int
+    rdp_level0: int
+    gpio_base: int
+    gpio_stride: int
+    gpio_ports: str
+    protected_pins: tuple[ProtectedPin, ...] = field(default_factory=tuple)
+    vdd_min_mv: int | None = None
+    vdd_max_mv: int | None = None
+    source: str = ""
+
+    def moder_address(self, port: str) -> int:
+        return self.gpio_base + self.gpio_ports.index(port.upper()) * self.gpio_stride
+
+    def summary(self) -> dict:
+        """A plain description an agent or a person can read."""
+        hexs = lambda r: {"name": r.name, "start": hex(r.start), "end": hex(r.end)}  # noqa: E731
+        return {
+            "board": self.name,
+            "chip": self.chip,
+            "dev_id": hex(self.dev_id),
+            "flash": hexs(self.flash),
+            "ram": [hexs(r) for r in self.ram],
+            "host_writes_allowed_in": [hexs(r) for r in self.allow_write],
+            "host_writes_forbidden_in": [hexs(r) | {"reason": r.reason} for r in self.forbid_write],
+            "firmware_refused_if_it_contains": [
+                {"word": hex(w.value), "reason": w.reason} for w in self.forbid_image_words
+            ],
+            "protected_pins": [
+                {"pin": f"P{p.port}{p.pin}", "reason": p.reason} for p in self.protected_pins
+            ],
+            "flash_requires": f"read protection level 0 (RDP byte {hex(self.rdp_level0)})",
+            "supply_voltage_mv": (
+                {"min": self.vdd_min_mv, "max": self.vdd_max_mv} if self.vdd_max_mv else "no meter may power this board"
+            ),
+        }
+
+
+def _region(d: dict, default_name: str = "") -> Region:
+    return Region(d.get("name", default_name), int(d["start"]), int(d["size"]), d.get("reason", ""))
+
+
+def parse_rules(data: dict, source: str = "") -> BoardRules:
+    board, mem, prot, gpio = data["board"], data["memory"], data["protection"], data.get("gpio", {})
+    power = data.get("power", {})
+    return BoardRules(
+        name=board["name"],
+        chip=board["chip"],
+        dev_id=int(board["dev_id"]),
+        idcode_address=int(board["idcode_address"]),
+        pyocd_target=board["pyocd_target"],
+        flash=_region(mem["flash"], "Flash"),
+        ram=tuple(_region(r) for r in mem["ram"]),
+        allow_write=tuple(_region(r) for r in data.get("allow_write", [])),
+        forbid_write=tuple(_region(r) for r in data.get("forbid_write", [])),
+        forbid_image_words=tuple(
+            ForbiddenWord(int(w["value"]), w["reason"]) for w in data.get("forbid_image_word", [])
+        ),
+        optr_address=int(prot["optr_address"]),
+        rdp_mask=int(prot["rdp_mask"]),
+        rdp_level0=int(prot["rdp_level0"]),
+        gpio_base=int(gpio.get("base", 0)),
+        gpio_stride=int(gpio.get("stride", 0)),
+        gpio_ports=gpio.get("ports", ""),
+        protected_pins=tuple(
+            ProtectedPin(p["port"].upper(), int(p["pin"]), int(p["required_mode"]), p["reason"])
+            for p in data.get("protected_pin", [])
+        ),
+        vdd_min_mv=power.get("vdd_min_mv"),
+        vdd_max_mv=power.get("vdd_max_mv"),
+        source=source,
+    )
+
+
+def builtin_boards() -> list[str]:
+    return sorted(p.name[:-5] for p in resources.files("siligent.boards").iterdir() if p.name.endswith(".toml"))
+
+
+def load_rules(name_or_path: str) -> BoardRules:
+    """Load rules by built-in name (e.g. 'stm32l476rg') or by file path."""
+    path = Path(name_or_path)
+    if path.suffix == ".toml" and path.exists():
+        return parse_rules(tomllib.loads(path.read_text()), str(path))
+    res = resources.files("siligent.boards") / f"{name_or_path.lower()}.toml"
+    if not res.is_file():
+        raise FileNotFoundError(f"no rules for board '{name_or_path}'; built-in: {', '.join(builtin_boards())}")
+    return parse_rules(tomllib.loads(res.read_text()), f"builtin:{name_or_path.lower()}")
+
+
+def rules_for_dev_id(dev_id: int) -> BoardRules | None:
+    """Find built-in rules whose chip matches a device ID read from the chip."""
+    for name in builtin_boards():
+        rules = load_rules(name)
+        if rules.dev_id == dev_id:
+            return rules
+    return None

siligent/runner.py

@@ -0,0 +1,134 @@
+"""Run on-device tests and collect pass/fail, cycles and energy.
+
+The firmware (see firmware/) writes its results to a RAM "mailbox" at the
+symbol `bp_results`. The host never talks to the chip while it measures
+energy: debug traffic adds current, so it waits a quiet period first and only
+then polls the mailbox for the result.
+"""
+
+from __future__ import annotations
+
+import struct
+import time
+from dataclasses import asdict, dataclass
+
+from .errors import SiligentError
+from .image import Image
+from .meters.base import PowerMeter
+from .probes.guarded import GuardedProbe
+
+MAGIC = 0x42504C54  # "BPLT"
+VERSION = 1
+HEADER = struct.Struct("<8I")  # magic, version, state, count, passed, failed, clock_hz, current
+ENTRY = struct.Struct("<20sIII")  # name, status, cycles, fail_line
+MAX_TESTS = 32
+MAILBOX_SIZE = HEADER.size + MAX_TESTS * ENTRY.size
+
+STATES = {0: "idle", 1: "running", 2: "done", 3: "crashed"}
+STATUS = {0: "not run", 1: "pass", 2: "fail", 3: "crashed"}
+
+
+@dataclass(frozen=True)
+class TestResult:
+    name: str
+    status: str
+    cycles: int
+    time_us: float | None
+    fail_line: int | None
+
+
+def parse_mailbox(data: bytes) -> dict:
+    magic, version, state, count, passed, failed, clock_hz, current = HEADER.unpack_from(data, 0)
+    if magic != MAGIC:
+        return {"state": "no results", "detail": "the firmware did not write a results mailbox"}
+    if version != VERSION:
+        return {"state": "unsupported", "detail": f"mailbox version {version}, expected {VERSION}"}
+    tests = []
+    for i in range(min(count, MAX_TESTS)):
+        name, status, cycles, line = ENTRY.unpack_from(data, HEADER.size + i * ENTRY.size)
+        tests.append(
+            TestResult(
+                name=name.split(b"\0", 1)[0].decode(errors="replace"),
+                status=STATUS.get(status, f"unknown ({status})"),
+                cycles=cycles,
+                time_us=round(cycles / clock_hz * 1e6, 3) if clock_hz else None,
+                fail_line=line if status == 2 else None,
+            )
+        )
+    result = {
+        "state": STATES.get(state, f"unknown ({state})"),
+        "passed": passed,
+        "failed": failed,
+        "clock_hz": clock_hz,
+        "tests": [asdict(t) for t in tests],
+    }
+    if state == 3:
+        result["crashed_in"] = tests[current].name if current < len(tests) else f"test #{current}"
+    return result
+
+
+def run_tests(
+    probe: GuardedProbe,
+    image: Image,
+    meter: PowerMeter | None = None,
+    timeout_s: float = 10.0,
+    quiet_s: float = 0.5,
+) -> dict:
+    if "bp_results" not in image.symbols:
+        raise SiligentError(
+            "this firmware has no 'bp_results' symbol; build it with the Siligent test harness (firmware/)"
+        )
+    mailbox = image.symbols["bp_results"][0]
+
+    flashed = probe.flash(image)
+    probe.reset(halt=True)
+    probe.write_memory(mailbox, bytes(HEADER.size))  # clear any old results
+    if meter:
+        meter.start()
+    started = time.monotonic()
+    probe.resume()
+
+    if meter:
+        time.sleep(quiet_s)
+    state = "timeout"
+    while time.monotonic() - started < timeout_s:
+        header = HEADER.unpack(probe.read_memory(mailbox, HEADER.size))
+        if header[0] == MAGIC and header[2] in (2, 3):
+            state = STATES[header[2]]
+            break
+        time.sleep(0.05)
+    elapsed = time.monotonic() - started
+    reading = meter.stop() if meter else None
+
+    # Read the final results with the core halted, so the read can be trusted
+    # whatever state the firmware left the chip in.
+    probe.halt()
+    result = parse_mailbox(probe.read_memory(mailbox, MAILBOX_SIZE))
+    probe.resume()
+    if state == "timeout" and result.get("state") in ("done", "crashed"):
+        state = result["state"]  # finished, but polling could not see it
+    if state == "timeout":
+        result["state"] = "timeout"
+        result["detail"] = f"tests did not finish within {timeout_s} s"
+    result["ok"] = result["state"] == "done" and result.get("failed", 1) == 0
+    result["wall_time_s"] = round(elapsed, 3)
+    result["image_sha256"] = flashed["sha256"]
+    virtual = not getattr(probe.backend, "persistent", True)
+    if reading:
+        result["energy"] = reading.to_dict()
+    elif virtual:
+        result["energy"] = {"measured": False, "detail": "virtual board: energy is not simulated yet"}
+    else:
+        result["energy"] = {"measured": False, "detail": "no power meter configured in bench.toml"}
+    if virtual:
+        result["virtual"] = True
+        result["note"] = "simulated in Renode: cycle counts come from simulated time, not the real chip"
+    probe.log.record(
+        "run_tests",
+        result["state"],
+        passed=result.get("passed"),
+        failed=result.get("failed"),
+        sha256=flashed["sha256"],
+        energy_uj=reading.energy_uj if reading else None,
+    )
+    return result

siligent/safety.py

@@ -0,0 +1,173 @@
+"""The safety gate: every write and every flash is checked here before it reaches a probe."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .errors import SafetyRefusal
+from .image import Image
+from .rules import BoardRules
+
+
+@dataclass
+class BenchState:
+    """Facts about the physical bench that software cannot see for itself.
+
+    `flash_allowed` must be set to True by a person in bench.toml, after
+    checking the bench is safe to flash (for example, that test equipment
+    which could be damaged is unplugged). Unset (None) or False refuses.
+    """
+
+    flash_allowed: bool | None = None
+
+
+class SafetyGate:
+    def __init__(self, rules: BoardRules, bench: BenchState | None = None) -> None:
+        self.rules = rules
+        self.bench = bench or BenchState()
+
+    # Bench preconditions -------------------------------------------------
+
+    def check_bench_for_flash(self) -> None:
+        if self.bench.flash_allowed is not True:
+            raise SafetyRefusal(
+                "bench.flash_not_allowed",
+                "A person has not confirmed this bench is safe to flash. Check the bench "
+                "(for example, unplug test equipment that must not be attached while flashing), "
+                "then set flash_allowed = true in bench.toml.",
+                flash_allowed=self.bench.flash_allowed,
+            )
+
+    # Host memory writes --------------------------------------------------
+
+    def check_host_write(self, address: int, data: bytes) -> None:
+        length = len(data)
+        if length == 0:
+            return
+        for region in self.rules.forbid_write:
+            if region.overlaps(address, length):
+                raise SafetyRefusal(
+                    "write.forbidden_region",
+                    f"Writes to {region.name} are not allowed. {region.reason}",
+                    address=hex(address),
+                    length=length,
+                    region=region.name,
+                )
+        if not any(r.contains(address, length) for r in self.rules.allow_write):
+            raise SafetyRefusal(
+                "write.outside_allowed",
+                "Host writes are only allowed in RAM, peripherals and core debug registers. "
+                "Use the flash tool to change flash.",
+                address=hex(address),
+                length=length,
+            )
+        self._check_protected_pins(address, data)
+
+    def _check_protected_pins(self, address: int, data: bytes) -> None:
+        for pin in self.rules.protected_pins:
+            moder = self.rules.moder_address(pin.port)
+            if not (address < moder + 4 and moder < address + len(data)):
+                continue
+            # Only a whole, aligned 32-bit write can be checked bit by bit.
+            if address > moder or address + len(data) < moder + 4:
+                raise SafetyRefusal(
+                    "pin.partial_moder_write",
+                    f"Partial write to GPIO{pin.port}_MODER cannot be checked; write the whole register.",
+                    address=hex(address),
+                )
+            off = moder - address
+            value = int.from_bytes(data[off : off + 4], "little")
+            mode = (value >> (2 * pin.pin)) & 0b11
+            if mode != pin.required_mode:
+                raise SafetyRefusal(
+                    "pin.protected",
+                    f"P{pin.port}{pin.pin} must stay in mode {pin.required_mode}: {pin.reason}",
+                    pin=f"P{pin.port}{pin.pin}",
+                    requested_mode=mode,
+                )
+
+    # Firmware images -----------------------------------------------------
+
+    def check_image(self, image: Image) -> None:
+        flash = self.rules.flash
+        for seg in image.segments:
+            if not flash.contains(seg.address, len(seg.data)):
+                raise SafetyRefusal(
+                    "image.outside_flash",
+                    f"Firmware has data at {hex(seg.address)}-{hex(seg.end)}, outside flash "
+                    f"({hex(flash.start)}-{hex(flash.end)}).",
+                    address=hex(seg.address),
+                    length=len(seg.data),
+                )
+        self._check_vector_table(image)
+        self._check_forbidden_words(image)
+
+    def _check_vector_table(self, image: Image) -> None:
+        start = self.rules.flash.start
+        sp, reset = image.word_at(start), image.word_at(start + 4)
+        if sp is None or reset is None:
+            raise SafetyRefusal(
+                "image.no_vector_table",
+                f"Firmware does not start with a vector table at {hex(start)}, so the chip would not boot it.",
+            )
+        if not any(r.start < sp <= r.end for r in self.rules.ram):
+            raise SafetyRefusal(
+                "image.bad_stack_pointer",
+                f"Initial stack pointer {hex(sp)} is not inside RAM.",
+                stack_pointer=hex(sp),
+            )
+        if not (reset & 1) or not self.rules.flash.contains(reset & ~1):
+            raise SafetyRefusal(
+                "image.bad_reset_vector",
+                f"Reset handler {hex(reset)} must be an odd (Thumb) address inside flash.",
+                reset_vector=hex(reset),
+            )
+
+    def _check_forbidden_words(self, image: Image) -> None:
+        for word in self.rules.forbid_image_words:
+            needle = word.value.to_bytes(4, "little")
+            for seg in image.segments:
+                pos = seg.data.find(needle)
+                if pos >= 0:
+                    raise SafetyRefusal(
+                        "image.forbidden_word",
+                        word.reason,
+                        word=hex(word.value),
+                        address=hex(seg.address + pos),
+                    )
+
+    # Power ------------------------------------------------------------------
+
+    def check_supply_voltage(self, voltage_mv: int) -> None:
+        """A meter that powers the board may only apply a voltage inside the board's range."""
+        lo, hi = self.rules.vdd_min_mv, self.rules.vdd_max_mv
+        if lo is None or hi is None:
+            raise SafetyRefusal(
+                "power.no_limits",
+                f"The rules for {self.rules.name} give no supply range, so no meter may power it.",
+            )
+        if not lo <= voltage_mv <= hi:
+            raise SafetyRefusal(
+                "power.voltage_out_of_range",
+                f"{voltage_mv} mV is outside the {self.rules.chip} supply range ({lo}-{hi} mV).",
+                voltage_mv=voltage_mv,
+            )
+
+    # Chip state ------------------------------------------------------------
+
+    def check_read_protection(self, optr: int) -> None:
+        if optr == 0:
+            # Reserved bits read as 1 on a real chip, so all zeros means the read failed.
+            raise SafetyRefusal(
+                "chip.unreadable",
+                "The option register read as all zeros, which a real chip never reports. The core may "
+                "be asleep or the probe link is bad; protection state is unknown, so flashing is refused.",
+            )
+        rdp = optr & self.rules.rdp_mask
+        if rdp != self.rules.rdp_level0:
+            raise SafetyRefusal(
+                "chip.read_protection",
+                f"Read protection is not at level 0 (RDP byte {hex(rdp)}, expected {hex(self.rules.rdp_level0)}). "
+                "Flashing could mass-erase or the chip may be locked; a person must handle this.",
+                optr=hex(optr),
+            )