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

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

@@ -2,6 +2,60 @@
 
 ## Unreleased
 
+## 0.0.54
+- (EN) Jobs (oep::SimpleInterface::job, the probe's worker): `oep_client.call.call_wait(hst, interface, op, timeout=,
+  wait=, **fields)` starts the job and reads its status op until it ends; it returns the status's fields (start_ns,
+  end_ns on the probe's clock) or raises `JobFailed` (code, message), `JobCancelled`, `JobTimeout` (a cancel sent
+  first) or `ProbeRestarted` (the boot_id changed). `wait(seconds)` is called between the reads (a stream's wait keeps
+  a capture going). `oep call ... --wait S` does the same from the command line.
+- (JA) ジョブ（oep::SimpleInterface::job、プローブのワーカー）: `oep_client.call.call_wait(hst, interface, op, timeout=,
+  wait=, **欄)` はジョブを始め、終わるまで status の op を読む。status の欄（プローブの時計の start_ns、end_ns）を返すか、
+  `JobFailed`（番号、文）、`JobCancelled`、`JobTimeout`（先に cancel を送る）、`ProbeRestarted`（boot_id が変わった）を投げる。
+  読む間に `wait(秒)` を呼ぶ（流し続けの wait なら取り込みが続く）。コマンドラインは `oep call ... --wait S`。
+- (EN) Any interface's op from the command line and Python: `oep call PROBE INTERFACE OP [ARGS...]` - by number with
+  the request as hex bytes, or by the name and fields its describe gives (oep-spec core §7.4 op_name / op_field,
+  draft e392ad5): `oep call oep://… io.github.you.mine add a=2 b=3` -> `completed  rev 1  sum=5`. Python:
+  `oep_client.call.call(hst, interface, op, payload=None, **fields)` returns the success fields by name (a dict and
+  attributes, `.revision`, `.payload`); `CommandRejected`, `CommandFailed` (code and message), and `InterfaceMissing` /
+  `RevisionMismatch` / `OpMissing`, all `NotOffered` for a test's skip. `oep dump` shows an op's signature
+  (`add(a: i32, b: i32) -> sum: i32`). The virtual bench's stand-in fn gives its two ops' names and fields. Registry,
+  vectors and the reviewed digests synced from oep-spec e392ad5 (the core's §7.4 tags and transports §3.1
+  usb.transports: the virtual bench knows the item).
+- (JA) どのインターフェースの op もコマンドラインと Python から呼べる: `oep call PROBE INTERFACE OP [ARGS...]`。番号と 16 進の
+  要求で、または describe が示す名前と欄で（oep-spec core §7.4 op_name / op_field、案 e392ad5）:
+  `oep call oep://… io.github.you.mine add a=2 b=3` → `completed  rev 1  sum=5`。Python は
+  `oep_client.call.call(hst, interface, op, payload=None, **fields)` で、成功の欄を名前で返す（辞書と属性、`.revision`、
+  `.payload`）。`CommandRejected`、`CommandFailed`（番号と文）、`InterfaceMissing` / `RevisionMismatch` / `OpMissing`（どれも
+  `NotOffered`: 試験の skip に）。`oep dump` は op の形（`add(a: i32, b: i32) -> sum: i32`）を出す。仮想ベンチの代役の fn は
+  2 つの op の名前と欄を持つ。registry、ベクタ、確かめた文書のダイジェストを oep-spec e392ad5 に合わせた（core §7.4 のタグと
+  transports §3.1 の usb.transports。仮想ベンチはその項目を知る）。
+
+## 0.0.53
+- (EN) An RP2040 board as a test's peer over an OEP probe's SWD alone (`oep_client.rp2040_peer`), for a peer whose USB goes to
+  the device under test: `python -m oep_client.rp2040_peer flash oep://<probe>/<port> <elf|bin>` (the port's labels
+  `<port>.swdio` / `<port>.swclk`; through ch32rv's broker sharing its lock when it runs, found with `$CH32RV`; the old
+  image's SEGGER RTT IDs left in RAM are wiped before the reboot, so the console finds the new one's), the console as
+  SEGGER RTT through the MEM-AP (`console`, and pyserial's `oep://` handler in `oep_client.pyserial`), and
+  `pytest_plugins = ["oep_client.pytest_rp2040_peer"]` for pytest-embedded-arduino-cli: arduino-pico's OpenOCD upload
+  (`uploadmethod=picoprobe_cmsis_dap`) handed to the writer through generated hook files, the peer's own device lock,
+  the DUT's ch32rv passed on.
+- (JA) RP2040 の基板を、OEP のプローブの SWD だけで試験の相手（peer）にする（`oep_client.rp2040_peer`）。USB を DUT に
+  つなぐ相手のため。`python -m oep_client.rp2040_peer flash oep://<probe>/<port> <elf|bin>`（口のラベル `<port>.swdio` /
+  `<port>.swclk`。ch32rv の broker が動いていれば、そのロックに相乗りする。broker は `$CH32RV` で探す。RAM に残った前の
+  イメージの SEGGER RTT の ID は起動し直す前に消し、コンソールが新しいものを見つけるようにする）、コンソールは
+  MEM-AP の上の SEGGER RTT（`console`、pyserial の `oep://` の handler は `oep_client.pyserial`）。pytest-embedded-arduino-cli
+  には `pytest_plugins = ["oep_client.pytest_rp2040_peer"]`: arduino-pico の OpenOCD の書き込み（`uploadmethod=picoprobe_cmsis_dap`）
+  を、書き出した hook のファイルで書き込みの道具に渡す。peer のロックは自分のもの。DUT の ch32rv を引き渡す。
+- (EN) `rp2040`: the RP2040's flash written over SWD through its boot ROM (`rom_table_lookup` at 0x18 on the function
+  table at 0x14), the sequence shared with `rp2350.Flash` (which now takes another chip's ROM lookup and spare RAM), and
+  a reboot by the watchdog the pico-sdk's way (PSM WDSEL all but the oscillators, SCRATCH4 0: left as it comes, the
+  trigger restarted nothing). `arm.CortexM.reset_halt()`: reset the core and stop on its first instruction (a core
+  locked up in a fault handler is no place to call the ROM from).
+- (JA) `rp2040`: RP2040 の flash を SWD でブート ROM から書く（関数表は 0x14、`rom_table_lookup` は 0x18）。手順は `rp2350.Flash` と
+  共通にし、Flash はほかのチップの ROM の引き方と空いている RAM を受け取れるようにした。起動し直しは pico-sdk と同じウォッチドッグの
+  手順（PSM の WDSEL を発振器以外すべて、SCRATCH4 を 0。そのままではトリガしても何も起動し直さなかった）。`arm.CortexM.reset_halt()`:
+  コアをリセットして最初の命令で止める（fault の処理の途中で lockup したコアからは ROM を呼べない）。
+
 ## 0.0.52
 - (EN) Capture format 1 is per-channel reductions (oep-spec 165a278, capture §1.3): `LogicCapture.configure(...,
   carriage={role: (carriage, D)})` with capture_blocks.SAMPLE / ANY_HIGH / ANY_LOW / CHANGE_LATCH (the `events`

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

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

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

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

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

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

{oep_client_python-0.0.52 → oep_client_python-0.0.54}/src/oep_client/__main__.py

@@ -125,6 +125,17 @@ def main(argv=None) -> int:
     rs.add_argument("--reopen-s", type=float, default=0.0, metavar="S",
                     help="when the probe is not back within its restart_max_ms, open it again for up to S more seconds "
                          "(your reopen: a host where the device returns late, e.g. WSL re-attaching it through usbipd)")
+    ca = sub.add_parser("call", help="run any interface's op: by number with the request as hex bytes, or by the name and "
+                                     "fields its describe gives (core §7.4 op_name / op_field)")
+    ca.add_argument("probe", help="a probe: oep://UNIT_ID[?via=...], a serial port, tcp://HOST:PORT or usb")
+    ca.add_argument("interface", help="the interface's name (io.github.you.thing); its fn is looked up")
+    ca.add_argument("op", help="the op: a number (0x10) or its name")
+    ca.add_argument("args", nargs="*", help="NAME=VALUE per field (integers 10 or 0x, bools true / false, lists 1,2,3, "
+                                             "bytes hex, text as it is), or the request as hex bytes")
+    ca.add_argument("--text", action="store_true", help="the request is ARGS joined by spaces, as UTF-8 bytes")
+    ca.add_argument("--wait", type=float, metavar="S", help="the op is a job (oep::SimpleInterface::job): wait up to S "
+                                                            "seconds for it by the interface's status op, then show that")
+    ca.add_argument("--json", action="store_true")
     fd = sub.add_parser("find", help="probes on the local network that announce _oep._tcp (DNS-SD over mDNS)")
     fd.add_argument("--timeout", type=float, default=2.0, help="seconds to listen for answers (default 2)")
     fd.add_argument("--engine", choices=("auto", "zeroconf", "minimal"), default="auto",
@@ -157,6 +168,8 @@ def main(argv=None) -> int:
         return _restart_cmd(args)
     if args.command == "find":
         return _find_cmd(args)
+    if args.command == "call":
+        return _call_cmd(args)
 
     confirm = (0, 1)
     if args.virtual:
@@ -237,6 +250,82 @@ def _restart_cmd(args) -> int:
     return 0
 
 
+# ---- oep call -----------------------------------------------------------------------------------------------------
+
+def _field_value(field, text: str):
+    from . import call as c
+    t = field.type
+    if t & c.LIST:
+        items = [x for x in text.replace(" ", "").split(",") if x]
+        return [(x.lower() in ("1", "true")) if (t & ~c.LIST) == c.T["bool"] else int(x, 0) for x in items]
+    if t == c.T["bool"]:
+        if text.lower() not in ("0", "1", "true", "false"):
+            raise SystemExit(f"oep call: {field.name} takes true or false")
+        return text.lower() in ("1", "true")
+    if t == c.T["bytes"]:
+        return bytes.fromhex(text)
+    if t == c.T["text"]:
+        return text
+    return int(text, 0)
+
+
+def _call_cmd(args) -> int:
+    import json
+    from . import call as c
+    hst = _open_host(args.probe)
+    try:
+        forms = c.ops(hst, args.interface)
+    except c.NotOffered as e:
+        raise SystemExit(f"oep call: {e}") from None
+    op: int | str = int(args.op, 0) if args.op[:1].isdigit() else args.op
+    form = forms.get(op) if isinstance(op, int) else next((f for f in forms.values() if f.name == op), None)
+    payload, fields = None, {}
+    if args.text:
+        payload = " ".join(args.args).encode()
+    elif form is not None and form.form and (any("=" in a for a in args.args) or not args.args):
+        by_name = {f.name: f for f in form.request}
+        for item in args.args:
+            name, eq, value = item.partition("=")
+            if not eq or name not in by_name:
+                raise SystemExit(f"oep call: {form.signature()}: give NAME=VALUE for its fields ({item!r})")
+            fields[name] = _field_value(by_name[name], value)
+    else:
+        try:
+            payload = bytes.fromhex("".join(args.args))
+        except ValueError:
+            raise SystemExit("oep call: the request as hex bytes (its describe gives this op no fields)") from None
+    if not (form is not None and form.lock_free):
+        core.take(hst, 10000 + int((args.wait or 0) * 1000), owner="oep call")   # a job's wait inside the lease
+    try:
+        if args.wait is not None:
+            r = c.call_wait(hst, args.interface, op, payload, timeout=args.wait, **fields)
+        else:
+            r = c.call(hst, args.interface, op, payload, **fields)
+    except (c.JobFailed, c.JobCancelled, c.JobTimeout, c.ProbeRestarted) as e:
+        st = getattr(e, "status", {})
+        print(json.dumps({"result": type(e).__name__, "why": str(e), "status": st}, default=str) if args.json
+              else f"{type(e).__name__}  {e}")
+        return 1
+    except TypeError as e:
+        raise SystemExit(f"oep call: {e}") from None
+    except c.NotOffered as e:
+        raise SystemExit(f"oep call: {e}") from None
+    except c.CommandFailed as e:
+        out = {"result": "failed", "op": e.op, "fields": e.fields, "payload": e.payload.hex()}
+        print(json.dumps(out, default=str) if args.json else f"failed  {e}" + ("" if e.fields else f"  {e.payload.hex()}"))
+        return 1
+    except c.CommandRejected as e:
+        print(json.dumps({"result": "rejected", "op": e.op, "why": str(e)}) if args.json else f"rejected  {e}")
+        return 1
+    shown = {k: (v.hex() if isinstance(v, bytes) else v) for k, v in r.items()}
+    if args.json:
+        print(json.dumps({"result": "completed", "revision": r.revision, "fields": shown, "payload": r.payload.hex()}))
+    else:
+        body = "  ".join(f"{k}={v}" for k, v in shown.items()) if shown or (form and form.form) else r.payload.hex()
+        print(f"completed  rev {r.revision}  {body}".rstrip())
+    return 0
+
+
 # ---- oep pins -----------------------------------------------------------------------------------------------------
 
 def _pins_cmd(args) -> int:

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

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

oep_client_python-0.0.54/src/oep_client/call.py

@@ -0,0 +1,284 @@
+"""Call any interface's op by its number, or by the name and fields its describe gives (oep-core §7.4 op_name /
+op_field) - an interface this host has no module for, such as a sketch's oep::SimpleInterface.
+
+    from oep_client import link, core
+    from oep_client.call import call
+    hst = link.open_host("/dev/ttyACM0")
+    core.take(hst, 10000, owner="my-test")
+    r = call(hst, "io.github.yourname.mine", "add", a=2, b=3)
+    r["sum"], r.sum, r.revision                     # the success fields by name; the interface's revision
+    call(hst, "io.github.yourname.mine", 0x10, b"\\x02\\0\\0\\0\\x03\\0\\0\\0").payload   # by number, the bytes as they are
+
+Errors: InterfaceMissing / RevisionMismatch / OpMissing (all NotOffered: a test can turn them into a skip),
+CommandRejected (the probe refused it: the reason), CommandFailed (completed failed: code and message when the op
+gives them).
+
+A job (oep::SimpleInterface::job: it starts work on the probe's worker and answers at once) and its status op:
+
+    st = call_wait(hst, "io.github.yourname.mine", "collect", count=3, timeout=10)
+    st.start_ns, st.end_ns                          # on the probe's clock (a capture's markers' one)
+    # wait=: a stream's wait (acquire.Request(during=...)) keeps the capture collecting while this waits
+
+JobFailed (the job's Worker::fail: code, message), JobCancelled, JobTimeout (cancel sent first), ProbeRestarted (its
+boot_id changed while the job ran)."""
+
+from __future__ import annotations
+
+import struct
+import time
+from typing import Any, Callable
+
+from . import catalog, core, host as h
+
+T = catalog.OP_FIELD_TYPES
+LIST = catalog.OP_FIELD_LIST
+_INT = {T["u8"]: "<B", T["u16"]: "<H", T["u32"]: "<I", T["u64"]: "<Q",
+        T["i8"]: "<b", T["i16"]: "<h", T["i32"]: "<i", T["i64"]: "<q", T["bool"]: "<B"}
+
+
+class NotOffered(LookupError):
+    """The probe does not offer what was asked: no such interface, another revision, no such op."""
+
+
+class InterfaceMissing(NotOffered):
+    pass
+
+
+class RevisionMismatch(NotOffered):
+    def __init__(self, interface: str, revision: int, wanted: int):
+        super().__init__(f"{interface} is revision {revision} on this probe, {wanted} asked")
+        self.revision, self.wanted = revision, wanted
+
+
+class OpMissing(NotOffered):
+    pass
+
+
+class CommandRejected(h.Rejected):
+    """The probe refused the op (resolution rejected): `result.detail` is the reason (core §4.3)."""
+
+    def __init__(self, op: str, result):
+        super().__init__(result)
+        self.op = op
+        self.args = (f"{op}: {result.describe()}",)
+
+
+class CommandFailed(h.Failed):
+    """The op ran and did not work (completed failed / partial): `fields` the failed part decoded (code, message for
+    an oep::SimpleInterface op), `payload` the bytes."""
+
+    def __init__(self, op: str, result, fields: dict | None):
+        why = f"{op}: {result.describe()}"
+        if fields and "code" in fields:
+            why += f" (code {fields['code']}" + (f": {fields['message']}" if fields.get("message") else "") + ")"
+        super().__init__(result, why)
+        self.op, self.fields, self.payload = op, fields or {}, result.payload
+        self.code, self.message = self.fields.get("code"), self.fields.get("message")
+
+
+class JobFailed(h.OepError):
+    """The job ended failed: `code` and `message` from its Worker::fail(), `status` the status op's fields."""
+
+    def __init__(self, op: str, status: dict):
+        super().__init__(f"{op}: failed (code {status.get('code')}"
+                         + (f": {status['message']}" if status.get("message") else "") + ")")
+        self.op, self.status, self.code, self.message = op, status, status.get("code"), status.get("message")
+
+
+class JobCancelled(h.OepError):
+    """The job stopped on a cancel (`status` the status op's fields)."""
+
+    def __init__(self, op: str, status: dict):
+        super().__init__(f"{op}: cancelled")
+        self.op, self.status = op, status
+
+
+class JobTimeout(h.OepError, TimeoutError):
+    """The job still ran at the timeout; a cancel was sent (`status` the last status op's fields)."""
+
+    def __init__(self, op: str, timeout: float, status: dict):
+        super().__init__(f"{op}: still running after {timeout} s (cancel sent)")
+        self.op, self.status = op, status
+
+
+class ProbeRestarted(h.OepError):
+    """The probe's boot_id changed while the job ran (core §6.5): it restarted, the job with it."""
+
+
+# The status op's state (oep::Worker::State): the firmware's convention, not the registry's
+JOB_STATES = {"idle": 0, "running": 1, "done": 2, "failed": 3, "cancelled": 4}
+
+
+class CallResult(dict):
+    """The success fields by name (a dict, and attributes), the raw payload, the interface's revision and the op."""
+
+    def __init__(self, fields: dict, payload: bytes, revision: int, op: catalog.OpForm | int):
+        super().__init__(fields)
+        self.payload, self.revision, self.op = payload, revision, op
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self[name]
+        except KeyError:
+            raise AttributeError(name) from None
+
+
+def encode(fields: list[catalog.OpField], values: dict) -> bytes:
+    """A request's fixed part from values by field name (ints, bools, bytes, str, lists of ints / bools)."""
+    missing = [f.name for f in fields if f.name not in values]
+    extra = sorted(set(values) - {f.name for f in fields})
+    if missing or extra:
+        raise TypeError(f"fields {', '.join(f'{f.name}: {f.type_name}' for f in fields) or 'none'}"
+                        + (f"; missing {missing}" if missing else "") + (f"; not fields {extra}" if extra else ""))
+    out = b""
+    for f in fields:
+        v = values[f.name]
+        if f.type & LIST:
+            items = list(v)
+            out += struct.pack("<H", len(items)) + b"".join(struct.pack(_INT[f.type & ~LIST], int(x)) for x in items)
+        elif f.type == T["bytes"]:
+            b = bytes(v)
+            out += struct.pack("<H", len(b)) + b
+        elif f.type == T["text"]:
+            b = str(v).encode()
+            out += struct.pack("<H", len(b)) + b
+        elif f.type in _INT:
+            out += struct.pack(_INT[f.type], int(v))
+        else:
+            raise TypeError(f"{f.name}: type {f.type} unknown to this host")
+    return out
+
+
+def decode(fields: list[catalog.OpField], payload: bytes) -> tuple[dict, bytes]:
+    """A fixed part's fields by name, and what follows them (the TLVs)."""
+    out, at = {}, 0
+    for f in fields:
+        if f.type & LIST:
+            (n,) = struct.unpack_from("<H", payload, at)
+            fmt = _INT[f.type & ~LIST]
+            w = struct.calcsize(fmt)
+            vals = [struct.unpack_from(fmt, payload, at + 2 + i * w)[0] for i in range(n)]
+            out[f.name] = [bool(x) for x in vals] if (f.type & ~LIST) == T["bool"] else vals
+            at += 2 + n * w
+        elif f.type in (T["bytes"], T["text"]):
+            (n,) = struct.unpack_from("<H", payload, at)
+            if at + 2 + n > len(payload):
+                raise h.ShortPayload(f"{f.name}: {n} bytes, the answer ends before")
+            raw = payload[at + 2:at + 2 + n]
+            out[f.name] = raw.decode("utf-8", "replace") if f.type == T["text"] else raw
+            at += 2 + n
+        else:
+            fmt = _INT[f.type]
+            out[f.name] = struct.unpack_from(fmt, payload, at)[0]
+            if f.type == T["bool"]:
+                out[f.name] = bool(out[f.name])
+            at += struct.calcsize(fmt)
+    return out, payload[at:]
+
+
+def ops(hst: h.Host, interface: str | int) -> dict[int, catalog.OpForm]:
+    """The op_name / op_field an interface's describe gives (by op number; empty when it gives none)."""
+    fn = interface if isinstance(interface, int) else _fn(hst, interface)
+    return catalog.decode_description(b"".join(catalog.tlv(t, v) for t, v in core.describe(hst, fn))).op_forms
+
+
+def _fn(hst: h.Host, interface: str) -> int:
+    try:
+        return core.find(hst, interface)
+    except LookupError as e:
+        raise InterfaceMissing(str(e)) from None
+
+
+def call(hst: h.Host, interface: str, op: int | str, payload: bytes | None = None, *, locked: bool | None = None,
+         revision: int | None = None, expect_ms: int = 0, **fields) -> CallResult:
+    """Run `op` (a number, or a name from the describe's op_name) of `interface` on the session `hst` holds.
+    payload: the request as bytes (then no fields); otherwise the fields by name, packed as op_field says.
+    locked: send it in the session (default: unless op_name says lock_free). revision: the one expected."""
+    fn = _fn(hst, interface)
+    rev = core.revision(hst, interface, fn)
+    if revision is not None and rev != revision:
+        raise RevisionMismatch(interface, rev, revision)
+    forms = ops(hst, fn)
+    if isinstance(op, str):
+        form = next((f for f in forms.values() if f.name == op), None)
+        if form is None:
+            raise OpMissing(f"{interface} has no op named {op!r}" + (f" (it names {', '.join(f.name for f in forms.values())})"
+                                                                     if forms else " (its describe names none)"))
+        code = form.op
+    else:
+        code, form = op, forms.get(op)
+    label = form.name if form else f"0x{code:02x}"
+    if not core.offers(hst, fn, code):
+        raise OpMissing(f"{interface} does not offer op {label}")
+    if payload is None:
+        if fields:
+            if form is None or not form.form:
+                raise TypeError(f"{interface} {label}: its describe gives no fields; pass payload= as bytes")
+            payload = encode(form.request, fields)
+        elif form is not None and form.form and form.request:
+            payload = encode(form.request, fields)        # raises: the fields it needs
+        else:
+            payload = b""
+    elif fields:
+        raise TypeError("payload= or fields, not both")
+    if locked is None:
+        locked = not (form is not None and form.lock_free)
+    try:
+        r = hst.request(fn, code, payload, locked=locked, expect_ms=expect_ms)
+    except h.Rejected as e:
+        raise CommandRejected(label, e.result) from None
+    if r.succeeded:
+        got = decode(form.success, r.payload)[0] if form is not None and form.form else {}
+        return CallResult(got, r.payload, rev, form or code)
+    failed = None
+    if r.ran and form is not None and form.form and form.failed:
+        try:
+            failed = decode(form.failed, r.payload)[0]
+        except (struct.error, h.ShortPayload):
+            failed = None                                  # a failed answer without its fields (a firmware bug)
+    raise CommandFailed(label, r, failed)
+
+
+def call_wait(hst: h.Host, interface: str, op: int | str, payload: bytes | None = None, *, timeout: float,
+              wait: Callable[[float], None] | None = None, interval: float = 0.05, status: str = "status",
+              cancel: str = "cancel", revision: int | None = None, **fields) -> CallResult:
+    """Start the job `op` (as call()) and wait for it by its `status` op: the status's fields when it ended done.
+    wait(seconds) sleeps between the status reads (time.sleep by default; a stream's wait keeps a capture going)."""
+    boot = hst.clock().boot_id
+    started = call(hst, interface, op, payload, revision=revision, **fields)
+    code = started.op.op if isinstance(started.op, catalog.OpForm) else started.op
+    label = started.op.name if isinstance(started.op, catalog.OpForm) else f"0x{code:02x}"
+    pause = wait or time.sleep
+    deadline = time.monotonic() + timeout
+    while True:
+        try:
+            st = call(hst, interface, status)
+        except (h.OepError, OSError):
+            _restarted(hst, boot, label)
+            raise
+        if st["op"] != code or st["state"] == JOB_STATES["idle"]:
+            _restarted(hst, boot, label)
+            raise ProbeRestarted(f"{label}: the status names op {st['op']} in state {st['state']}, not this job")
+        if st["state"] != JOB_STATES["running"]:
+            break
+        if time.monotonic() >= deadline:
+            try:
+                call(hst, interface, cancel)
+            except (h.OepError, OSError):
+                pass                                       # the timeout is the error to report
+            raise JobTimeout(label, timeout, dict(st))
+        pause(interval)
+    if st["state"] == JOB_STATES["failed"]:
+        raise JobFailed(label, dict(st))
+    if st["state"] == JOB_STATES["cancelled"]:
+        raise JobCancelled(label, dict(st))
+    return st
+
+
+def _restarted(hst: h.Host, boot: int, label: str) -> None:
+    try:
+        now = hst.clock().boot_id
+    except (h.OepError, OSError):
+        return
+    if now != boot:
+        raise ProbeRestarted(f"{label}: the probe restarted while the job ran (boot_id {boot:#x} -> {now:#x})")

{oep_client_python-0.0.52 → oep_client_python-0.0.54}/src/oep_client/catalog.py

@@ -32,6 +32,13 @@ MIN_CLOCK_HZ = _COMMON["min_clock_hz"]     # u32
 FEATURES = _COMMON["features"]             # u32, bits defined by the interface
 CHANNEL_GROUP = _COMMON["channel_group"]   # group(u8) n(u8) then n x (role(u8), channel(u16)): a fixed pin set
 OPS = _COMMON["ops"]                       # base(u8) bitmap: the ops this fn offers (core §1.2, §7.4)
+OP_NAME = _COMMON["op_name"]               # op(u8) flags(u8) name: an op's name (core §7.4, optional)
+OP_FIELD = _COMMON["op_field"]             # op(u8) part(u8) type(u8) name: one field of an op's fixed part (core §7.4)
+OP_NAME_FORM = reg.CORE.enum["op_name_flag"]["form"]
+OP_NAME_LOCK_FREE = reg.CORE.enum["op_name_flag"]["lock_free"]
+OP_FIELD_PARTS = reg.CORE.enum["op_field_part"]          # request / success / failed
+OP_FIELD_TYPES = reg.CORE.enum["op_field_type"]          # u8 ... text, and the list bit
+OP_FIELD_LIST = OP_FIELD_TYPES["list"]
 assert OPS == m.TAG_OPS
 CRITICAL = 0x80
 INTERFACE_TAG_FIRST = 0x40
@@ -197,6 +204,50 @@ def text(tag: int, s: str) -> bytes:
     return tlv(tag, s.encode("ascii"))
 
 
+class OpField:
+    """One field of an op's fixed part (core §7.4 op_field): its name and type (registry op_field_type)."""
+
+    def __init__(self, name: str, type: int):
+        self.name, self.type = name, type
+
+    @property
+    def type_name(self) -> str:
+        names = {v: k for k, v in OP_FIELD_TYPES.items() if k != "list"}
+        base = self.type & ~OP_FIELD_LIST
+        label = names.get(base, f"type{base}")
+        return label + "[]" if self.type & OP_FIELD_LIST else label
+
+    def __repr__(self) -> str:
+        return f"{self.name}: {self.type_name}"
+
+
+@dataclass
+class OpForm:
+    """An op's name and, with form, its request / success / failed fixed parts' fields (core §7.4)."""
+
+    op: int
+    name: str
+    flags: int
+    request: list[OpField] = field(default_factory=list)
+    success: list[OpField] = field(default_factory=list)
+    failed: list[OpField] = field(default_factory=list)
+
+    @property
+    def form(self) -> bool:
+        return bool(self.flags & OP_NAME_FORM)
+
+    @property
+    def lock_free(self) -> bool:
+        return bool(self.flags & OP_NAME_LOCK_FREE)
+
+    def signature(self) -> str:
+        """measure(mode: u8) -> temp: i32, hum: u32 (the name alone without form)"""
+        if not self.form:
+            return self.name
+        s = f"{self.name}({', '.join(map(repr, self.request))})"
+        return s + (" -> " + ", ".join(map(repr, self.success)) if self.success else "")
+
+
 @dataclass
 class Description:
     """Common tags decoded; interface-specific and unknown tags kept raw, in order."""
@@ -212,11 +263,13 @@ class Description:
     specific: list[tuple[int, bytes]] = field(default_factory=list)
     unknown_critical: list[int] = field(default_factory=list)
     broken: list[int] = field(default_factory=list)   # common tags whose value is not their defined length (not used)
+    op_forms: dict[int, OpForm] = field(default_factory=dict)   # op -> its op_name / op_field (core §7.4)
 
 
 def decode_description(data: bytes) -> Description:
     d = Description()
     seen: set[int] = set()
+    fields: list[tuple[int, int, int, str]] = []         # op_field (op, part, type, name), in the describe's order
     for tag, value in split_tlv(data):
         if tag & CRITICAL:
             continue                                # bit 7 in an answer: an unknown tag, skipped (core §2.2)
@@ -248,11 +301,28 @@ def decode_description(data: bytes) -> Description:
                 d.ops_invalid = why
             else:
                 d.ops = unpack_ops(value)
+        elif t == OP_NAME:
+            if len(value) < 3:
+                d.broken.append(tag)
+                continue
+            if value[0] in d.op_forms:
+                continue                                    # a second op_name for an op: the first is used
+            d.op_forms[value[0]] = OpForm(value[0], value[2:].decode("ascii", "replace"), value[1])
+        elif t == OP_FIELD:
+            if len(value) < 4:
+                d.broken.append(tag)
+                continue
+            fields.append((value[0], value[1], value[2], value[3:].decode("ascii", "replace")))
         elif t >= INTERFACE_TAG_FIRST:
             d.specific.append((tag, value))
         elif tag & CRITICAL:
             d.unknown_critical.append(tag)
         # an unknown non-critical common tag is skipped
+    parts = {OP_FIELD_PARTS["request"]: "request", OP_FIELD_PARTS["success"]: "success", OP_FIELD_PARTS["failed"]: "failed"}
+    for op, part, type_, name in fields:                   # only an op named with form takes its fields
+        form = d.op_forms.get(op)
+        if form is not None and form.form and part in parts:
+            getattr(form, parts[part]).append(OpField(name, type_))
     for role in d.roles:
         d.roles[role] = sorted(set(d.roles[role]))
     if d.ops_invalid:

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

@@ -145,7 +145,7 @@ def checker_sources_sha256():
             for name in CHECKER_SOURCES}
 
 
-REVIEWED_CORE_SHA256 = '0408d232e728bb9692ab1c24cefa1fdbf109c35aeebd378034d86c0f4d19789a'   # oep-spec docs/oep-core.ja.md
+REVIEWED_CORE_SHA256 = '81cffc532f2626812b109d0aa5eef81636799011f410a8bc2fb9ea520fcbf4bc'   # oep-spec docs/oep-core.ja.md
 
 
 def require_reviewed_contract(registry, spec=None):

{oep_client_python-0.0.52 → oep_client_python-0.0.54}/src/oep_client/conformance/core_smoke.py

@@ -8,7 +8,7 @@ import struct
 from . import ops, require, tlvs
 from .. import conformance as _helpers
 
-REVIEWED_CORE_SHA256 = '0408d232e728bb9692ab1c24cefa1fdbf109c35aeebd378034d86c0f4d19789a'  # oep-spec docs/oep-core.ja.md
+REVIEWED_CORE_SHA256 = '81cffc532f2626812b109d0aa5eef81636799011f410a8bc2fb9ea520fcbf4bc'  # oep-spec docs/oep-core.ja.md
 
 
 class CoreSmokeChecks:

{oep_client_python-0.0.52 → oep_client_python-0.0.54}/src/oep_client/conformance/host_core.py

@@ -4,7 +4,7 @@ from pathlib import Path
 import struct
 from . import require,spec_identity
 
-REVIEWED_CORE_SHA256='0408d232e728bb9692ab1c24cefa1fdbf109c35aeebd378034d86c0f4d19789a'
+REVIEWED_CORE_SHA256='81cffc532f2626812b109d0aa5eef81636799011f410a8bc2fb9ea520fcbf4bc'
 CORE_OPS={'confirm':1,'list':2,'describe':3,'clock':4,'open':16,'end':17,'keepalive':18,'lock_state':19}
 # the settings' ops (core §13.5 / §13.7, transports §7.3): their numbers reviewed, their results not read here
 SETTINGS_OPS={'get':32,'set':33,'unset':34,'save':35,'state':36,'network':37}

{oep_client_python-0.0.52 → oep_client_python-0.0.54}/src/oep_client/conformance/host_deadline.py

@@ -9,8 +9,8 @@ from pathlib import Path
 from . import require,spec_identity
 
 
-REVIEWED={'docs/oep-core.ja.md':'0408d232e728bb9692ab1c24cefa1fdbf109c35aeebd378034d86c0f4d19789a',
-          'docs/oep-transports.ja.md':'2e99bf8039a3d8f5b55c80b66ac97ac40ddf7ad4711079177ffc947c5790103f'}
+REVIEWED={'docs/oep-core.ja.md':'81cffc532f2626812b109d0aa5eef81636799011f410a8bc2fb9ea520fcbf4bc',
+          'docs/oep-transports.ja.md':'a22754ee25997058be0e698bd62ea132537627914f38a06caffd48e3d79f096e'}
 QUICK_MS=1000  # core_quick_op_max_ms