embeddedci 2.2.0__tar.gz → 2.3.0__tar.gz

{embeddedci-2.2.0 → embeddedci-2.3.0}/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 2.3.0
+
+- SPI master on the LA pins: `BenchPod.open_spi()` returns an `SpiSession` for raw full-duplex
+  transfers (`transfer`, CS held across calls with `hold_cs`) and SPI NOR flash work
+  (`flash_id`, `flash_read`, `flash_erase`, `flash_write`, `flash_program`).
+  `BenchPod.spi_flash(image, addr)` erases, writes and verifies a whole image in one call, and can
+  hold the DUT in reset while it runs (`hold_reset=True`). Pins come from the wiring profile
+  (`spi_sclk`, `spi_mosi`, `spi_miso`, `spi_cs`) or as arguments; up to 6 MHz, modes 0 and 3.
+  Needs firmware 3.3+ with gateware v45 (capability `spi_master`, new `Capabilities.spi_master`).
+  Works over the LAN, USB and the cloud.
+- pytest plugin: with `BENCHPOD_LIFT_DAC_LIMITS=1` a session fixture clears the pod's DAC output
+  limits for the run and writes the same limits back at the end, even when tests fail.
+
 ## 2.2.0
 
 - Cloud: the session token the SDK mints is renewed shortly before it expires, and once more if the

{embeddedci-2.2.0 → embeddedci-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: embeddedci
-Version: 2.2.0
+Version: 2.3.0
 Summary: BenchPod SDK and pytest plugin for EmbeddedCI hardware-in-the-loop testing
 Project-URL: Homepage, https://embeddedci.com
 Project-URL: Repository, https://github.com/embeddedci-com/embeddedci-python
@@ -541,6 +541,33 @@ assert result.ok, result.stderr     # also: returncode, stdout, target_unreachab
   empties the target config's clock-boost reset events, which otherwise race the SWD link.
 * OpenOCD runs on the machine running the test, on every transport including the cloud.
 
+## SPI flash and SPI devices
+
+Pods with gateware v45+ (`bp.capabilities.spi_master`) run an SPI master on any four LA pins, up
+to 6 MHz, modes 0 and 3. Wire a 25-series SPI NOR flash (W25Q, MX25, GD25, ...) with its SCK, DI,
+DO and CS on LA channels (power it at the LA voltage, tie /WP and /HOLD high) and program it:
+
+```python
+res = bp.spi_flash("fw.bin", 0x0, sck=13, mosi=14, miso=6, cs=5, hold_reset=True)
+print(res.jedec_id, res.length, res.seconds)       # erased, written and verified
+```
+
+Or work with a session (pins from the wiring profile's `spi_sclk`, `spi_mosi`, `spi_miso`,
+`spi_cs` when omitted):
+
+```python
+with bp.open_spi(hz=6_000_000) as spi:
+    print(spi.flash_id())                          # SpiFlashInfo(jedec_id='ef4017', present=True, ...)
+    data = spi.flash_read(0x0, 4096)
+    spi.flash_erase(0x10000, 65536)
+    spi.flash_write(0x10000, payload)              # 768 B per command, each verified
+    rx = spi.transfer(b"\x9f\x00\x00\x00")        # raw full-duplex, for any SPI device
+```
+
+`hold_reset=True` holds the DUT in reset for the job (rev3 pods), so its own controller does not
+drive the same bus. The SPI master shares the SWD engine: an SWD flash cannot run while a session
+is open. Expect about 30 KB/s written (verified) over the LAN, less over the cloud.
+
 ## UART
 
 `rx` is the LA channel the pod **samples** (wire the DUT's TX here); `tx` is the channel the pod

{embeddedci-2.2.0 → embeddedci-2.3.0}/README.md

@@ -503,6 +503,33 @@ assert result.ok, result.stderr     # also: returncode, stdout, target_unreachab
   empties the target config's clock-boost reset events, which otherwise race the SWD link.
 * OpenOCD runs on the machine running the test, on every transport including the cloud.
 
+## SPI flash and SPI devices
+
+Pods with gateware v45+ (`bp.capabilities.spi_master`) run an SPI master on any four LA pins, up
+to 6 MHz, modes 0 and 3. Wire a 25-series SPI NOR flash (W25Q, MX25, GD25, ...) with its SCK, DI,
+DO and CS on LA channels (power it at the LA voltage, tie /WP and /HOLD high) and program it:
+
+```python
+res = bp.spi_flash("fw.bin", 0x0, sck=13, mosi=14, miso=6, cs=5, hold_reset=True)
+print(res.jedec_id, res.length, res.seconds)       # erased, written and verified
+```
+
+Or work with a session (pins from the wiring profile's `spi_sclk`, `spi_mosi`, `spi_miso`,
+`spi_cs` when omitted):
+
+```python
+with bp.open_spi(hz=6_000_000) as spi:
+    print(spi.flash_id())                          # SpiFlashInfo(jedec_id='ef4017', present=True, ...)
+    data = spi.flash_read(0x0, 4096)
+    spi.flash_erase(0x10000, 65536)
+    spi.flash_write(0x10000, payload)              # 768 B per command, each verified
+    rx = spi.transfer(b"\x9f\x00\x00\x00")        # raw full-duplex, for any SPI device
+```
+
+`hold_reset=True` holds the DUT in reset for the job (rev3 pods), so its own controller does not
+drive the same bus. The SPI master shares the SWD engine: an SWD flash cannot run while a session
+is open. Expect about 30 KB/s written (verified) over the LAN, less over the cloud.
+
 ## UART
 
 `rx` is the LA channel the pod **samples** (wire the DUT's TX here); `tx` is the channel the pod

{embeddedci-2.2.0 → embeddedci-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "embeddedci"
-version = "2.2.0"
+version = "2.3.0"
 description = "BenchPod SDK and pytest plugin for EmbeddedCI hardware-in-the-loop testing"
 readme = "README.md"
 requires-python = ">=3.10"

{embeddedci-2.2.0 → embeddedci-2.3.0}/src/embeddedci/benchpod/__init__.py

@@ -118,6 +118,7 @@ from .state import (
     UsbCcStatus,
 )
 from .uart import UartCapture, UartSession
+from .spi import SpiFlashInfo, SpiFlashResult, SpiSession
 from .waveforms import Waveform, WaveformLibrary
 from .wiring import Signal, Wiring
 
@@ -150,6 +151,9 @@ __all__ = [
     "FlashResult",
     "UartCapture",
     "UartSession",
+    "SpiSession",
+    "SpiFlashInfo",
+    "SpiFlashResult",
     # CAN
     "can",
     "CanBus",

{embeddedci-2.2.0 → embeddedci-2.3.0}/src/embeddedci/benchpod/capabilities.py

@@ -158,6 +158,9 @@ class Capabilities:
     nrst_pin: bool = False
     #: USB-C CC-line monitoring (rev3 pods): :meth:`BenchPod.usb_cc`.
     usb_cc: bool = False
+    #: SPI master on four LA pins and SPI NOR flash programming (gateware >= v45):
+    #: :meth:`BenchPod.open_spi`, :meth:`BenchPod.spi_flash`.
+    spi_master: bool = False
 
     #: LA I/O-bank voltage the pod currently reports (mV), if known.
     la_vccio_mv: int = 0
@@ -233,6 +236,7 @@ class Capabilities:
                 ("capture_b64", "capture_b64"),
                 ("nrst_pin", "nrst_pin"),
                 ("usb_cc", "usb_cc"),
+                ("spi_master", "spi_master"),
             ):
                 if name in names and hasattr(c, attr):
                     setattr(c, attr, True)
@@ -282,6 +286,7 @@ class Capabilities:
             ("capture_trigger", "cap.capture_trigger"), ("power_profile", "cap.power_profile"),
             ("capture_b64", "cap.capture_b64"),
             ("nrst_pin", "cap.nrst_pin"), ("usb_cc", "cap.usb_cc"),
+            ("spi_master", "cap.spi_master"),
         ):
             b = _as_bool(params, key)
             if b is not None:

{embeddedci-2.2.0 → embeddedci-2.3.0}/src/embeddedci/benchpod/client.py

@@ -39,6 +39,7 @@ from . import dsp as _dsp
 from . import flash as _flash
 from . import i2c as _i2c
 from . import sensor as _sensor
+from . import spi as _spi
 from . import uart as _uart
 from .capabilities import Capabilities
 from .constants import (
@@ -849,6 +850,72 @@ class BenchPod:
         link = self._uart_link(rx, tx, baud)
         return _uart.UartSession(link, max_buffer=max_buffer)
 
+    # -- SPI master / SPI flash ------------------------------------------------
+
+    def open_spi(
+        self,
+        *,
+        sck: Union[Pin, int, str, None] = None,
+        mosi: Union[Pin, int, str, None] = None,
+        miso: Union[Pin, int, str, None] = None,
+        cs: Union[Pin, int, str, None] = None,
+        hz: int = 1_000_000,
+        mode: int = 0,
+    ) -> _spi.SpiSession:
+        """Arm the SPI master on four LA pins and return a :class:`~embeddedci.benchpod.spi.SpiSession`
+        (a context manager; closing it releases the pins)::
+
+            with bp.open_spi(sck=13, mosi=14, miso=6, cs=5, hz=6_000_000) as spi:
+                print(spi.flash_id())
+                spi.flash_program(open("fw.bin", "rb").read())
+
+        Omitted pins come from the wiring profile (``spi_sclk``, ``spi_mosi``, ``spi_miso``,
+        ``spi_cs``). ``hz`` is rounded down to 24 MHz / (2 * n), n = 2..63 (6 MHz .. 190 kHz); the
+        session's ``hz`` is the rate used. ``mode`` is 0 or 3. Needs gateware v45+
+        (capability ``spi_master``); an SWD flash cannot run while a session is open.
+        """
+        self._require_capability("spi_master", "the SPI master")
+        if mode not in (0, 3):
+            raise ValueError("mode must be 0 or 3")
+        req = {"cmd": "spi_start", "sck": self._wired(sck, "spi_sclk"), "mosi": self._wired(mosi, "spi_mosi"),
+               "miso": self._wired(miso, "spi_miso"), "cs": self._wired(cs, "spi_cs"),
+               "hz": int(hz), "mode": int(mode)}
+        return _spi.SpiSession(self.command, _dict(self.command(req)))
+
+    def spi_flash(
+        self,
+        image: Union[bytes, str, "os.PathLike[str]"],
+        addr: int = 0,
+        *,
+        erase: bool = True,
+        verify: bool = True,
+        hold_reset: bool = False,
+        sck: Union[Pin, int, str, None] = None,
+        mosi: Union[Pin, int, str, None] = None,
+        miso: Union[Pin, int, str, None] = None,
+        cs: Union[Pin, int, str, None] = None,
+        hz: int = 6_000_000,
+        mode: int = 0,
+        progress: Optional[_spi.Progress] = None,
+    ) -> _spi.SpiFlashResult:
+        """Program an image (bytes or a file path) into the SPI NOR flash on the SPI pins.
+
+        Erases the sectors the image covers (unless ``erase=False``), writes it 768 bytes per
+        command and verifies every chunk (unless ``verify=False``). ``hold_reset`` holds the DUT
+        in reset for the whole job (rev3 pods), so its own controller does not drive the same
+        bus; it is released again afterwards, also on failure. Pins come from the wiring
+        profile unless given. ``progress(done, total)`` is called as it goes.
+        """
+        data = bytes(image) if isinstance(image, (bytes, bytearray, memoryview)) else open(image, "rb").read()
+        if hold_reset:
+            self.set_reset(True)
+        try:
+            with self.open_spi(sck=sck, mosi=mosi, miso=miso, cs=cs, hz=hz, mode=mode) as spi:
+                return spi.flash_program(data, addr, erase=erase, verify=verify, progress=progress)
+        finally:
+            if hold_reset:
+                self.set_reset(False)
+
     # -- ADC / logic-analyzer capture -----------------------------------------
 
     def capture_adc(self, samples: int = 4096, *, sample_rate_hz: Optional[float] = None,

{embeddedci-2.2.0 → embeddedci-2.3.0}/src/embeddedci/benchpod/pytest_plugin.py

@@ -280,6 +280,41 @@ def benchpod_connection(pytestconfig: "pytest.Config") -> str:
     return conn
 
 
+LIFT_DAC_LIMITS_ENV = "BENCHPOD_LIFT_DAC_LIMITS"
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _benchpod_lift_dac_limits(pytestconfig: "pytest.Config") -> Iterator[None]:
+    """With ``BENCHPOD_LIFT_DAC_LIMITS=1``: clear the pod's DAC output limits for the session and
+    put the SAME limits back at the end, even when tests fail.
+
+    The limits protect an external output stage (a solar simulator module on the 5 V path, say).
+    With the stage switched off a hardware test run may drive the DAC freely; without the variable
+    nothing changes and the pod refuses what the limits forbid. Opens its own short connection, so
+    it applies whichever fixture a suite then uses to talk to the pod."""
+    conn = _resolve_connection(pytestconfig)
+    if os.environ.get(LIFT_DAC_LIMITS_ENV) != "1" or not conn:
+        yield
+        return
+    saved = None
+    try:
+        with BenchPod(conn) as pod:
+            limits = pod.command({"cmd": "dac_limits"})
+            if isinstance(limits, dict) and limits.get("enabled"):
+                pod.command({"cmd": "dac_limits", "enabled": False})
+                saved = limits
+    except Exception as exc:                      # older firmware has no dac_limits: nothing to do
+        print(f"[benchpod] {LIFT_DAC_LIMITS_ENV}: could not read/clear DAC limits: {exc}")
+    try:
+        yield
+    finally:
+        if saved is not None:
+            restore = {"cmd": "dac_limits", "path": saved["path"], "inverted": saved["inverted"],
+                       "min_mv": saved["min_mv"], "max_mv": saved["max_mv"]}
+            with BenchPod(conn) as pod:
+                pod.command(restore)
+
+
 @pytest.fixture(scope="session")
 def benchpod_la_voltage() -> Optional[float]:
     """The I/O voltage of the board under test, selected on the pod when the session connects.

embeddedci-2.3.0/src/embeddedci/benchpod/spi.py

@@ -0,0 +1,195 @@
+"""SPI master on the LA pins: raw transfers and SPI NOR flash programming.
+
+Firmware 3.x with gateware v45+ (capability ``spi_master``) runs an SPI master on any four LA
+channels (SCK, MOSI, MISO, CS), up to 6 MHz, modes 0 and 3. It shares the SWD engine, so an SPI
+session and an SWD flash exclude each other. The flash operations are the pod's own
+``spi_flash`` command: standard 25-series parts (W25Q, MX25, GD25, IS25, ...), 3-byte addresses
+(the first 16 MB). Every request and reply fits one cloud command frame, so all of this works over
+the LAN, the USB console and the cloud alike.
+
+Open a session with :meth:`BenchPod.open_spi`; program a whole image with :meth:`BenchPod.spi_flash`.
+"""
+
+from __future__ import annotations
+
+import base64
+import time
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Optional, Tuple
+
+#: Bytes per ``spi_xfer`` / ``spi_flash write`` command, and per ``spi_flash read``.
+XFER_MAX = 768
+READ_MAX = 1024
+#: Bytes per ``spi_flash erase`` command: at most 16 block erases, a few seconds.
+ERASE_STEP = 1 << 20
+
+Progress = Callable[[int, int], None]
+
+
+def _b64(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")
+
+
+def _unb64(text: str) -> bytes:
+    return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
+
+
+@dataclass(frozen=True)
+class SpiFlashInfo:
+    """What :meth:`SpiSession.flash_id` found on the bus."""
+
+    #: JEDEC ID as 6 hex digits, e.g. ``"ef4017"`` (Winbond W25Q64).
+    jedec_id: str
+    #: False when the ID read all 00 or all FF: nothing is answering on those pins.
+    present: bool
+    #: Capacity in bytes from the ID, or 0 when the ID does not encode it.
+    size: int
+    #: Status register 1.
+    status: int
+
+
+@dataclass(frozen=True)
+class SpiFlashResult:
+    """The outcome of :meth:`SpiSession.flash_program` / :meth:`BenchPod.spi_flash`."""
+
+    jedec_id: str
+    addr: int
+    length: int
+    #: Bytes erased (whole 4 KB sectors covering the image), 0 with ``erase=False``.
+    erased: int
+    verified: bool
+    seconds: float
+
+
+class SpiSession:
+    """An armed SPI master (from :meth:`BenchPod.open_spi`). Use it as a context manager, or call
+    :meth:`close` to release the four pins."""
+
+    def __init__(self, command: Callable[[Dict[str, Any]], Any], info: Dict[str, Any]) -> None:
+        self._command = command
+        self.sck = int(info.get("sck", 0))
+        self.mosi = int(info.get("mosi", 0))
+        self.miso = int(info.get("miso", 0))
+        self.cs = int(info.get("cs", 0))
+        #: The SCK rate the pod picked (at or below the one asked for).
+        self.hz = int(info.get("hz", 0))
+        self.mode = int(info.get("mode", 0))
+        self._closed = False
+
+    # -- lifetime ----------------------------------------------------------------------------
+    def close(self) -> None:
+        """Stop the SPI master and release its pins (they go back to high-Z). Idempotent."""
+        if not self._closed:
+            self._closed = True
+            self._command({"cmd": "spi_stop"})
+
+    def __enter__(self) -> "SpiSession":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # -- raw transfers -----------------------------------------------------------------------
+    def transfer(self, data: bytes, *, hold_cs: bool = False) -> bytes:
+        """Full duplex: clock ``data`` out on MOSI and return the bytes clocked in on MISO.
+
+        CS is asserted before the first byte and released after the last, unless ``hold_cs``
+        keeps it asserted for the next :meth:`transfer` (one transaction over several calls).
+        Longer data is split into 768-byte commands with CS held between them."""
+        data = bytes(data)
+        if not data:
+            raise ValueError("transfer needs at least one byte")
+        out = bytearray()
+        for off in range(0, len(data), XFER_MAX):
+            last = off + XFER_MAX >= len(data)
+            reply = self._command({"cmd": "spi_xfer", "tx": _b64(data[off:off + XFER_MAX]),
+                                   "cs": "release" if last and not hold_cs else "hold"})
+            out += _unb64(str(reply["rx"]))
+        return bytes(out)
+
+    # -- SPI NOR flash -----------------------------------------------------------------------
+    def flash_id(self) -> SpiFlashInfo:
+        """Read the JEDEC ID and status register."""
+        r = self._command({"cmd": "spi_flash", "op": "id"})
+        return SpiFlashInfo(jedec_id=str(r["id"]), present=bool(r["present"]),
+                            size=int(r.get("size", 0)), status=int(r.get("status", 0)))
+
+    def flash_read(self, addr: int, length: int, *, progress: Optional[Progress] = None) -> bytes:
+        """Read ``length`` bytes from ``addr`` (1 KB per command)."""
+        if length <= 0:
+            raise ValueError("length must be positive")
+        out = bytearray()
+        while len(out) < length:
+            n = min(READ_MAX, length - len(out))
+            r = self._command({"cmd": "spi_flash", "op": "read", "addr": addr + len(out), "len": n})
+            out += _unb64(str(r["data"]))
+            if progress:
+                progress(len(out), length)
+        return bytes(out)
+
+    def flash_erase(self, addr: int, length: int, *, progress: Optional[Progress] = None) -> Tuple[int, int]:
+        """Erase every 4 KB sector ``[addr, addr+length)`` touches (64 KB blocks where whole).
+        Returns the range actually erased as ``(start, length)``; it is sector-aligned."""
+        if length <= 0:
+            raise ValueError("length must be positive")
+        start = end = None
+        pos, stop = addr, addr + length
+        while pos < stop:
+            n = min(ERASE_STEP, stop - pos)
+            r = self._command({"cmd": "spi_flash", "op": "erase", "addr": pos, "len": n})
+            s, l = int(r["addr"]), int(r["len"])
+            start = s if start is None else start
+            end = s + l
+            pos = max(pos + n, end)
+            if progress:
+                progress(min(pos, stop) - addr, length)
+        assert start is not None and end is not None
+        return start, end - start
+
+    def flash_chip_erase(self) -> float:
+        """Erase the whole chip; returns the seconds the pod reported. A large part can take
+        minutes, longer than a cloud command may wait: prefer :meth:`flash_erase` there."""
+        r = self._command({"cmd": "spi_flash", "op": "chip_erase"})
+        return int(r.get("ms", 0)) / 1000.0
+
+    def flash_write(self, addr: int, data: bytes, *, verify: bool = True,
+                    progress: Optional[Progress] = None) -> None:
+        """Program ``data`` at ``addr`` (768 bytes per command; the range must be erased).
+        With ``verify`` the pod reads every chunk back and fails on the first difference."""
+        data = bytes(data)
+        for off in range(0, len(data), XFER_MAX):
+            req: Dict[str, Any] = {"cmd": "spi_flash", "op": "write", "addr": addr + off,
+                                   "data": _b64(data[off:off + XFER_MAX])}
+            if not verify:
+                req["verify"] = False
+            self._command(req)
+            if progress:
+                progress(min(off + XFER_MAX, len(data)), len(data))
+
+    def flash_program(self, data: bytes, addr: int = 0, *, erase: bool = True, verify: bool = True,
+                      progress: Optional[Progress] = None) -> SpiFlashResult:
+        """Erase (unless ``erase=False``) and write a whole image, verifying every chunk.
+
+        ``progress(done, total)`` counts erase bytes first, then written bytes.
+        Raises :class:`~embeddedci.benchpod.errors.FirmwareError` when no flash answers."""
+        data = bytes(data)
+        if not data:
+            raise ValueError("the image is empty")
+        t0 = time.monotonic()
+        info = self.flash_id()
+        if not info.present:
+            from .errors import FirmwareError
+            raise FirmwareError(f"no SPI flash answers on SCK LA{self.sck} / MISO LA{self.miso} "
+                                f"(JEDEC ID {info.jedec_id})", cmd="spi_flash")
+        if info.size and addr + len(data) > info.size:
+            raise ValueError(f"{len(data)} bytes at 0x{addr:x} do not fit the {info.size}-byte flash")
+        total = (len(data) if erase else 0) + len(data)
+        erased = 0
+        if erase:
+            _, erased = self.flash_erase(addr, len(data),
+                                         progress=(lambda d, t: progress(d, total)) if progress else None)
+        base = len(data) if erase else 0
+        self.flash_write(addr, data, verify=verify,
+                         progress=(lambda d, t: progress(base + d, total)) if progress else None)
+        return SpiFlashResult(jedec_id=info.jedec_id, addr=addr, length=len(data), erased=erased,
+                              verified=verify, seconds=time.monotonic() - t0)

{embeddedci-2.2.0 → embeddedci-2.3.0}/tests/api_surface.json

@@ -69,6 +69,7 @@
     "loop_probe": "(self) -> '_control_loop.IVPoint'",
     "measure_power": "(self, duration: 'float', *, efuse: 'Optional[Union[Efuse, int]]' = None, rate_hz: 'float' = 500.0, keep_samples: 'int' = 0) -> 'PowerProfile'",
     "open_can": "(self, *, bitrate: 'int' = 500000, mode: 'CanMode' = 'normal', term: 'bool' = False, fd: 'bool' = False) -> '_can.CanBus'",
+    "open_spi": "(self, *, sck: 'Union[Pin, int, str, None]' = None, mosi: 'Union[Pin, int, str, None]' = None, miso: 'Union[Pin, int, str, None]' = None, cs: 'Union[Pin, int, str, None]' = None, hz: 'int' = 1000000, mode: 'int' = 0) -> '_spi.SpiSession'",
     "open_uart": "(self, *, rx: 'Union[Pin, int, str, None]' = None, tx: 'Union[Pin, int, str, None]' = None, baud: 'Optional[int]' = None, max_buffer: 'int' = 1048576) -> '_uart.UartSession'",
     "pin_levels": "(self) -> 'Dict[int, int]'",
     "ping": "(self) -> 'Any'",
@@ -94,6 +95,7 @@
     "set_pull": "(self, la: 'Union[Pin, int]', enabled: 'bool') -> 'PullState'",
     "set_reset": "(self, asserted: 'bool') -> 'ResetState'",
     "signal": "(self, name: 'str') -> 'GpioPin'",
+    "spi_flash": "(self, image: \"Union[bytes, str, 'os.PathLike[str]']\", addr: 'int' = 0, *, erase: 'bool' = True, verify: 'bool' = True, hold_reset: 'bool' = False, sck: 'Union[Pin, int, str, None]' = None, mosi: 'Union[Pin, int, str, None]' = None, miso: 'Union[Pin, int, str, None]' = None, cs: 'Union[Pin, int, str, None]' = None, hz: 'int' = 6000000, mode: 'int' = 0, progress: 'Optional[_spi.Progress]' = None) -> '_spi.SpiFlashResult'",
     "status": "(self) -> 'Dict[str, Any]'",
     "target_power": "(self, efuse: 'Optional[Union[Efuse, int]]' = None, *, on: 'bool', delay: 'Optional[float]' = None) -> 'None'",
     "target_status": "(self) -> 'TargetStatus'",
@@ -188,6 +190,7 @@
       "capture_b64",
       "nrst_pin",
       "usb_cc",
+      "spi_master",
       "la_vccio_mv",
       "safe_mode",
       "safe_reason",
@@ -603,6 +606,24 @@
     ],
     "to_dict": "(self) -> 'Dict[str, Any]'"
   },
+  "SpiFlashInfo": {
+    "__fields__": [
+      "jedec_id",
+      "present",
+      "size",
+      "status"
+    ]
+  },
+  "SpiFlashResult": {
+    "__fields__": [
+      "jedec_id",
+      "addr",
+      "length",
+      "erased",
+      "verified",
+      "seconds"
+    ]
+  },
   "SpiFrame": {
     "__fields__": [
       "index",
@@ -614,6 +635,17 @@
       "miso_hex"
     ]
   },
+  "SpiSession": {
+    "__init__": "(self, command: 'Callable[[Dict[str, Any]], Any]', info: 'Dict[str, Any]') -> 'None'",
+    "close": "(self) -> 'None'",
+    "flash_chip_erase": "(self) -> 'float'",
+    "flash_erase": "(self, addr: 'int', length: 'int', *, progress: 'Optional[Progress]' = None) -> 'Tuple[int, int]'",
+    "flash_id": "(self) -> 'SpiFlashInfo'",
+    "flash_program": "(self, data: 'bytes', addr: 'int' = 0, *, erase: 'bool' = True, verify: 'bool' = True, progress: 'Optional[Progress]' = None) -> 'SpiFlashResult'",
+    "flash_read": "(self, addr: 'int', length: 'int', *, progress: 'Optional[Progress]' = None) -> 'bytes'",
+    "flash_write": "(self, addr: 'int', data: 'bytes', *, verify: 'bool' = True, progress: 'Optional[Progress]' = None) -> 'None'",
+    "transfer": "(self, data: 'bytes', *, hold_cs: 'bool' = False) -> 'bytes'"
+  },
   "TargetStatus": {
     "__fields__": [
       "internal",
@@ -838,7 +870,10 @@
     "ServerApi",
     "ServerApiError",
     "Signal",
+    "SpiFlashInfo",
+    "SpiFlashResult",
     "SpiFrame",
+    "SpiSession",
     "TargetStatus",
     "TargetUnreachableError",
     "TransportError",

{embeddedci-2.2.0 → embeddedci-2.3.0}/tests/e2e/conftest.py

@@ -51,6 +51,7 @@ class Bench:
     board_rev: str        # the PCB revision this bench's pod must report ("" = accept any)
     nrst_la: Optional[int]  # LA channel jumpered to the pod's reset pin (J1 pin 22), if any
     ext_loop: bool = False  # the DAC 0-5 V output is wired to the ADC's front SMA
+    spi: Optional[Tuple[int, int, int, int]] = None   # SPI flash on (sck, mosi, miso, cs), or none
 
 
 @pytest.fixture(scope="session")
@@ -74,6 +75,7 @@ def bench() -> Bench:
         board_rev=_env("BOARD_REV", ""),
         nrst_la=int(_env("NRST_LA", "0")) or None,
         ext_loop=_env("EXT_LOOP", "0") == "1",
+        spi=tuple(int(x) for x in _env("SPI", "").split(",")) if _env("SPI", "") else None,  # type: ignore[arg-type]
     )
 
 

{embeddedci-2.2.0 → embeddedci-2.3.0}/tests/e2e/test_e2e_la13_14.py

@@ -2,7 +2,7 @@
 
     pytest packages/embeddedci/tests/e2e/test_e2e_la13_14.py --benchpod-connection=<pod host>
 
-Nothing may be wired to LA13/LA14 (override with BENCHPOD_E2E_TOP_LA). Each path that used to stop
+LA13/LA14 must be free of drivers (device INPUTS are fine; override with BENCHPOD_E2E_TOP_LA). Each path that used to stop
 at 12 gets one check: the pin table, GPIO drive + read-back, a capture, a trigger, a UART session.
 Firmware older than 3.1 only has 12 channels, so these skip there; on 3.1+ a missing channel fails.
 """
@@ -104,8 +104,13 @@ def test_level_trigger_on_la13(pod, top):
 
 
 def test_step_train_on_la14_is_captured(pod, top):
-    """An exact count: the 40 ms train starts 0.5 s into a 2 s capture, so none of it is missed."""
+    """An exact count: the 40 ms train starts 0.5 s into a 2 s capture, so none of it is missed.
+
+    LA14 is held low as a GPIO output first (the train then pulses the GPIO pin), so an undriven
+    line cannot add an edge: with something wired to LA14 (a device input) it otherwise floats
+    and picked up a stray edge now and then."""
     _, la14 = top
+    pod.gpio(la14, "output", level=0)
     result = {}
 
     def run():

embeddedci-2.3.0/tests/e2e/test_e2e_spi.py

@@ -0,0 +1,64 @@
+"""Tier "spi": the SPI master and SPI NOR flash programming (gateware v45+, capability spi_master).
+
+    BENCHPOD_E2E_SPI=13,14,6,5 pytest packages/embeddedci/tests/e2e/test_e2e_spi.py --benchpod-connection=<pod host>
+
+Needs a 25-series SPI NOR flash (W25Q, MX25, GD25, XT25, ...) wired to the pod: BENCHPOD_E2E_SPI
+gives its SCK, MOSI (the chip's DI), MISO (DO) and CS as LA channels, powered at the LA voltage,
+/WP and /HOLD tied high. Skips without it. The tests erase and write the 64 KB block at 0x10000.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from embeddedci.benchpod import FirmwareError, PinConflictError
+
+pytestmark = pytest.mark.hardware
+
+BASE = 0x10000
+
+
+@pytest.fixture
+def spi_pins(pod, bench):
+    if bench.spi is None:
+        pytest.skip("set BENCHPOD_E2E_SPI=sck,mosi,miso,cs to run the SPI flash tier")
+    if not pod.capabilities.spi_master:
+        pytest.skip("the pod has no SPI master (gateware v45+, capability spi_master)")
+    sck, mosi, miso, cs = bench.spi
+    return dict(sck=sck, mosi=mosi, miso=miso, cs=cs)
+
+
+@pytest.mark.parametrize("hz,mode", [(1_000_000, 0), (6_000_000, 0), (6_000_000, 3)])
+def test_program_and_read_back(pod, spi_pins, hz, mode):
+    image = os.urandom(20_000)
+    res = pod.spi_flash(image, BASE, hz=hz, mode=mode, **spi_pins)
+    assert res.verified and res.length == len(image) and res.erased >= len(image)
+    with pod.open_spi(hz=hz, mode=mode, **spi_pins) as spi:
+        assert spi.hz <= hz
+        assert spi.flash_read(BASE, len(image)) == image
+
+
+def test_raw_transfer_reads_the_jedec_id(pod, spi_pins):
+    with pod.open_spi(**spi_pins) as spi:
+        info = spi.flash_id()
+        assert info.present, f"no flash answering: {info}"
+        rx = spi.transfer(b"\x9f\x00\x00\x00")
+        assert rx[1:].hex() == info.jedec_id
+
+
+def test_writing_over_data_fails_verify(pod, spi_pins):
+    with pod.open_spi(**spi_pins) as spi:
+        spi.flash_erase(BASE, 4096)
+        spi.flash_write(BASE, b"\x00\x00")
+        with pytest.raises(FirmwareError, match="verify failed"):
+            spi.flash_write(BASE, b"\xff\xff")
+
+
+def test_pins_are_owned_while_open_and_released_after(pod, spi_pins):
+    with pod.open_spi(**spi_pins):
+        with pytest.raises(PinConflictError):
+            pod.gpio(spi_pins["cs"], "output", level=1)
+    pod.gpio(spi_pins["cs"], "output", level=1)       # free again once the session closed
+    pod.release_gpio()

embeddedci-2.3.0/tests/test_spi.py

@@ -0,0 +1,205 @@
+"""SPI master + SPI flash, against a fake pod that speaks the firmware's spi_* contract."""
+
+from __future__ import annotations
+
+import base64
+from typing import Any, Dict, List
+
+import pytest
+
+from embeddedci.benchpod import BenchPod, BenchPodError, FirmwareError, SpiFlashInfo, Wiring
+from embeddedci.benchpod.spi import ERASE_STEP, READ_MAX, XFER_MAX
+
+
+def b64(d: bytes) -> str:
+    return base64.urlsafe_b64encode(d).decode().rstrip("=")
+
+
+def unb64(t: str) -> bytes:
+    return base64.urlsafe_b64decode(t + "=" * (-len(t) % 4))
+
+
+class SpiPod:
+    """The firmware's SPI commands over a 1 MB flash model (limits as in command_handler_spi.c)."""
+
+    def __init__(self, *, caps=None, present=True) -> None:
+        self.caps = ["la", "la_pins", "spi_master", "nrst_pin"] if caps is None else caps
+        self.mem = bytearray(b"\xff" * (1 << 20))
+        self.present = present
+        self.armed = None
+        self.cs_held = False
+        self.commands: List[dict] = []
+        self.reset_log: List[bool] = []
+        self.fail_write_at = None
+
+    def status(self) -> Dict[str, Any]:
+        return {"board": "stm32h563", "adc_bits": 16, "version": "3.3.0", "caps": self.caps,
+                "nrst_pin": True}
+
+    def ping(self) -> Any:
+        return "pong"
+
+    def close(self) -> None:
+        pass
+
+    def command(self, req: dict) -> Any:
+        self.commands.append(req)
+        cmd = req["cmd"]
+        if cmd == "nrst":
+            self.reset_log.append(bool(req["assert"]))
+            return {"supported": True, "asserted": bool(req["assert"])}
+        if cmd == "spi_start":
+            pins = [req[k] for k in ("sck", "mosi", "miso", "cs")]
+            assert len(set(pins)) == 4 and all(1 <= p <= 14 for p in pins)
+            assert self.armed is None, "spi busy"
+            self.armed = req
+            half = max(2, min(63, -(-24_000_000 // (2 * req["hz"]))))
+            return {**{k: req[k] for k in ("sck", "mosi", "miso", "cs", "mode")}, "hz": 24_000_000 // (2 * half)}
+        if cmd == "spi_stop":
+            self.armed = None
+            return "spi stopped"
+        if self.armed is None:
+            raise FirmwareError("no SPI session: send spi_start first", cmd=cmd)
+        if cmd == "spi_xfer":
+            tx = unb64(req["tx"])
+            assert 1 <= len(tx) <= 768
+            self.cs_held = req.get("cs", "release") == "hold"
+            return {"rx": b64(bytes((b ^ 0xFF) for b in tx)), "cs": "held" if self.cs_held else "released"}
+        assert cmd == "spi_flash"
+        op = req["op"]
+        if op == "id":
+            return {"id": "ef4014" if self.present else "ffffff", "present": self.present,
+                    "size": (1 << 20) if self.present else 0, "status": 0}
+        if not self.present:
+            raise FirmwareError("write enable did not stick: no flash answering, or it is write-protected", cmd=cmd)
+        if op == "read":
+            assert 1 <= req["len"] <= 1024
+            return {"addr": req["addr"], "len": req["len"],
+                    "data": b64(bytes(self.mem[req["addr"]:req["addr"] + req["len"]]))}
+        if op == "erase":
+            assert 1 <= req["len"] <= 1 << 20
+            a = req["addr"] & ~0xFFF
+            end = (req["addr"] + req["len"] + 0xFFF) & ~0xFFF
+            self.mem[a:end] = b"\xff" * (end - a)
+            return {"addr": a, "len": end - a, "ms": 10}
+        if op == "write":
+            data = unb64(req["data"])
+            assert 1 <= len(data) <= 768
+            if self.fail_write_at is not None and req["addr"] >= self.fail_write_at:
+                raise FirmwareError(f"verify failed at 0x{req['addr']:06x}: not erased, write-protected, or a bad wire", cmd=cmd)
+            for i, b in enumerate(data):
+                self.mem[req["addr"] + i] &= b
+            return {"addr": req["addr"], "len": len(data), "verified": req.get("verify", True), "ms": 1}
+        raise AssertionError(op)
+
+
+@pytest.fixture
+def pod():
+    fake = SpiPod()
+    bp = BenchPod(transport=fake, wiring=Wiring(uart_rx=3, uart_tx=4, spi_sclk=13, spi_mosi=14, spi_miso=6, spi_cs=5))
+    return bp, fake
+
+
+def test_open_spi_takes_pins_from_wiring_and_rounds_hz(pod):
+    bp, fake = pod
+    with bp.open_spi(hz=5_000_000) as spi:
+        assert (spi.sck, spi.mosi, spi.miso, spi.cs) == (13, 14, 6, 5)
+        assert spi.hz == 4_000_000                    # 24 MHz / (2 * 3): never faster than asked
+    assert fake.armed is None                         # closed: spi_stop sent
+    assert fake.commands[-1] == {"cmd": "spi_stop"}
+
+
+def test_open_spi_needs_the_capability_and_a_valid_mode():
+    bp = BenchPod(transport=SpiPod(caps=["la"]), wiring=Wiring(spi_sclk=7, spi_mosi=8, spi_miso=9, spi_cs=10))
+    with pytest.raises(BenchPodError):
+        bp.open_spi()
+    bp = BenchPod(transport=SpiPod(), wiring=Wiring(spi_sclk=7, spi_mosi=8, spi_miso=9, spi_cs=10))
+    with pytest.raises(ValueError):
+        bp.open_spi(mode=1)
+
+
+def test_open_spi_without_wiring_pins_says_which_is_missing():
+    bp = BenchPod(transport=SpiPod())
+    with pytest.raises(ValueError, match="spi_sclk"):
+        bp.open_spi()
+
+
+def test_transfer_splits_long_data_and_holds_cs_between_chunks(pod):
+    bp, fake = pod
+    data = bytes(range(256)) * 7                      # 1792 bytes: 768 + 768 + 256
+    with bp.open_spi() as spi:
+        rx = spi.transfer(data)
+        xf = [c for c in fake.commands if c["cmd"] == "spi_xfer"]
+        assert [len(unb64(c["tx"])) for c in xf] == [768, 768, 256]
+        assert [c["cs"] for c in xf] == ["hold", "hold", "release"]
+        assert rx == bytes(b ^ 0xFF for b in data)
+        spi.transfer(b"\x9f", hold_cs=True)
+        assert fake.cs_held
+
+
+def test_flash_id_read_erase_write_chunking(pod):
+    bp, fake = pod
+    with bp.open_spi() as spi:
+        assert spi.flash_id() == SpiFlashInfo(jedec_id="ef4014", present=True, size=1 << 20, status=0)
+        img = bytes((i * 7) & 0xFF for i in range(3000))
+        start, length = spi.flash_erase(0x1100, len(img))
+        assert (start, length) == (0x1000, 0x1000)                   # 0x1100..0x1cb8: one sector
+        spi.flash_write(0x1100, img)
+        writes = [c for c in fake.commands if c.get("op") == "write"]
+        assert [len(unb64(c["data"])) for c in writes] == [768, 768, 768, 696]
+        assert all("verify" not in c for c in writes)                  # verify is the default
+        assert spi.flash_read(0x1100, len(img)) == img
+        reads = [c for c in fake.commands if c.get("op") == "read"]
+        assert [c["len"] for c in reads] == [READ_MAX, READ_MAX, 3000 - 2 * READ_MAX]
+
+
+def test_erase_is_sent_in_one_megabyte_steps(pod):
+    bp, fake = pod
+    fake.mem = bytearray(b"\xff" * (4 << 20))
+    with bp.open_spi() as spi:
+        spi.flash_erase(0, 2 * ERASE_STEP + 10)
+    erases = [c for c in fake.commands if c.get("op") == "erase"]
+    assert [c["len"] for c in erases] == [ERASE_STEP, ERASE_STEP, 10]
+
+
+def test_spi_flash_programs_verifies_and_reports_progress(pod, tmp_path):
+    bp, fake = pod
+    img = bytes((i * 13 + 5) & 0xFF for i in range(10_000))
+    path = tmp_path / "fw.bin"
+    path.write_bytes(img)
+    seen = []
+    res = bp.spi_flash(str(path), 0x2000, progress=lambda d, t: seen.append((d, t)))
+    assert bytes(fake.mem[0x2000:0x2000 + len(img)]) == img
+    assert res.length == len(img) and res.verified and res.erased == 12288 and res.jedec_id == "ef4014"
+    assert seen[-1] == (2 * len(img), 2 * len(img)) and all(d <= t for d, t in seen)
+    assert fake.armed is None
+    assert fake.commands[0]["cmd"] == "spi_start" and fake.commands[0]["hz"] == 6_000_000
+
+
+def test_spi_flash_holds_reset_and_releases_it_on_failure(pod):
+    bp, fake = pod
+    fake.fail_write_at = 0x800
+    with pytest.raises(FirmwareError, match="verify failed"):
+        bp.spi_flash(bytes(4096), hold_reset=True)
+    assert fake.reset_log == [True, False]           # held for the job, released after the failure
+    assert fake.armed is None                        # and the pins were released
+
+
+def test_spi_flash_refuses_an_empty_bus_before_erasing():
+    fake = SpiPod(present=False)
+    bp = BenchPod(transport=fake, wiring=Wiring(spi_sclk=7, spi_mosi=8, spi_miso=9, spi_cs=10))
+    with pytest.raises(FirmwareError, match="no SPI flash answers"):
+        bp.spi_flash(b"\x01\x02")
+    assert not [c for c in fake.commands if c.get("op") in ("erase", "write")]
+
+
+def test_spi_flash_refuses_an_image_larger_than_the_part(pod):
+    bp, fake = pod
+    with pytest.raises(ValueError, match="do not fit"):
+        bp.spi_flash(bytes(4096), (1 << 20) - 100)
+
+
+def test_capability_flag_parses_from_status_caps():
+    bp = BenchPod(transport=SpiPod())
+    assert bp.capabilities.spi_master
+    assert not BenchPod(transport=SpiPod(caps=["la"])).capabilities.spi_master