oep-client-python 0.0.18__py3-none-any.whl → 0.0.20__py3-none-any.whl

oep_client/__init__.py

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

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/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/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/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/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/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)
 
@@ -136,10 +136,12 @@ class StreamIO:
         self.lost = 0
 
     def _limits(self) -> tuple[int, int]:
-        """(read, write) chunk sizes that fit the probe's frame: request header 6 + session 4 + stream 1 + count 2,
-        result header 5 + start 8 + flags 1."""
+        """(read, write) chunk sizes that fit the probe's frame: a write is request header 6 + session 4 + the stream's
+        prefix (the console's stream u16, none on a fixture UART) + count 2; a read's result is header 5 + start 8 +
+        flags 1. (The write was frame - 13 for both: one byte over on the console's 64-byte frames.)"""
         frame = self.source.host.confirmed()["max_frame"]
-        return max(1, min(self.MAX_READ, frame - 14)), max(1, min(self.MAX_WRITE, frame - 13))
+        write = frame - 12 - len(self.source._stream_prefix())
+        return max(1, min(self.MAX_READ, frame - 14)), max(1, min(self.MAX_WRITE, write))
 
     def read(self, n: int = 512) -> bytes:
         c = self.source.read_from(self.position, min(n, self._limits()[0]))

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

oep_client/endpoint.py

@@ -68,6 +68,25 @@ class Reject(Exception):
         self.reason, self.payload = reason, payload
 
 
+_UNA = reg.CORE.tlv["unavailable_payload"]
+UNAVAILABLE_CAUSE, HOLDER_KIND = reg.CORE.enum["unavailable_cause"], reg.CORE.enum["holder_kind"]
+
+
+def unavailable(cause: str | None = None, channel: int | None = None, holder_fn: int | None = None,
+                holder_kind: str | None = None, extra: bytes = b"") -> Reject:
+    """rejected unavailable with core §4.3's payload: why, the channel, who holds it (each optional)."""
+    body = b""
+    if cause:
+        body += m.tlv(_UNA["cause"], bytes([UNAVAILABLE_CAUSE[cause]]))
+    if channel is not None:
+        body += m.tlv(_UNA["channel"], struct.pack("<H", channel))
+    if holder_fn is not None:
+        body += m.tlv(_UNA["holder_fn"], struct.pack("<H", holder_fn))
+    if holder_kind:
+        body += m.tlv(_UNA["holder_kind"], bytes([HOLDER_KIND[holder_kind]]))
+    return Reject(m.UNAVAILABLE, body + extra)
+
+
 class Take:
     """Reads a request's fixed part; too short -> rejected malformed. `tail(known)` applies the request-tail rule."""
 
@@ -241,6 +260,7 @@ class Endpoint:
         self.window, self.max_inflight = window, max_inflight
         self.remember_max = remember_max
         self.names = {o.fn: o.name for o in probe.offered}
+        self.identity = {o.fn: (o.name, o.instance, o.revision) for o in probe.offered}   # what a saved item names
         self.fns = {name: fn for fn, name in sorted(self.names.items(), reverse=True)}   # first fn of each name
         self.static = {o.fn: o.tlvs for o in probe.offered}
         self.static_labels: dict[int, str] = {}
@@ -277,7 +297,7 @@ class Endpoint:
         self.target = next(iter(self.targets.values()), FakeTarget())
         self.captures: dict[int, fake_capture.FakeCapture] = {
             fn: self._capture_from(self.static[fn]) for fn, name in self.names.items()
-            if name in ("oep.fixture.capture", "oep.fixture.analog")}
+            if name in ("oep.fixture.logic", "oep.fixture.analog")}
         self.groups: dict[int, fake_capture.FakeGroup] = {
             fn: self._group_from(self.static[fn]) for fn, name in self.names.items() if name == "oep.fixture.capture-group"}
         self.mechanisms = set()
@@ -329,6 +349,8 @@ class Endpoint:
         self.uart_tx: dict[int, bytearray] = {}        # what a serial port's raw bytes sent out on a fixture UART
         self.config: dict[tuple[int, int], bytes | list[bytes]] = {}   # (item tag, key) -> value (plan: list)
         self.saved: dict | None = getattr(self, "saved", None)
+        self.saved_ids: dict[int, tuple] = getattr(self, "saved_ids", {})   # saved fn -> (name, instance, revision)
+        self.saved_reason = 0                          # why the saved settings were not applied (probe.config §4)
         self.slots: dict[int, Slot] = {}
         self.binds: dict[int, Bind] = {}
         self.slot_rt: dict[int, SlotRuntime] = {}
@@ -338,7 +360,7 @@ class Endpoint:
         self.held_ports: set[int] = set()
         self.session_resets: dict[tuple[int, int], tuple[object, int]] = {}   # stream key -> (sid, position)
         if self.saved is not None:
-            self._apply_config(dict(self.saved), boot=True)
+            self._apply_saved()
 
     @property
     def target_id(self) -> int | None:
@@ -351,7 +373,7 @@ class Endpoint:
     @staticmethod
     def _capture_from(tlvs: list[bytes]) -> fake_capture.FakeCapture:
         """A capture as its describe declares it (modes, the w allowed, the rate range, max_read, the ring)."""
-        d = reg.FIXTURE_CAPTURE.tlv["describe"]
+        d = reg.FIXTURE_LOGIC.tlv["describe"]
         modes, widths, lo, hi, ring, most, fronts = set(), {8}, 1, 1_000_000, 1, 1024, {}
         for t in tlvs:
             tag, v = t[0], t[2:2 + t[1]]
@@ -427,7 +449,7 @@ class Endpoint:
                     cap.slipped = self.capture_slipped
                 return self._answer(cap.answer(settled), ignored)
             if op in (O["start"], O["stop"], O["force"]) and cap.group is not None:
-                raise Reject(m.UNAVAILABLE)                        # bound: the group starts and stops it
+                raise unavailable("bound_in_group")                # bound: the group starts and stops it
             if op == O["start"]:
                 t.tail()
                 self._events(fn, cap.start(self.now()))
@@ -786,7 +808,8 @@ class Endpoint:
                     return m.REJECTED, m.UNSUPPORTED, bytes([tag])
             named = {fn for fn, _, _ in got}
             if named & self.plan_from_config:                       # the settings' plan is the settings' (core §8)
-                raise Reject(m.UNAVAILABLE)
+                raise unavailable("held_by_settings", holder_fn=min(named & self.plan_from_config),
+                                  holder_kind="settings_plan")
             self._check_plan(got)
             self.plan = {a for a in self.plan if a[0] not in named} | set(got)
             return m.COMPLETED, m.SUCCESS, b""
@@ -812,21 +835,31 @@ class Endpoint:
         slot_pins = {p for s in self.slots.values() for p in s.pair if p != 0xFFFF}
         slot_pins |= {p for c in self.conns.values() for p in c.pair if p != 0xFFFF}   # a live connection's pins too
         analog = {fn for fn, cap in self.captures.items() if cap.analog}
+        def held(ch: int, holder: int | None) -> Reject:
+            if holder is not None:
+                return unavailable("pin_in_use", ch, holder, "plan")
+            slot = next((n for n, s in self.slots.items() if ch in s.pair), None)
+            conn = next((c.fn for c in self.conns.values() if ch in c.pair), None)
+            return unavailable("pin_in_use", ch, conn, "slot" if slot is not None else "connection")
         for fn, role, ch in got:
             beside = [f for f, _, c in got if c == ch and f != fn] + [a[0] for a in others if a[2] == ch]
             if fn in analog:   # the analog shares its pin with nothing: another fn's plan, a slot, a connection
-                if role not in self._declared_roles(fn, ch) or beside or ch in slot_pins:
-                    raise Reject(m.UNAVAILABLE)
+                if role not in self._declared_roles(fn, ch):
+                    raise unavailable(channel=ch)
+                if beside or ch in slot_pins:
+                    raise held(ch, beside[0] if beside else None)
                 continue
             if any(f in analog for f in beside):   # nor may anything come onto an analog pin
-                raise Reject(m.UNAVAILABLE)
+                raise held(ch, next(f for f in beside if f in analog))
             if fn in self.captures:
                 if role not in self._declared_roles(fn, ch):
-                    raise Reject(m.UNAVAILABLE)
+                    raise unavailable(channel=ch)
                 continue
             roles = {"oep.fixture.gpio": {1}, "oep.fixture.uart": {1, 2}}.get(self.names.get(fn, ""), set())
-            if role not in roles or any(k[2] == ch for k in kept) or ch in slot_pins:
-                raise Reject(m.UNAVAILABLE)
+            if role not in roles:
+                raise unavailable(channel=ch)
+            if any(k[2] == ch for k in kept) or ch in slot_pins:
+                raise held(ch, next((k[0] for k in kept if k[2] == ch), None))
 
     def _declared_roles(self, fn: int, channel: int) -> set[int]:
         """The roles fn's describe offers on `channel` (role_channels)."""
@@ -853,8 +886,9 @@ class Endpoint:
         elif self.names[fn] == "oep.probe.config":
             tlvs = [t for t in tlvs if t[0] != CFG_DESCRIBE["storage"]]
             saved_hash = self._hash(self.saved) if self.saved is not None else 0
+            state = 0 if self.saved is None else 2 if self.saved_reason else 1
             tlvs.insert(0, catalog.tlv(CFG_DESCRIBE["storage"], struct.pack(
-                "<IBII", self.storage_max, 0 if self.saved is None else 1, saved_hash, 20)))
+                "<IBIIB", self.storage_max, state, saved_hash, 20, self.saved_reason)))
             tlvs += [catalog.tlv(CFG_DESCRIBE["slot_state"], self._slot_state(n)) for n in sorted(self.slots)]
             tlvs += [catalog.tlv(CFG_DESCRIBE["bind_state"], self._bind_state(p)) for p in sorted(self.binds)]
         return tlvs
@@ -890,7 +924,7 @@ class Endpoint:
             for p in pairs:
                 tg = self._target(fn, p)
                 if tg.present:                                     # a live connection's pair: read over it, no restart
-                    found.append(struct.pack("<BHHI", 1, *p, tg.dmstatus()))
+                    found.append(m.element(struct.pack("<BHHI", 1, *p, tg.dmstatus())))
             return m.COMPLETED, m.SUCCESS, struct.pack("<BB", len(pairs), len(found)) + b"".join(found)
         if op in (0x02, 0x04):                                     # attach, attach_under_reset
             if op == 0x02:
@@ -956,7 +990,7 @@ class Endpoint:
                 users = (1 if "host" in c.users else 0) | (2 if any(u != "host" for u in c.users) else 0)
                 slot = next((n for n, s in self.slots.items() if s.wire_fn == fn and s.pair == c.pair), NO_SLOT)
                 tid = b"" if c.tid is None else struct.pack("<I", c.tid)
-                out += struct.pack("<HHHIBBBB", cid, *c.pair, c.speed, users, slot, 1 if tid else 0, len(tid)) + tid
+                out += m.element(struct.pack("<HHHIBBBB", cid, *c.pair, c.speed, users, slot, 1 if tid else 0, len(tid)) + tid)
             return m.COMPLETED, m.SUCCESS, bytes(out)
         return m.REJECTED, m.UNKNOWN_OPERATION, b""
 
@@ -1188,7 +1222,7 @@ class Endpoint:
             hits = [mk for mk in s.marks if m.serial_diff(mk[0], frm) >= 0]
             page = hits[:self.MARKS_PER_ANSWER]
             body = struct.pack("<BB", int(len(hits) > len(page)), len(page))
-            body += b"".join(struct.pack("<IQBIB", *mk) for mk in page)
+            body += b"".join(m.element(struct.pack("<IQBIB", *mk)) for mk in page)
             return self._answer(body, ignored)
         if s.closed:
             raise Reject(m.UNAVAILABLE)
@@ -1225,7 +1259,7 @@ class Endpoint:
         sid = t.take("H")
         s = self.streams.get(sid)
         if s is None:
-            raise Reject(m.UNAVAILABLE)
+            raise Reject(m.NO_CONNECTION)                          # a number it does not know (core §4.3)
         if op == _CON.op["close"]:
             t.tail()
             s.closed = True
@@ -1268,8 +1302,8 @@ class Endpoint:
             pairs = [t.take("HB") for _ in range(n)]
             t.tail()
             for i, (ch, mode) in enumerate(pairs):
-                if ch not in mine or mode > 7:
-                    raise Reject(m.UNAVAILABLE, bytes([i]))
+                if ch not in mine or mode > 7:                     # the position as the gpio's TLV (fixture §1)
+                    raise unavailable(channel=ch, extra=m.tlv(_GPIO.tlv["unavailable_payload"]["index"], bytes([i])))
             for ch, mode in pairs:
                 self.gpio_modes[ch] = mode
                 self.gpio_log.append((ch, mode))
@@ -1280,7 +1314,7 @@ class Endpoint:
             _, ignored = t.tail()
             for i, ch in enumerate(chans):
                 if ch not in mine:
-                    raise Reject(m.UNAVAILABLE, bytes([i]))
+                    raise unavailable(channel=ch, extra=m.tlv(_GPIO.tlv["unavailable_payload"]["index"], bytes([i])))
             levels = []
             for ch in chans:
                 mode = self.gpio_modes.get(ch, 0)
@@ -1359,12 +1393,14 @@ class Endpoint:
         if op == _CFG.op["save"]:
             t.tail()
             if len(b"".join(self._canonical(self.config))) > self.storage_max:
-                raise Reject(m.UNAVAILABLE)
+                raise unavailable("storage_full")
             self.saved = dict(self.config)
+            self.saved_ids = {fn: self.identity[fn] for fn in self._referenced(self.config) if fn in self.identity}
+            self.saved_reason = 0
             return m.COMPLETED, m.SUCCESS, struct.pack("<I", self._hash(self.config))
         if op == _CFG.op["erase"]:
             t.tail()
-            self.saved = None
+            self.saved, self.saved_ids, self.saved_reason = None, {}, 0
             return m.COMPLETED, m.SUCCESS, b""
         return m.REJECTED, m.UNKNOWN_OPERATION, b""
 
@@ -1389,6 +1425,51 @@ class Endpoint:
     def _hash(self, config: dict | None) -> int:
         return zlib.crc32(b"".join(self._canonical(config or {})))
 
+    @staticmethod
+    def _referenced(config: dict) -> set[int]:
+        """The fns saved items name (probe.config §2): plan fns, slot wire_fns, fixture UARTs a bind carries."""
+        fns = set()
+        for (tag, key), value in config.items():
+            if tag == ITEM["plan"]:
+                fns.add(key)
+            elif tag == ITEM["slot"]:
+                fns.add(struct.unpack_from("<H", value, 1)[0])
+            elif tag == ITEM["bind"]:
+                for k in range(value[3]):
+                    if value[4 + 3 * k] == BIND_STREAM["fixture_uart"]:
+                        fns.add(struct.unpack_from("<H", value, 5 + 3 * k)[0])
+        return fns
+
+    def _apply_saved(self) -> None:
+        """At boot: the saved items' fns found again by (name, instance, revision) and renumbered, then applied; one
+        not found (or of another revision) leaves the whole unapplied (probe.config §2)."""
+        now = {ident: fn for fn, ident in self.identity.items()}
+        remap = {}
+        for fn, ident in self.saved_ids.items():
+            if ident not in now:
+                self.saved_reason = 2
+                return
+            remap[fn] = now[ident]
+        pack = lambda fn: struct.pack("<H", remap.get(fn, fn))
+        new = {}
+        for (tag, key), value in self.saved.items():
+            if tag == ITEM["plan"]:
+                new[(tag, remap.get(key, key))] = [pack(key) + v[2:] for v in value]
+            elif tag == ITEM["slot"]:
+                new[(tag, key)] = value[:1] + pack(struct.unpack_from("<H", value, 1)[0]) + value[3:]
+            elif tag == ITEM["bind"]:
+                v = bytearray(value)
+                for k in range(v[3]):
+                    if v[4 + 3 * k] == BIND_STREAM["fixture_uart"]:
+                        v[5 + 3 * k:7 + 3 * k] = pack(struct.unpack_from("<H", v, 5 + 3 * k)[0])
+                new[(tag, key)] = bytes(v)
+            else:
+                new[(tag, key)] = value
+        try:
+            self._apply_config(new, boot=True)
+        except Reject:
+            self.saved_reason = 3
+
     def load_config(self, items: list[bytes], saved: bool = True) -> None:
         """Put `items` (item TLVs) in as the config, as a set would; with `saved` they are also the saved config
         (a probe that booted with them)."""
@@ -1402,6 +1483,7 @@ class Endpoint:
         self._apply_config(new, changed_slots=None)
         if saved:
             self.saved = dict(self.config)
+            self.saved_ids = {fn: self.identity[fn] for fn in self._referenced(self.config) if fn in self.identity}
 
     def _apply_config(self, new: dict, changed_slots: set[int] | None = None, boot: bool = False) -> None:
         """Check the whole config, then make it the current one (set is all-or-nothing up to reserving resources);
@@ -1469,8 +1551,8 @@ class Endpoint:
         t = Take(v)
         n, wire_fn, swdio, swclk, attach, retry_s, max_speed, idle_clock, mech, name_len = t.take("BHHHBHIBBB")
         name = t.bytes(name_len)
-        scheme = t.take("B")
-        rest = v[t.at:]
+        lock_len = t.take("B")                                     # the lock's part; 0 = none (probe.config §1.1)
+        lock_part = t.bytes(lock_len)                              # what follows is for later fields: skipped (core §2.3)
         if n >= self.slots_max or attach not in SLOT_ATTACH.values():
             raise Reject(m.MALFORMED)
         if retry_s and attach != SLOT_ATTACH["at_boot"]:
@@ -1484,19 +1566,18 @@ class Endpoint:
         if mech not in self.mechanisms:
             raise Reject(m.UNSUPPORTED)
         lock = None
-        if scheme:
-            if not rest or len(rest) % 2:
+        if lock_len:
+            if lock_len < 3 or lock_len % 2 == 0 or lock_part[0] == 0:
                 raise Reject(m.MALFORMED)
-            lock = (scheme, rest[:len(rest) // 2], rest[len(rest) // 2:])
-        elif rest:
-            raise Reject(m.MALFORMED)
+            half = (lock_len - 1) // 2
+            lock = (lock_part[0], lock_part[1:1 + half], lock_part[1 + half:])
         return Slot(n, wire_fn, (swdio, swclk), attach, retry_s, max_speed, idle_clock, mech, name.decode(), lock)
 
     def _parse_bind(self, v: bytes, slots: dict[int, Slot]) -> Bind:
         t = Take(v)
         port, mode, selected, n = t.take("BBBB")
         streams = tuple(t.take("BH") for _ in range(n))
-        if t.at != len(v) or n == 0:
+        if n == 0:                                                 # after the streams: later fields, skipped
             raise Reject(m.MALFORMED)
         if port not in self.serial_ports:
             raise Reject(m.UNAVAILABLE)
@@ -1735,5 +1816,5 @@ class Endpoint:
 
 SIMS = {"oep.wire.rvswd": "wire", "oep.wire.swio": "wire", "oep.target.riscv-dm": "dm",
         "oep.target.console": "console", "oep.fixture.gpio": "gpio", "oep.fixture.uart": "uart",
-        "oep.probe.config": "config_op", "oep.fixture.capture": "capture", "oep.fixture.analog": "capture",
+        "oep.probe.config": "config_op", "oep.fixture.logic": "capture", "oep.fixture.analog": "capture",
         "oep.fixture.capture-group": "group"}