oep-client-python 0.0.52__tar.gz → 0.0.53__tar.gz

{oep_client_python-0.0.52 → oep_client_python-0.0.53}/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## Unreleased
 
+## 0.0.53
+- (EN) An RP2040 board as a test's peer over an OEP probe's SWD alone (`oep_client.rp2040_peer`), for a peer whose USB goes to
+  the device under test: `python -m oep_client.rp2040_peer flash oep://<probe>/<port> <elf|bin>` (the port's labels
+  `<port>.swdio` / `<port>.swclk`; through ch32rv's broker sharing its lock when it runs, found with `$CH32RV`; the old
+  image's SEGGER RTT IDs left in RAM are wiped before the reboot, so the console finds the new one's), the console as
+  SEGGER RTT through the MEM-AP (`console`, and pyserial's `oep://` handler in `oep_client.pyserial`), and
+  `pytest_plugins = ["oep_client.pytest_rp2040_peer"]` for pytest-embedded-arduino-cli: arduino-pico's OpenOCD upload
+  (`uploadmethod=picoprobe_cmsis_dap`) handed to the writer through generated hook files, the peer's own device lock,
+  the DUT's ch32rv passed on.
+- (JA) RP2040 の基板を、OEP のプローブの SWD だけで試験の相手（peer）にする（`oep_client.rp2040_peer`）。USB を DUT に
+  つなぐ相手のため。`python -m oep_client.rp2040_peer flash oep://<probe>/<port> <elf|bin>`（口のラベル `<port>.swdio` /
+  `<port>.swclk`。ch32rv の broker が動いていれば、そのロックに相乗りする。broker は `$CH32RV` で探す。RAM に残った前の
+  イメージの SEGGER RTT の ID は起動し直す前に消し、コンソールが新しいものを見つけるようにする）、コンソールは
+  MEM-AP の上の SEGGER RTT（`console`、pyserial の `oep://` の handler は `oep_client.pyserial`）。pytest-embedded-arduino-cli
+  には `pytest_plugins = ["oep_client.pytest_rp2040_peer"]`: arduino-pico の OpenOCD の書き込み（`uploadmethod=picoprobe_cmsis_dap`）
+  を、書き出した hook のファイルで書き込みの道具に渡す。peer のロックは自分のもの。DUT の ch32rv を引き渡す。
+- (EN) `rp2040`: the RP2040's flash written over SWD through its boot ROM (`rom_table_lookup` at 0x18 on the function
+  table at 0x14), the sequence shared with `rp2350.Flash` (which now takes another chip's ROM lookup and spare RAM), and
+  a reboot by the watchdog the pico-sdk's way (PSM WDSEL all but the oscillators, SCRATCH4 0: left as it comes, the
+  trigger restarted nothing). `arm.CortexM.reset_halt()`: reset the core and stop on its first instruction (a core
+  locked up in a fault handler is no place to call the ROM from).
+- (JA) `rp2040`: RP2040 の flash を SWD でブート ROM から書く（関数表は 0x14、`rom_table_lookup` は 0x18）。手順は `rp2350.Flash` と
+  共通にし、Flash はほかのチップの ROM の引き方と空いている RAM を受け取れるようにした。起動し直しは pico-sdk と同じウォッチドッグの
+  手順（PSM の WDSEL を発振器以外すべて、SCRATCH4 を 0。そのままではトリガしても何も起動し直さなかった）。`arm.CortexM.reset_halt()`:
+  コアをリセットして最初の命令で止める（fault の処理の途中で lockup したコアからは ROM を呼べない）。
+
 ## 0.0.52
 - (EN) Capture format 1 is per-channel reductions (oep-spec 165a278, capture §1.3): `LogicCapture.configure(...,
   carriage={role: (carriage, D)})` with capture_blocks.SAMPLE / ANY_HIGH / ANY_LOW / CHANGE_LATCH (the `events`

{oep_client_python-0.0.52 → oep_client_python-0.0.53}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oep-client-python
-Version: 0.0.52
+Version: 0.0.53
 Summary: Open Embedded Probe (OEP) v1 host: serial / USB / TCP transports, the session rules, the standard interfaces, and a virtual bench
 Project-URL: Homepage, https://github.com/Open-Embedded-Probe/oep-client-python
 Project-URL: Repository, https://github.com/Open-Embedded-Probe/oep-client-python

{oep_client_python-0.0.52 → oep_client_python-0.0.53}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oep-client-python"
-version = "0.0.52"
+version = "0.0.53"
 description = "Open Embedded Probe (OEP) v1 host: serial / USB / TCP transports, the session rules, the standard interfaces, and a virtual bench"
 readme = "README.md"
 license = "MIT"

{oep_client_python-0.0.52 → oep_client_python-0.0.53}/src/oep_client/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.0.52"
+__version__ = "0.0.53"

{oep_client_python-0.0.52 → oep_client_python-0.0.53}/src/oep_client/arm.py

@@ -315,6 +315,19 @@ class CortexM:
             raise h.OepError(f"stopped at {pc:#010x}, not at the return breakpoint")
         return self.reg(0)
 
+    DEMCR, VC_CORERESET = 0xE000EDFC, 1
+
+    def reset_halt(self, timeout: float = 1.0) -> int:
+        """Reset the core and stop it on its first instruction (DEMCR.VC_CORERESET through AIRCR.SYSRESETREQ), the
+        catch cleared again: a clean core to call ROM functions on (a core left locked up in a fault handler is not
+        one). C_MASKINTS is cleared first (it survives the reset). -> PC"""
+        self.mem.write32(self.DHCSR, self.KEY | self.C_DEBUGEN | self.C_HALT)
+        self.mem.write32(self.DEMCR, self.mem.read32(self.DEMCR) | self.VC_CORERESET)
+        self.mem.write32(self.AIRCR, 0x05FA0004)
+        self._wait(self.S_HALT, timeout)
+        self.mem.write32(self.DEMCR, self.mem.read32(self.DEMCR) & ~self.VC_CORERESET)
+        return self.reg(self.PC)
+
     def sys_reset(self) -> None:
         """AIRCR.SYSRESETREQ: the core restarts; debug-domain state (DHCSR) survives, so clear the mask first."""
         self.mem.write32(self.DHCSR, self.KEY | self.C_DEBUGEN | self.C_HALT)

oep_client_python-0.0.53/src/oep_client/pyserial/__init__.py

@@ -0,0 +1 @@
+"""pyserial URL handlers (serial.protocol_handler_packages.append("oep_client.pyserial")): oep:// - see protocol_oep."""

oep_client_python-0.0.53/src/oep_client/pyserial/protocol_oep.py

@@ -0,0 +1,92 @@
+"""pyserial's handler for oep://<probe>/<port>: an RP2040 peer's console over the probe's SWD (SEGGER RTT through the
+MEM-AP, oep_client.rp2040_peer.Console). Baud rate, parity and the control lines mean nothing here and are taken as
+given. A console that stops (the session lost, the target gone) raises on the next read."""
+
+from __future__ import annotations
+
+import time
+
+from serial.serialutil import PortNotOpenError, SerialBase, SerialException
+
+from ..rp2040_peer import Console
+
+
+class Serial(SerialBase):
+    def open(self):
+        if self._port is None:
+            raise SerialException("port must be configured before it can be used")
+        if self.is_open:
+            raise SerialException("port already open")
+        try:
+            self._console = Console(self.portstr)
+        except Exception as e:
+            raise SerialException(f"{self.portstr}: {e}") from e
+        self.is_open = True
+
+    def close(self):
+        if self.is_open:
+            self._console.close()
+            self.is_open = False
+
+    def from_url(self, url):
+        return url
+
+    def _reconfigure_port(self):
+        pass
+
+    @property
+    def in_waiting(self):
+        if not self.is_open:
+            raise PortNotOpenError()
+        return self._console.in_waiting()
+
+    def read(self, size=1):
+        if not self.is_open:
+            raise PortNotOpenError()
+        deadline = None if self._timeout is None else time.monotonic() + self._timeout
+        out = bytearray()
+        while len(out) < size:
+            if self._console.error:
+                raise SerialException(f"{self.portstr}: {self._console.error}")
+            out += self._console.read(size - len(out))
+            if len(out) >= size or (deadline is not None and time.monotonic() >= deadline):
+                break
+            time.sleep(0.005)
+        return bytes(out)
+
+    def write(self, data):
+        if not self.is_open:
+            raise PortNotOpenError()
+        return self._console.write(bytes(data))
+
+    def reset_input_buffer(self):
+        if self.is_open:
+            self._console.read()
+
+    def reset_output_buffer(self):
+        pass
+
+    def _update_break_state(self):
+        pass
+
+    def _update_rts_state(self):
+        pass
+
+    def _update_dtr_state(self):
+        pass
+
+    @property
+    def cts(self):
+        return True
+
+    @property
+    def dsr(self):
+        return True
+
+    @property
+    def ri(self):
+        return False
+
+    @property
+    def cd(self):
+        return True

oep_client_python-0.0.53/src/oep_client/pytest_rp2040_peer.py

@@ -0,0 +1,68 @@
+"""pytest-embedded-arduino-cli peers that are RP2040 boards on an OEP probe's SWD (oep_client.rp2040_peer), enabled by
+`pytest_plugins = ["oep_client.pytest_rp2040_peer"]` in a conftest.py.
+
+A peer `peer_<name>/` is such a peer when its address, the environment variable `TEST_SERIAL_PORT_PEER_<NAME>` (the
+plugin's own), is `oep://<probe>/<port>`, and its profile uploads with arduino-pico's `uploadmethod=picoprobe_cmsis_dap`.
+Then:
+
+- its console: pyserial opens `oep://...` as the RTT console over SWD (oep_client.pyserial is registered);
+- its upload: `interface/cmsis-dap.cfg` and `target/rp2040.cfg` are generated in the peer's directory (keep them out of
+  git), so arduino-pico's OpenOCD hands the ELF to `python -m oep_client.rp2040_peer flash` instead of a CMSIS-DAP;
+- its device lock: its own (`rp2040-swd:<address>`), not the probe's - it shares the probe with the DUT through ch32rv's
+  broker;
+- the broker: when the DUT is ch32rv's (pytest-embedded-arduino-cli-ch32rv's `ch32rv` fixture), its ch32rv goes to the
+  writer as `CH32RV`, which finds the broker the DUT's monitor started and shares its lock.
+"""
+
+from __future__ import annotations
+
+import os
+import pathlib
+
+import pytest
+import serial
+
+from . import rp2040_peer
+
+if "oep_client.pyserial" not in serial.protocol_handler_packages:
+    serial.protocol_handler_packages.append("oep_client.pyserial")
+
+
+def _env_name(peer: str) -> str:
+    return "TEST_SERIAL_PORT_PEER_" + peer.upper().replace("-", "_")
+
+
+def _peer_addresses() -> set[str]:
+    return {v for k, v in os.environ.items() if k.startswith("TEST_SERIAL_PORT_PEER_") and v.startswith("oep://")}
+
+
+def pytest_collection_modifyitems(session, config, items):
+    """The OpenOCD hook in every RP2040 peer directory beside the collected tests."""
+    seen = set()
+    for item in items:
+        for peer_dir in pathlib.Path(item.path).parent.glob("peer_*"):
+            if peer_dir in seen or not peer_dir.is_dir():
+                continue
+            seen.add(peer_dir)
+            name = peer_dir.name[len("peer_"):]
+            address = os.environ.get(_env_name(name), "")
+            yaml = peer_dir / "sketch.yaml"
+            if address.startswith("oep://") and yaml.exists() and "picoprobe_cmsis_dap" in yaml.read_text():
+                rp2040_peer.write_openocd_hook(str(peer_dir), _env_name(name))
+
+
+def pytest_arduino_cli_device_lock_key(config, port):
+    if port and port in _peer_addresses():
+        return f"rp2040-swd:{port}"
+    return None
+
+
+@pytest.fixture(autouse=True)
+def _oep_rp2040_peer_broker(request, monkeypatch):
+    """The DUT's ch32rv (when there is one) for the peer's writer, which runs under OpenOCD apart from pytest."""
+    if not _peer_addresses():
+        return
+    try:
+        monkeypatch.setenv("CH32RV", str(request.getfixturevalue("ch32rv")))
+    except pytest.FixtureLookupError:
+        pass

oep_client_python-0.0.53/src/oep_client/rp2040.py

@@ -0,0 +1,68 @@
+"""RP2040 target knowledge for the host: its boot ROM's function lookup, the RAM a host-driven call can use, and a reboot
+- the flash sequence itself is RP2350's (rp2350.Flash: the pico-sdk's hardware_flash order through the same ROM function
+codes). The probe knows none of this.
+
+Facts from the pico-sdk (boot_bootrom_headers/bootrom_constants.h, pico_bootrom/bootrom.h, regs/addressmap.h): the
+ROM keeps a halfword pointer to its public function table at 0x14 and to rom_table_lookup(table, code) at 0x18; the
+codes are two characters ('I', 'F') = 'I' | 'F' << 8; SRAM is 0x20000000 - 0x20042000. The RP2040 ROM has no reboot
+function: the watchdog's trigger restarts the chip (USB included).
+"""
+
+from __future__ import annotations
+
+from .arm import CortexM
+from . import rp2350
+
+FUNC_TABLE_PTR, TABLE_LOOKUP_PTR = 0x14, 0x18
+# RAM the target can spare while the host drives it (SRAM ends at 0x20042000; SRAM4 / 5 above 0x20040000 kept free):
+# the return breakpoint, the data buffer for programming, and the stack the ROM functions run on.
+BKPT_AT, BUF, BUF_BYTES, STACK_TOP = 0x20030000, 0x20031000, 16 * 1024, 0x20040000
+# the watchdog (WATCHDOG_BASE 0x40058000: CTRL, SCRATCH4) and what its reset takes (PSM_BASE 0x40010000: WDSEL), as
+# the pico-sdk's watchdog_reboot sets them: everything but ROSC / XOSC, SCRATCH4 0 for a normal boot
+WATCHDOG_CTRL, WATCHDOG_SCRATCH4, WATCHDOG_TRIGGER = 0x40058000, 0x4005801C, 1 << 31
+PSM_WDSEL, PSM_WDSEL_ALL_BUT_OSCS = 0x40010008, 0x0001FFFF & ~0x3
+# TARGETSEL of the multidrop SWD (RP2040 datasheet: core 0, core 1, the rescue DP)
+TARGETSEL_CORE0, TARGETSEL_CORE1, TARGETSEL_RESCUE = 0x01002927, 0x11002927, 0xF1002927
+
+
+def _hword(core: CortexM, at: int) -> int:
+    word = core.mem.read32(at & ~3)
+    return (word >> (8 * (at & 3))) & 0xFFFF
+
+
+class Rom:
+    def __init__(self, core: CortexM):
+        self.core = core
+        self._fn: dict[str, int] = {}
+
+    def lookup(self, c: str) -> int:
+        if c not in self._fn:
+            table, lookup = _hword(self.core, FUNC_TABLE_PTR), _hword(self.core, TABLE_LOOKUP_PTR)
+            addr = self.core.call(lookup, (table, rp2350.code(*c)))
+            if not 0 < addr < 0x4000:
+                raise LookupError(f"ROM has no function {c!r} (lookup returned {addr:#x})")
+            self._fn[c] = addr
+        return self._fn[c]
+
+    def reboot(self) -> None:
+        """The whole chip restarted by the watchdog's trigger, as the pico-sdk's watchdog_reboot(0, 0, 0): WDSEL set to
+        everything but the oscillators (left as it comes, the trigger restarted nothing: the core stayed locked up on
+        the return breakpoint, 2026-11-10), SCRATCH4 0 (a normal boot), not paused for debug. The core is let go
+        first (C_MASKINTS off: it survives every reset but power-on); the USB device re-enumerates."""
+        mem = self.core.mem
+        mem.write32(WATCHDOG_SCRATCH4, 0)
+        mem.write32(PSM_WDSEL, PSM_WDSEL_ALL_BUT_OSCS)
+        self.core.release()
+        mem.write32(WATCHDOG_CTRL, WATCHDOG_TRIGGER)
+
+
+def flash(core: CortexM) -> rp2350.Flash:
+    return rp2350.Flash(core, Rom(core), BUF, BUF_BYTES)
+
+
+def core_of(mem) -> CortexM:
+    return CortexM(mem, bkpt_at=BKPT_AT, stack_top=STACK_TOP)
+
+
+def program_and_verify(core: CortexM, image: bytes, offset: int = 0, log=lambda s: None) -> bool:
+    return rp2350.program_and_verify(core, image, offset, log, flash(core))

oep_client_python-0.0.53/src/oep_client/rp2040_peer.py

@@ -0,0 +1,358 @@
+"""An RP2040 board as a test's peer over an OEP probe's SWD alone: written over SWD (rp2040), its console the SEGGER RTT
+rings read and written through the MEM-AP while the core runs. For a peer whose native USB goes to the device under test,
+so neither the USB writing nor a USB console is there.
+
+The address is `oep://<probe>/<port>`: the probe's channels labelled `<port>.swdio` / `<port>.swclk` are the wire. When
+ch32rv's broker serves that probe (the DUT's monitor started it), the session shares its lock (ch32rv's named extension
+io.github.ch32-riscv-ug.share, as its own tools and pytest's oep_host do); else the probe is opened directly.
+
+- `python -m oep_client.rp2040_peer flash oep://<probe>/<port> <image.elf|.bin>`: write, verify, reboot.
+- `python -m oep_client.rp2040_peer console oep://<probe>/<port> [seconds]`: print the RTT output.
+- pyserial: `serial.protocol_handler_packages.append("oep_client.pyserial")` makes `serial_for_url("oep://...")` this
+  console (the handler is oep_client.pyserial.protocol_oep).
+- `write_openocd_hook(sketch_dir, env)`: files for arduino-pico's OpenOCD upload (uploadmethod=picoprobe_cmsis_dap)
+  that hand the ELF to `flash` with the address from the environment variable `env` instead of driving a CMSIS-DAP.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import struct
+import subprocess
+import sys
+import threading
+import time
+import urllib.parse
+
+from . import acquire, arm, core, link, rp2040
+
+SHARE = "io.github.ch32-riscv-ug.share"   # ch32rv's broker: share the lock its tools hold
+LEASE_MS = 60000
+RAM, RAM_END = 0x20000000, 0x20042000
+RTT_ID = b"SEGGER RTT\0\0\0\0\0\0"
+FLASH_BASE, FLASH_END = 0x10000000, 0x11000000
+
+
+def parse(address: str) -> tuple[str, str]:
+    """oep://<probe>/<port>[?...] -> (unit id, port)."""
+    u = urllib.parse.urlparse(address)
+    port = u.path.strip("/").split("/")[0] if u.path.strip("/") else ""
+    if u.scheme != "oep" or not u.netloc or not port:
+        raise ValueError(f"{address}: want oep://<probe>/<port> (the port's labels <port>.swdio / <port>.swclk)")
+    return u.netloc, port
+
+
+def _broker_endpoint(unit: str) -> str | None:
+    """ch32rv's broker for this probe, when one runs (`ch32rv broker endpoint --json`; ch32rv from $CH32RV or PATH)."""
+    exe = os.environ.get("CH32RV") or shutil.which("ch32rv")
+    if not exe:
+        return None
+    try:
+        r = subprocess.run([exe, "broker", "endpoint", "--probe", f"oep://{unit}", "--json"], capture_output=True,
+                           text=True, timeout=20)
+        return (json.loads(r.stdout).get("result") or {}).get("endpoint")
+    except (OSError, ValueError, subprocess.TimeoutExpired):
+        return None
+
+
+def open_host(unit: str, owner: str):
+    """A Host in a session on the probe: through ch32rv's broker sharing its lock when it runs, else directly."""
+    from . import host as oh, message as m
+    endpoint = _broker_endpoint(unit)
+    if endpoint:
+        host_, port = endpoint.rsplit(":", 1)
+        lk = link.SerialLink.on_stream(link.TcpStream(host_, int(port)), "length", 3.0)
+        h = oh.Host(lk.send)
+        lk.attach_host(h)
+        h.link = lk                                   # closed with the session, as a direct one's
+        try:
+            h.open(LEASE_MS, owner=owner, extensions=[SHARE])
+        except oh.Unsupported as e:
+            if e.tag != m.TAG_NAMED_EXTENSION | m.TAG_CRITICAL:
+                raise
+            h.open(LEASE_MS, owner=owner)
+        return h
+    h = link.open_host(f"oep://{unit}?via=usb")
+    h.open(LEASE_MS, owner=owner)
+    return h
+
+
+class Target:
+    """The RP2040's core 0 on the port's SWD pair: wire, connection, MEM-AP, CortexM."""
+
+    def __init__(self, h, port: str):
+        swdio, swclk = acquire._channels(core, h, [f"{port}.swdio", f"{port}.swclk"])
+        self.host, self.wire = h, arm.SwdWire(h)
+        self.conn, self.dpidr, _ = self.wire.attach(targetsel=rp2040.TARGETSEL_CORE0, pins=(swdio, swclk))
+        adi = arm.ArmAdi(h, self.conn)
+        adi.power_up()
+        self.mem = arm.MemAp(adi, 0)
+        self.core = rp2040.core_of(self.mem)
+
+    def close(self) -> None:
+        try:
+            self.wire.detach(self.conn)
+        except Exception:
+            pass
+
+
+def image_of(path: str) -> bytes:
+    """A flash image from 0x10000000: a .bin as it is, an ELF's loadable segments in flash laid out by address."""
+    data = open(path, "rb").read()
+    if data[:4] != b"\x7fELF":
+        return data
+    if data[4] != 1 or data[5] != 1:
+        raise ValueError(f"{path}: want a 32-bit little-endian ELF")
+    phoff, = struct.unpack_from("<I", data, 28)
+    phentsize, phnum = struct.unpack_from("<HH", data, 42)
+    parts = []
+    for i in range(phnum):
+        p_type, p_offset, _vaddr, p_paddr, p_filesz = struct.unpack_from("<IIIII", data, phoff + i * phentsize)
+        if p_type == 1 and p_filesz and FLASH_BASE <= p_paddr < FLASH_END:
+            parts.append((p_paddr, data[p_offset:p_offset + p_filesz]))
+    if not parts:
+        raise ValueError(f"{path}: no loadable segment in flash")
+    end = max(a + len(b) for a, b in parts)
+    image = bytearray(b"\xff" * (end - FLASH_BASE))
+    for a, b in parts:
+        image[a - FLASH_BASE:a - FLASH_BASE + len(b)] = b
+    return bytes(image)
+
+
+def clear_rtt_ids(mem) -> int:
+    """Wipe every SEGGER RTT control block's ID left in RAM (RAM outlives a reboot): a console opened after the reboot
+    then finds only the block the new image writes, never the old one - whose offsets, written back while the new
+    image set them up again, lost its first lines. The core must be halted. -> how many were wiped."""
+    n, chunk = 0, 16 * 1024
+    for at in range(RAM, RAM_END, chunk):
+        words = mem.read_block(at, min(chunk, RAM_END - at) // 4)
+        raw = struct.pack(f"<{len(words)}I", *words)
+        i = raw.find(RTT_ID)
+        while i >= 0:
+            if i % 4 == 0:
+                mem.write32(at + i, 0)
+                n += 1
+            i = raw.find(RTT_ID, i + 1)
+    return n
+
+
+def flash(address: str, path: str, log=print) -> None:
+    """Write the image over SWD, verify it, reboot the chip. Raises on a mismatch."""
+    unit, port = parse(address)
+    image = image_of(path)
+    h = open_host(unit, f"rp2040 flash {port}")
+    try:
+        t = Target(h, port)
+        try:
+            t.core.halt()
+            t.core.reset_halt()                       # a clean core to call the ROM from
+            if not rp2040.program_and_verify(t.core, image, 0, log=log):
+                raise RuntimeError(f"{address}: the flash did not read back as written ({len(image)} B)")
+            log(f"{address}: {len(image)} B written and verified")
+            clear_rtt_ids(t.mem)
+            rp2040.Rom(t.core).reboot()
+        finally:
+            t.close()
+    finally:
+        try:
+            h.end()
+        finally:
+            h.link.close()
+
+
+class Rtt:
+    """SEGGER RTT's up buffer 0 (target -> host) and down buffer 0 (host -> target) through the MEM-AP, the core
+    running. The control block is found by its ID in RAM (it is written at run time; `wait` seconds for it)."""
+
+    def __init__(self, mem, wait: float = 5.0):
+        self.mem = mem
+        self.cb = self._find(wait)
+        nup, ndown = mem.read_block(self.cb + 16, 2)
+        self.up = self.cb + 24                        # aUp[0]: sName pBuffer SizeOfBuffer WrOff RdOff Flags
+        self.down = self.cb + 24 + 24 * nup           # aDown[0]
+        _, self.up_buf, self.up_size, _, _, _ = mem.read_block(self.up, 6)
+        _, self.down_buf, self.down_size, _, _, _ = mem.read_block(self.down, 6) if ndown else (0, 0, 0, 0, 0, 0)
+
+    def _find(self, wait: float) -> int:
+        deadline = time.monotonic() + wait
+        chunk = 16 * 1024
+        while True:
+            for at in range(RAM, RAM_END, chunk):
+                words = self.mem.read_block(at, min(chunk, RAM_END - at) // 4)
+                raw = struct.pack(f"<{len(words)}I", *words)
+                i = raw.find(RTT_ID)
+                while i >= 0:
+                    if i % 4 == 0:
+                        return at + i
+                    i = raw.find(RTT_ID, i + 1)
+            if time.monotonic() > deadline:
+                raise RuntimeError("no SEGGER RTT control block in RAM (is the sketch using RTT and running?)")
+            time.sleep(0.2)
+
+    def read(self) -> bytes:
+        wr, rd = self.mem.read_block(self.up + 12, 2)
+        if wr == rd or not self.up_size:
+            return b""
+        base = self.up_buf & ~3                       # the buffer need not be word aligned; block reads are
+        skew = self.up_buf - base
+        words = self.mem.read_block(base, (skew + self.up_size + 3) // 4)
+        buf = struct.pack(f"<{len(words)}I", *words)[skew:skew + self.up_size]
+        out = buf[rd:wr] if wr > rd else buf[rd:self.up_size] + buf[:wr]
+        self.mem.write32(self.up + 16, wr)
+        return out
+
+    def write(self, data: bytes) -> int:
+        if not self.down_size:
+            return 0
+        wr, rd = self.mem.read_block(self.down + 12, 2)
+        room = (rd - wr - 1) % self.down_size
+        data = data[:room]
+        for b in data:
+            at = self.down_buf + wr
+            word = self.mem.read32(at & ~3)
+            sh = 8 * (at & 3)
+            self.mem.write32(at & ~3, (word & ~(0xFF << sh)) | (b << sh))
+            wr = (wr + 1) % self.down_size
+        self.mem.write32(self.down + 12, wr)
+        return len(data)
+
+
+class Console:
+    """The peer's console: a session, the SWD connection and the RTT rings, polled in a thread into a buffer."""
+
+    POLL_S = 0.01
+
+    def __init__(self, address: str, wait: float = 10.0):
+        unit, port = parse(address)
+        self.address = address
+        self.host = open_host(unit, f"rp2040 console {port}")
+        self.target = Target(self.host, port)
+        self.rtt = Rtt(self.target.mem, wait)
+        self._buf = bytearray()
+        self._out = bytearray()
+        self._lock = threading.Lock()
+        self._stop = False
+        self.error: Exception | None = None
+        self._thread = threading.Thread(target=self._run, name="rp2040-rtt", daemon=True)
+        self._thread.start()
+
+    def _run(self) -> None:
+        last = time.monotonic()
+        while not self._stop:
+            try:
+                with self._lock:
+                    out, self._out = bytes(self._out), bytearray()
+                while out:
+                    n = self.rtt.write(out)
+                    out = out[n:]
+                    if out:
+                        time.sleep(self.POLL_S)
+                data = self.rtt.read()
+                if data:
+                    with self._lock:
+                        self._buf += data
+                if time.monotonic() - last > 5:       # the lease: polling is requests, but keep it explicit
+                    last = time.monotonic()
+            except Exception as e:                    # the console's end: kept for the reader to see
+                self.error = e
+                return
+            time.sleep(self.POLL_S)
+
+    def read(self, size: int = -1) -> bytes:
+        with self._lock:
+            n = len(self._buf) if size < 0 else min(size, len(self._buf))
+            data = bytes(self._buf[:n])
+            del self._buf[:n]
+        return data
+
+    def in_waiting(self) -> int:
+        with self._lock:
+            return len(self._buf)
+
+    def write(self, data: bytes) -> int:
+        with self._lock:
+            self._out += data
+        return len(data)
+
+    def close(self) -> None:
+        self._stop = True
+        self._thread.join(2)
+        self.target.close()
+        try:
+            self.host.end()
+        except Exception:
+            pass
+        close = getattr(getattr(self.host, "link", None), "close", None)
+        if close:
+            close()
+
+
+OPENOCD_TARGET = """# generated by oep_client.rp2040_peer.write_openocd_hook: arduino-pico's OpenOCD upload hands the ELF to the OEP
+# probe's SWD instead of a CMSIS-DAP (the address from the environment variable {env})
+rename init _oep_orig_init
+proc init {{}} {{}}
+rename adapter _oep_orig_adapter
+proc adapter {{args}} {{}}
+rename program _oep_orig_program
+proc program {{file args}} {{
+    if {{![info exists ::env({env})]}} {{ error "set {env} to the peer's oep://<probe>/<port>" }}
+    echo [exec {python} -m oep_client.rp2040_peer flash $::env({env}) $file 2>@1]
+}}
+proc reset {{args}} {{}}
+"""
+
+
+def write_openocd_hook(sketch_dir: str, env: str, python: str | None = None) -> list[str]:
+    """interface/cmsis-dap.cfg and target/rp2040.cfg in the peer's sketch directory (OpenOCD looks in its cwd, the
+    sketch directory, before its own scripts): they turn arduino-pico's `program` into `flash` here. Generated
+    files - keep them out of git. -> the paths written."""
+    python = python or sys.executable
+    out = []
+    for rel, text in (("interface/cmsis-dap.cfg", "# generated by oep_client.rp2040_peer: no adapter (target/rp2040.cfg flashes)\n"),
+                      ("target/rp2040.cfg", OPENOCD_TARGET.format(env=env, python=python))):
+        path = os.path.join(sketch_dir, rel)
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w") as f:
+            f.write(text)
+        out.append(path)
+    return out
+
+
+def main(argv=None) -> int:
+    import argparse
+    ap = argparse.ArgumentParser(prog="python -m oep_client.rp2040_peer", description=__doc__.split("\n\n")[0])
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    f = sub.add_parser("flash", help="write an image over SWD, verify, reboot")
+    f.add_argument("address")
+    f.add_argument("image")
+    c = sub.add_parser("console", help="print the RTT output")
+    c.add_argument("address")
+    c.add_argument("seconds", type=float, nargs="?", default=5.0)
+    a = ap.parse_args(argv)
+    if a.cmd == "flash":
+        try:
+            flash(a.address, a.image)
+        except Exception as e:
+            print(f"rp2040_peer flash: {e}", file=sys.stderr)
+            return 1
+        return 0
+    con = Console(a.address)
+    try:
+        t = time.monotonic()
+        while time.monotonic() - t < a.seconds:
+            data = con.read()
+            if data:
+                sys.stdout.write(data.decode(errors="replace"))
+                sys.stdout.flush()
+            if con.error:
+                raise con.error
+            time.sleep(0.05)
+    finally:
+        con.close()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())