oep-client-python 0.0.1__tar.gz

oep_client_python-0.0.1/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+.pytest_cache/
+*.egg-info/
+build/
+dist/

oep_client_python-0.0.1/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog / 変更履歴
+
+## Unreleased
+
+## 0.0.1
+- (EN) First beta on PyPI (`pip install oep-client-python`, imported as `oep_client`). OEP v1 host: serial ports always COBS with the probe's raw bytes skipped as noise and opened exclusively (TIOCEXCL), USB vendor bulk / HID and TCP (a broker) with length frames, all under one `Host` (`link.open_host(target)`); the session rules (owner, resend with the same corr, `core.take` for the lock); the standard interfaces; `Host.on_capture` for run recorders; a fake probe (`oep_client.v1.endpoint`) and `python -m oep_client.v1.fake_serve` (pty / TCP) as the working spec for other hosts' tests.
+- (JA) PyPI での最初のβ版（`pip install oep-client-python`、import は `oep_client`）。OEP v1 の host: シリアルの口は常に COBS（probe の生のバイトは雑音として捨てる、排他で開く TIOCEXCL）、USB の vendor bulk / HID と TCP（ブローカー）は長さつきのフレームで、どれも同じ `Host`（`link.open_host(target)`）。セッションの規則（owner、同じ corr での送り直し、ロックの取り方 `core.take`）、標準インターフェース、記録の受け口 `Host.on_capture`。ほかの host の試験のための「動く spec」として、偽の probe（`oep_client.v1.endpoint`）と `python -m oep_client.v1.fake_serve`（pty / TCP）。

oep_client_python-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Open Embedded Probe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oep_client_python-0.0.1/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: oep-client-python
+Version: 0.0.1
+Summary: Open Embedded Probe (OEP) v1 host: serial / USB / TCP transports, the session rules, the standard interfaces, and a fake probe
+Project-URL: Homepage, https://github.com/Open-Embedded-Probe/oep-client-python
+Project-URL: Repository, https://github.com/Open-Embedded-Probe/oep-client-python
+Author: TANAKA Masayuki
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: pyserial>=3.5
+Requires-Dist: pyusb>=1.3
+Provides-Extra: hid
+Requires-Dist: hidapi>=0.14; extra == 'hid'
+Provides-Extra: usb-async
+Requires-Dist: libusb1>=3; extra == 'usb-async'
+Description-Content-Type: text/markdown
+
+# OEP Python client
+
+Open Embedded Probe の host 側。v1（oep-spec の `docs/oep-core.ja.md` と `docs/oep-if-*.ja.md`、固める候補の形）を話す。番号は oep-spec の
+`generated/oep-v1/oep_v1_registry.py` をそのまま写した `oep_client.v1.registry` から取る。破壊的変更を前提とする
+実験段階で、互換 API は約束しない。OEP を初めて読む人は oep-spec の `docs/review-guide.ja.md`（どこに何が書いてあるか）から。
+
+target の知識は host にある、という OEP の分担に従う。probe は線と DMI / DP・AP の転送しか知らず、CH32 の flash
+コントローラ、RAM ローダー、RP2350 の boot ROM、Cortex-M の debug レジスタなどはここに置く。
+
+```sh
+pip install oep-client-python     # PyPI (import oep_client); a checkout: pip install -e <checkout>
+uv run pytest                                                            # in a checkout
+```
+
+`import oep_client.v1` だけで使える（`sys.path` に `src/` を足す使い方は不要になった）。番号の表は `tools/sync_registry.sh` で
+oep-spec から写す。PyPI の `oep-client` は別のプロジェクトなので、配布名は `oep-client-python`。
+
+リリースは GitHub Actions の Release（workflow_dispatch、version = X.Y.Z か X.Y.ZbN）: `tools/prepare_release.py` が
+pyproject.toml と `oep_client.__version__` を書き換え、CHANGELOG.md の Unreleased をその版にし、試験と build の後に commit と tag、
+GitHub Release、PyPI（Trusted Publishing）へ出す。変更は CHANGELOG.md の Unreleased に (EN) / (JA) で書き足しておく。
+
+## モジュール（`oep_client.v1`）
+
+| モジュール | 中身 |
+|---|---|
+| `host` | 要求と結果、session_id とロック、`call()`（失敗なら例外）、pipeline、エラーの階層（`OepError` / `Rejected` / `Failed`） |
+| `link` | transport: シリアルの口（常に COBS + CRC、`0x00 <COBS> 0x00`、フレームの外は雑音として捨てる、排他で開く）、USB vendor bulk / HID と TCP（長さつきフレーム、§5.1 の立て直し）、corr による照合と送り直し、`open_host(target)` |
+| `core` | インターフェースを名前で探す（キャッシュつき）、confirm、probe の describe（ラベル、transport の一覧）、ロックの取り方（`take`）、ピンの割り当て（plan）、`Interface` の土台 |
+| `riscv` | `oep.wire.rvswd` / `oep.wire.swio`、`oep.target.riscv-dm`、リセット線の探索、GPIO 経由の attach |
+| `console` | `oep.target.console`（位置つきのストリーム）と、バイト列として読む `ConsoleIO` |
+| `fixture` | `oep.fixture.gpio` / `uart`（revision 1） |
+| `capture` | `oep.fixture.capture`（revision 1、oep-spec の oep-if-capture）。読んだ区画は `Host.on_capture` の callback に `CaptureRecord` で渡る（記録の受け口。wireskein には依存しない） |
+| `esp32_targets` | 独自インターフェース `io.github.ch32-riscv-ug.esp32.i2c-target` / `spi-target`（oep-probe-arduino の ESP32 の I2C / SPI の target） |
+| `decode` | キャプチャのチャネルの復号（I2C） |
+| `registry` | oep-spec の番号の表から生成したモジュール（編集しない。oep-spec から写し直す） |
+| `arm` | `oep.wire.swd`、`oep.target.arm-adi`、MEM-AP、Cortex-M の停止と関数呼び出し |
+| `ch32_flash` | CH32 の書き込み（RAM ローダー、ページ単位の書き直し） |
+| `rp2350` | RP2350 の boot ROM 経由の flash と reboot |
+| `uiapduino` | UIAPduino のブートローダへの出入り |
+| `catalog` / `names` / `interfaces` / `dump` | 能力の一覧と describe の形、表示 |
+| `fake` / `endpoint` / `fake_serial` / `fake_serve` | 偽の probe（下の「偽の probe」） |
+| `target` | 上の主なものを 1 か所から import する入口（最初の版に合わせて書いた呼び出し側のため） |
+
+## 使い方の例
+
+```python
+from oep_client.v1 import core, link, riscv, ch32_flash
+
+hst = link.open_host("/run/board-identify/by-id/esp32-series-30eda0e31108")   # pipelining つき
+# a serial port (always COBS), "tcp://127.0.0.1:PORT" (a broker), "usb" / "usb:303a:0002[:SERIAL]" (vendor, then HID)
+core.take(hst, 30000, owner="flash script")   # the only way in: force; else wait out the lease, name the holder
+wire = riscv.Wire(hst, "oep.wire.rvswd")
+conn, _ = wire.attach(halt=True)
+dm = riscv.RiscvDm(hst, conn)
+dm.reset_halt()
+result = ch32_flash.program(hst, dm, open("sketch.bin", "rb").read(), ch32_flash.PROFILES["x035"])
+dm.reset(confirm=True)
+wire.detach(conn)
+hst.end()
+```
+
+能力の一覧は `uv run python -m oep_client.v1 dump --port <probe>`（`--fake p4-x035` でハードウェアなし）。
+実機での一通りの確認は ArduinoCore-CH32 の `tests/manual/oep_smoke/`（`oep_smoke.py`、`oep_probe_checks.py`）。
+
+## 偽の probe（動く spec）
+
+`endpoint.Endpoint` は oep-spec の規範どおりに答える偽の probe で、ch32rv・この client・probe の firmware を突き合わせる
+「動く spec」として使う（spec が変わったら、probe の firmware より先にここを合わせる）。`fake` は宣言の例（profile:
+`p4-x035`、`esp32-v003`、`p4-bench` = スロット 3 か所と席 2 つの架空の治具）、`fake_serial` はシリアルの口のバイトの側（COBS の
+候補、生のバイトと bind、セッション中の停止と再開）。
+
+外のプログラムの試験には `fake_serve` を子プロセスで使う:
+
+```sh
+uv run python -m oep_client.v1.fake_serve --pty --profile p4-bench --slot x035 --bind last-reset \
+    --console 'uptime %d\r\n' --every 100
+# 最初の行: PTY /dev/pts/N（--tcp 0 なら PORT n）。stdin を閉じると終わる
+```
+
+pty がシリアルの口（host が TIOCEXCL を掛けて開く）、`--tcp PORT` は `--framing cobs`（シリアルの口）か `--framing length`
+（vendor bulk / TCP の形）。故障の注入は `--drop N`（N 番目の答えを 1 回出さない。要求は実行済みなので送り直しは覚えた答えを
+受ける）、`--noise TEXT`（答えの前に雑音）、`--corrupt N`（N 番目の答えの CRC を 1 回壊す）。ほかは `--help`。
+
+v0 の client（`oep_client.v0`）は 2026-09-26 に消した（git の履歴に残る）。v0 を話す probe はもう無い。

oep_client_python-0.0.1/README.ja.md

@@ -0,0 +1,84 @@
+# OEP Python client
+
+Open Embedded Probe の host 側。v1（oep-spec の `docs/oep-core.ja.md` と `docs/oep-if-*.ja.md`、固める候補の形）を話す。番号は oep-spec の
+`generated/oep-v1/oep_v1_registry.py` をそのまま写した `oep_client.v1.registry` から取る。破壊的変更を前提とする
+実験段階で、互換 API は約束しない。OEP を初めて読む人は oep-spec の `docs/review-guide.ja.md`（どこに何が書いてあるか）から。
+
+target の知識は host にある、という OEP の分担に従う。probe は線と DMI / DP・AP の転送しか知らず、CH32 の flash
+コントローラ、RAM ローダー、RP2350 の boot ROM、Cortex-M の debug レジスタなどはここに置く。
+
+```sh
+pip install oep-client-python     # PyPI (import oep_client); a checkout: pip install -e <checkout>
+uv run pytest                                                            # in a checkout
+```
+
+`import oep_client.v1` だけで使える（`sys.path` に `src/` を足す使い方は不要になった）。番号の表は `tools/sync_registry.sh` で
+oep-spec から写す。PyPI の `oep-client` は別のプロジェクトなので、配布名は `oep-client-python`。
+
+リリースは GitHub Actions の Release（workflow_dispatch、version = X.Y.Z か X.Y.ZbN）: `tools/prepare_release.py` が
+pyproject.toml と `oep_client.__version__` を書き換え、CHANGELOG.md の Unreleased をその版にし、試験と build の後に commit と tag、
+GitHub Release、PyPI（Trusted Publishing）へ出す。変更は CHANGELOG.md の Unreleased に (EN) / (JA) で書き足しておく。
+
+## モジュール（`oep_client.v1`）
+
+| モジュール | 中身 |
+|---|---|
+| `host` | 要求と結果、session_id とロック、`call()`（失敗なら例外）、pipeline、エラーの階層（`OepError` / `Rejected` / `Failed`） |
+| `link` | transport: シリアルの口（常に COBS + CRC、`0x00 <COBS> 0x00`、フレームの外は雑音として捨てる、排他で開く）、USB vendor bulk / HID と TCP（長さつきフレーム、§5.1 の立て直し）、corr による照合と送り直し、`open_host(target)` |
+| `core` | インターフェースを名前で探す（キャッシュつき）、confirm、probe の describe（ラベル、transport の一覧）、ロックの取り方（`take`）、ピンの割り当て（plan）、`Interface` の土台 |
+| `riscv` | `oep.wire.rvswd` / `oep.wire.swio`、`oep.target.riscv-dm`、リセット線の探索、GPIO 経由の attach |
+| `console` | `oep.target.console`（位置つきのストリーム）と、バイト列として読む `ConsoleIO` |
+| `fixture` | `oep.fixture.gpio` / `uart`（revision 1） |
+| `capture` | `oep.fixture.capture`（revision 1、oep-spec の oep-if-capture）。読んだ区画は `Host.on_capture` の callback に `CaptureRecord` で渡る（記録の受け口。wireskein には依存しない） |
+| `esp32_targets` | 独自インターフェース `io.github.ch32-riscv-ug.esp32.i2c-target` / `spi-target`（oep-probe-arduino の ESP32 の I2C / SPI の target） |
+| `decode` | キャプチャのチャネルの復号（I2C） |
+| `registry` | oep-spec の番号の表から生成したモジュール（編集しない。oep-spec から写し直す） |
+| `arm` | `oep.wire.swd`、`oep.target.arm-adi`、MEM-AP、Cortex-M の停止と関数呼び出し |
+| `ch32_flash` | CH32 の書き込み（RAM ローダー、ページ単位の書き直し） |
+| `rp2350` | RP2350 の boot ROM 経由の flash と reboot |
+| `uiapduino` | UIAPduino のブートローダへの出入り |
+| `catalog` / `names` / `interfaces` / `dump` | 能力の一覧と describe の形、表示 |
+| `fake` / `endpoint` / `fake_serial` / `fake_serve` | 偽の probe（下の「偽の probe」） |
+| `target` | 上の主なものを 1 か所から import する入口（最初の版に合わせて書いた呼び出し側のため） |
+
+## 使い方の例
+
+```python
+from oep_client.v1 import core, link, riscv, ch32_flash
+
+hst = link.open_host("/run/board-identify/by-id/esp32-series-30eda0e31108")   # pipelining つき
+# a serial port (always COBS), "tcp://127.0.0.1:PORT" (a broker), "usb" / "usb:303a:0002[:SERIAL]" (vendor, then HID)
+core.take(hst, 30000, owner="flash script")   # the only way in: force; else wait out the lease, name the holder
+wire = riscv.Wire(hst, "oep.wire.rvswd")
+conn, _ = wire.attach(halt=True)
+dm = riscv.RiscvDm(hst, conn)
+dm.reset_halt()
+result = ch32_flash.program(hst, dm, open("sketch.bin", "rb").read(), ch32_flash.PROFILES["x035"])
+dm.reset(confirm=True)
+wire.detach(conn)
+hst.end()
+```
+
+能力の一覧は `uv run python -m oep_client.v1 dump --port <probe>`（`--fake p4-x035` でハードウェアなし）。
+実機での一通りの確認は ArduinoCore-CH32 の `tests/manual/oep_smoke/`（`oep_smoke.py`、`oep_probe_checks.py`）。
+
+## 偽の probe（動く spec）
+
+`endpoint.Endpoint` は oep-spec の規範どおりに答える偽の probe で、ch32rv・この client・probe の firmware を突き合わせる
+「動く spec」として使う（spec が変わったら、probe の firmware より先にここを合わせる）。`fake` は宣言の例（profile:
+`p4-x035`、`esp32-v003`、`p4-bench` = スロット 3 か所と席 2 つの架空の治具）、`fake_serial` はシリアルの口のバイトの側（COBS の
+候補、生のバイトと bind、セッション中の停止と再開）。
+
+外のプログラムの試験には `fake_serve` を子プロセスで使う:
+
+```sh
+uv run python -m oep_client.v1.fake_serve --pty --profile p4-bench --slot x035 --bind last-reset \
+    --console 'uptime %d\r\n' --every 100
+# 最初の行: PTY /dev/pts/N（--tcp 0 なら PORT n）。stdin を閉じると終わる
+```
+
+pty がシリアルの口（host が TIOCEXCL を掛けて開く）、`--tcp PORT` は `--framing cobs`（シリアルの口）か `--framing length`
+（vendor bulk / TCP の形）。故障の注入は `--drop N`（N 番目の答えを 1 回出さない。要求は実行済みなので送り直しは覚えた答えを
+受ける）、`--noise TEXT`（答えの前に雑音）、`--corrupt N`（N 番目の答えの CRC を 1 回壊す）。ほかは `--help`。
+
+v0 の client（`oep_client.v0`）は 2026-09-26 に消した（git の履歴に残る）。v0 を話す probe はもう無い。

oep_client_python-0.0.1/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "oep-client-python"
+version = "0.0.1"
+description = "Open Embedded Probe (OEP) v1 host: serial / USB / TCP transports, the session rules, the standard interfaces, and a fake probe"
+readme = "README.ja.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+  { name = "TANAKA Masayuki" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Embedded Systems",
+  "Topic :: Software Development :: Testing",
+]
+dependencies = ["pyserial>=3.5", "pyusb>=1.3"]
+
+[project.optional-dependencies]
+usb-async = ["libusb1>=3"]   # queued asynchronous IN transfers: streaming near the USB HS ceiling
+hid = ["hidapi>=0.14"]      # the vendor HID way in through the OS HID driver (Windows without WinUSB, Linux hidraw)
+
+[project.scripts]
+oep = "oep_client.v1.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/Open-Embedded-Probe/oep-client-python"
+Repository = "https://github.com/Open-Embedded-Probe/oep-client-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/oep_client"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/oep_client", "tests", "README.ja.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]
+
+[dependency-groups]
+dev = ["pytest>=8"]

oep_client_python-0.0.1/src/oep_client/__init__.py

@@ -0,0 +1,5 @@
+"""Open Embedded Probe (OEP) host client. `oep_client.v1` speaks the v1 protocol (oep-spec docs/oep-core.ja.md)."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.0.1"

oep_client_python-0.0.1/src/oep_client/v1/__init__.py

@@ -0,0 +1 @@
+"""Draft: capability discovery by name (oep-spec capability-*.ja.md). No hardware yet."""

oep_client_python-0.0.1/src/oep_client/v1/__main__.py

@@ -0,0 +1,40 @@
+"""Draft OEP capability discovery by name, on an in-process fake or a v1 draft probe.
+
+  uv run python -m oep_client.v1 dump --port /run/board-identify/by-id/<probe>
+  uv run python -m oep_client.v1 dump --fake p4-x035
+  uv run python -m oep_client.v1 dump --fake esp32-v003 --prefix oep.fixture
+  uv run python -m oep_client.v1 dump --fake p4-x035 --prefix oep.target --json
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import dump, fake, host, link
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(description="OEP capability discovery (draft)")
+    sub = parser.add_subparsers(dest="command", required=True)
+    d = sub.add_parser("dump", help="list and describe every interface a probe offers")
+    src = d.add_mutually_exclusive_group(required=True)
+    src.add_argument("--fake", choices=sorted(fake.PROFILES), help="in-process example probe")
+    src.add_argument("--port", help="a probe: a serial port, tcp://HOST:PORT or usb[:VID:PID] (lock-free reads only)")
+    d.add_argument("--prefix", default="", help="only names under this namespace (label boundaries)")
+    d.add_argument("--exact", action="store_true", help="the prefix is a whole name")
+    d.add_argument("--json", action="store_true", help="machine-readable output")
+    args = parser.parse_args(argv)
+
+    if args.fake:
+        call = fake.PROFILES[args.fake]().call
+    else:
+        hst = link.open_host(args.port)
+        call = lambda fn, op, payload: hst.request(fn, op, payload, locked=False).payload   # noqa: E731
+    caps = dump.collect(call, args.prefix, args.exact)
+    sys.stdout.write(dump.to_json(caps) + "\n" if args.json else dump.to_text(caps))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

oep_client_python-0.0.1/src/oep_client/v1/arm.py

@@ -0,0 +1,269 @@
+"""oep.wire.swd and oep.target.arm-adi, revision 1 (oep-spec oep-if-debug §1, §5-§6).
+
+The probe moves raw DP / AP transfers and MEM-AP blocks; everything above - power-up, SELECT (ADIv5 APSEL/APBANKSEL or
+ADIv6 AP addresses), CSW, the Cortex-M debug registers - is here, as target knowledge belongs to the host.
+"""
+
+from __future__ import annotations
+
+import struct
+
+from . import host as h, message as m, registry as reg
+from .core import Interface
+from .riscv import OK, TargetError, WireBase, check, ran, status_name  # noqa: F401
+
+DP_DPIDR = DP_ABORT = 0x0
+DP_CTRL_STAT = 0x4
+DP_SELECT = 0x8
+DP_RDBUFF = 0xC
+_ADI = reg.TARGET_ARM_ADI
+
+
+class SwdWire(WireBase):
+    NAME = "oep.wire.swd"
+    TAG_TARGETSEL = reg.WIRE_SWD.tlv["attach"]["targetsel"]
+
+    def __init__(self, hst: h.Host):
+        super().__init__(hst)
+        self.speed_hz = 0
+        self.existing = False
+
+    def attach(self, targetsel: int | None = None, max_speed: int | None = None,
+               pins: tuple[int, int] | None = None) -> tuple[int, int, bool]:
+        """-> (connection, DPIDR, woke from dormant). targetsel (multidrop) and max_speed go as critical TLVs: a probe
+        that cannot honour them refuses. self.existing: the wire was attached already (its connection returned)."""
+        body = self._speed_tlv(max_speed) + self._pins_tlv(pins)
+        if targetsel is not None:
+            body += m.tlv(self.TAG_TARGETSEL, struct.pack("<I", targetsel), critical=True)
+        rd = m.Reader(self._call(self.ATTACH, body).payload)
+        conn, dpidr, flags, self.speed_hz = rd.take("HIBI")
+        self.existing = bool(flags & 2)
+        rd.tail()
+        return conn, dpidr, bool(flags & 1)
+
+
+class AdiError(TargetError):
+    pass
+
+
+def transfer_reads(steps: bytes) -> list[bool]:
+    """Per transfer in a packed list: True for a read (1 byte), False for a write (1 + 4 bytes)."""
+    out, at = [], 0
+    while at < len(steps):
+        read = bool(steps[at] & 2)
+        out.append(read)
+        at += 1 if read else 5
+    if at != len(steps):
+        raise ValueError("the transfer list ends inside a write")
+    return out
+
+
+class ArmAdi(Interface):
+    NAME = "oep.target.arm-adi"
+    REVISION = 1
+    TRANSFER, READ_BLOCK, WRITE_BLOCK = _ADI.op["transfer"], _ADI.op["read_block"], _ADI.op["write_block"]
+
+    def __init__(self, hst: h.Host, conn: int, adiv6: bool = False):
+        super().__init__(hst, prefix=struct.pack("<H", conn))
+        self.conn = conn
+        self.adiv6 = adiv6
+        self._select: int | None = None
+
+    # ---- raw transfers ----
+    @staticmethod
+    def req(ap: bool, read: bool, addr: int, value: int = 0) -> bytes:
+        b = bytes([int(ap) | (int(read) << 1) | (((addr >> 2) & 3) << 2)])
+        return b if read else b + struct.pack("<I", value)
+
+    def transfer(self, steps: bytes) -> list[int]:
+        """A packed transfer list (req() concatenated). -> the values read, in order (an AP read's value arrives one
+        transfer late, as on the wire). A list that stopped raises AdiError (status, done, the values it read, and
+        self.last_ack = the raw ACK of the last transfer)."""
+        reads = transfer_reads(steps)
+        r = self._request(self.TRANSFER, struct.pack("<H", len(reads)) + steps)
+        rd = ran(r)
+        done, status, self.last_ack = rd.take("HBB")
+        values = rd.words(sum(reads[:done]))
+        rd.tail()
+        if status != OK or not r.succeeded or done != len(reads):
+            raise AdiError(f"transfer (ack {self.last_ack:#x})", status, r, done=done, values=values)
+        return values
+    def dp_read(self, addr: int) -> int:
+        return self.transfer(self.req(False, True, addr))[0]
+
+    def dp_write(self, addr: int, value: int) -> None:
+        self.transfer(self.req(False, False, addr, value))
+
+    def select(self, value: int) -> None:
+        if value != self._select:
+            self.dp_write(DP_SELECT, value)
+            self._select = value
+
+    def _ap_select(self, ap: int, reg: int) -> None:
+        """ADIv5: ap = APSEL (0..255), reg = register offset in the AP. ADIv6: ap = the AP's base address."""
+        if self.adiv6:
+            self.select((ap + reg) & ~0xF)
+        else:
+            self.select((ap << 24) | (reg & 0xF0))
+
+    def ap_read(self, ap: int, reg: int) -> int:
+        self._ap_select(ap, reg)
+        return self.transfer(self.req(True, True, reg) + self.req(False, True, DP_RDBUFF))[1]   # posted
+
+    def ap_write(self, ap: int, reg: int, value: int) -> None:
+        self._ap_select(ap, reg)
+        self.transfer(self.req(True, False, reg, value))
+
+    def power_up(self) -> int:
+        """Clear sticky errors, request debug + system power, wait for both acks. -> CTRL/STAT"""
+        self.dp_write(DP_ABORT, 0x1E)
+        self._select = None
+        self.select(0)
+        self.dp_write(DP_CTRL_STAT, 0x50000000)
+        for _ in range(100):
+            cs = self.dp_read(DP_CTRL_STAT)
+            if (cs >> 29) & 1 and (cs >> 31) & 1:
+                return cs
+        raise h.OepError(f"no power-up ack: CTRL/STAT {cs:#010x}")
+
+
+class MemAp:
+    """One MEM-AP (ADIv5 APSEL or ADIv6 base address) with 32-bit, auto-incrementing access."""
+
+    def __init__(self, adi: ArmAdi, ap: int, csw_set: int = 0, csw_clear: int = 0):
+        """csw_set / csw_clear: target-specific CSW bits (protection, security). The RP2350's AHB-APs come up
+        non-secure (CSW bit 30), and its SRAM then faults: pass csw_clear=1 << 30 there (2026-09-24)."""
+        self.adi, self.ap = adi, ap
+        self.base = 0xD00 if adi.adiv6 else 0x00        # CSW, TAR, DRW at base + 0x0 / 0x4 / 0xC
+        csw = adi.ap_read(ap, self.base)
+        adi.ap_write(ap, self.base, (((csw & ~0x37) | 0x12) | csw_set) & ~csw_clear)   # 32 bits, AddrInc single
+        adi._ap_select(ap, self.base)                        # the bank the block operations assume
+        # Words per block operation, from the probe's frame limit: request header 6 + session 4 + connection 2 +
+        # address 4 + count 2 on the way in (the answer's 5 + done 2 + status 1 is smaller).
+        from .core import confirm
+        self.chunk = max(1, (confirm(adi.host)["max_frame"] - 18) // 4)
+
+    def write_many(self, pairs: list[tuple[int, int]]) -> None:
+        """Scattered single-word writes in one transfer list (TAR, DRW per word, RDBUFF at the end so the last one
+        has landed): one round trip instead of one per word - what a debug-register sequence needs."""
+        self.adi._ap_select(self.ap, self.base)
+        steps = b"".join(self.adi.req(True, False, self.base + 0x4, a) + self.adi.req(True, False, self.base + 0xC, v)
+                         for a, v in pairs)
+        self.adi.transfer(steps + self.adi.req(False, True, DP_RDBUFF))
+
+    def read_block(self, address: int, words: int) -> list[int]:
+        out, chunk = [], self.chunk
+        for off in range(0, words, chunk):
+            self.adi._ap_select(self.ap, self.base)
+            n = min(chunk, words - off)
+            r = self.adi._request(ArmAdi.READ_BLOCK, struct.pack("<IH", address + off * 4, n))
+            rd = ran(r)
+            done, status = rd.take("HB")
+            got = rd.words(done)
+            rd.tail()
+            if status != OK or not r.succeeded or done != n:
+                raise AdiError("read_block", status, r, done=off + done, values=out + got)
+            out += got
+        return out
+
+    def write_block(self, address: int, values: list[int]) -> None:
+        chunk = self.chunk
+        for off in range(0, len(values), chunk):
+            self.adi._ap_select(self.ap, self.base)
+            part = values[off:off + chunk]
+            r = self.adi._request(ArmAdi.WRITE_BLOCK, struct.pack("<IH", address + off * 4, len(part))
+                                  + struct.pack(f"<{len(part)}I", *part))
+            rd = ran(r)
+            done, status = rd.take("HB")
+            rd.tail()
+            if status != OK or not r.succeeded:
+                raise AdiError("write_block", status, r, done=off + done)
+
+    def read32(self, address: int) -> int:
+        return self.read_block(address, 1)[0]
+
+    def write32(self, address: int, value: int) -> None:
+        self.write_block(address, [value])
+
+
+class CortexM:
+    """Armv7-M / Armv8-M core debug through a MEM-AP: halt, resume, core registers through DCRSR / DCRDR, and running
+    a function on the target (arguments in r0-r3, LR at a BKPT in RAM, run until the core halts on it) - the way a
+    host-side flash algorithm drives the target's own ROM or a RAM loader."""
+
+    DHCSR, DCRSR, DCRDR, AIRCR = 0xE000EDF0, 0xE000EDF4, 0xE000EDF8, 0xE000ED0C
+    KEY = 0xA05F0000
+    C_DEBUGEN, C_HALT, C_MASKINTS = 1, 2, 8
+    S_REGRDY, S_HALT = 1 << 16, 1 << 17
+    SP, LR, PC, XPSR = 13, 14, 15, 16
+
+    def __init__(self, mem: MemAp, bkpt_at: int, stack_top: int):
+        """bkpt_at: a word of RAM the target does not need (the return breakpoint goes there); stack_top: where the
+        called function's stack starts (its RAM below is clobbered)."""
+        self.mem, self.bkpt_at, self.stack_top = mem, bkpt_at, stack_top
+
+    def _wait(self, mask: int, timeout: float):
+        import time
+        deadline = time.monotonic() + timeout
+        while True:
+            v = self.mem.read32(self.DHCSR)
+            if v & mask:
+                return v
+            if time.monotonic() > deadline:
+                raise TimeoutError(f"DHCSR {v:#010x}: waiting for {mask:#x}")
+
+    def halted(self) -> bool:
+        return bool(self.mem.read32(self.DHCSR) & self.S_HALT)
+
+    def halt(self) -> None:
+        self.mem.write32(self.DHCSR, self.KEY | self.C_DEBUGEN | self.C_HALT)
+        self._wait(self.S_HALT, 1.0)
+
+    def resume(self, mask_ints: bool = False) -> None:
+        self.mem.write32(self.DHCSR, self.KEY | self.C_DEBUGEN | (self.C_MASKINTS if mask_ints else 0))
+
+    def release(self) -> None:
+        """Run, debug off. C_MASKINTS is cleared first: it lives in the debug domain and survives every reset but
+        power-on, and firmware left with it set runs without SysTick / USB interrupts (RP2350, 2026-09-24)."""
+        self.mem.write32(self.DHCSR, self.KEY | self.C_DEBUGEN | self.C_HALT)
+        self.mem.write32(self.DHCSR, self.KEY)
+
+    def reg(self, n: int) -> int:
+        self.mem.write32(self.DCRSR, n)
+        self._wait(self.S_REGRDY, 1.0)
+        return self.mem.read32(self.DCRDR)
+
+    def set_reg(self, n: int, value: int) -> None:
+        self.mem.write32(self.DCRDR, value)
+        self.mem.write32(self.DCRSR, (1 << 16) | n)
+        self._wait(self.S_REGRDY, 1.0)
+
+    def prepare_call(self, fn: int, args=()) -> None:
+        """Registers for fn(args...): r0-r3, SP, LR to the breakpoint, PC, Thumb bit, no active exception. The
+        writes go out as one transfer list; a register write takes the core a few cycles and each SWD transfer
+        takes microseconds, so S_REGRDY is checked once at the end rather than after each."""
+        xpsr = (self.reg(self.XPSR) | 1 << 24) & ~0x1FF
+        regs = [*enumerate(args), (self.SP, self.stack_top), (self.LR, self.bkpt_at | 1), (self.PC, fn & ~1),
+                (self.XPSR, xpsr)]
+        pairs = [(self.bkpt_at, 0xBE00BE00)]                    # bkpt #0, twice
+        for n, value in regs:
+            pairs += [(self.DCRDR, value), (self.DCRSR, (1 << 16) | n)]
+        self.mem.write_many(pairs)
+        self._wait(self.S_REGRDY, 1.0)
+
+    def call(self, fn: int, args=(), timeout: float = 10.0) -> int:
+        """Run fn(args...) on the halted core with interrupts masked (their handlers may live in flash that the call
+        makes unreadable), wait for the breakpoint, clear the mask, return r0."""
+        self.prepare_call(fn, args)
+        self.resume(mask_ints=True)
+        self._wait(self.S_HALT, timeout)
+        self.mem.write32(self.DHCSR, self.KEY | self.C_DEBUGEN | self.C_HALT)   # MASKINTS off while halted
+        pc = self.reg(self.PC)
+        if pc & ~3 != self.bkpt_at:
+            raise h.OepError(f"stopped at {pc:#010x}, not at the return breakpoint")
+        return self.reg(0)
+
+    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)
+        self.mem.write32(self.AIRCR, 0x05FA0004)