oep-client-python 0.0.1__py3-none-any.whl

oep_client/v1/ch32_flash.py

@@ -0,0 +1,254 @@
+"""CH32 flash programming from the host with v1 draft parts (oep-spec experiments/flash-primitives F4 / F5).
+
+The probe knows nothing about flash: the host places a RAM loader, block-writes each chunk into a RAM buffer and
+runs the loader until its ebreak (oep.target.riscv-dm), then reads everything back. Pages that fail or read back
+wrong are written again, up to twice (a DMI transfer is garbled now and then).
+
+  fast-page  CH32X035 / CH32L103 (QingKe V4, 256-byte fast page programming). Loader: oep-spec
+             experiments/flash-primitives/x035_loader.S at 0x20000000; a0 = page, a1 = buffer; ebreak at +0xb0.
+  v003-wlink CH32V003 (QingKe V2, 64-byte pages). The wlink RAM loader (MIT / Apache-2.0) at 0x20000000; a0 = flags
+             (bit0 unlock, bit1 mass erase, bit2 page erase, bit3 program, bit4 verify), a1 = address, a2 = bytes;
+             ebreak at +0x15c. One mass erase, then program-only runs, as WCH-LinkE does.
+"""
+
+from __future__ import annotations
+
+import struct
+import time
+from dataclasses import dataclass, field
+
+from . import host as h, riscv, target
+
+# oep-spec experiments/flash-primitives/x035_loader.S, assembled at 0x20000000 (riscv32-esp-elf binutils)
+FAST_PAGE_LOADER = bytes.fromhex(
+    "b72202403703020023a8620023aaa2001363030423a86200"
+    "83a3c20013fe1300e31c0efe13fe030163160e0823a80200"
+    "3703010023a86200b70e0800b3ee6e0023a8d20183a3c200"
+    "13fe1300e31c0efeb70e0400b3ee6e00130f0500930f0510"
+    "83a3050023207f0023a8d20183a3c20013fe1300e31c0efe"
+    "93854500130f4f00e310ffff23a8620023aaa200936e0304"
+    "23a8d20183a3c20013fe1300e31c0efe13fe030163180e00"
+    "23a80200130500007300100023a802003705008033657500"
+    "73001000"
+)
+# oep-probe-arduino src/OepCh32Dm.cpp kV003FlashLoader (from ch32-rs/wlink), little endian
+V003_LOADER = bytes.fromhex(
+    "111122cc26ca02c89377150099cfb7066745b72702409386"
+    "36123797efcdd4c31307b79ad8c3d4d3d8d3937725009dc7"
+    "b7270240984bad66373300401367470098cb984b9386a6aa"
+    "1367070498cbd847058b63160710984b6d9b98cb93774500"
+    "a9cb9307f60399832ec02d6381763ec4b7320040b7270240"
+    "1303a3aafd16984bb70302003367770098cb0247d8cb984b"
+    "1367070498cbd847058b69e7984b758f98cb024713070704"
+    "3ac022477d173ac479f793778500f1cf9307f6032ec09983"
+    "372702403ec41c4bc1662d63d58f1ccb3707002013070720"
+    "b7270240b7030800b73200401303a3aa944bb3e6760094cb"
+    "d447858af5fe8246ba843704040036c2c14636c692468440"
+    "110784c2944bc18e94cbd447858ab1ea9246ba84910636c2"
+    "b246fd1636c6f9fe8246d4cb944b93e6060494cbd447858a"
+    "85eed447c18a85ced847b706f3fffd1613670701d8c7984b"
+    "2145758f98cb6244d244710102902320d300f5b523a06200"
+    "3db723a0620055b723a06200c1b782469386060436c0a246"
+    "fd1636c4b5f2984bb706f3fffd16758f98cb418919e10145"
+    "7dbf2ec00d0602c40982b707002032c69387072094431387"
+    "4700a24702468a07b2979c436399f602a24782468a07b697"
+    "9443c247b6973ec8a24785073ec42246b246ba87e368d6fc"
+    "b707002003a70761c247e306f7fa41459db7ffff"
+)
+
+
+@dataclass(frozen=True)
+class FlashProfile:
+    method: str            # "fast-page" or "v003-wlink"
+    base: int = 0x08000000
+    size: int = 0          # bytes of flash
+    page: int = 256
+
+
+PROFILES = {
+    "x035": FlashProfile("fast-page", size=63488, page=256),
+    "l103": FlashProfile("fast-page", size=65536, page=256),
+    "v003": FlashProfile("v003-wlink", size=16384, page=64),
+}
+
+
+@dataclass
+class ProgramResult:
+    bytes: int
+    verified: bool
+    rewritten_pages: int = 0
+    failures: list = field(default_factory=list)
+    timings: dict = field(default_factory=dict)
+
+    def as_dict(self) -> dict:
+        return {"bytes": self.bytes, "verified": self.verified, "rewritten_pages": self.rewritten_pages,
+                "failures": self.failures[:5], "timings_seconds": self.timings}
+
+
+KEYR, CTLR, MODEKEYR = 0x40022004, 0x40022010, 0x40022024
+LOCK, FLOCK = 1 << 7, 1 << 15
+LOADER, FAST_BUFFER, FAST_DONE = 0x20000000, 0x20000400, 0x200000B0
+V003_INPUT, V003_STACK, V003_EBREAK, V003_RUN = 0x20000200, 0x20000800, 0x2000015C, 1024
+
+
+def _block_size(hst: h.Host) -> int:
+    info = target.confirm(hst)
+    # request header 6 + session 4 + connection 1 + address 4 + count 2 (the read answer's 5 + done 2 + status 1 is
+    # smaller); a little slack for the result header
+    return (info["max_frame"] - 5 - 6 - 4 - 1 - 4 - 2) // 4 * 4
+
+
+def _write_requests(dm: target.RiscvDm, address: int, data: bytes, block: int) -> list[tuple[int, int, bytes]]:
+    return [dm.request(dm.WRITE_BLOCK, dm.write_block_body(address + off, data[off:off + block]))
+            for off in range(0, len(data), block)]
+
+
+def _write_ok(r) -> bool:
+    """A write_block result that wrote every word: outcome success and status ok (§5.4)."""
+    if not r.succeeded:
+        return False
+    try:
+        rd = target.ran(r)
+        rd.u16()
+        return rd.u8() == riscv.OK
+    except h.OepError:
+        return False
+
+
+def _write(dm: target.RiscvDm, address: int, data: bytes, block: int) -> None:
+    for r in dm.host.pipeline_calls(_write_requests(dm, address, data, block)):
+        if not _write_ok(r):
+            raise riscv.TargetError("write_block", target.ran(r).take("HB")[1], r)
+
+
+def _read(dm: target.RiscvDm, address: int, length: int, block: int) -> bytes:
+    """Read back in blocks, pipelined when the host has the link's exchange (reads are independent)."""
+    spans = [(address + off, min(block, length - off) // 4) for off in range(0, length, block)]
+    out = b""
+    for (a, n), r in zip(spans, dm.host.pipeline_calls([dm.request(dm.READ_BLOCK, struct.pack("<IH", a, n))
+                                                         for a, n in spans])):
+        data, done, status = dm.read_block_result(r)
+        if status != riscv.OK or done != n:
+            raise riscv.TargetError("read_block", status, r, done=done, data=data)
+        out += data
+    return out
+
+
+PIPELINE_PAGES = 16   # pages per pipelined batch: enough to keep the link busy, small enough to show progress
+
+
+def program(hst: h.Host, dm: target.RiscvDm, image: bytes, profile: FlashProfile) -> ProgramResult:
+    """Program `image` at profile.base on a halted, attached target (dm), verify by reading back."""
+    image = image + b"\xff" * (-len(image) % profile.page)
+    if profile.size and len(image) > profile.size:
+        raise ValueError(f"image of {len(image)} bytes exceeds {profile.size}")
+    block = _block_size(hst)
+    t = {}
+    t0 = time.perf_counter()
+    if profile.method == "fast-page":
+        loader = FAST_PAGE_LOADER
+        if dm.read32(CTLR) & (LOCK | FLOCK):
+            for reg in (KEYR, MODEKEYR):
+                dm.write32(reg, 0x45670123)
+                dm.write32(reg, 0xCDEF89AB)
+            if dm.read32(CTLR) & (LOCK | FLOCK):
+                raise RuntimeError(f"the flash controller stayed locked (CTLR {dm.read32(CTLR):#x})")
+    elif profile.method == "v003-wlink":
+        loader = V003_LOADER
+    else:
+        raise ValueError(f"unknown flash method {profile.method!r}")
+    loader = loader + b"\0" * (-len(loader) % 4)
+
+    def place_loader() -> None:
+        # Read it back before it runs: a garbled loader is the worst garbling there is - it drives the flash
+        # controller, still reaches its ebreak, and writes wrong data into every page after it (the CH32L103's
+        # RP2350 probe, 2026-09-24: 38 pages rewritten, none right). A probe's ack proves nothing about content.
+        for _ in range(3):
+            _write(dm, LOADER, loader, block)
+            if _read(dm, LOADER, len(loader), block) == loader:
+                return
+        raise RuntimeError("the RAM loader did not read back after three tries")
+
+    place_loader()
+
+    def page_job(off: int, length: int, flags: int) -> tuple[list, tuple[int, int, bytes], int]:
+        """The requests for one page (buffer writes, then the loader run) and the dpc that means success."""
+        if profile.method == "fast-page":
+            writes = _write_requests(dm, FAST_BUFFER, image[off:off + profile.page], block)
+            run = dm.request(dm.RUN, dm.run_body(LOADER, [(0x100A, profile.base + off), (0x100B, FAST_BUFFER),
+                                                          (0x0300, 0)], outs=(riscv.REG_A0,)))
+            return writes, run, FAST_DONE
+        writes = _write_requests(dm, V003_INPUT, image[off:off + length], block)
+        run = dm.request(dm.RUN, dm.run_body(LOADER, [(0x100A, flags), (0x100B, profile.base + off), (0x100C, length),
+                                                      (0x1002, V003_STACK), (0x0300, 0)], timeout_ms=1000,
+                                                     outs=(riscv.REG_A0,)))
+        return writes, run, V003_EBREAK
+
+    def run_pages(jobs: list[tuple[int, int, int]]) -> list[dict]:
+        """Pipelined in batches: the probe runs requests in order, so each page's buffer writes land before its
+        run. A page whose write or run did not work is reported; the read-back catches anything else."""
+        failures = []
+        for at in range(0, len(jobs), PIPELINE_PAGES):
+            batch = [page_job(*job) for job in jobs[at:at + PIPELINE_PAGES]]
+            reqs = [r for writes, run, _ in batch for r in writes + [run]]
+            results = iter(hst.pipeline(reqs))
+            for (off, _, _), (writes, _, done_pc) in zip(jobs[at:at + PIPELINE_PAGES], batch):
+                wrote = all([_write_ok(next(results)) for _ in writes])
+                r = next(results)
+                if not (wrote and r.ran):
+                    failures.append({"address": hex(profile.base + off), "dpc": None})
+                    continue
+                run = dm.run_result(r, 1)
+                a0 = run.values[0]
+                if not (r.succeeded and run.status == riscv.OK and run.stopped and run.dpc == done_pc
+                        and (profile.method != "fast-page" or a0 == 0)):
+                    failures.append({"address": hex(profile.base + off), "dpc": hex(run.dpc)})
+        return failures
+
+    if profile.method == "fast-page":
+        failures = run_pages([(off, profile.page, 0) for off in range(0, len(image), profile.page)])
+    else:
+        for _ in range(3):   # unlock + mass erase; a stop at the loader's first instruction never ran (the probe
+            # does not re-issue a run, oep-if-debug §4.4 - erasing twice is harmless, so the host asks again)
+            run = dm.run(LOADER, [(0x100A, 0x03), (0x100B, profile.base), (0x100C, 0),
+                                  (0x1002, V003_STACK), (0x0300, 0)], timeout_ms=1000)
+            if not (run.stopped and run.dpc == LOADER):
+                break
+        if not (run.stopped and run.dpc == V003_EBREAK):
+            raise RuntimeError(f"mass erase did not stop on the loader's ebreak (dpc {run.dpc:#x})")
+        failures = run_pages([(off, min(V003_RUN, len(image) - off), 0x09) for off in range(0, len(image), V003_RUN)])
+    t["program"] = round(time.perf_counter() - t0, 3)
+    t0 = time.perf_counter()
+    back = _read(dm, profile.base, len(image), block)
+    t["verify"] = round(time.perf_counter() - t0, 3)
+    rewritten = 0
+    for _ in range(2):
+        bad = sorted({int(f["address"], 16) - profile.base for f in failures} |
+                     {off for off in range(0, len(image), profile.page)
+                      if back[off:off + profile.page] != image[off:off + profile.page]})
+        if not bad:
+            break
+        place_loader()   # the pages came out wrong: the loader itself may have been hit, place it again
+        rewritten += len(bad)
+        failures = run_pages([(off - off % profile.page, profile.page, 0x1D) for off in bad])
+        back = _read(dm, profile.base, len(image), block)
+    return ProgramResult(len(image), back == image, rewritten, failures, t)
+
+
+def resume(dm: riscv.RiscvDm, tries: int = 8) -> bool:
+    """resume for a CH32 - the host's knowledge, not the probe's (oep-if-debug §4.2): a CH32V006 now and then misses a
+    resumereq, and a CH32L103 never raises allresumeack, so a hart that stops again at once (a breakpoint ahead) looks
+    as if it never went. So: resume; when the probe saw it not go, read dpc - moved means it ran and stopped again,
+    unchanged means ask again. -> True once it went. The hart must be halted first; a breakpoint on the instruction
+    dpc points at cannot be told from not running, so step off it first."""
+    before = dm.read_register(dm.DPC)
+    for _ in range(tries):
+        try:
+            dm.resume()
+            return True
+        except riscv.TargetError as e:
+            if e.status != riscv.STATUS["state"]:
+                raise
+        if dm.read_register(dm.DPC) != before:
+            return True
+    return False

oep_client/v1/cobs.py

@@ -0,0 +1,73 @@
+"""Serial-port framing (oep-core §3.1): message + CRC-16 little endian, COBS-encoded, sent as 0x00 <COBS> 0x00.
+
+CRC-16/CCITT-FALSE: poly 0x1021, init 0xFFFF, no reflection, no final xor ("123456789" -> 0x29B1).
+Mirrors oep-probe-arduino OepFrame (CobsReader / writeCobsFrame).
+"""
+
+from __future__ import annotations
+
+
+class CorruptFrame(ValueError):
+    pass
+
+
+def crc16(data: bytes, crc: int = 0xFFFF) -> int:
+    for b in data:
+        crc ^= b << 8
+        for _ in range(8):
+            crc = ((crc << 1) ^ 0x1021) & 0xFFFF if crc & 0x8000 else (crc << 1) & 0xFFFF
+    return crc
+
+
+def encode(data: bytes) -> bytes:
+    """Standard COBS (no delimiter): blocks of length+1 and up to 254 non-zero bytes; a full block implies no
+    zero. When the data ends right after a full block no empty block follows (oep-core §3.1: the sender leaves it
+    out, a receiver takes both forms)."""
+    out = bytearray()
+    i, n = 0, len(data)
+    while True:
+        j = i
+        while j < n and data[j] != 0 and j - i < 254:
+            j += 1
+        code = j - i + 1
+        out.append(code)
+        out += data[i:j]
+        if j >= n:
+            return bytes(out)
+        if code == 0xFF:
+            i = j
+            continue
+        i = j + 1
+
+
+def decode(raw: bytes) -> bytes:
+    out = bytearray()
+    i, n = 0, len(raw)
+    while i < n:
+        code = raw[i]
+        i += 1
+        if code == 0 or i + code - 1 > n:
+            raise CorruptFrame("COBS block runs past the frame")
+        out += raw[i:i + code - 1]
+        i += code - 1
+        if code != 0xFF and i < n:
+            out.append(0)
+    return bytes(out)
+
+
+def frame(message: bytes) -> bytes:
+    """0x00 <COBS(message + CRC)> 0x00: the leading delimiter too, so a receiver that saw raw bytes before starts
+    the frame clean (oep-core §3.1, §3.4)."""
+    crc = crc16(message)
+    return b"\x00" + encode(message + bytes([crc & 0xFF, crc >> 8])) + b"\x00"
+
+
+def unframe(raw: bytes) -> bytes:
+    """raw: the bytes between two delimiters (without the 0x00)."""
+    data = decode(raw)
+    if len(data) < 3:
+        raise CorruptFrame("frame shorter than a message and its CRC")
+    body, got = data[:-2], data[-2] | data[-1] << 8
+    if crc16(body) != got:
+        raise CorruptFrame("CRC mismatch")
+    return body

oep_client/v1/console.py

@@ -0,0 +1,165 @@
+"""oep.target.console revision 1: the target's console as a position stream on a debug connection (oep-spec
+oep-if-console, oep-if-common §1), and ConsoleIO, the same as a plain byte stream.
+
+The position streams of oep.target.console and oep.fixture.uart share their read / marks / clear / mark / write
+operations (same numbers and meanings; the UART has no stream byte): `PositionStream` holds them, `prefix` is the
+stream byte or nothing.
+"""
+
+from __future__ import annotations
+
+import struct
+import time
+from dataclasses import dataclass
+
+from . import host as h, message as m, registry as reg
+from .core import Interface
+
+_CON = reg.TARGET_CONSOLE
+
+
+@dataclass
+class Mark:
+    serial: int          # per stream, wraps (u32): marks are read on by serial
+    position: int
+    kind: int
+    time_ms: int         # probe uptime in ms (u32, wraps after ~49.7 days)
+    detail: int
+
+
+MARK_NAMES = {v: k.replace("_", "-") for k, v in _CON.enum["mark_kind"].items()}
+
+
+@dataclass
+class Chunk:
+    start: int
+    more: bool
+    gap: bool
+    data: bytes
+
+    def __iter__(self):                      # (start, more, gap, data), as the first version returned
+        return iter((self.start, self.more, self.gap, self.data))
+
+
+class PositionStream(Interface):
+    """read / marks / clear / mark / write of a position stream (console §5.7, fixture.uart §5.8)."""
+    READ, MARKS, CLEAR, MARK, WRITE = (_CON.op[k] for k in ("read", "marks", "clear", "mark", "write"))
+    FROM_POSITION, FROM_OLDEST, FROM_NOW, FROM_MARK = (_CON.enum["read_from"][k]
+                                                       for k in ("position", "oldest", "now", "last_mark"))
+
+    def _stream_prefix(self) -> bytes:
+        return b""
+
+    def read(self, start: int = FROM_OLDEST, arg: int = 0, maximum: int = 1000) -> Chunk:
+        """-> Chunk(start position, more, gap, data). start: FROM_* ; arg: a position or a mark kind (0: any).
+        Lock-free; reading does not consume."""
+        p = self._call(self.READ, self._stream_prefix() + struct.pack("<BQH", start, arg, maximum), locked=False).payload
+        rd = m.Reader(p)
+        pos, flags = rd.take("QB")
+        return Chunk(pos, bool(flags & 1), bool(flags & 2), rd.rest())   # data ends the result: no tail (§0)
+
+    def read_from(self, position: int, maximum: int = 1000) -> Chunk:
+        return self.read(self.FROM_POSITION, position, maximum)
+
+    def marks_page(self, from_serial: int = 0) -> tuple[list[Mark], bool]:
+        """One answer's marks with serial >= from_serial (in serial order). -> (marks, more)."""
+        rd = m.Reader(self._call(self.MARKS, self._stream_prefix() + struct.pack("<I", from_serial), locked=False).payload)
+        more, count = rd.take("BB")
+        marks = [Mark(*rd.take("IQBIB")) for _ in range(count)]
+        rd.tail()
+        return marks, bool(more)
+
+    def marks(self, from_serial: int = 0) -> list[Mark]:
+        """Every mark from `from_serial` on, following `more` (no mark lost or repeated when several share a position)."""
+        out: list[Mark] = []
+        while True:
+            page, more = self.marks_page(from_serial)
+            out += page
+            if not more or not page:
+                return out
+            from_serial = (page[-1].serial + 1) & 0xFFFFFFFF
+
+    def clear(self) -> None:
+        self._call(self.CLEAR, self._stream_prefix())
+
+    def mark(self, value: int) -> None:
+        """A host mark (kind host, detail = value)."""
+        self._call(self.MARK, self._stream_prefix() + bytes([value]))
+
+    def write(self, data: bytes) -> int:
+        """-> bytes accepted (the probe does not buffer; fewer than asked is completed partial, not an error)."""
+        r = self._request(self.WRITE, self._stream_prefix() + struct.pack("<H", len(data)) + data)
+        if r.resolution != m.COMPLETED or r.detail not in (m.SUCCESS, m.PARTIAL):
+            raise h.Failed(r)
+        rd = m.Reader(r.payload)
+        accepted = rd.u16()
+        rd.tail()
+        return accepted
+
+
+class Console(PositionStream):
+    """oep.target.console: streams on a debug connection, one per (connection, mechanism); reads and marks need no
+    lock. A stream whose connection is lost is closed with a link-lost mark and stays readable until the next open."""
+    NAME = "oep.target.console"
+    REVISION = 1
+    OPEN, CLOSE = _CON.op["open"], _CON.op["close"]
+    SDI, DMDATA, DMSEQ = (_CON.enum["mechanism"][k] for k in ("sdi", "dmdata", "dmseq"))
+
+    def __init__(self, hst: h.Host, name: str = "oep.target.console"):
+        super().__init__(hst, name)
+        self.stream = 1
+        self.existing = False
+
+    def _stream_prefix(self) -> bytes:
+        return struct.pack("<H", self.stream)
+
+    def open(self, conn: int, mechanism: int = DMSEQ) -> int:
+        """-> the stream. An open stream of the same (connection, mechanism) comes back as it is (self.existing):
+        position and marks carry on. An unknown mechanism is rejected unsupported."""
+        rd = m.Reader(self._call(self.OPEN, struct.pack("<HB", conn, mechanism)).payload)
+        self.stream, flags = rd.take("HB")
+        self.existing = bool(flags & 1)
+        rd.tail()
+        return self.stream
+
+    def close(self) -> None:
+        self._call(self.CLOSE, struct.pack("<H", self.stream))
+
+
+class StreamIO:
+    """A position stream read from a position onwards, as a plain byte stream (console or fixture UART)."""
+    MAX_READ, MAX_WRITE = 1000, 64
+
+    def __init__(self, source: PositionStream, start: int | None = None):
+        self.source = source
+        self.position = source.read(PositionStream.FROM_NOW, 0, 0).start if start is None else start
+        self.lost = 0
+
+    def _limits(self) -> tuple[int, int]:
+        """(read, write) chunk sizes that fit the probe's frame: request header 6 + session 4 + stream 1 + count 2,
+        result header 5 + start 8 + flags 1."""
+        frame = self.source.host.confirmed()["max_frame"]
+        return max(1, min(self.MAX_READ, frame - 14)), max(1, min(self.MAX_WRITE, frame - 13))
+
+    def read(self, n: int = 512) -> bytes:
+        c = self.source.read_from(self.position, min(n, self._limits()[0]))
+        if c.gap:
+            self.lost += c.start - self.position   # u64 positions: no wrap
+        self.position = c.start + len(c.data)
+        return c.data
+
+    def write(self, data: bytes) -> None:
+        chunk = self._limits()[1]
+        while data:
+            took = self.source.write(data[:chunk])
+            data = data[took:]
+            if not took:
+                time.sleep(0.005)   # the target has not taken the last chunk yet
+
+
+class ConsoleIO(StreamIO):
+    """A console stream read from a position onwards (default: from now), as a plain byte stream."""
+
+    def __init__(self, console: Console, start: int | None = None):
+        super().__init__(console, start)
+        self.console = console

oep_client/v1/core.py

@@ -0,0 +1,172 @@
+"""The probe's core (fn 0) as the other clients need it: finding interfaces by name, confirm, the probe's own labels,
+the pin plan - and `Interface`, the base every interface client shares (its fn, its revision checked against the list
+entry, and calls that raise unless they worked)."""
+
+from __future__ import annotations
+
+import struct
+
+from . import catalog, host as h, message as m, registry as reg
+
+OP_PLAN_APPLY, OP_PLAN_RELEASE = m.OP_PLAN_APPLY, m.OP_PLAN_RELEASE
+TAG_ROLE_ASSIGNMENT = reg.CORE.tlv["plan_apply"]["role_assignment"]     # already critical (0x90)
+CORE_LABEL = reg.CORE.tlv["describe"]["label"]
+CORE_TRANSPORT = reg.CORE.tlv["describe"]["transport"]
+TRANSPORT_KIND = reg.CORE.enum["transport_kind"]
+SERIAL_KINDS = {TRANSPORT_KIND["uart_bridge"], TRANSPORT_KIND["usb_cdc"], TRANSPORT_KIND["usb_serial_jtag"]}
+
+
+class UnsupportedRevision(h.OepError):
+    """The probe offers the interface in a revision whose payload shapes this client does not speak (oep-core §2.7:
+    a host never uses an interface revision it does not know)."""
+
+
+def list_entries(hst: h.Host, name: str = "", exact: bool = False) -> list[catalog.ListEntry]:
+    """Every list entry under `name` (exact: that name only), paged by first (u16). The fn -> revision of each is
+    remembered on the host."""
+    entries: list[catalog.ListEntry] = []
+    while True:
+        total, page = catalog.unpack_list_result(
+            hst.request(m.CORE_FN, m.OP_LIST, catalog.pack_list_request(name, exact, len(entries)), locked=False).payload)
+        entries += page
+        if not page or len(entries) >= total:    # an empty page ends it too: no endless loop on a short answer
+            break
+    for e in entries:
+        hst._revisions[e.fn] = e.revision
+    return entries
+
+
+def find_all(hst: h.Host, name: str) -> list[int]:
+    """fns of every interface with exactly this name (instances of the same kind, e.g. two UARTs)."""
+    return [e.fn for e in list_entries(hst, name, True)]
+
+
+def find(hst: h.Host, name: str) -> int:
+    """fn of the first interface with exactly this name. Cached on the host until the probe reboots (boot_id), so
+    building a client per connection costs no list request."""
+    fn = hst._fns.get(name)
+    if fn is None:
+        fns = find_all(hst, name)
+        if not fns:
+            raise LookupError(f"probe does not offer {name}")
+        fn = hst._fns[name] = fns[0]
+    return fn
+
+
+def revision(hst: h.Host, name: str, fn: int) -> int:
+    """The list entry's revision of interface `fn` (asked by name when not known yet)."""
+    if fn not in hst._revisions:
+        list_entries(hst, name, True)
+    if fn not in hst._revisions:
+        raise LookupError(f"probe lists no {name} at fn {fn}")
+    return hst._revisions[fn]
+
+
+def confirm(hst: h.Host) -> dict:
+    """The probe's limits (asked once per host): revision, flags, max_frame, window (u32), max_inflight."""
+    return hst.confirmed()
+
+
+def describe(hst: h.Host, fn: int = 0) -> list[tuple[int, bytes]]:
+    """Every describe TLV of `fn` (0: the probe itself), paged by first."""
+    data, first = b"", 0
+    while True:
+        p = hst.request(m.CORE_FN, m.OP_DESCRIBE, catalog.pack_describe_request(fn, first), locked=False).payload
+        more, chunk = m.Reader(p).u8(), p[1:]
+        data += chunk
+        first += len(catalog.split_tlv(chunk))
+        if not more or not chunk:
+            break
+    return catalog.split_tlv(data)
+
+
+def probe_labels(hst: h.Host) -> dict[str, int]:
+    """Channel labels the probe declares in oep.core's describe (tag 0x46): {"NRST": 23, ...}."""
+    return {value[2:].decode("ascii", "replace"): struct.unpack_from("<H", value)[0]
+            for tag, value in describe(hst) if tag & 0x7F == CORE_LABEL and len(value) >= 2}
+
+
+def transports(hst: h.Host) -> list[tuple[int, int, int]]:
+    """The probe's transports from oep.core's describe (core §7.5): [(index, kind, usb interface or 0xFF)]."""
+    return [(v[0], v[1], v[2] if len(v) > 2 else 0xFF) for tag, v in describe(hst) if tag & 0x7F == CORE_TRANSPORT
+            and len(v) >= 2]
+
+
+def take(hst: h.Host, lease_ms: int = 3000, *, owner: str | None = None, wait_s: float = 5.0,
+         force: bool = False) -> h.Opened:
+    """Take the lock as host guide §2 says: when the probe's only transport is a serial port and this host opened it
+    exclusively, the previous holder cannot be there any more - force at once; otherwise wait out the holder's lease
+    (up to wait_s), and name it (InUse) if it keeps it going. force: the user asked for it."""
+    link = getattr(hst, "link", None)
+    ways = transports(hst)
+    only = len(ways) == 1 and ways[0][1] in SERIAL_KINDS and getattr(link, "framing", None) == "cobs" \
+        and getattr(link, "transport", None) == "serial"
+    return hst.take(lease_ms, owner=owner, only_way_in=only, wait_s=wait_s, force=force)
+
+
+def plan_apply(hst: h.Host, assignments: list[tuple[int, int, int]]) -> None:
+    """assignments: (fn, role, channel). The fns named get these plans, every other fn keeps its own (oep-core §8);
+    all interfaces accept their roles or nothing changes. The plan is the
+    session's resource: kept over an explicit end, released at a lease lapse or a force takeover (oep-core §9)."""
+    tlv = b"".join(bytes([TAG_ROLE_ASSIGNMENT, 5]) + struct.pack("<HBH", fn, role, ch) for fn, role, ch in assignments)
+    hst.call(m.CORE_FN, OP_PLAN_APPLY, tlv)
+
+
+def plan_release(hst: h.Host, fns: list[int] | tuple[int, ...] = ()) -> None:
+    """Release the plan of these fns (none: every fn, oep-core §8)."""
+    hst.call(m.CORE_FN, OP_PLAN_RELEASE, bytes([len(fns)]) + b"".join(struct.pack("<H", f) for f in fns))
+
+
+class Interface:
+    """One interface client: its fn (found by name, cached), and calls that raise Rejected / Failed unless the probe
+    says it worked. `prefix` goes in front of every payload (the connection byte of a target interface).
+    REVISION: the interface revision whose shapes the class speaks; the list entry must say the same (None: any)."""
+
+    NAME = ""
+    REVISION: int | None = None
+
+    def __init__(self, hst: h.Host, name: str | None = None, prefix: bytes = b"", fn: int | None = None):
+        self.host = hst
+        self.name = name or self.NAME
+        self.fn = fn if fn is not None else find(hst, self.name)
+        self.prefix = prefix
+        if self.REVISION is not None:
+            rev = revision(hst, self.name, self.fn)
+            if rev != self.REVISION:
+                raise UnsupportedRevision(f"{self.name} (fn {self.fn}) is revision {rev} on this probe; this client "
+                                          f"speaks revision {self.REVISION} only")
+
+    def _call(self, op: int, body: bytes = b"", *, locked: bool = True) -> m.Result:
+        return self.host.call(self.fn, op, self.prefix + body, locked=locked)
+
+    def _request(self, op: int, body: bytes = b"", *, locked: bool = True) -> m.Result:
+        """Rejections raise; completed results of any outcome come back for the caller to decode."""
+        return self.host.request(self.fn, op, self.prefix + body, locked=locked)
+
+    def request(self, op: int, body: bytes = b"") -> tuple[int, int, bytes]:
+        """The raw (fn, op, payload) of one operation, for Host.pipeline / pipeline_calls."""
+        return self.fn, op, self.prefix + body
+
+
+LINK_SOURCE, LINK_SINK = m.OP_LINK_SOURCE, m.OP_LINK_SINK   # core, lock-free
+
+
+def link_speed(hst: h.Host, *, size: int | None = None, inflight: int | None = None, seconds: float = 1.0) -> dict:
+    """The link's request/response throughput both ways, as a repeat read or a write sees it: `inflight` requests of
+    `size` bytes kept going in batches for `seconds` (defaults: one full frame, the probe's in-flight limit).
+    -> {"in_mb_s", "out_mb_s", "size", "inflight"} (in = probe to host)."""
+    import time
+    limits = confirm(hst)
+    size = size or limits["max_frame"] - 16
+    inflight = min(inflight or limits["max_inflight"], limits["max_inflight"])
+    first = hst.call(m.CORE_FN, LINK_SOURCE, struct.pack("<I", size), locked=False).payload
+    if len(first) != size or any(b != (k & 0xFF) for k, b in enumerate(first[:256])):
+        raise h.ProtocolError(f"link_source answered {len(first)} bytes, not the {size} asked (or a wrong pattern)")
+    out = {"size": size, "inflight": inflight}
+    for key, op, body in (("in_mb_s", LINK_SOURCE, struct.pack("<I", size)), ("out_mb_s", LINK_SINK, bytes(size))):
+        moved, t0 = 0, time.perf_counter()
+        while time.perf_counter() - t0 < seconds:
+            for r in hst.pipeline_calls([(m.CORE_FN, op, body)] * inflight, locked=False):
+                moved += len(r.payload) if op == LINK_SOURCE else m.Reader(r.payload).u32()
+        out[key] = moved / (time.perf_counter() - t0) / 1e6
+    return out