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

oep_client/v1/riscv.py

@@ -0,0 +1,430 @@
+"""oep.wire.rvswd / oep.wire.swio and oep.target.riscv-dm, revision 1 (oep-spec oep-if-debug §1-§4).
+
+The host knows the target; the probe only moves wires and DMI. Everything chip-specific (flash controller, RAM loaders,
+register meanings) stays on this side.
+
+§5.4: wire and target results carry a status (ok, wait, line, fault, timeout, state; any other value is a failure). A
+request the probe ran but that did not get through is completed failed (nothing done) or partial (some done) with the
+success shape, so `done` and `status` say how far it went: this module raises TargetError with them.
+"""
+
+from __future__ import annotations
+
+import struct
+import time
+from dataclasses import dataclass, field
+
+from . import host as h, message as m, registry as reg
+from .core import Interface
+from .fixture import Gpio
+
+STATUS = reg.STATUS
+OK = STATUS["ok"]
+TIMEOUT = STATUS["timeout"]
+STATUS_NAMES = {v: k for k, v in STATUS.items()}
+_RV = reg.TARGET_RISCV_DM
+STEP = _RV.enum["dmi_step"]
+STEP_WRITE, STEP_READ, STEP_POLL_READS, STEP_WAIT_US, STEP_POLL_US = (
+    STEP["write"], STEP["read"], STEP["poll_reads"], STEP["wait_us"], STEP["poll_us"])
+STEP_SIZES = {STEP_WRITE: 6, STEP_READ: 2, STEP_POLL_READS: 12, STEP_WAIT_US: 5, STEP_POLL_US: 14}
+VALUE_STEPS = {STEP_READ, STEP_POLL_READS, STEP_POLL_US}      # steps that add a value to the result
+POLL_STEPS = {STEP_POLL_READS, STEP_POLL_US}                  # ... and add their last value when they time out
+REG_A0, REG_A1 = 0x100A, 0x100B
+
+
+def status_name(status: int) -> str:
+    return STATUS_NAMES.get(status, f"unknown status 0x{status:02x}")
+
+
+class TargetError(h.OepError):
+    """A wire or target operation that did not get through: `status` (§5.4), `done` (steps / words completed, where
+    the op has it), `values` (what it did read), `result` (the probe's answer)."""
+
+    def __init__(self, what: str, status: int, result: m.Result | None = None, done: int | None = None,
+                 values: list[int] | None = None, data: bytes = b""):
+        at = f" after {done}" if done is not None else ""
+        outcome = f" ({result.describe()})" if result is not None else ""
+        super().__init__(f"{what} stopped{at}: {status_name(status)}{outcome}")
+        self.status, self.result, self.done, self.values, self.data = status, result, done, values or [], data
+
+
+def ran(result: m.Result) -> m.Reader:
+    """The payload of a result the probe ran (success, failed or partial: all in the success shape); an unknown
+    resolution or outcome raises Failed (§0)."""
+    if not result.ran:
+        raise h.Failed(result)
+    return m.Reader(result.payload)
+
+
+def check(what: str, result: m.Result, status: int, **kw) -> None:
+    """Success needs outcome success AND status ok; anything else (an unknown status included) raises."""
+    if status != OK or not result.succeeded:
+        raise TargetError(what, status, result, **kw)
+
+
+@dataclass
+class Found:
+    kind: int
+    pins: tuple[int, int]
+    dmstatus: int
+
+
+class WireBase(Interface):
+    """oep.wire.<link>: scan / attach / detach. The shared part; each link's attach takes its own arguments."""
+    SCAN, ATTACH, DETACH, ATTACH_UNDER_RESET = 0x01, 0x02, 0x03, 0x04
+    REVISION = 1
+    TAG_MAX_SPEED = 0x01
+    TAG_PINS = 0x03          # swdio(u16) swclk(u16, 0xFFFF on one wire), critical (oep-if-debug §1)
+
+    def scan(self, pairs: list[tuple[int, int]] | None = None) -> list[Found]:
+        """Try `pairs` of (swdio, swclk); None = every pair the probe allows (describe's channel_group /
+        role_channels). A pair the probe does not allow refuses the whole scan (rejected unavailable). The probe stops
+        when its answer would not fit one frame and says how many pairs it tried; the rest go again (oep-if-debug §1)."""
+        pairs = list(pairs or [])
+        out = []
+        while True:
+            body = bytes([len(pairs)]) + b"".join(struct.pack("<HH", d, c) for d, c in pairs)
+            rd = m.Reader(self._call(self.SCAN, body).payload)
+            tried, count = rd.take("BB")
+            for _ in range(count):
+                kind, dio, clk, status = rd.take("BHHI")
+                out.append(Found(kind, (dio, clk), status))
+            rd.tail()
+            if not pairs or tried >= len(pairs) or tried == 0:
+                return out
+            pairs = pairs[tried:]
+
+    def detach(self, conn: int) -> None:
+        self._call(self.DETACH, struct.pack("<H", conn))
+
+    def _speed_tlv(self, max_speed: int | None) -> bytes:
+        # critical: a probe that cannot keep to a ceiling must refuse, not ignore it (§0: safety arguments)
+        return b"" if max_speed is None else m.tlv(self.TAG_MAX_SPEED, struct.pack("<I", max_speed), critical=True)
+
+    def _pins_tlv(self, pins: tuple[int, int] | None) -> bytes:
+        # the pair to attach on (a scan result's .pins); None: the probe's only pair
+        return b"" if pins is None else m.tlv(self.TAG_PINS, struct.pack("<HH", *pins), critical=True)
+
+
+class Wire(WireBase):
+    """oep.wire.rvswd / oep.wire.swio (CH32 debug links to a RISC-V debug module)."""
+    NAME = "oep.wire.rvswd"
+    DEFAULT_RESET = 0xFFFF
+    RUN, HALT = reg.WIRE_RVSWD.enum["attach_method"]["run"], reg.WIRE_RVSWD.enum["attach_method"]["halt"]
+    TAG_TARGET_ID = reg.WIRE_RVSWD.tlv["attach_answer"]["target_id"]
+    SCHEME_WCH_DMI_7F = reg.WIRE_RVSWD.enum["target_id_scheme"]["wch_dmi_7f"]
+
+    def __init__(self, hst: h.Host, name: str = "oep.wire.rvswd"):
+        super().__init__(hst, name)
+        self.had_reset = self.existing = False
+        self.speed_hz = 0
+        self.ignored: list[int] = []
+        self.target_id: tuple[int, bytes] | None = None   # (scheme, value) the last attach read, or None
+
+    def _take_target_id(self, tail: m.Tail) -> None:
+        v = tail.get(self.TAG_TARGET_ID)
+        self.target_id = (v[0], bytes(v[1:])) if v else None
+
+    def attach(self, halt: bool = True, max_speed: int | None = None, pins: tuple[int, int] | None = None) -> tuple[int, int]:
+        """-> (connection, DMSTATUS). Attaching an attached wire returns its connection as it is (self.existing).
+        self.had_reset: a pending havereset was acknowledged first (a V00x's DMSTATUS halt / run bits stay frozen
+        until then); self.speed_hz: the speed the probe chose; max_speed: a ceiling the probe must keep (critical);
+        self.target_id: (scheme, value) of the target's identity when the probe could read one (oep-if-debug §1)."""
+        body = bytes([self.HALT if halt else self.RUN]) + self._speed_tlv(max_speed) + self._pins_tlv(pins)
+        rd = m.Reader(self._call(self.ATTACH, body).payload)
+        conn, status, flags, self.speed_hz = rd.take("HIBI")
+        self.had_reset, self.existing = bool(flags & 1), bool(flags & 2)
+        tail = rd.tail()
+        self.ignored = tail.ignored
+        self._take_target_id(tail)
+        return conn, status
+
+    def attach_under_reset(self, channel: int | None = None, hold_ms: int = 20,
+                           max_speed: int | None = None, pins: tuple[int, int] | None = None) -> tuple[int, int]:
+        """Hold the target in reset through `channel` (None: the probe's default reset line), attach, release and
+        halt it at once - the way back from firmware that turns the debug pins into GPIOs. -> (connection, dpc)"""
+        body = (struct.pack("<HH", self.DEFAULT_RESET if channel is None else channel, hold_ms) + self._speed_tlv(max_speed)
+                + self._pins_tlv(pins))
+        rd = m.Reader(self._call(self.ATTACH_UNDER_RESET, body).payload)
+        conn, dpc, self.speed_hz = rd.take("HII")
+        self._take_target_id(rd.tail())
+        return conn, dpc
+
+    def find_reset_line(self, candidates: list[int], reset_vector: int = 0, hold_ms: int = 20,
+                        tries: int = 3) -> list[int]:
+        """Which of `candidates` resets the target: attach under reset through each, and see where the hart stops.
+        The real line stops it before its first instruction (dpc = reset_vector); any other channel leaves the
+        target running, so the halt lands somewhere in its code. A channel counts once any of `tries` lands on the
+        vector: the CH32L103 is caught by polling right after the release (it keeps no haltreq through NRST), which
+        misses now and then (1 in 60 after the probe fix of 2026-09-24), while landing on the vector by chance is
+        not a worry. Channels the probe does not allow (rejected) are skipped; a failed attach
+        counts as a miss and is tried again. Each try pulls one channel
+        low (open drain) for hold_ms. The target is left running (or halted, where resume is not acknowledged)."""
+        hits = []
+        self.last_search = {}   # channel -> list of dpc values (None: attach failed), or the rejection
+        for channel in candidates:
+            seen = []
+            for _ in range(tries):
+                try:
+                    conn, dpc = self.attach_under_reset(channel, hold_ms)
+                except h.Rejected as e:                    # not a channel this probe allows
+                    seen = e
+                    break
+                except h.Failed:
+                    seen.append(None)                      # the attach itself failed: try again
+                    continue
+                seen.append(dpc)
+                dm = RiscvDm(self.host, conn)
+                try:
+                    if dpc == reset_vector:
+                        # Leave the vector for real: a hart left halted there reads dpc = vector again through the
+                        # next, wrong channel (2026-09-24: a CH32L103 whose resume was not acknowledged made the
+                        # channel after NRST a false hit). A reset-and-run always gets it going.
+                        dm.reset(confirm=True)
+                    else:
+                        dm.resume()
+                except h.OepError:
+                    pass   # a CH32L103 raises no allresumeack; a hart left halted mid-code still lands off the vector
+                finally:
+                    self.detach(conn)
+                if dpc == reset_vector:
+                    hits.append(channel)
+                    break
+            self.last_search[channel] = seen
+        return hits
+
+
+class StepListError(TargetError):
+    """A DMI step list that stopped early: `done` = the failed step's index, `values` = what it did read."""
+
+    def __init__(self, done: int, status: int, values: list[int], result: m.Result | None = None):
+        super().__init__("step list", status, result, done=done, values=values)
+
+
+@dataclass
+class RunResult:
+    status: int
+    stopped: bool                 # the hart halted on its own (ebreak) before timeout_ms
+    dpc: int
+    elapsed_us: int
+    values: list[int] = field(default_factory=list)   # the registers asked for in `outs`, in order
+
+
+def count_steps(steps: bytes) -> list[int]:
+    """The kinds of a packed step list, in order (so the count and the value rule need no bookkeeping by callers)."""
+    kinds, at = [], 0
+    while at < len(steps):
+        kind = steps[at]
+        if kind not in STEP_SIZES:
+            raise ValueError(f"DMI step kind 0x{kind:02x} at byte {at} is not one this client knows")
+        kinds.append(kind)
+        at += STEP_SIZES[kind]
+    if at != len(steps):
+        raise ValueError("the step list ends inside a step")
+    return kinds
+
+
+def dmi_value_count(kinds: list[int], done: int, status: int) -> int:
+    """§5.5: the reads and polls among the first `done` steps, plus the failed step's last value when it is a poll
+    that timed out (a poll whose read failed on the line adds nothing)."""
+    n = sum(k in VALUE_STEPS for k in kinds[:done])
+    if status == TIMEOUT and done < len(kinds) and kinds[done] in POLL_STEPS:
+        n += 1
+    return n
+
+
+class RiscvDm(Interface):
+    """oep.target.riscv-dm on one connection (every request starts with the connection, u16)."""
+    NAME = "oep.target.riscv-dm"
+    REVISION = 1
+    DMI, HALT, RESUME, RESET, READ_BLOCK, WRITE_BLOCK, RUN, STEP = (
+        _RV.op[k] for k in ("dmi", "halt", "resume", "reset", "read_block", "write_block", "run", "step"))
+    RESET_RUN, RESET_RUN_CONFIRM, RESET_HALT = (_RV.enum["reset_mode"][k] for k in ("run", "run_verified", "halt_at_reset"))
+    METHOD_DEFAULT, METHOD_NDMRESET, METHOD_SYSTEM = (_RV.enum["reset_method"][k]
+                                                      for k in ("probe_default", "ndmreset", "system_reset"))
+    TAG_RESET_METHOD = _RV.tlv["reset"]["method"]
+    NO_TIMEOUT = 0xFFFFFFFF
+
+    def __init__(self, hst: h.Host, conn: int, name: str = "oep.target.riscv-dm"):
+        super().__init__(hst, name, prefix=struct.pack("<H", conn))
+        self.conn = conn
+
+    def _status_only(self, what: str, op: int) -> None:
+        r = self._request(op)
+        rd = ran(r)
+        status = rd.u8()
+        rd.tail()
+        check(what, r, status)
+
+    def halt(self) -> None:
+        """Idempotent: an already halted hart is ok."""
+        self._status_only("halt", self.HALT)
+
+    def resume(self) -> None:
+        """One resumereq; ok = the hart left debug mode (status state if the probe saw it not go). Parts that need more
+        (the CH32 rule) are the host's: ch32_flash.resume."""
+        self._status_only("resume", self.RESUME)
+
+    DPC = 0x07B1
+
+    def read_register(self, regno: int) -> int:
+        """A GPR / CSR of the halted hart through an abstract command (access register, 32 bits) in plain DMI steps, so
+        any probe with dmi does it. A cmderr is cleared, then raised."""
+        _, values = self.dmi([self.step_write(0x17, 0x00220000 | regno), self.step_poll(0x16, 1 << 12, 0, 100),
+                              self.step_read(0x04)])
+        cs, data0 = values[0], values[1]
+        if (cs >> 8) & 7:
+            self.dmi([self.step_write(0x16, 0x700)])
+            raise RuntimeError(f"abstract command for register {regno:#x} failed (cmderr {(cs >> 8) & 7})")
+        return data0
+
+    def _reset(self, mode: int, method: int | None) -> tuple[int, int, int]:
+        body = bytes([mode])
+        if method is not None:
+            body += m.tlv(self.TAG_RESET_METHOD, bytes([method]), critical=True)
+        r = self._request(self.RESET, body)
+        rd = ran(r)
+        status, flags, attempts, pc = rd.take("BBBI")
+        rd.tail()
+        check("reset", r, status)
+        return flags, attempts, pc
+
+    def reset(self, confirm: bool = True, method: int | None = None) -> tuple[int, int, int]:
+        """Reset and let it run (confirm: seen running). method: METHOD_* (critical; None: the probe chooses).
+        -> (flags, attempts, pc)"""
+        return self._reset(self.RESET_RUN_CONFIRM if confirm else self.RESET_RUN, method)
+
+    def reset_halt(self, method: int | None = None) -> int:
+        """Reset and stop before the first instruction (haltreq held through the reset). -> dpc"""
+        return self._reset(self.RESET_HALT, method)[2]
+
+    def step(self) -> tuple[bool, int, int]:
+        """One instruction (dcsr.step, one resume, privilege kept). -> (moved, dpc before, dpc after)"""
+        r = self._request(self.STEP)
+        rd = ran(r)
+        status, moved, before, after = rd.take("BBII")
+        rd.tail()
+        check("step", r, status)
+        return bool(moved), before, after
+
+    def read_block(self, address: int, count: int) -> bytes:
+        """`count` words from `address`. A read that stopped raises TargetError (.data = the words it did read)."""
+        r = self._request(self.READ_BLOCK, struct.pack("<IH", address, count))
+        data, done, status = self.read_block_result(r)
+        if status != OK or not r.succeeded or done != count:
+            raise TargetError("read_block", status, r, done=done, data=data)
+        return data
+
+    @staticmethod
+    def read_block_result(r: m.Result) -> tuple[bytes, int, int]:
+        """-> (the words read as bytes, done, status)."""
+        rd = ran(r)
+        done, status = rd.take("HB")
+        data = rd.bytes(4 * done)
+        rd.tail()
+        return data, done, status
+
+    @staticmethod
+    def write_block_body(address: int, data: bytes) -> bytes:
+        if len(data) % 4:
+            raise ValueError("write_block writes whole words")
+        return struct.pack("<IH", address, len(data) // 4) + data
+
+    def write_block(self, address: int, data: bytes) -> None:
+        r = self._request(self.WRITE_BLOCK, self.write_block_body(address, data))
+        rd = ran(r)
+        done, status = rd.take("HB")
+        rd.tail()
+        check("write_block", r, status, done=done)
+
+    def write32(self, address: int, value: int) -> None:
+        self.write_block(address, struct.pack("<I", value))
+
+    def read32(self, address: int) -> int:
+        return struct.unpack("<I", self.read_block(address, 1))[0]
+
+    @classmethod
+    def run_body(cls, pc: int, regs: list[tuple[int, int]], timeout_ms: int | None = 200,
+                 outs: tuple[int, ...] = (REG_A0,)) -> bytes:
+        """pc, timeout_ms (None: no limit), the registers to set, then the registers to read back (`outs`)."""
+        t = cls.NO_TIMEOUT if timeout_ms is None else timeout_ms
+        return (struct.pack("<IIB", pc, t, len(regs)) + b"".join(struct.pack("<HI", r, v) for r, v in regs)
+                + struct.pack("<B", len(outs)) + b"".join(struct.pack("<H", r) for r in outs))
+
+    @staticmethod
+    def run_result(result: m.Result, n_out: int = 1) -> RunResult:
+        """Decode a run result (any known outcome) without judging it."""
+        rd = ran(result)
+        status, stopped, dpc, us = rd.take("BBII")
+        values = rd.words(n_out)
+        rd.tail()
+        return RunResult(status, bool(stopped), dpc, us, values)
+
+    def run(self, pc: int, regs: list[tuple[int, int]], timeout_ms: int | None = 200,
+            outs: tuple[int, ...] = (REG_A0,)) -> RunResult:
+        """Set registers and dpc (dcsr.ebreakm, prv = M), resume, wait for the hart's own ebreak (forced halt at the
+        timeout: stopped False, status timeout - returned, not raised). Other statuses raise TargetError."""
+        r = self._request(self.RUN, self.run_body(pc, regs, timeout_ms, outs))
+        res = self.run_result(r, len(outs))
+        if res.status == STATUS["timeout"] and not res.stopped:
+            return res
+        check("run", r, res.status)
+        return res
+
+    def dmi(self, steps: bytes | list[bytes]) -> tuple[int, list[int]]:
+        """Run a step list (the step_* builders, concatenated or as a list). -> (steps done, values: one per read and
+        poll step). A list that stopped early raises StepListError (with what it did read): a caller cannot mistake
+        an unfinished poll for a met one."""
+        raw = b"".join(steps) if isinstance(steps, list) else steps
+        kinds = count_steps(raw)
+        r = self._request(self.DMI, struct.pack("<H", len(kinds)) + raw)
+        rd = ran(r)
+        done, status = rd.take("HB")
+        values = rd.words(dmi_value_count(kinds, done, status))
+        rd.tail()
+        if status != OK or not r.succeeded or done != len(kinds):
+            raise StepListError(done, status, values, r)
+        return done, values
+
+    @staticmethod
+    def step_write(address: int, value: int) -> bytes:
+        return struct.pack("<BBI", STEP_WRITE, address, value)
+
+    @staticmethod
+    def step_read(address: int) -> bytes:
+        return struct.pack("<BB", STEP_READ, address)
+
+    @staticmethod
+    def step_poll(address: int, mask: int, value: int, max_reads: int) -> bytes:
+        """Read until (value & mask) == value, at most max_reads times; adds the last value read (met or not)."""
+        return struct.pack("<BBIIH", STEP_POLL_READS, address, mask, value, max_reads)
+
+    @staticmethod
+    def step_delay(us: int) -> bytes:
+        return struct.pack("<BI", STEP_WAIT_US, us)
+
+    @staticmethod
+    def step_poll_time(address: int, mask: int, value: int, max_us: int) -> bytes:
+        """poll bounded by time rather than reads: the same meaning on a slow bit-banged link and a fast one."""
+        return struct.pack("<BBIII", STEP_POLL_US, address, mask, value, max_us)
+
+
+def attach_after_gpio_reset(hst: h.Host, wire_: Wire, gpio_fn: int, channel: int, exchange=None, *, tries: int = 10,
+                            low_s: float = 0.02) -> tuple[int, int]:
+    """For a probe without attach_under_reset: pull `channel` low through oep.fixture.gpio, then send its release
+    and an attach (halt) in one exchange so the probe starts the attach right after the release, and retry - a race
+    at the edge of the target's reset window (2026-09-24, CH32V003 with SWIO turned off: 2 of 5 pipelined, 0 of 5
+    one request at a time). `exchange` is the link's pipelining exchange (default: the host's). -> (connection, DMSTATUS)"""
+    gpio = Gpio(hst, gpio_fn)
+    last = None
+    for _ in range(tries):
+        gpio.pull_low(channel)
+        time.sleep(low_s)
+        release, last = hst.pipeline([gpio.request_release(channel), wire_.request(Wire.ATTACH, bytes([Wire.HALT]))],
+                                     exchange=exchange)
+        if not release.succeeded:
+            raise h.Failed(release)                       # never leave the reset line held
+        if last.succeeded:
+            conn, status = m.Reader(last.payload).take("HI")
+            return conn, status
+    raise h.Failed(last) if last is not None else ValueError("tries must be at least 1")

oep_client/v1/rp2350.py

@@ -0,0 +1,85 @@
+"""RP2350 target knowledge for the host: its boot ROM's function table and the ROM-driven flash sequence (the
+pico-sdk's hardware_flash order), run on the halted core through CortexM.call. The probe knows none of this.
+
+Measured 2026-09-24 through an RP2040-Zero OEP probe (bit-bang SWD, 500 ns half period) on a Pro Micro RP2350:
+98 KiB erased in 0.3 s, programmed in 3.0 s, verified (fast-XIP read) in 2.0 s; ROM reboot re-enumerates the USB.
+"""
+
+from __future__ import annotations
+
+import struct
+import time
+
+from .arm import CortexM
+
+FLASH_XIP = 0x10000000
+SECTOR, BLOCK, BLOCK_ERASE_CMD, PAGE = 4096, 65536, 0xD8, 256
+RT_FLAG_FUNC_ARM_SEC = 0x0004
+TABLE_LOOKUP_PTR = 0x16          # halfword in the ROM: rom_table_lookup(code, mask) (Arm, RP2350)
+# RAM the target can spare while the host drives it (main SRAM ends at 0x20082000): the return breakpoint, the data
+# buffer for programming, and the stack the ROM functions run on. Whatever ran before is restarted afterwards.
+BKPT_AT, BUF, BUF_BYTES, STACK_TOP = 0x20040000, 0x20041000, 16 * 1024, 0x20080000
+
+
+def code(a: str, b: str) -> int:
+    return ord(a) | ord(b) << 8
+
+
+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:
+            word = self.core.mem.read32(TABLE_LOOKUP_PTR & ~3)
+            lookup = (word >> (8 * (TABLE_LOOKUP_PTR & 3))) & 0xFFFF
+            addr = self.core.call(lookup, (code(*c), RT_FLAG_FUNC_ARM_SEC))
+            if not 0 < addr < 0x8000:
+                raise LookupError(f"ROM has no function {c!r} (lookup returned {addr:#x})")
+            self._fn[c] = addr
+        return self._fn[c]
+
+    def reboot(self, delay_ms: int = 10) -> None:
+        """reboot(flags=0: normal boot, delay_ms, 0, 0): a whole-chip reboot, so the USB device re-enumerates. The core
+        is let go into it with interrupts enabled (its handlers are in flash, readable again by now)."""
+        self.core.prepare_call(self.lookup("RB"), (0, delay_ms, 0, 0))
+        self.core.release()
+
+
+class Flash:
+    def __init__(self, core: CortexM):
+        self.core, self.rom = core, Rom(core)
+
+    def program(self, offset: int, data: bytes, log=lambda s: None) -> bytes:
+        """Erase and program at flash `offset` (sector aligned). Leaves the flash in command-XIP mode: reads through
+        0x10000000+ work (slowly) for verification; a reboot restores the fast mode. Returns the page-padded image."""
+        if offset % SECTOR:
+            raise ValueError("offset must be a multiple of the 4 KiB sector")
+        data = data + b"\xff" * (-len(data) % PAGE)
+        erase = len(data) + (-len(data) % SECTOR)
+        fn = {c: self.rom.lookup(c) for c in ("IF", "EX", "RE", "RP", "FC", "CX")}
+        t0 = time.monotonic()
+        self.core.call(fn["IF"])                                                # connect_internal_flash
+        self.core.call(fn["EX"])                                                # flash_exit_xip
+        self.core.call(fn["RE"], (offset, erase, BLOCK, BLOCK_ERASE_CMD), timeout=120)   # flash_range_erase
+        t1 = time.monotonic()
+        for at in range(0, len(data), BUF_BYTES):
+            chunk = data[at:at + BUF_BYTES]
+            self.core.mem.write_block(BUF, list(struct.unpack(f"<{len(chunk) // 4}I", chunk)))
+            self.core.call(fn["RP"], (offset + at, BUF, len(chunk)), timeout=30)   # flash_range_program
+        t2 = time.monotonic()
+        self.core.call(fn["FC"])                                                # flash_flush_cache
+        self.core.call(fn["CX"])                                                # flash_enter_cmd_xip
+        log(f"erased {erase} B in {t1 - t0:.2f} s, programmed {len(data)} B in {t2 - t1:.2f} s")
+        return data
+
+    def read(self, offset: int, length: int) -> bytes:
+        words = self.core.mem.read_block(FLASH_XIP + offset, (length + 3) // 4)
+        return struct.pack(f"<{len(words)}I", *words)[:length]
+
+
+def program_and_verify(core: CortexM, image: bytes, offset: int = 0, log=lambda s: None) -> bool:
+    flash = Flash(core)
+    padded = flash.program(offset, image, log)
+    return flash.read(offset, len(padded)) == padded

oep_client/v1/target.py

@@ -0,0 +1,16 @@
+"""The v1 client API in one place, for callers written against the first draft (oep_smoke, the experiments).
+
+New code can import the modules directly: core (finding interfaces, the plan), riscv (oep.wire.rvswd / swio,
+oep.target.riscv-dm), console (oep.target.console), fixture (gpio / uart), capture (oep.fixture.capture), arm
+(oep.wire.swd, oep.target.arm-adi).
+"""
+
+from .capture import LogicCapture  # noqa: F401
+from .console import MARK_NAMES, Console, ConsoleIO, Mark, StreamIO  # noqa: F401
+from .core import (OP_PLAN_APPLY, OP_PLAN_RELEASE, Interface, UnsupportedRevision, confirm, find,  # noqa: F401
+                   find_all, plan_apply, plan_release, probe_labels)
+from .fixture import FixtureUart, FixtureUartIO, Gpio  # noqa: F401
+from .host import Failed, NoConnection, NotV1, OepError, Rejected, Unsupported  # noqa: F401
+from .riscv import (Found, RiscvDm, RunResult, StepListError, TargetError, Wire, WireBase,  # noqa: F401
+                    attach_after_gpio_reset, ran)
+from . import host as h  # noqa: F401  (callers use target.h.Rejected)

oep_client/v1/uiapduino.py

@@ -0,0 +1,121 @@
+"""UIAPduino (CH32V003) bootloader entry and return to user mode, from the host with v1 draft parts only.
+
+The knowledge that used to sit in the v0 probe (target.control reset modes 1 and 2) lives here now: two RAM
+payloads (wch-protocols E129 / E130, assembled for the V003) that the V003's own CPU runs, because the same
+registers written from a halted debug session do not take (E127). The probe only moves a gpio line, writes RAM and
+walks DMI steps (oep-spec capability-name-hierarchy.ja.md: NRST is a labelled gpio channel, not a capability).
+
+  enter_bootloader: the bootloader stays only when RCC_RSTSCKR.PINRSTF is set (E161). Read it first: if a pin
+                    reset's flag is still there (nobody wrote RMVF since), go in over SWIO alone; otherwise pulse
+                    NRST when the jig has it wired, or say what is needed. Then attach halted, place PREPARE_BOOT and
+                    resume into it with mstatus = 0 -> HID 1209:b803 in about a second.
+                    Only an external NRST pulse sets PINRSTF on the V003: not the IWDG, the WWDG, a software reset,
+                    nor the target driving its own PD7 low while the reset function owns the pad (measured
+                    2026-09-24, oep-spec experiments/v003-reset-flags); power-on leaves it 0 per the RM.
+  normalize_user:   the same with NORMALIZE_USER (clears BOOT_MODE) and no pin pulse
+"""
+
+from __future__ import annotations
+
+import struct
+import time
+
+from . import host as h, target
+from .fixture import Gpio
+
+GPIO_OPEN_DRAIN_LOW, GPIO_OPEN_DRAIN_RELEASE = Gpio.OPEN_DRAIN_LOW, Gpio.OPEN_DRAIN_RELEASE   # for older scripts
+
+PAYLOAD_BASE = 0x20000000
+RSTSCKR, PINRSTF = 0x40021024, 1 << 26
+DMCONTROL, ABSTRACTCS, COMMAND, DATA0 = 0x10, 0x16, 0x17, 0x04
+MSTATUS, DPC = 0x0300, 0x07B1
+
+# kNormalizeUserReset: unlock FLASH, clear BOOT_MODE, PFIC SYSRST
+NORMALIZE_USER = [
+    0x400222b7, 0x00428293, 0x45670337, 0x12330313, 0x0062a023, 0xcdef9337,
+    0x9ab30313, 0x0062a023, 0x400222b7, 0x02428293, 0x45670337, 0x12330313,
+    0x0062a023, 0xcdef9337, 0x9ab30313, 0x0062a023, 0x400222b7, 0x02828293,
+    0x45670337, 0x12330313, 0x0062a023, 0xcdef9337, 0x9ab30313, 0x0062a023,
+    0x400222b7, 0x00c28293, 0x0002a303, 0xffffc3b7, 0xfff38393, 0x00737333,
+    0x0062a023, 0xe000e2b7, 0x04828293, 0xbeef0337, 0x08030313, 0x0062a023,
+    0x0000006f,
+]
+# kPrepareBootAndReset: unlock, set BOOT_MODE, PD4 (software USB D-) low for a detach window, PFIC SYSRST
+PREPARE_BOOT = [
+    0x400222b7, 0x00428293, 0x45670337, 0x12330313, 0x0062a023, 0xcdef9337,
+    0x9ab30313, 0x0062a023, 0x400222b7, 0x02428293, 0x45670337, 0x12330313,
+    0x0062a023, 0xcdef9337, 0x9ab30313, 0x0062a023, 0x400222b7, 0x02828293,
+    0x45670337, 0x12330313, 0x0062a023, 0xcdef9337, 0x9ab30313, 0x0062a023,
+    0x400222b7, 0x00c28293, 0x0002a303, 0xffffc3b7, 0xfff38393, 0x00737333,
+    0x000043b7, 0x00736333, 0x0062a023, 0x400212b7, 0x01828293, 0x0002a303,
+    0x02036313, 0x0062a023, 0x400112b7, 0x40028293, 0x0002a303, 0xfff103b7,
+    0xfff38393, 0x00737333, 0x000303b7, 0x00736333, 0x0062a023, 0x400112b7,
+    0x41428293, 0x01000313, 0x0062a023, 0x004c52b7, 0xb4028293, 0xfff28293,
+    0xfe029ee3, 0xe000e2b7, 0x04828293, 0xbeef0337, 0x08030313, 0x0062a023,
+    0x0000006f,
+]
+
+
+def _write_register(dm: target.RiscvDm, regno: int, value: int) -> bytes:
+    """DMI steps of one abstract-command register write (aarsize 32, transfer, write), then wait for it."""
+    return (dm.step_write(DATA0, value) + dm.step_write(COMMAND, 0x00230000 | regno)
+            + dm.step_poll(ABSTRACTCS, 1 << 12, 0, 100))
+
+
+def run_payload(hst: h.Host, wire: target.Wire, payload: list[int]) -> None:
+    """Attach halted, place the payload, resume into it with interrupts off, and let go of the target."""
+    conn, _ = wire.attach(halt=True)
+    try:
+        dm = target.RiscvDm(hst, conn)
+        data = struct.pack(f"<{len(payload)}I", *payload)
+        dm.write_block(PAYLOAD_BASE, data)
+        if dm.read_block(PAYLOAD_BASE, len(payload)) != data:
+            raise RuntimeError("payload did not read back")
+        # mstatus = 0 first: with MIE set the halted application's SysTick ran over the payload (2026-09-22).
+        # resumereq twice, then drop haltreq so the payload's own system reset is not halted again (E129).
+        # dmi() raises if an abstract-command poll gave up, so a register write that did not land stops here.
+        steps = (_write_register(dm, MSTATUS, 0) + _write_register(dm, DPC, PAYLOAD_BASE)
+                 + dm.step_write(DMCONTROL, 0x40000001) + dm.step_write(DMCONTROL, 0x40000001)
+                 + dm.step_write(DMCONTROL, 0x00000001))
+        dm.dmi(steps)
+        time.sleep(0.02)
+    finally:
+        wire.detach(conn)
+
+
+def pulse_nrst(hst: h.Host, gpio_fn: int, channel: int, low_s: float = 0.02) -> None:
+    """Open-drain low, then released to Hi-Z (never driven high). This drops any debug connection."""
+    Gpio(hst, gpio_fn).pulse_low(channel, low_s)
+
+
+class NeedsPinReset(RuntimeError):
+    pass
+
+
+def pin_reset_flag(hst: h.Host, wire: target.Wire) -> bool:
+    conn, _ = wire.attach(halt=True)
+    dm = target.RiscvDm(hst, conn)
+    try:
+        return bool(dm.read32(RSTSCKR) & PINRSTF)
+    finally:
+        dm.resume()
+        wire.detach(conn)
+
+
+def enter_bootloader(hst: h.Host, wire: target.Wire, gpio_fn: int | None = None,
+                     nrst_channel: int | None = None) -> str:
+    """-> "swio" (a pin reset's flag was still set) or "nrst" (pulsed). Raises NeedsPinReset otherwise."""
+    how = "swio"
+    if not pin_reset_flag(hst, wire):
+        if gpio_fn is None or nrst_channel is None:
+            raise NeedsPinReset("PINRSTF is clear and no NRST line was given: press the board's reset or "
+                                "power-cycle it (without the sketch clearing the flags), then try again")
+        pulse_nrst(hst, gpio_fn, nrst_channel)
+        time.sleep(0.3)
+        how = "nrst"
+    run_payload(hst, wire, PREPARE_BOOT)
+    return how
+
+
+def normalize_user(hst: h.Host, wire: target.Wire) -> None:
+    run_payload(hst, wire, NORMALIZE_USER)