oep-client-python 0.0.18__tar.gz → 0.0.19__tar.gz

{oep_client_python-0.0.18 → oep_client_python-0.0.19}/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.0.19
+- (EN) The pre-freeze decisions (oep-spec docs/v1-freeze-decisions.ja.md), in the fake and the client at once:
+  - `oep.fixture.capture` is `oep.fixture.logic`; the I2C / SPI targets are the standard `oep.fixture.i2c-target` / `spi-target` (`fixture.I2cTarget` / `SpiTarget`; `esp32_targets` is gone). Their status is separate fields (`I2cStatus(state=, mode=, armed=, queued=, …)`); `read_hw` is gone, `set_stretch` is `stretch` (op 0x07).
+  - Answer lists put each element's length first (core §2.3): list, scan, connections, marks, capture segments (`message.Reader.element()`, `message.element()`); what an element carries after the known fields is skipped.
+  - probe.config: a slot's lock is length-prefixed (`lock_len`, 0 = none); settings are saved with the (name, instance, revision) of each interface they name and renumbered at boot, so another interface added or moved leaves them in force (the fake: `saved_ids`); the storage says why it is unreadable (`State.unreadable`). The item classes (`Plan`, `Label`, `Idle`, `Slot`, `Bind`) take keyword arguments only.
+  - rejected unavailable carries core §4.3's TLVs: `host.Unavailable` with `.cause`, `.channels`, `.holder_fn`, `.holder_kind` (and `.tlvs`; gpio's refused position is its TLV 0x40). An unknown console stream is `no_connection`.
+  - The analog's zero and scale are signed (i32).
+  - USB: the vendor transport is the class 0xFF interface's bulk pair (not the first bulk pair); `open_host("usb:<unit id>")` finds the OEP probe whose USB serial is that unit id; unit_id is text (the fake: `esp32p4` / `esp32` / `rp2350` models, lowercase hex unit ids).
+  - `target` (the first draft's re-exports) is gone: import the modules; README lists the public modules and the version pairing with the firmware.
+- (JA) 凍結前の決定（oep-spec docs/v1-freeze-decisions.ja.md）を、fake とクライアントに一度に入れた:
+  - `oep.fixture.capture` は `oep.fixture.logic` になった。I2C / SPI の target は標準の `oep.fixture.i2c-target` / `spi-target`（`fixture.I2cTarget` / `SpiTarget`。`esp32_targets` は無くなった）。status は分けたフィールド（`I2cStatus(state=, mode=, armed=, queued=, …)`）、`read_hw` は無くなり、`set_stretch` は `stretch`（op 0x07）。
+  - 応答の並びは要素の前に長さを置く（core §2.3）: list、scan、connections、marks、capture の segments（`message.Reader.element()`、`message.element()`）。要素の知っているフィールドの後ろは飛ばす。
+  - probe.config: スロットの錠は長さ付き（`lock_len`、0 は錠なし）。設定は、指すインターフェースの (name、instance、revision) と一緒に保存し、起動時に番号を読み替える。ほかのインターフェースを足したり動かしたりしても設定は効いたまま（fake: `saved_ids`）。storage は読めない理由を返す（`State.unreadable`）。項目のクラス（`Plan`、`Label`、`Idle`、`Slot`、`Bind`）はキーワード引数だけを取る。
+  - rejected unavailable は core §4.3 の TLV を持つ: `host.Unavailable` の `.cause`、`.channels`、`.holder_fn`、`.holder_kind`（と `.tlvs`。gpio の断った位置は、その TLV 0x40）。知らない console の stream は `no_connection`。
+  - アナログの zero と scale は符号付き（i32）。
+  - USB: vendor の経路は class 0xFF のインターフェースの bulk の組（最初の bulk の組ではない）。`open_host("usb:<unit id>")` は、USB の serial がその unit id の OEP の probe を探す。unit_id は text（fake: model は `esp32p4` / `esp32` / `rp2350`、unit id は小文字の 16 進）。
+  - `target`（最初の版の再輸出）は無くなった: モジュールを直接 import する。README に公開のモジュールと、firmware との版の組を書いた。
+
 ## 0.0.18
 - (EN) No user-facing changes recorded.
 - (JA) ユーザー向け変更の記録はありません。

{oep_client_python-0.0.18 → oep_client_python-0.0.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oep-client-python
-Version: 0.0.18
+Version: 0.0.19
 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
@@ -49,6 +49,10 @@ under Unreleased in CHANGELOG.md, (EN) and (JA).
 
 ## Modules (`oep_client`)
 
+The modules below are the public API; import them directly (`from oep_client import riscv`). Anything not listed, and
+names starting with `_`, may change. A probe firmware and this client go together by version: OpenEmbeddedProbe X.Y.Z with
+oep-client-python X.Y.Z (until the v1 freeze every release may break the wire; the versions move together).
+
 | Module | Contents |
 |---|---|
 | `host` | requests and results, the session id and the lock, `call()` (raises unless it worked), pipelining, the errors (`OepError` / `Rejected` / `Failed`) |
@@ -56,10 +60,9 @@ under Unreleased in CHANGELOG.md, (EN) and (JA).
 | `core` | interfaces by name (cached), confirm, the probe's describe (labels, the transport list), taking the lock (`take`), the pin plan, the `Interface` base |
 | `riscv` | `oep.wire.rvswd` / `oep.wire.swio`, `oep.target.riscv-dm`, finding the reset line, attach through GPIO |
 | `console` | `oep.target.console` (position streams) and `ConsoleIO`, read as bytes |
-| `fixture` | `oep.fixture.gpio` / `uart` (revision 1) |
+| `fixture` | `oep.fixture.gpio` / `uart` / `i2c-target` / `spi-target` (revision 1) |
 | `config` | `oep.probe.config` (slots, binds, plan / label / idle items, get / set / save / erase, the live slot and bind state) |
-| `capture` | `oep.fixture.capture` (revision 1, oep-spec oep-if-capture). Every segment read goes to the `Host.on_capture` callbacks as a `CaptureRecord` (the hook for run recorders; no wireskein dependency) |
-| `esp32_targets` | the custom interfaces `io.github.ch32-riscv-ug.esp32.i2c-target` / `spi-target` (the ESP32 I2C / SPI targets of oep-probe-arduino) |
+| `capture` | `oep.fixture.logic` (revision 1, oep-spec oep-if-capture). Every segment read goes to the `Host.on_capture` callbacks as a `CaptureRecord` (the hook for run recorders; no wireskein dependency) |
 | `decode` | decoding capture channels (I2C) |
 | `registry` | generated from oep-spec's number table (never edited; copied again from oep-spec) |
 | `arm` | `oep.wire.swd`, `oep.target.arm-adi`, MEM-AP, halting and calling functions on a Cortex-M |
@@ -68,7 +71,6 @@ under Unreleased in CHANGELOG.md, (EN) and (JA).
 | `uiapduino` | into and out of the UIAPduino bootloader |
 | `catalog` / `names` / `interfaces` / `dump` | the capability list and describe shapes, display |
 | `fake` / `endpoint` / `fake_serial` / `fake_serve` | the fake probe (below) |
-| `target` | one place to import the main ones from |
 
 ## Example
 
@@ -76,7 +78,8 @@ under Unreleased in CHANGELOG.md, (EN) and (JA).
 from oep_client import core, link, riscv, ch32_flash
 
 hst = link.open_host("/run/board-identify/by-id/esp32-series-30eda0e31108")   # pipelined
-# a serial port (always COBS), "tcp://127.0.0.1:PORT" (a broker), "usb" / "usb:303a:0002[:SERIAL]" (vendor, then HID)
+# a serial port (always COBS), "tcp://127.0.0.1:PORT" (a broker), "usb:<unit id>" (the probe whose USB serial it is),
+# "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)
@@ -111,7 +114,7 @@ against it (when the spec changes, this is brought in line before the firmware).
 chooses), `fake_serial` the byte side of a serial port (COBS candidates, raw bytes and binds, held during a session and
 resumed after it).
 
-`fake_capture` is `oep.fixture.capture` (logic): one-shot, repeat (segments with the clock at the actual rate, a ring,
+`fake_capture` is `oep.fixture.logic` (logic): one-shot, repeat (segments with the clock at the actual rate, a ring,
 release) and streaming (data pushes while subscribed), level / edge triggers with a pretrigger, and events. What it
 captures is known: sample i is the counter i, channel k its bit k (a square wave of period 2^(k+1) samples), in the layout
 the profile allows (`p4-x035`: w 1-16 as the P4's PARLIO, three channels in w 4; `esp32-v003`: w 8 as the classic ESP32's

{oep_client_python-0.0.18 → oep_client_python-0.0.19}/README.ja.md

@@ -23,6 +23,10 @@ GitHub Release、PyPI（Trusted Publishing）へ出す。変更は CHANGELOG.md
 
 ## モジュール（`oep_client`）
 
+下の表のモジュールが公開の API です。直接 import します（`from oep_client import riscv`）。表に無いものと、`_` で始まる名前は
+変わることがあります。probe の firmware とこのクライアントは版で組になります: OpenEmbeddedProbe X.Y.Z と oep-client-python
+X.Y.Z（v1 の凍結までは、どのリリースも wire を壊しうるので、版を一緒に動かします）。
+
 | モジュール | 中身 |
 |---|---|
 | `host` | 要求と結果、session_id とロック、`call()`（失敗なら例外）、pipeline、エラーの階層（`OepError` / `Rejected` / `Failed`） |
@@ -30,10 +34,9 @@ GitHub Release、PyPI（Trusted Publishing）へ出す。変更は CHANGELOG.md
 | `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） |
+| `fixture` | `oep.fixture.gpio` / `uart` / `i2c-target` / `spi-target`（revision 1） |
 | `config` | `oep.probe.config`（スロット、bind、plan / label / idle の項目、get / set / save / erase、スロットと bind の今の状態） |
-| `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） |
+| `capture` | `oep.fixture.logic`（revision 1、oep-spec の oep-if-capture）。読んだ区画は `Host.on_capture` の callback に `CaptureRecord` で渡る（記録の受け口。wireskein には依存しない） |
 | `decode` | キャプチャのチャネルの復号（I2C） |
 | `registry` | oep-spec の番号の表から生成したモジュール（編集しない。oep-spec から写し直す） |
 | `arm` | `oep.wire.swd`、`oep.target.arm-adi`、MEM-AP、Cortex-M の停止と関数呼び出し |
@@ -42,7 +45,6 @@ GitHub Release、PyPI（Trusted Publishing）へ出す。変更は CHANGELOG.md
 | `uiapduino` | UIAPduino のブートローダへの出入り |
 | `catalog` / `names` / `interfaces` / `dump` | 能力の一覧と describe の形、表示 |
 | `fake` / `endpoint` / `fake_serial` / `fake_serve` | 偽の probe（下の「偽の probe」） |
-| `target` | 上の主なものを 1 か所から import する入口（最初の版に合わせて書いた呼び出し側のため） |
 
 ## 使い方の例
 
@@ -50,7 +52,8 @@ GitHub Release、PyPI（Trusted Publishing）へ出す。変更は CHANGELOG.md
 from oep_client 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)
+# a serial port (always COBS), "tcp://127.0.0.1:PORT" (a broker), "usb:<unit id>" (the probe whose USB serial it is),
+# "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)
@@ -83,7 +86,7 @@ oep config save <probe>                      # 再起動の後も残す（remove
 `p4-x035`、`esp32-v003`、`p4-bench` = スロット 3 か所と席 2 つの架空の治具、`rp2350-pins` = host がピンを選ぶ wire）、`fake_serial` は
 シリアルの口のバイトの側（COBS の候補、生のバイトと bind、セッション中の停止と再開）。
 
-`fake_capture` は `oep.fixture.capture`（ロジック）: ワンショット、リピート（実際のレートで時計どおりに区画ができ、リング、release）、
+`fake_capture` は `oep.fixture.logic`（ロジック）: ワンショット、リピート（実際のレートで時計どおりに区画ができ、リング、release）、
 ストリーミング（購読している間のデータの push）、レベル / エッジのトリガとプリトリガ、出来事。取れるものは決まっている: サンプル i は
 カウンタの値 i で、チャネル k はそのビット k（周期 2^(k+1) サンプルの方形波）。layout は profile が許す形（`p4-x035`: P4 の
 PARLIO と同じ w 1〜16、3 本なら w 4。`esp32-v003`: classic ESP32 の sampler と同じ w 8、ワンショットだけ）。capture は聞くだけ

{oep_client_python-0.0.18 → oep_client_python-0.0.19}/README.md

@@ -27,6 +27,10 @@ under Unreleased in CHANGELOG.md, (EN) and (JA).
 
 ## Modules (`oep_client`)
 
+The modules below are the public API; import them directly (`from oep_client import riscv`). Anything not listed, and
+names starting with `_`, may change. A probe firmware and this client go together by version: OpenEmbeddedProbe X.Y.Z with
+oep-client-python X.Y.Z (until the v1 freeze every release may break the wire; the versions move together).
+
 | Module | Contents |
 |---|---|
 | `host` | requests and results, the session id and the lock, `call()` (raises unless it worked), pipelining, the errors (`OepError` / `Rejected` / `Failed`) |
@@ -34,10 +38,9 @@ under Unreleased in CHANGELOG.md, (EN) and (JA).
 | `core` | interfaces by name (cached), confirm, the probe's describe (labels, the transport list), taking the lock (`take`), the pin plan, the `Interface` base |
 | `riscv` | `oep.wire.rvswd` / `oep.wire.swio`, `oep.target.riscv-dm`, finding the reset line, attach through GPIO |
 | `console` | `oep.target.console` (position streams) and `ConsoleIO`, read as bytes |
-| `fixture` | `oep.fixture.gpio` / `uart` (revision 1) |
+| `fixture` | `oep.fixture.gpio` / `uart` / `i2c-target` / `spi-target` (revision 1) |
 | `config` | `oep.probe.config` (slots, binds, plan / label / idle items, get / set / save / erase, the live slot and bind state) |
-| `capture` | `oep.fixture.capture` (revision 1, oep-spec oep-if-capture). Every segment read goes to the `Host.on_capture` callbacks as a `CaptureRecord` (the hook for run recorders; no wireskein dependency) |
-| `esp32_targets` | the custom interfaces `io.github.ch32-riscv-ug.esp32.i2c-target` / `spi-target` (the ESP32 I2C / SPI targets of oep-probe-arduino) |
+| `capture` | `oep.fixture.logic` (revision 1, oep-spec oep-if-capture). Every segment read goes to the `Host.on_capture` callbacks as a `CaptureRecord` (the hook for run recorders; no wireskein dependency) |
 | `decode` | decoding capture channels (I2C) |
 | `registry` | generated from oep-spec's number table (never edited; copied again from oep-spec) |
 | `arm` | `oep.wire.swd`, `oep.target.arm-adi`, MEM-AP, halting and calling functions on a Cortex-M |
@@ -46,7 +49,6 @@ under Unreleased in CHANGELOG.md, (EN) and (JA).
 | `uiapduino` | into and out of the UIAPduino bootloader |
 | `catalog` / `names` / `interfaces` / `dump` | the capability list and describe shapes, display |
 | `fake` / `endpoint` / `fake_serial` / `fake_serve` | the fake probe (below) |
-| `target` | one place to import the main ones from |
 
 ## Example
 
@@ -54,7 +56,8 @@ under Unreleased in CHANGELOG.md, (EN) and (JA).
 from oep_client import core, link, riscv, ch32_flash
 
 hst = link.open_host("/run/board-identify/by-id/esp32-series-30eda0e31108")   # pipelined
-# a serial port (always COBS), "tcp://127.0.0.1:PORT" (a broker), "usb" / "usb:303a:0002[:SERIAL]" (vendor, then HID)
+# a serial port (always COBS), "tcp://127.0.0.1:PORT" (a broker), "usb:<unit id>" (the probe whose USB serial it is),
+# "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)
@@ -89,7 +92,7 @@ against it (when the spec changes, this is brought in line before the firmware).
 chooses), `fake_serial` the byte side of a serial port (COBS candidates, raw bytes and binds, held during a session and
 resumed after it).
 
-`fake_capture` is `oep.fixture.capture` (logic): one-shot, repeat (segments with the clock at the actual rate, a ring,
+`fake_capture` is `oep.fixture.logic` (logic): one-shot, repeat (segments with the clock at the actual rate, a ring,
 release) and streaming (data pushes while subscribed), level / edge triggers with a pretrigger, and events. What it
 captures is known: sample i is the counter i, channel k its bit k (a square wave of period 2^(k+1) samples), in the layout
 the profile allows (`p4-x035`: w 1-16 as the P4's PARLIO, three channels in w 4; `esp32-v003`: w 8 as the classic ESP32's

{oep_client_python-0.0.18 → oep_client_python-0.0.19}/pyproject.toml

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

{oep_client_python-0.0.18 → oep_client_python-0.0.19}/src/oep_client/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.0.18"
+__version__ = "0.0.19"

{oep_client_python-0.0.18 → oep_client_python-0.0.19}/src/oep_client/__main__.py

@@ -186,12 +186,14 @@ def _config(args) -> int:
             if args.lock:
                 mask, _, value = args.lock.partition(":")
                 lock = (1, struct.pack("<I", int(mask, 16)), struct.pack("<I", int(value, 16)))
-            it = config.Slot(args.slot, fn, _pins(hst, fn, args.pins, args.wire), args.name, args.attach, args.retry,
-                             args.mechanism, lock, args.max_speed, args.idle_clock)
+            it = config.Slot(slot=args.slot, wire_fn=fn, pins=_pins(hst, fn, args.pins, args.wire), name=args.name,
+                             attach=args.attach, retry_s=args.retry, mechanism=args.mechanism, lock=lock,
+                             max_speed=args.max_speed, idle_clock=args.idle_clock)
             _change(hst, cfg, [it], args.save)
         elif args.action == "bind":
             slots = {it.name: it.slot for it in cfg.items() if isinstance(it, config.Slot)}
-            it = config.Bind(args.port, args.mode, [_stream(s, slots) for s in args.stream], args.select)
+            it = config.Bind(port=args.port, mode=args.mode, streams=[_stream(s, slots) for s in args.stream],
+                             selected=args.select)
             _change(hst, cfg, [it], args.save)
         elif args.action == "plan":
             fn, roles = _plan_fn(hst, args.fn)
@@ -203,12 +205,12 @@ def _config(args) -> int:
                 number = int(role) if role.isdigit() else roles.get(role.lower())
                 if number is None:
                     raise SystemExit(f"{role}: not a role of fn {fn} (roles: {', '.join(sorted(roles)) or 'numbers only'})")
-                items.append(config.Plan(fn, number, int(ch, 0)))
+                items.append(config.Plan(fn=fn, role=number, channel=int(ch, 0)))
             _change(hst, cfg, items, args.save)
         elif args.action == "label":
-            _change(hst, cfg, [config.Label(args.channel, args.text)], args.save)
+            _change(hst, cfg, [config.Label(channel=args.channel, text=args.text)], args.save)
         elif args.action == "idle":
-            _change(hst, cfg, [config.Idle(args.channel, args.mode)], args.save)
+            _change(hst, cfg, [config.Idle(channel=args.channel, mode=args.mode)], args.save)
         elif args.action == "remove":
             _change(hst, cfg, [config.remove(args.kind, args.key)], args.save)
         else:

{oep_client_python-0.0.18 → oep_client_python-0.0.19}/src/oep_client/capture.py

@@ -1,4 +1,4 @@
-"""oep.fixture.capture / oep.fixture.analog / oep.fixture.capture-group revision 1 (oep-spec docs/oep-if-capture.ja.md:
+"""oep.fixture.logic / oep.fixture.analog / oep.fixture.capture-group revision 1 (oep-spec docs/oep-if-capture.ja.md:
 §1 layouts, §2 segments, §3 operations, §3.8 calibration, §4 groups). Numbers from `registry`.
 
 Times are the probe's one clock (ns since its boot, comparable within one boot_id): estimates with an uncertainty, the
@@ -20,7 +20,7 @@ from . import cobs, host as h, message as m, registry as reg
 from .frames import FramingLost
 from .core import Interface, confirm
 
-_CAP = reg.FIXTURE_CAPTURE
+_CAP = reg.FIXTURE_LOGIC
 _ANA = reg.FIXTURE_ANALOG
 _GRP = reg.FIXTURE_CAPTURE_GROUP
 # configure TLVs; bit 7 of a tag = critical (the probe must reject what it cannot do)
@@ -158,7 +158,7 @@ def _config(payload: bytes, analog: bool) -> Config:
         elif tag == RATE_ACCURACY:
             c.rate_measured, c.rate_ppm = v[0] == 1, struct.unpack_from("<I", v, 1)[0]
         elif tag == SCALE and analog:
-            role, zero, scale = struct.unpack("<BII", v)
+            role, zero, scale = struct.unpack("<Bii", v)            # signed: an inverting frontend (§3.3)
             c.zero[role], c.scale_nv[role] = zero, scale
         elif tag == SKEW and analog:
             role, ns = struct.unpack("<BI", v)
@@ -177,7 +177,7 @@ def _config(payload: bytes, analog: bool) -> Config:
 
 class LogicCapture(Interface):
     """Basic logic capture. Channels are the plan's roles 0..C-1."""
-    NAME = "oep.fixture.capture"
+    NAME = "oep.fixture.logic"
     REVISION = 1
     ANALOG = False
     CONFIGURE, START, STOP, FORCE, STATUS, READ, SEGMENTS, RELEASE, QUERY_OP = (
@@ -301,7 +301,7 @@ class LogicCapture(Interface):
 
     def segments(self, from_serial: int = 0) -> list[Segment]:
         rd = m.Reader(self._call(self.SEGMENTS, struct.pack("<I", from_serial), locked=False).payload)
-        out = [Segment.unpack(rd.bytes(SEGMENT_BYTES)) for _ in range(rd.u8())]
+        out = [Segment.unpack(rd.element().bytes(SEGMENT_BYTES)) for _ in range(rd.u8())]
         rd.tail()
         return out
 

{oep_client_python-0.0.18 → oep_client_python-0.0.19}/src/oep_client/catalog.py

@@ -1,7 +1,7 @@
 """Draft wire forms for capability discovery by name (oep-spec docs/capability-declaration-model.ja.md).
 
 list request : flags(u8) first(u16) prefix_len(u8) prefix     flags bit0 = exact
-list result  : total(u16) count(u8) entries [TLV tail]         oep.core (fn 0) is the first entry
+list result  : total(u16) count(u8) count x (len(u8) entry) [TLV tail]   oep.core (fn 0) is the first entry
 list entry   : fn(u16) instance(u16) revision(u8) flags(u8) name_len(u8) name
 describe     : request fn(u16) first(u16); result more(u8) then TLV bytes (tag u8, len u8, value;
                tag bit 7 = critical). more = 1: TLVs remain after this page, ask again from first + count
@@ -15,7 +15,7 @@ from __future__ import annotations
 import struct
 from dataclasses import dataclass, field
 
-from .message import Reader, split_tlvs
+from .message import Reader, element, split_tlvs
 
 LIST_EXACT = 0x01
 
@@ -65,7 +65,7 @@ def pack_entry(e: ListEntry) -> bytes:
 
 
 def pack_list_result(total: int, entries: list[ListEntry]) -> bytes:
-    return struct.pack("<HB", total, len(entries)) + b"".join(pack_entry(e) for e in entries)
+    return struct.pack("<HB", total, len(entries)) + b"".join(element(pack_entry(e)) for e in entries)
 
 
 def unpack_list_result(payload: bytes) -> tuple[int, list[ListEntry]]:
@@ -74,8 +74,9 @@ def unpack_list_result(payload: bytes) -> tuple[int, list[ListEntry]]:
     total, count = rd.take("HB")
     out = []
     for _ in range(count):
-        fn, instance, revision, flags, n = rd.take("HHBBB")
-        out.append(ListEntry(fn, instance, revision, flags, rd.bytes(n).decode("ascii", "replace")))
+        e = rd.element()
+        fn, instance, revision, flags, n = e.take("HHBBB")
+        out.append(ListEntry(fn, instance, revision, flags, e.bytes(n).decode("ascii", "replace")))
     rd.tail()
     return total, out
 

{oep_client_python-0.0.18 → oep_client_python-0.0.19}/src/oep_client/ch32_flash.py

@@ -17,7 +17,7 @@ import struct
 import time
 from dataclasses import dataclass, field
 
-from . import host as h, riscv, target
+from . import core, host as h, riscv
 
 # oep-spec experiments/flash-primitives/x035_loader.S, assembled at 0x20000000 (riscv32-esp-elf binutils)
 FAST_PAGE_LOADER = bytes.fromhex(
@@ -92,13 +92,13 @@ V003_INPUT, V003_STACK, V003_EBREAK, V003_RUN = 0x20000200, 0x20000800, 0x200001
 
 
 def _block_size(hst: h.Host) -> int:
-    info = target.confirm(hst)
+    info = core.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]]:
+def _write_requests(dm: riscv.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)]
 
@@ -108,20 +108,20 @@ def _write_ok(r) -> bool:
     if not r.succeeded:
         return False
     try:
-        rd = target.ran(r)
+        rd = riscv.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:
+def _write(dm: riscv.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)
+            raise riscv.TargetError("write_block", riscv.ran(r).take("HB")[1], r)
 
 
-def _read(dm: target.RiscvDm, address: int, length: int, block: int) -> bytes:
+def _read(dm: riscv.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""
@@ -137,7 +137,7 @@ def _read(dm: target.RiscvDm, address: int, length: int, block: int) -> bytes:
 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:
+def program(hst: h.Host, dm: riscv.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:

{oep_client_python-0.0.18 → oep_client_python-0.0.19}/src/oep_client/config.py

@@ -2,8 +2,8 @@
 pins, slots, binds - read and set as items, saved when the host says so, and the live slot / bind state.
 
     cfg = config.ProbeConfig(hst)
-    cfg.set([config.Slot(0, wire_fn, (2, 54), "x035", attach="at-boot", retry_s=1, mechanism="dmseq"),
-             config.Bind(1, "last-reset", [("slot", 0)])])
+    cfg.set([config.Slot(slot=0, wire_fn=wire_fn, pins=(2, 54), name="x035", attach="at-boot", retry_s=1),
+             config.Bind(port=1, mode="last-reset", streams=[("slot", 0)])])
     cfg.save()
     cfg.items(), cfg.state()
 
@@ -31,13 +31,14 @@ BIND_FLOW = {v: k for k, v in _CFG.enum["bind_flow"].items()}
 IDLE = {k.replace("_", "-"): v for k, v in _CFG.enum["idle_mode"].items()}
 IDLE_CLOCK = dict(reg.WIRE_RVSWD.enum["idle_clock"])            # a slot's idle_clock (oep-if-debug §3)
 STORAGE_STATE = {v: k for k, v in _CFG.enum["storage_state"].items()}
+UNREADABLE = {1: "unreadable form", 2: "an interface it names is gone or of another revision", 3: "refused when applied"}
 
 
 def _name(table: dict[str, int], value: int) -> str:
     return next((k for k, v in table.items() if v == value), str(value))
 
 
-@dataclass
+@dataclass(kw_only=True)
 class Plan:
     fn: int
     role: int
@@ -48,7 +49,7 @@ class Plan:
         return struct.pack("<HBH", self.fn, self.role, self.channel)
 
 
-@dataclass
+@dataclass(kw_only=True)
 class Label:
     channel: int
     text: str
@@ -58,7 +59,7 @@ class Label:
         return struct.pack("<H", self.channel) + self.text.encode()
 
 
-@dataclass
+@dataclass(kw_only=True)
 class Idle:
     channel: int
     mode: str = "pull-up"          # hi-z, pull-up, pull-down
@@ -68,7 +69,7 @@ class Idle:
         return struct.pack("<HB", self.channel, IDLE[self.mode])
 
 
-@dataclass
+@dataclass(kw_only=True)
 class Slot:
     """A place a target is wired to (probe.config §1.1). pins: (swdio, swclk), swclk 0xFFFF on one wire (swio).
     lock: (scheme, mask, value) - the target_id a connection must show, e.g. (1, mask u32 LE, value u32 LE)."""
@@ -90,14 +91,14 @@ class Slot:
                         self.retry_s if self.attach == "at-boot" else 0, self.max_speed, IDLE_CLOCK[self.idle_clock],
                         MECHANISM[self.mechanism], len(name)) + name
         if self.lock is None:
-            return v + b"\x00"
+            return v + b"\x00"                                    # lock_len 0: no lock
         scheme, mask, value = self.lock
-        if len(mask) != len(value) or not mask:
-            raise ValueError("a lock's mask and value have the same length, at least 1 byte")
-        return v + bytes([scheme]) + mask + value
+        if len(mask) != len(value) or not mask or not scheme:
+            raise ValueError("a lock has a scheme and a mask and value of the same length, at least 1 byte")
+        return v + bytes([1 + 2 * len(mask), scheme]) + mask + value
 
 
-@dataclass
+@dataclass(kw_only=True)
 class Bind:
     """What serial port `port` (the describe transport index) carries (probe.config §1.2). streams: ("slot", n) or
     ("uart", fn); selected: manual's choice (an index into streams)."""
@@ -126,25 +127,28 @@ def remove(kind: str, key: int) -> bytes:
 def decode(tag: int, v: bytes):
     """One item as one of the classes above (an unknown tag: (tag, value))."""
     if tag == ITEM["plan"] and len(v) == 5:
-        return Plan(*struct.unpack("<HBH", v))
+        fn, role, channel = struct.unpack("<HBH", v)
+        return Plan(fn=fn, role=role, channel=channel)
     if tag == ITEM["label"] and len(v) >= 2:
-        return Label(struct.unpack_from("<H", v)[0], v[2:].decode("utf-8", "replace"))
+        return Label(channel=struct.unpack_from("<H", v)[0], text=v[2:].decode("utf-8", "replace"))
     if tag == ITEM["idle"] and len(v) == 3:
-        return Idle(struct.unpack_from("<H", v)[0], _name(IDLE, v[2]))
+        return Idle(channel=struct.unpack_from("<H", v)[0], mode=_name(IDLE, v[2]))
     if tag == ITEM["slot"] and len(v) >= 18:
         n, wire_fn, swdio, swclk, attach, retry_s, max_speed, idle, mech, name_len = struct.unpack_from("<BHHHBHIBBB", v)
         name = v[17:17 + name_len].decode("ascii", "replace")
-        rest = v[17 + name_len:]
+        at = 17 + name_len
+        lock_len = v[at] if at < len(v) else 0
+        part = v[at + 1:at + 1 + lock_len]                         # after it: later fields (core §2.3), skipped
         lock = None
-        if rest and rest[0]:
-            half = (len(rest) - 1) // 2
-            lock = (rest[0], rest[1:1 + half], rest[1 + half:])
-        return Slot(n, wire_fn, (swdio, swclk), name, _name(ATTACH, attach), retry_s, _name(MECHANISM, mech), lock,
-                    max_speed, _name(IDLE_CLOCK, idle))
+        if lock_len >= 3:
+            half = (lock_len - 1) // 2
+            lock = (part[0], part[1:1 + half], part[1 + half:])
+        return Slot(slot=n, wire_fn=wire_fn, pins=(swdio, swclk), name=name, attach=_name(ATTACH, attach), retry_s=retry_s,
+                    mechanism=_name(MECHANISM, mech), lock=lock, max_speed=max_speed, idle_clock=_name(IDLE_CLOCK, idle))
     if tag == ITEM["bind"] and len(v) >= 4:
         port, mode, selected, n = struct.unpack_from("<BBBB", v)
         streams = [(_name(STREAM, v[4 + 3 * k]), struct.unpack_from("<H", v, 5 + 3 * k)[0]) for k in range(n)]
-        return Bind(port, _name(MODE, mode), streams, selected)
+        return Bind(port=port, mode=_name(MODE, mode), streams=streams, selected=selected)
     return (tag, v)
 
 
@@ -170,6 +174,7 @@ class State:
     storage_bytes: int = 0
     storage: str = "none"          # none, applied, unreadable
     saved_hash: int = 0
+    unreadable: str | None = None  # why, when unreadable (probe.config §4)
     items: list[int] = field(default_factory=list)
     slots_max: int = 0
     bind_modes: list[str] = field(default_factory=list)
@@ -216,6 +221,8 @@ class ProbeConfig(Interface):
             if tag == DESCRIBE["storage"] and len(v) >= 9:
                 st.storage_bytes, state, st.saved_hash = struct.unpack_from("<IBI", v)
                 st.storage = STORAGE_STATE.get(state, str(state))
+                if len(v) >= 14 and v[13]:
+                    st.unreadable = UNREADABLE.get(v[13], str(v[13]))
             elif tag == DESCRIBE["items"]:
                 st.items = list(v)
             elif tag == DESCRIBE["slots_max"] and v:

{oep_client_python-0.0.18 → oep_client_python-0.0.19}/src/oep_client/console.py

@@ -65,7 +65,7 @@ class PositionStream(Interface):
         """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)]
+        marks = [Mark(*rd.element().take("IQBIB")) for _ in range(count)]
         rd.tail()
         return marks, bool(more)
 

{oep_client_python-0.0.18 → oep_client_python-0.0.19}/src/oep_client/decode.py

@@ -1,4 +1,4 @@
-"""Host-side decoders for capture channels (oep.fixture.capture: `LogicCapture.channel(data, k)` gives one value
+"""Host-side decoders for capture channels (oep.fixture.logic: `LogicCapture.channel(data, k)` gives one value
 per sample)."""
 
 from __future__ import annotations