flashgate 0.7.2__tar.gz → 0.8.0__tar.gz

{flashgate-0.7.2 → flashgate-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashgate
-Version: 0.7.2
+Version: 0.8.0
 Summary: Hardware-in-the-loop verification gate: your agent can't claim the firmware works until the board says so.
 License: MIT
 Project-URL: Homepage, https://github.com/Lion-1209/flashgate
@@ -244,10 +244,24 @@ Stop-hook escalation — plus the full session of a real Claude Code agent
 getting blocked, diagnosing the firmware↔profile contract, fixing both
 sides, and passing on hardware ([24 MB GIF, release asset](https://github.com/Lion-1209/flashgate/releases/download/v0.3.0/5-agent-blocked.gif)).
 
+## Debug backends (Phase 2)
+
+The verify pipeline is backend-agnostic: `flash.adapter:` in the board
+profile picks the probe tool — `cubeprogrammer` (default, the original
+implementation), `openocd` (same ST-Link, no ST toolchain needed, and
+the standard route to Linux/ARM64 bench hosts like a Raspberry Pi), or
+`fake` (scripted, for tests). Validated on the same Apollo board:
+swapping to `openocd` is a one-line profile change — verify stays green
+with identical records, zero upper-layer edits, and runs slightly
+faster. OpenOCD is discovered via PATH or `$OPENOCD_BIN`; the target
+script maps from the MCU family (`STM32H7*` -> `stm32h7x`, override
+with `flash.openocd_target`).
+
 ## Board profiles
 
-One yaml per board (`boards/`): build command, artifact, flash address,
-serial adapter hints, banner template, probes, watch globs. The console-side
+One yaml per board (`boards/`): build command, artifact, flash address
+(`flash.adapter:` picks the debug backend), serial adapter hints,
+banner template, probes, watch globs. The console-side
 USB adapter is a property of your bench, not the board — port resolution
 goes explicit `serial.port` / `FLASHGATE_SERIAL_PORT`, then VID/PID hint,
 then the sole serial port, with the banner match as the final identity
@@ -258,10 +272,10 @@ full profile field reference.
 ## Status
 
 Boot gate, probe gate, Stop hook, MCP server, SWD signature channel,
-verification records (per-check evidence with artifact hashes), and the
-remote bench over device-connect — all implemented and validated on real
-hardware, the remote bench cross-host (Wi-Fi laptop driving a wired
-bench, 2026-09-15). Windows-first; Linux/macOS untested.
+verification records (per-check evidence with artifact hashes), the
+remote bench over device-connect (validated cross-host), and a second
+debug backend (OpenOCD, validated on the same board) — all on real
+hardware. Windows-first; Linux/macOS untested.
 
 ## License
 

{flashgate-0.7.2 → flashgate-0.8.0}/README.md

@@ -223,10 +223,24 @@ Stop-hook escalation — plus the full session of a real Claude Code agent
 getting blocked, diagnosing the firmware↔profile contract, fixing both
 sides, and passing on hardware ([24 MB GIF, release asset](https://github.com/Lion-1209/flashgate/releases/download/v0.3.0/5-agent-blocked.gif)).
 
+## Debug backends (Phase 2)
+
+The verify pipeline is backend-agnostic: `flash.adapter:` in the board
+profile picks the probe tool — `cubeprogrammer` (default, the original
+implementation), `openocd` (same ST-Link, no ST toolchain needed, and
+the standard route to Linux/ARM64 bench hosts like a Raspberry Pi), or
+`fake` (scripted, for tests). Validated on the same Apollo board:
+swapping to `openocd` is a one-line profile change — verify stays green
+with identical records, zero upper-layer edits, and runs slightly
+faster. OpenOCD is discovered via PATH or `$OPENOCD_BIN`; the target
+script maps from the MCU family (`STM32H7*` -> `stm32h7x`, override
+with `flash.openocd_target`).
+
 ## Board profiles
 
-One yaml per board (`boards/`): build command, artifact, flash address,
-serial adapter hints, banner template, probes, watch globs. The console-side
+One yaml per board (`boards/`): build command, artifact, flash address
+(`flash.adapter:` picks the debug backend), serial adapter hints,
+banner template, probes, watch globs. The console-side
 USB adapter is a property of your bench, not the board — port resolution
 goes explicit `serial.port` / `FLASHGATE_SERIAL_PORT`, then VID/PID hint,
 then the sole serial port, with the banner match as the final identity
@@ -237,10 +251,10 @@ full profile field reference.
 ## Status
 
 Boot gate, probe gate, Stop hook, MCP server, SWD signature channel,
-verification records (per-check evidence with artifact hashes), and the
-remote bench over device-connect — all implemented and validated on real
-hardware, the remote bench cross-host (Wi-Fi laptop driving a wired
-bench, 2026-09-15). Windows-first; Linux/macOS untested.
+verification records (per-check evidence with artifact hashes), the
+remote bench over device-connect (validated cross-host), and a second
+debug backend (OpenOCD, validated on the same board) — all on real
+hardware. Windows-first; Linux/macOS untested.
 
 ## License
 

flashgate-0.8.0/flashgate/backends.py

@@ -0,0 +1,313 @@
+"""Debug backends: the adapter layer between the verify pipeline and the
+physical debug probe (design doc §5.6, Phase 2).
+
+A backend owns EVERYTHING probe-specific: discovery, flashing, memory
+access. The verify pipeline — and everything above it: records, bench,
+MCP — is backend-agnostic. Swapping CubeProgrammer for OpenOCD is a
+one-line board-profile change (`flash.adapter:`) and zero upper-layer
+edits; that substitution property is the Phase 2 acceptance criterion.
+
+Semantics every backend must honor (they are the gate's, not the
+adapter's):
+- flash(start=False) writes and verifies but does NOT run: the caller
+  wipes the boot signature in between, then start_app() — so a stale
+  RAM signature from a previous boot can never lie about identity.
+- write32/read_mem are the wipe/poll primitives behind that contract.
+- The `connect` string is opaque and backend-specific (CubeProgrammer
+  syntax like "port=SWD"; ignored by OpenOCD, which targets via its own
+  config derived from the board's MCU).
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from . import flasher, swdsig
+from .sttools import augmented_env, find_cubeprogrammer
+
+# OpenOCD target scripts by MCU family prefix. Explicit override lives in
+# the board profile (`flash.openocd_target`) for anything unmapped.
+_OPENOCD_TARGETS: tuple[tuple[str, str], ...] = (
+    ("STM32H7", "stm32h7x"),
+    ("STM32F7", "stm32f7x"),
+    ("STM32F4", "stm32f4x"),
+    ("STM32F1", "stm32f1x"),
+    ("STM32L4", "stm32l4x"),
+    ("STM32G0", "stm32g0x"),
+    ("STM32G4", "stm32g4x"),
+    ("STM32U5", "stm32u5x"),
+    ("STM32WB", "stm32wbx"),
+    ("STM32WL", "stm32wlx"),
+)
+_OPENOCD_TIMEOUT_S = 60
+
+
+def openocd_target_for(mcu: str) -> str | None:
+    mcu = (mcu or "").upper()
+    for prefix, target in _OPENOCD_TARGETS:
+        if mcu.startswith(prefix):
+            return target
+    return None
+
+
+def find_openocd() -> Path | None:
+    """openocd.exe via PATH, $OPENOCD_BIN, or the xpack layout."""
+    exe = "openocd.exe" if shutil.os.name == "nt" else "openocd"
+    found = shutil.which(exe, path=augmented_env().get("PATH", ""))
+    if found:
+        return Path(found)
+    import os
+    for env_name in ("OPENOCD_BIN", "OPENOCD_HOME"):
+        base = os.environ.get(env_name)
+        if base:
+            cand = Path(base)
+            if cand.is_file():
+                return cand
+            hit = cand / "bin" / exe
+            if hit.is_file():
+                return hit
+    return None
+
+
+class DebugBackend(ABC):
+    """The probe-facing surface the verify pipeline depends on."""
+
+    name: str = "abstract"
+
+    @abstractmethod
+    def available(self) -> str | None:
+        """Usable executable path (doctor shows it), or None."""
+
+    @abstractmethod
+    def discover(self) -> str:
+        """Human-readable listing of attached probes (doctor)."""
+
+    @abstractmethod
+    def flash(self, bin_path: Path, connect: str, address: str,
+              start: bool = True) -> flasher.FlashResult: ...
+
+    @abstractmethod
+    def write32(self, connect: str, value: int, address: int) -> bool: ...
+
+    @abstractmethod
+    def start_app(self, connect: str) -> bool: ...
+
+    @abstractmethod
+    def read_mem(self, connect: str, address: int, size: int) -> bytes | None: ...
+
+    def probe_detected(self, discover_output: str) -> bool:
+        """Did discover() actually see a probe? Backend-specific markers —
+        each backend knows its own tool's output format."""
+        return bool(discover_output.strip())
+
+
+class CubeProgrammerBackend(DebugBackend):
+    """STM32CubeProgrammer CLI over ST-Link — the original implementation,
+    unchanged semantics, now behind the interface."""
+
+    name = "cubeprogrammer"
+
+    def available(self) -> str | None:
+        cli = find_cubeprogrammer()
+        return str(cli) if cli else None
+
+    def discover(self) -> str:
+        return flasher.list_stlink()
+
+    def flash(self, bin_path, connect, address, start=True):
+        return flasher.flash(bin_path, connect, address, start=start)
+
+    def write32(self, connect, value, address) -> bool:
+        return flasher.write32(connect, value, address)
+
+    def start_app(self, connect) -> bool:
+        return flasher.start_app(connect)
+
+    def read_mem(self, connect, address, size):
+        return swdsig.read_ram(connect, address, size)
+
+    def probe_detected(self, discover_output: str) -> bool:
+        return "ST-LINK SN" in discover_output
+
+
+class OpenOcdBackend(DebugBackend):
+    """OpenOCD over ST-Link (or any adapter OpenOCD speaks). The second
+    flash implementation that validates the abstraction — and the
+    standard route to Linux/ARM64 bench hosts (e.g. Raspberry Pi), where
+    CubeProgrammer is the awkward dependency.
+
+    `connect` is ignored (it carries CubeProgrammer syntax); targeting
+    comes from the board's MCU mapped to an OpenOCD target script, or an
+    explicit `flash.openocd_target` in the profile. Interface defaults
+    to ST-Link; override with `flash.openocd_interface`.
+    """
+
+    name = "openocd"
+
+    def __init__(self, mcu: str = "",
+                 interface: str = "interface/stlink-dap.cfg",
+                 target: str | None = None):
+        self._interface = interface or "interface/stlink-dap.cfg"
+        self._target = target or openocd_target_for(mcu)
+
+    def available(self) -> str | None:
+        exe = find_openocd()
+        return str(exe) if exe else None
+
+    def _run(self, commands: list[str]) -> tuple[int, str]:
+        exe = find_openocd()
+        if self._target is None:
+            return -1, ("no OpenOCD target mapping for this MCU — set "
+                        "flash.openocd_target in the board profile")
+        if exe is None:
+            return -1, "openocd not found (install it or set OPENOCD_BIN)"
+        cmd = [str(exe)]
+        # xpack layout keeps scripts outside bin/ — pass the search dir
+        # explicitly so `-f target/...` resolves regardless of build.
+        scripts = exe.parent.parent / "openocd" / "scripts"
+        if scripts.is_dir():
+            cmd += ["-s", str(scripts)]
+        # target names map into the target/ script dir; profile overrides
+        # may carry a path or extension already
+        t = self._target
+        target_cfg = t if ("/" in t or t.endswith(".cfg")) else f"target/{t}.cfg"
+        i = self._interface
+        interface_cfg = i if ("/" in i or i.endswith(".cfg")) else f"interface/{i}.cfg"
+        cmd += ["-c", "adapter speed 4000",
+                "-f", interface_cfg, "-f", target_cfg,
+                # mdw/mww/reset need an initialized session; `program`
+                # inits internally and tolerates the explicit one.
+                "-c", "init"]
+        for c in commands:
+            cmd += ["-c", c]
+        cmd += ["-c", "shutdown"]
+        try:
+            proc = subprocess.run(
+                cmd, capture_output=True, text=True, timeout=_OPENOCD_TIMEOUT_S,
+                encoding="utf-8", errors="replace",
+                # Neutral cwd (F3): OpenOCD resolves relative -f paths
+                # against ITS cwd first — running from the gated repo
+                # would let a checked-in target/*.cfg shadow the stock
+                # scripts.
+                cwd=str(exe.parent),
+            )
+        except (subprocess.TimeoutExpired, OSError) as exc:
+            return -1, str(exc)
+        return proc.returncode, (proc.stdout or "") + (proc.stderr or "")
+
+    def discover(self) -> str:
+        rc, out = self._run(["adapter list"])
+        if rc == 0:
+            return out.strip()
+        return f"(openocd probe listing unavailable: {out[-300:]})"
+
+    def probe_detected(self, discover_output: str) -> bool:
+        # a connected ST-Link shows up as VID:PID 0483:... plus a DPIDR
+        # line once init reaches the target
+        return ("VID:PID 0483:" in discover_output
+                or "DPIDR" in discover_output)
+
+    def flash(self, bin_path: Path, connect: str, address: str,
+              start: bool = True) -> flasher.FlashResult:
+        if not Path(bin_path).is_file():
+            return flasher.FlashResult(False, f"artifact not found: {bin_path}")
+        # Tcl eats backslashes as escapes — hand OpenOCD forward slashes,
+        # braced so nothing else gets substituted. Braces have NO escape
+        # mechanism: a path containing '{' or '}' cannot be passed safely
+        # and is refused outright (F2).
+        tcl_bin = str(Path(bin_path)).replace("\\", "/")
+        if "{" in tcl_bin or "}" in tcl_bin:
+            return flasher.FlashResult(
+                False, f"artifact path contains '{{' or '}}' — cannot be "
+                f"passed to OpenOCD safely: {tcl_bin}")
+        steps = [f"program {{{tcl_bin}}} {address} verify"]
+        if start:
+            steps.append("reset run")
+        rc, out = self._run(steps)
+        # OpenOCD prints '** Programming Finished **' on success
+        ok = rc == 0 and "** Programming Finished **" in out
+        return flasher.FlashResult(ok, out.strip()[-1200:])
+
+    def write32(self, connect: str, value: int, address: int) -> bool:
+        rc, out = self._run([f"mww 0x{address:08x} 0x{value:08x}"])
+        return rc == 0
+
+    def start_app(self, connect: str) -> bool:
+        rc, out = self._run(["reset run"])
+        return rc == 0
+
+    def read_mem(self, connect: str, address: int, size: int) -> bytes | None:
+        """mdw-based read; returns None on any failure (poll semantics)."""
+        words = (size + 3) // 4
+        rc, out = self._run([f"mdw 0x{address:08x} {words}"])
+        if rc != 0:
+            return None
+        got: list[int] = []
+        # OpenOCD mdw format: "0x2001ff00: f1a5c0de 00010001 ..." —
+        # the ADDRESS carries 0x, the words do not.
+        for m in re.finditer(r"0x[0-9a-fA-F]+:\s+((?:[0-9a-fA-F]{8}\s*)+)",
+                             out):
+            for w in re.finditer(r"[0-9a-fA-F]{8}", m.group(1)):
+                got.append(int(w.group(0), 16))
+        if len(got) < words:
+            return None
+        blob = b"".join(w.to_bytes(4, "little") for w in got[:words])
+        return blob[:size]
+
+
+class FakeBackend(DebugBackend):
+    """CI adapter: no probe, no hardware — scripts decide what happens
+    (design doc §14: build fail / flash timeout / stale identity / probe
+    assertion fail, all in-process)."""
+
+    name = "fake"
+
+    def __init__(self, *, flash_ok: bool = True, signature: bytes | None = None):
+        self.flash_ok = flash_ok
+        self.signature = signature
+        self.calls: list[str] = []
+
+    def available(self) -> str | None:
+        return "fake"
+
+    def discover(self) -> str:
+        return "(fake backend)"
+
+    def flash(self, bin_path, connect, address, start=True):
+        self.calls.append(f"flash:{bin_path}@{address}:start={start}")
+        return flasher.FlashResult(self.flash_ok, "fake flash")
+
+    def write32(self, connect, value, address):
+        self.calls.append(f"write32:{address:#x}={value:#x}")
+        return True
+
+    def start_app(self, connect):
+        self.calls.append("start_app")
+        return True
+
+    def read_mem(self, connect, address, size):
+        self.calls.append(f"read:{address:#x}+{size}")
+        return self.signature[:size] if self.signature else None
+
+
+_BACKENDS: dict[str, type] = {
+    CubeProgrammerBackend.name: CubeProgrammerBackend,
+    OpenOcdBackend.name: OpenOcdBackend,
+    FakeBackend.name: FakeBackend,
+}
+
+
+def known_backends() -> list[str]:
+    return sorted(_BACKENDS)
+
+
+def get_backend(name: str, **kwargs) -> DebugBackend:
+    try:
+        return _BACKENDS[name](**kwargs)
+    except KeyError:
+        raise ValueError(
+            f"unknown debug backend {name!r}; known: {known_backends()}") from None

{flashgate-0.7.2 → flashgate-0.8.0}/flashgate/board.py

@@ -28,6 +28,9 @@ class Board:
     artifact: Path
     flash_connect: str
     flash_address: str
+    flash_adapter: str
+    openocd_target: str
+    openocd_interface: str
     serial_port: str
     usb_vid: int
     usb_pids: tuple[int, ...]
@@ -81,6 +84,35 @@ def load_board(yaml_path: Path) -> Board:
 
     fw = raw.get("firmware") or {}
     flash = raw.get("flash") or {}
+    import re as _re
+    flash_adapter = str(flash.get("adapter", "cubeprogrammer")).lower()
+    if flash_adapter not in ("cubeprogrammer", "openocd", "fake"):
+        raise BoardError(
+            f"board profile {yaml_path.name}: flash.adapter must be one of "
+            f"cubeprogrammer|openocd|fake, got {flash_adapter!r}")
+    # Tcl-injection surface (adversarial review F1/F2): flash.address is a
+    # VALUE inside an OpenOCD command line where ';' separates commands
+    # and '}' escapes braces; target/interface strings reach -f scripts.
+    # These are enumerations/paths, not free text — whitelist them.
+    address = str(flash.get("address", "0x08000000"))
+    if not _re.fullmatch(r"0x[0-9a-fA-F]{1,10}", address):
+        raise BoardError(
+            f"board profile {yaml_path.name}: flash.address must be "
+            f"0x-prefixed hex (got {address!r})")
+    _SAFE_CFG = _re.compile(r"[A-Za-z0-9_./+-]+")
+    for key in ("openocd_target", "openocd_interface"):
+        value = str(flash.get(key, ""))
+        if value and not _SAFE_CFG.fullmatch(value):
+            raise BoardError(
+                f"board profile {yaml_path.name}: flash.{key} may only "
+                f"contain [A-Za-z0-9_./+-] (got {value!r})")
+    if (flash_adapter == "fake"
+            and os.environ.get("FLASHGATE_ALLOW_FAKE") != "1"):
+        raise BoardError(
+            f"board profile {yaml_path.name}: flash.adapter 'fake' is a "
+            "test adapter — set FLASHGATE_ALLOW_FAKE=1 to use it "
+            "(a fake flash never writes hardware and can green-light a "
+            "board that was never programmed)")
     ser = raw.get("serial") or {}
     ev = raw.get("evidence") or {}
     evidence_mode = str(ev.get("mode", "auto")).lower()
@@ -116,6 +148,9 @@ def load_board(yaml_path: Path) -> Board:
             build_command=fw["build"],
             artifact=(base / fw["dir"] / fw["artifact"]).resolve(),
             flash_connect=flash.get("connect", "port=SWD"),
+            flash_adapter=flash_adapter,
+            openocd_target=str(flash.get("openocd_target", "")),
+            openocd_interface=str(flash.get("openocd_interface", "")),
             flash_address=str(flash.get("address", "0x08000000")),
             serial_port=str(ser.get("port", "") or ""),
             usb_vid=int(str(ser.get("vid", "0x1A86")), 0),

{flashgate-0.7.2 → flashgate-0.8.0}/flashgate/cli.py

@@ -26,8 +26,8 @@ import yaml
 
 from . import __version__
 from .board import Board, BoardError, default_board_path, load_board
-from . import flasher, gatestate, probes as probe_mod, records, serialmon, swdsig
-from .sttools import augmented_env, find_cubeprogrammer
+from . import backends, flasher, gatestate, probes as probe_mod, records, serialmon, swdsig
+from .sttools import augmented_env
 
 EXIT_OK = 0
 EXIT_BUILD = 1
@@ -94,6 +94,16 @@ def _resolve_board(args: argparse.Namespace) -> Board:
     return load_board(Path(path))
 
 
+def _board_backend(board: Board) -> backends.DebugBackend:
+    """The debug backend a board profile selects (Phase 2)."""
+    if board.flash_adapter == "openocd":
+        return backends.OpenOcdBackend(
+            mcu=board.mcu,
+            target=board.openocd_target or None,
+            interface=board.openocd_interface or None)
+    return backends.get_backend(board.flash_adapter)
+
+
 def _run(cmd: str, cwd: Path) -> tuple[int, str]:
     proc = subprocess.run(
         cmd, shell=True, cwd=cwd, capture_output=True, text=True,
@@ -109,21 +119,21 @@ def cmd_doctor(board: Board) -> int:
     print(f"  artifact   : {board.artifact}")
     problems: list[str] = []
 
-    cli = find_cubeprogrammer()
-    if cli:
-        print(_green(f"  programmer : {cli}"))
+    backend = _board_backend(board)
+    exe = backend.available()
+    if exe:
+        print(_green(f"  backend    : {backend.name} ({exe})"))
     else:
-        problems.append("STM32CubeProgrammer CLI not found")
-        print(_red("  programmer : NOT FOUND"))
-
-    if cli:
-        listing = flasher.list_stlink()
-        sn_lines = [ln.strip() for ln in listing.splitlines() if "ST-LINK SN" in ln]
-        if sn_lines:
-            print(_green(f"  ST-Link    : {sn_lines[0]}"))
+        problems.append(f"backend {backend.name!r} executable not found")
+        print(_red(f"  backend    : {backend.name} — EXECUTABLE NOT FOUND"))
+
+    if exe:
+        listing = backend.discover()
+        if backend.probe_detected(listing):
+            print(_green("  probe      : detected"))
         else:
-            problems.append("no ST-Link probe detected (check USB, power, driver)")
-            print(_red("  ST-Link    : none detected"))
+            problems.append("no debug probe detected (check USB, power, driver)")
+            print(_red("  probe      : none detected"))
 
     port, why = serialmon.resolve_console_port(board.serial_port, board.usb_vid, board.usb_pids)
     if port:
@@ -147,7 +157,8 @@ def cmd_doctor(board: Board) -> int:
     # Live SWD signature: what the board is running RIGHT NOW, no serial needed
     try:
         info, _ = swdsig.wait_for_signature(
-            board.flash_connect, board.sig_address, board.sig_size, timeout_s=2.0)
+            board.flash_connect, board.sig_address, board.sig_size, timeout_s=2.0,
+            read_fn=backend.read_mem)
         if info:
             print(_green(f"  on-board   : git={info['git']} build={info['build']} (SWD signature)"))
         else:
@@ -219,8 +230,10 @@ def cmd_build(board: Board) -> int:
 
 
 def cmd_flash(board: Board) -> int:
-    print(_cyan(f"[flash] {board.artifact.name} @ {board.flash_address} via {board.flash_connect}"))
-    result = flasher.flash(board.artifact, board.flash_connect, board.flash_address)
+    backend = _board_backend(board)
+    print(_cyan(f"[flash] {board.artifact.name} @ {board.flash_address} via "
+                f"{backend.name}:{board.flash_connect}"))
+    result = backend.flash(board.artifact, board.flash_connect, board.flash_address)
     if not result.ok:
         print(_red("[flash] FAILED"))
         print(result.detail[-1200:])
@@ -390,7 +403,8 @@ def _verify_swd(board: Board, probe_names: list[str] | None,
 
     # Flash WITHOUT starting, wipe the stale signature, then start: RAM is
     # not cleared by reset, so a surviving old-boot signature would lie.
-    result = flasher.flash(board.artifact, board.flash_connect, board.flash_address,
+    backend = _board_backend(board)
+    result = backend.flash(board.artifact, board.flash_connect, board.flash_address,
                            start=False)
     if not result.ok:
         print(_red("[flash] FAILED"))
@@ -398,11 +412,11 @@ def _verify_swd(board: Board, probe_names: list[str] | None,
         j.check("flash", "failed", result.detail[-300:].strip())
         return EXIT_FLASH
     wipe_note = ""
-    if not flasher.write32(board.flash_connect, 0, board.sig_address):
+    if not backend.write32(board.flash_connect, 0, board.sig_address):
         wipe_note = "; WARNING: stale signature could not be wiped"
         print(_yellow("[verify] warning: could not wipe the old signature "
                       "(stale-identity false-pass window)"))
-    if not flasher.start_app(board.flash_connect):
+    if not backend.start_app(board.flash_connect):
         print(_red("[flash] FAILED to start the application"))
         j.check("flash", "failed", "start_app failed")
         return EXIT_FLASH
@@ -412,7 +426,7 @@ def _verify_swd(board: Board, probe_names: list[str] | None,
     print(_cyan(f"[verify] polling signature @ {board.sig_address:#010x} via {board.flash_connect}"))
     info, err = swdsig.wait_for_signature(
         board.flash_connect, board.sig_address, board.sig_size,
-        timeout_s=board.banner_timeout_s)
+        timeout_s=board.banner_timeout_s, read_fn=backend.read_mem)
     if info is None:
         if "not supported" in err:
             print(_red(f"[verify] SIGNATURE LAYOUT MISMATCH: {err}"))

{flashgate-0.7.2 → flashgate-0.8.0}/flashgate/swdsig.py

@@ -81,7 +81,8 @@ def parse_signature(buf: bytes) -> dict | None:
 
 
 def wait_for_signature(
-    connect: str, address: int, size: int = 64, timeout_s: float = 15.0
+    connect: str, address: int, size: int = 64, timeout_s: float = 15.0,
+    read_fn=None,
 ) -> tuple[dict | None, str]:
     """Poll the signature until valid or timeout. Returns (info, last_error).
 
@@ -92,7 +93,7 @@ def wait_for_signature(
     last = "no valid signature yet"
     while time.monotonic() < deadline:
         try:
-            buf = read_ram(connect, address, size)
+            buf = (read_fn or read_ram)(connect, address, size)
         except SwdError as exc:
             last = str(exc)
             time.sleep(1.0)

{flashgate-0.7.2 → flashgate-0.8.0}/flashgate.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashgate
-Version: 0.7.2
+Version: 0.8.0
 Summary: Hardware-in-the-loop verification gate: your agent can't claim the firmware works until the board says so.
 License: MIT
 Project-URL: Homepage, https://github.com/Lion-1209/flashgate
@@ -244,10 +244,24 @@ Stop-hook escalation — plus the full session of a real Claude Code agent
 getting blocked, diagnosing the firmware↔profile contract, fixing both
 sides, and passing on hardware ([24 MB GIF, release asset](https://github.com/Lion-1209/flashgate/releases/download/v0.3.0/5-agent-blocked.gif)).
 
+## Debug backends (Phase 2)
+
+The verify pipeline is backend-agnostic: `flash.adapter:` in the board
+profile picks the probe tool — `cubeprogrammer` (default, the original
+implementation), `openocd` (same ST-Link, no ST toolchain needed, and
+the standard route to Linux/ARM64 bench hosts like a Raspberry Pi), or
+`fake` (scripted, for tests). Validated on the same Apollo board:
+swapping to `openocd` is a one-line profile change — verify stays green
+with identical records, zero upper-layer edits, and runs slightly
+faster. OpenOCD is discovered via PATH or `$OPENOCD_BIN`; the target
+script maps from the MCU family (`STM32H7*` -> `stm32h7x`, override
+with `flash.openocd_target`).
+
 ## Board profiles
 
-One yaml per board (`boards/`): build command, artifact, flash address,
-serial adapter hints, banner template, probes, watch globs. The console-side
+One yaml per board (`boards/`): build command, artifact, flash address
+(`flash.adapter:` picks the debug backend), serial adapter hints,
+banner template, probes, watch globs. The console-side
 USB adapter is a property of your bench, not the board — port resolution
 goes explicit `serial.port` / `FLASHGATE_SERIAL_PORT`, then VID/PID hint,
 then the sole serial port, with the banner match as the final identity
@@ -258,10 +272,10 @@ full profile field reference.
 ## Status
 
 Boot gate, probe gate, Stop hook, MCP server, SWD signature channel,
-verification records (per-check evidence with artifact hashes), and the
-remote bench over device-connect — all implemented and validated on real
-hardware, the remote bench cross-host (Wi-Fi laptop driving a wired
-bench, 2026-09-15). Windows-first; Linux/macOS untested.
+verification records (per-check evidence with artifact hashes), the
+remote bench over device-connect (validated cross-host), and a second
+debug backend (OpenOCD, validated on the same board) — all on real
+hardware. Windows-first; Linux/macOS untested.
 
 ## License
 

{flashgate-0.7.2 → flashgate-0.8.0}/flashgate.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 flashgate/__init__.py
 flashgate/__main__.py
+flashgate/backends.py
 flashgate/bench.py
 flashgate/bench_serve.py
 flashgate/board.py
@@ -22,6 +23,7 @@ flashgate.egg-info/dependency_links.txt
 flashgate.egg-info/entry_points.txt
 flashgate.egg-info/requires.txt
 flashgate.egg-info/top_level.txt
+tests/test_backends.py
 tests/test_bench.py
 tests/test_bench_serve.py
 tests/test_board.py

{flashgate-0.7.2 → flashgate-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flashgate"
-version = "0.7.2"
+version = "0.8.0"
 description = "Hardware-in-the-loop verification gate: your agent can't claim the firmware works until the board says so."
 readme = "README.md"
 requires-python = ">=3.11"

flashgate-0.8.0/tests/test_backends.py

@@ -0,0 +1,307 @@
+"""Debug-backend adapters (Phase 2): registry, targeting, memory-parse,
+profile selection, and the read_fn injection that decouples swdsig from
+CubeProgrammer."""
+
+import pytest
+
+from flashgate import backends
+
+
+class TestRegistry:
+    def test_known_and_default(self):
+        assert backends.known_backends() == ["cubeprogrammer", "fake", "openocd"]
+        assert backends.get_backend("cubeprogrammer").name == "cubeprogrammer"
+
+    def test_unknown_rejected(self):
+        with pytest.raises(ValueError, match="unknown debug backend"):
+            backends.get_backend("jlink-someday")
+
+
+class TestTargetMapping:
+    def test_mcu_prefix_map(self):
+        assert backends.openocd_target_for("STM32H743IIT6") == "stm32h7x"
+        assert backends.openocd_target_for("stm32f407") == "stm32f4x"
+        assert backends.openocd_target_for("LPC55S69") is None
+
+
+class TestReadMemParsing:
+    def test_mdw_words_without_0x_prefix(self, monkeypatch):
+        b = backends.OpenOcdBackend(mcu="STM32H743IIT6")
+        out = ("Info : blah\n"
+               "0x2001ff00: f1a5c0de 01000100 37323463 \n"
+               "0x2001ff10: 2d656337 \n"
+               "shutdown command invoked\n")
+        monkeypatch.setattr(b, "_run", lambda cmds: (0, out))
+        blob = b.read_mem("x", 0x2001FF00, 8)
+        assert blob == bytes.fromhex("dec0a5f1" "00010001")
+
+    def test_failed_run_returns_none(self, monkeypatch):
+        b = backends.OpenOcdBackend(mcu="STM32H743IIT6")
+        monkeypatch.setattr(b, "_run", lambda cmds: (1, "boom"))
+        assert b.read_mem("x", 0, 64) is None
+
+    def test_unparsed_output_returns_none(self, monkeypatch):
+        b = backends.OpenOcdBackend(mcu="STM32H743IIT6")
+        monkeypatch.setattr(b, "_run", lambda cmds: (0, "no memory lines"))
+        assert b.read_mem("x", 0, 64) is None
+
+    def test_no_target_mapping_reports_clearly(self):
+        b = backends.OpenOcdBackend(mcu="LPC55S69")
+        rc, out = b._run(["init"])
+        assert rc == -1 and "openocd_target" in out
+
+
+class TestSwdsigReadInjection:
+    def test_wait_uses_injected_reader(self):
+        from flashgate import swdsig
+        import struct
+        import zlib
+        calls = []
+
+        # valid v1 signature: magic+ver+flags(8) | git@0x08(16) |
+        # build@0x18(24) | crc32 of first 0x30 bytes @0x30
+        buf = bytearray(64)
+        struct.pack_into("<IHH", buf, 0, swdsig.SIG_MAGIC, 1, 0)
+        buf[0x08:0x0F] = b"c4277ce"
+        buf[0x18:0x2C] = b"2026-01-01T00:00:00Z"
+        struct.pack_into("<I", buf, 0x30,
+                         zlib.crc32(bytes(buf[:0x30])) & 0xFFFFFFFF)
+        blob = bytes(buf)
+
+        def fake_read(connect, address, size):
+            calls.append((address, size))
+            return blob[:size]
+
+        info, err = swdsig.wait_for_signature(
+            "c", 0x2001FF00, 64, timeout_s=1.0, read_fn=fake_read)
+        assert calls, "injected reader must be used"
+        assert info is not None and info["version"] == 1
+
+
+class TestFakeBackend:
+    def test_scripts_the_pipeline(self):
+        b = backends.FakeBackend(flash_ok=False)
+        assert b.flash("x", "c", "0x08000000").ok is False
+        assert b.write32("c", 0, 0x2001FF00) is True
+        assert b.read_mem("c", 0, 64) is None
+        assert b.calls[0].startswith("flash:")
+
+
+class TestFakeBackendPipeline:
+    """The design doc §14 simulated-integration list, driven end-to-end
+    through cmd_verify with a scripted fake backend: flash failure,
+    signature timeout, stale identity, happy path — no probe attached."""
+
+    @pytest.fixture(autouse=True)
+    def _allow_fake(self, monkeypatch):
+        monkeypatch.setenv("FLASHGATE_ALLOW_FAKE", "1")
+
+    @staticmethod
+    def _board(tmp_path, extra=""):
+        from flashgate.board import load_board
+        fw = tmp_path / "fw"
+        fw.mkdir(exist_ok=True)
+        p = tmp_path / "b.yaml"
+        p.write_text(
+            "board: t\nmcu: STM32H743\nfirmware:\n  dir: fw\n"
+            "  build: ninja\n  artifact: fw.bin\n"
+            f"flash:\n  adapter: fake\n{extra}"
+            "evidence:\n  mode: swd\n"
+            "serial:\n  banner: 'BOOT {git}'\n"
+            "  banner_timeout_s: 0.3\n", encoding="utf-8")
+        (fw / "fw.bin").write_bytes(b"\x00" * 16)
+        return load_board(p)
+
+    @staticmethod
+    def _sig(git: bytes = b"aaaaaaa"):
+        import struct
+        import zlib
+        from flashgate import swdsig as sg
+        buf = bytearray(64)
+        struct.pack_into("<IHH", buf, 0, sg.SIG_MAGIC, 1, 0)
+        buf[0x08:0x08 + len(git)] = git
+        struct.pack_into("<I", buf, 0x30,
+                         zlib.crc32(bytes(buf[:0x30])) & 0xFFFFFFFF)
+        return bytes(buf)
+
+    def _run(self, tmp_path, fake, monkeypatch, extra=""):
+        from flashgate import cli
+        board = self._board(tmp_path, extra)
+        monkeypatch.setattr(cli, "_build", lambda b, j=None: cli.EXIT_OK)
+        monkeypatch.setattr(cli, "_board_backend", lambda b: fake)
+        return cli.cmd_verify(board, None)
+
+    def test_flash_failure_exit_2(self, tmp_path, monkeypatch):
+        from flashgate import backends, cli
+        rc = self._run(tmp_path, backends.FakeBackend(flash_ok=False),
+                       monkeypatch)
+        assert rc == cli.EXIT_FLASH
+
+    def test_signature_timeout_exit_3(self, tmp_path, monkeypatch):
+        from flashgate import backends, cli
+        rc = self._run(tmp_path, backends.FakeBackend(signature=None),
+                       monkeypatch)
+        assert rc == cli.EXIT_BANNER_TIMEOUT
+
+    def test_stale_identity_exit_5(self, tmp_path, monkeypatch):
+        from flashgate import backends, cli
+        from flashgate.board import Board
+        fake = backends.FakeBackend(signature=self._sig(b"bbbbbbb"))
+        monkeypatch.setattr(Board, "head_sha",
+                            lambda self: "aaaaaaa-dirty")
+        rc = self._run(tmp_path, fake, monkeypatch)
+        assert rc == cli.EXIT_SHA_MISMATCH
+
+    def test_happy_path_exit_0(self, tmp_path, monkeypatch):
+        from flashgate import backends, cli
+        from flashgate.board import Board
+        fake = backends.FakeBackend(
+            signature=self._sig(b"aaaaaaa-dirty"))   # matches head_sha
+        monkeypatch.setattr(Board, "head_sha", lambda self: "aaaaaaa-dirty")
+        rc = self._run(tmp_path, fake, monkeypatch)
+        assert rc == cli.EXIT_OK
+
+    def test_fake_adapter_selectable_from_profile(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("FLASHGATE_ALLOW_FAKE", "1")
+        board = self._board(tmp_path)
+        assert board.flash_adapter == "fake"
+
+    def test_fake_requires_explicit_opt_in(self, tmp_path, monkeypatch):
+        # F4: without the env gate, a fake profile must not even load —
+        # a simulated flash can green-light a board never programmed.
+        import pytest as _pytest
+        from flashgate.board import BoardError
+        monkeypatch.delenv("FLASHGATE_ALLOW_FAKE", raising=False)
+        with _pytest.raises(BoardError, match="FLASHGATE_ALLOW_FAKE"):
+            self._board(tmp_path)
+
+    def test_unknown_adapter_rejected_at_load(self, tmp_path):
+        import pytest
+        from flashgate.board import BoardError
+        with pytest.raises(BoardError, match="flash.adapter"):
+            self._board(tmp_path, extra="  adapter: jlink\n")
+
+
+class TestPhase2AuditFixes:
+    """Runtime-audit gaps: openocd_target wiring, per-backend probe
+    detection, doctor's on-board read through the backend."""
+
+    def test_openocd_target_override_wired_from_profile(self, tmp_path):
+        from flashgate.board import load_board
+        fw = tmp_path / "fw"; fw.mkdir()
+        p = tmp_path / "b.yaml"
+        p.write_text(
+            "board: t\nmcu: STM32H743\nfirmware:\n  dir: fw\n"
+            "  build: ninja\n  artifact: fw.bin\n"
+            "flash:\n  adapter: openocd\n"
+            "  openocd_target: my_custom_target\n"
+            "evidence:\n  mode: swd\nserial:\n  banner: 'B {git}'\n",
+            encoding="utf-8")
+        board = load_board(p)
+        assert board.openocd_target == "my_custom_target"
+        from flashgate import backends
+        b = backends.OpenOcdBackend(
+            mcu=board.mcu, target=board.openocd_target or None)
+        assert b._target == "my_custom_target"
+
+    def test_probe_detection_markers(self):
+        cp = backends.CubeProgrammerBackend()
+        assert cp.probe_detected("--- ST-LINK SN : 56FF ---") is True
+        assert cp.probe_detected("(CubeProgrammer CLI not found)") is False
+        oc = backends.OpenOcdBackend(mcu="STM32H743")
+        assert oc.probe_detected("Info : STLINK V2 (API v2) VID:PID 0483:3748") is True
+        assert oc.probe_detected("SWD DPIDR 0x6ba02477") is True
+        assert oc.probe_detected("(openocd probe listing unavailable: x)") is False
+        fake = backends.FakeBackend()
+        assert fake.probe_detected("(fake backend)") is True
+        assert fake.probe_detected("") is False
+
+    def test_board_backend_passes_overrides(self, tmp_path, monkeypatch):
+        from flashgate.board import load_board
+        from flashgate import cli
+        fw = tmp_path / "fw"; fw.mkdir()
+        p = tmp_path / "b.yaml"
+        p.write_text(
+            "board: t\nmcu: STM32H743\nfirmware:\n  dir: fw\n"
+            "  build: ninja\n  artifact: fw.bin\n"
+            "flash:\n  adapter: openocd\n"
+            "  openocd_interface: interface/cmsis-dap.cfg\n"
+            "evidence:\n  mode: swd\nserial:\n  banner: 'B {git}'\n",
+            encoding="utf-8")
+        board = load_board(p)
+        b = cli._board_backend(board)
+        assert isinstance(b, backends.OpenOcdBackend)
+        assert b._interface == "interface/cmsis-dap.cfg"
+        assert b._target == "stm32h7x"          # MCU mapping still applies
+
+
+class TestInjectionAndDelegation:
+    """Q4/Q6 mutation survivors + F1/F2 injection rejections."""
+
+    def test_program_command_is_forward_slashed_and_braced(self, monkeypatch):
+        b = backends.OpenOcdBackend(mcu="STM32H743")
+        seen = {}
+        monkeypatch.setattr(b, "_run",
+                            lambda cmds: (seen.update(cmds=cmds) or (0, "")))
+        import pathlib
+        fake_bin = pathlib.PureWindowsPath(r"E:\dir\na me\App.bin")
+        monkeypatch.setattr(backends.Path, "is_file",
+                            lambda self: True, raising=False)
+        b.flash(fake_bin, "c", "0x08000000")
+        cmd = seen["cmds"][0]
+        assert cmd == "program {E:/dir/na me/App.bin} 0x08000000 verify"
+
+    def test_brace_in_artifact_path_refused(self, tmp_path):
+        evil = tmp_path / "we}ird.bin"
+        evil.write_bytes(b"x")
+        b = backends.OpenOcdBackend(mcu="STM32H743")
+        res = b.flash(evil, "c", "0x08000000")
+        assert res.ok is False and "cannot be passed" in res.detail
+
+    def test_address_with_tcl_separator_rejected_at_load(self, tmp_path):
+        import pytest as _pytest
+        from flashgate.board import BoardError, load_board
+        fw = tmp_path / "fw"; fw.mkdir()
+        p = tmp_path / "b.yaml"
+        p.write_text("board: t\nmcu: STM32H743\nfirmware:\n  dir: fw\n"
+                     "  build: ninja\n  artifact: fw.bin\n"
+                     'flash:\n  address: "0x08000000; shutdown"\n'
+                     "serial:\n  banner: 'B {git}'\n", encoding="utf-8")
+        with _pytest.raises(BoardError, match="flash.address"):
+            load_board(p)
+
+    def test_openocd_target_with_brace_rejected_at_load(self, tmp_path):
+        import pytest as _pytest
+        from flashgate.board import BoardError, load_board
+        fw = tmp_path / "fw"; fw.mkdir()
+        p = tmp_path / "b.yaml"
+        p.write_text("board: t\nmcu: STM32H743\nfirmware:\n  dir: fw\n"
+                     "  build: ninja\n  artifact: fw.bin\n"
+                     "flash:\n  adapter: openocd\n"
+                     "  openocd_target: 'x}; echo PWNED; #'\n"
+                     "serial:\n  banner: 'B {git}'\n", encoding="utf-8")
+        with _pytest.raises(BoardError, match="openocd_target"):
+            load_board(p)
+
+    def test_cubeprogrammer_read_mem_delegates_in_order(self, monkeypatch):
+        from flashgate import swdsig as swsig
+        seen = {}
+        monkeypatch.setattr(swsig, "read_ram",
+                            lambda c, a, s: seen.update(c=c, a=a, s=s) or b"")
+        b = backends.CubeProgrammerBackend()
+        b.read_mem("port=SWD", 0x2001FF00, 64)
+        assert seen == {"c": "port=SWD", "a": 0x2001FF00, "s": 64}
+
+    def test_interface_short_name_gets_prefix(self, monkeypatch):
+        b = backends.OpenOcdBackend(mcu="STM32H743",
+                                    interface="cmsis-dap")
+        seen = {}
+        monkeypatch.setattr(b, "_run",
+                            lambda cmds: (seen.update(cmds=cmds) or (0, "")))
+        b.write32("c", 0, 0x2001FF00)
+        argv = seen["cmds"]  # not full argv; assert via prefixing behavior
+        assert b._interface == "cmsis-dap"
+        # prefixing happens in _run's cmd construction; assert through flash
+        import flashgate.backends as bm
+        src = open(bm.__file__, encoding="utf-8").read()
+        assert 'f"interface/{i}.cfg"' in src