oep-client-python 0.0.21__py3-none-any.whl → 0.0.22__py3-none-any.whl

oep_client/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.0.21"
+__version__ = "0.0.22"

oep_client/__main__.py

@@ -1,10 +1,12 @@
 """The oep command: what a probe offers (dump) and its settings (config).
 
   oep dump --port /run/board-identify/by-id/<probe>        oep dump --fake p4-x035 --prefix oep.target --json
-  oep config show <probe>
+  oep config show <probe>                 (the settings and what the probe declares; lock-free)
+  oep config state <probe>                (the live slot / bind / storage state; lock-free)
   oep config slot <probe> --name x035 --wire rvswd --pins 2,54 --attach at-boot --retry 1 --mechanism dmseq
   oep config bind <probe> --port 1 --mode last-reset --stream slot:x035
   oep config plan <probe> oep.fixture.uart#1 rx=48 tx=49       (the fn's whole plan; fn number or name#instance)
+  oep config uart <probe> oep.fixture.uart#1 115200 --format 8N1
   oep config remove <probe> bind 1        oep config save <probe>        oep config erase <probe>
 
 <probe>: a serial port, tcp://HOST:PORT or usb[:VID:PID[:SERIAL]]. A change takes the lock (owner "oep config") and
@@ -52,9 +54,12 @@ def main(argv=None) -> int:
 def _config_parser(sub) -> None:
     c = sub.add_parser("config", help="the probe's settings (oep.probe.config): slots, binds, save")
     cs = c.add_subparsers(dest="action", required=True)
-    show = cs.add_parser("show", help="the settings and the live slot / bind state")
+    show = cs.add_parser("show", help="the settings, what the probe declares, and the live slot / bind state")
     show.add_argument("probe")
     show.add_argument("--json", action="store_true")
+    state = cs.add_parser("state", help="the live slot / bind / storage state (op state, lock-free)")
+    state.add_argument("probe")
+    state.add_argument("--json", action="store_true")
     slot = cs.add_parser("slot", help="register a slot (a place a target is wired to)")
     slot.add_argument("probe")
     slot.add_argument("--slot", type=int, default=0, help="the slot number (default 0)")
@@ -62,8 +67,9 @@ def _config_parser(sub) -> None:
     slot.add_argument("--wire", help="rvswd or swio (or an fn); default: the probe's only wire")
     slot.add_argument("--pins", help="swdio,swclk (one pin on swio); default: the wire's only pin set")
     slot.add_argument("--attach", choices=sorted(config.ATTACH), default="host")
-    slot.add_argument("--retry", type=int, default=0, help="at-boot: try again every N s while absent (0: never)")
-    slot.add_argument("--mechanism", choices=sorted(config.MECHANISM), default="dmseq")
+    slot.add_argument("--retry", type=float, default=0, help="at-boot: try again every N s while absent (0: never)")
+    slot.add_argument("--mechanism", choices=sorted(config.MECHANISM), default="dmseq",
+                      help="the console's mechanism, or none (no console on this slot)")
     slot.add_argument("--max-speed", type=int, default=0,
                       help="the line's ceiling in Hz for the probe's own attach (0: none); the target's, e.g. 1000000")
     slot.add_argument("--idle-clock", choices=sorted(config.IDLE_CLOCK), default="high",
@@ -92,9 +98,15 @@ def _config_parser(sub) -> None:
     idle.add_argument("channel", type=int)
     idle.add_argument("mode", choices=sorted(config.IDLE))
     idle.add_argument("--save", action="store_true")
-    rm = cs.add_parser("remove", help="remove one item: slot N, bind PORT, plan FN, label CH, idle CH")
+    uart = cs.add_parser("uart", help="a fixture UART's baud / format, applied whenever its plan has RX or TX")
+    uart.add_argument("probe")
+    uart.add_argument("fn", help="an fn, or name#instance of the oep.fixture.uart")
+    uart.add_argument("baud", type=int)
+    uart.add_argument("--format", default="8N1", help="data bits, parity, stop bits: 8N1 (default), 8E1, 7O2 ...")
+    uart.add_argument("--save", action="store_true")
+    rm = cs.add_parser("remove", help="remove one item (unset): slot N, bind PORT, plan FN, label CH, idle CH, uart FN")
     rm.add_argument("probe")
-    rm.add_argument("kind", choices=["slot", "bind", "plan", "label", "idle"])
+    rm.add_argument("kind", choices=sorted(config.ITEM))
     rm.add_argument("key", type=int)
     rm.add_argument("--save", action="store_true")
     for name in ("save", "erase"):
@@ -108,7 +120,7 @@ def _pins(hst, fn: int, text: str | None, wire: str) -> tuple[int, int]:
     groups = []
     for tag, v in core.describe(hst, fn):
         if tag & 0x7F == catalog.CHANNEL_GROUP:
-            roles = {v[1 + 3 * i]: struct.unpack_from("<H", v, 2 + 3 * i)[0] for i in range((len(v) - 1) // 3)}
+            roles = dict(catalog.unpack_channel_group(v)[1])
             groups.append((roles.get(1, 0xFFFF), roles.get(2, 0xFFFF)))
     if len(groups) != 1:
         raise SystemExit(f"{wire}: {len(groups)} pin sets on this probe - name one with --pins")
@@ -180,6 +192,8 @@ def _config(args) -> int:
         cfg = config.ProbeConfig(hst)
         if args.action == "show":
             return _show(hst, cfg, args.json)
+        if args.action == "state":
+            return _state(cfg, args.json)
         if args.action == "slot":
             fn = _wire_fn(hst, args.wire)
             args.wire = args.wire or str(fn)
@@ -208,6 +222,15 @@ def _config(args) -> int:
                     raise SystemExit(f"{role}: not a role of fn {fn} (roles: {', '.join(sorted(roles)) or 'numbers only'})")
                 items.append(config.Plan(fn=fn, role=number, channel=int(ch, 0)))
             _change(hst, cfg, items, args.save)
+        elif args.action == "uart":
+            fn, _ = _plan_fn(hst, args.fn)
+            from .fixture import FixtureUart
+            fmt = args.format.upper()
+            try:
+                byte = FixtureUart.format_byte(int(fmt[0]), fmt[1], int(fmt[2]))
+            except (KeyError, ValueError, IndexError):
+                raise SystemExit(f"--format {args.format}: want <data bits><parity><stop bits>, e.g. 8N1, 8E2, 7O1") from None
+            _change(hst, cfg, [config.Uart(fn=fn, baud=args.baud, format=byte)], args.save)
         elif args.action == "label":
             _change(hst, cfg, [config.Label(channel=args.channel, text=args.text)], args.save)
         elif args.action == "idle":
@@ -232,42 +255,66 @@ def _config(args) -> int:
         hst.link.close()
 
 
+def _plain(o):
+    return {k: (v.hex() if isinstance(v, bytes) else v) for k, v in vars(o).items()} if hasattr(o, "__dict__") \
+        else list(o)
+
+
+def _state_dict(st) -> dict:
+    return {**{k: v for k, v in vars(st).items() if k not in ("slots", "binds")},
+            "slots": [_plain(s) for s in st.slots], "binds": [_plain(b) for b in st.binds]}
+
+
+def _state(cfg, as_json: bool) -> int:
+    """The live state alone (op state, lock-free): what a monitor polls."""
+    st = cfg.state()
+    if as_json:
+        print(json.dumps(_state_dict(st), indent=2, default=lambda o: o.hex() if isinstance(o, bytes) else str(o)))
+        return 0
+    why = f" ({st.unreadable})" if st.unreadable else ""
+    print(f"storage: {st.storage}{why}, saved hash 0x{st.saved_hash:08x}")
+    for s in st.slots:
+        print(f"  slot {s.slot}: {s.state}" + (f", connection {s.connection}" if s.connection else "")
+              + (f", tried at {s.last_try_at_ns / 1e9:.3f} s" if s.last_try_at_ns is not None else "")
+              + (f", target_id {s.target_id[::-1].hex()}" if s.target_id else ""))
+    for b in st.binds:
+        print(f"  port {b.port}: {b.mode}, {b.flow}" + (f", carrying {b.selected}" if b.selected is not None else ""))
+    return 0
+
+
 def _show(hst, cfg, as_json: bool) -> int:
     h, _ = cfg.get()
     items = cfg.items()
+    decl = cfg.describe()
     st = cfg.state()
     kinds = {i: _name(k) for i, k, _ in core.transports(hst)}
     if as_json:
-        def plain(o):
-            return {k: (v.hex() if isinstance(v, bytes) else v) for k, v in vars(o).items()} if hasattr(o, "__dict__") \
-                else list(o)
-        out = {"hash": h, "items": [dict(type=type(i).__name__, **plain(i)) if hasattr(i, "__dict__") else plain(i)
+        out = {"hash": h, "items": [dict(type=type(i).__name__, **_plain(i)) if hasattr(i, "__dict__") else _plain(i)
                                      for i in items],
-               "state": {**{k: v for k, v in vars(st).items() if k not in ("slots", "binds")},
-                         "slots": [plain(s) for s in st.slots], "binds": [plain(b) for b in st.binds]},
-               "transports": kinds}
+               "declared": _plain(decl), "state": _state_dict(st), "transports": kinds}
         print(json.dumps(out, indent=2, default=lambda o: o.hex() if isinstance(o, bytes) else str(o)))
         return 0
-    print(f"storage: {st.storage} ({st.storage_bytes} bytes), saved hash 0x{st.saved_hash:08x}; now 0x{h:08x}")
+    why = f" ({st.unreadable})" if st.unreadable else ""
+    print(f"storage: {st.storage}{why} ({decl.storage_bytes} bytes), saved hash 0x{st.saved_hash:08x}; now 0x{h:08x}")
     print("transports: " + ", ".join(f"{i} {k}" for i, k in kinds.items()))
     by_slot = {s.slot: s for s in st.slots}
-    print(f"slots (up to {st.slots_max}):")
+    print(f"slots (up to {decl.slots_max}):")
     for it in items:
         if isinstance(it, config.Slot):
             s = by_slot.get(it.slot)
             pins = f"{it.pins[0]}" if it.pins[1] == 0xFFFF else f"{it.pins[0]},{it.pins[1]}"
-            retry = f" retry {it.retry_s} s" if it.attach == "at-boot" else ""
+            retry = f" retry {it.retry_s:g} s" if it.attach == "at-boot" else ""
             retry += (f" max {it.max_speed} Hz" if it.max_speed else "") + (" idle-low" if it.idle_clock == "low" else "")
             lock = (f" lock {int.from_bytes(it.lock[1], 'little'):08x}:{int.from_bytes(it.lock[2], 'little'):08x}"
                     if it.lock else "")
             live = ""
             if s:
-                tried = "never tried" if s.last_try_ms is None else f"tried {s.last_try_ms} ms ago"
+                tried = "never tried" if s.last_try_at_ns is None else f"tried at {s.last_try_at_ns / 1e9:.3f} s"
                 tid = f" target_id {s.target_id[::-1].hex()}" if s.target_id else ""
                 live = f"  -> {s.state}" + (f" (connection {s.connection})" if s.connection else f" ({tried})") + tid
             print(f"  {it.slot} {it.name}: fn {it.wire_fn} pins {pins} {it.attach}{retry} {it.mechanism}{lock}{live}")
     by_port = {b.port: b for b in st.binds}
-    print(f"binds (modes: {', '.join(st.bind_modes) or '-'}):")
+    print(f"binds (modes: {', '.join(decl.bind_modes) or '-'}):")
     names = {it.slot: it.name for it in items if isinstance(it, config.Slot)}
     for it in items:
         if isinstance(it, config.Bind):

oep_client/arm.py

@@ -29,17 +29,19 @@ class SwdWire(WireBase):
         self.existing = False
 
     def attach(self, targetsel: int | None = None, max_speed: int | None = None,
-               pins: tuple[int, int] | None = None) -> tuple[int, int, bool]:
-        """-> (connection, DPIDR, woke from dormant). targetsel (multidrop) and max_speed go as critical TLVs: a probe
-        that cannot honour them refuses. self.existing: the wire was attached already (its connection returned)."""
-        body = self._speed_tlv(max_speed) + self._pins_tlv(pins)
+               pins: tuple[int, int] | None = None, reset: tuple[int, int] | None = None) -> tuple[int, int, bool]:
+        """-> (connection, DPIDR, woke from dormant). The request is method 0 (swd has no halting attach) and TLVs:
+        max_speed (required, critical; None: the wire's declared max_clock_hz), targetsel (multidrop, critical), pins,
+        reset = (channel, hold_ms) (critical). self.existing: the wire was attached already (its connection returned).
+        self.flags: the attach_flags byte."""
+        body = bytes([0]) + self._speed_tlv(self._speed_or_default(max_speed)) + self._pins_tlv(pins) + self._reset_tlv(reset)
         if targetsel is not None:
             body += m.tlv(self.TAG_TARGETSEL, struct.pack("<I", targetsel), critical=True)
         rd = m.Reader(self._call(self.ATTACH, body).payload)
-        conn, dpidr, flags, self.speed_hz = rd.take("HIBI")
-        self.existing = bool(flags & 2)
+        conn, dpidr, self.flags, self.speed_hz = rd.take("HIBI")
+        self.existing = bool(self.flags & self.FLAGS["existing"])
         rd.tail()
-        return conn, dpidr, bool(flags & 1)
+        return conn, dpidr, bool(self.flags & self.FLAGS["dormant_woken"])
 
 
 class AdiError(TargetError):
@@ -82,8 +84,8 @@ class ArmAdi(Interface):
         reads = transfer_reads(steps)
         r = self._request(self.TRANSFER, struct.pack("<H", len(reads)) + steps)
         rd = ran(r)
-        done, status, self.last_ack = rd.take("HBB")
-        values = rd.words(sum(reads[:done]))
+        done, status, self.last_ack, nvals = rd.take("HBBH")    # nvals: the values the answer carries (debug §6)
+        values = rd.words(nvals)
         rd.tail()
         if status != OK or not r.succeeded or done != len(reads):
             raise AdiError(f"transfer (ack {self.last_ack:#x})", status, r, done=done, values=values)

oep_client/capture.py

@@ -5,6 +5,11 @@ Times are the probe's one clock (ns since its boot, comparable within one boot_i
 probe's known corrections applied. Analog values are always raw; the probe's 1st-order scale, its calibration data and
 its reference are for the host to choose from.
 
+Every start begins a new generation (u32, from 1): segment serials and positions count from 0 inside it, and read and
+release name it, so a read sent for the last capture never returns the next one's bytes (oep-if-capture §3.2). The
+client keeps it (`LogicCapture.generation`, from start / status / the group's start) and passes it on; `read_segment`
+takes the segment's own.
+
 configure: a TLV the probe cannot honour is refused (rejected unsupported, 0x0B, payload = the tag) when the host marked
 it critical, and otherwise ignored and listed in the answer's ignored TLV (0x7F, oep-core §2.3)."""
 
@@ -24,13 +29,17 @@ _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)
-MODE, RATE, SAMPLES, SEGMENTS, TRIGGER, PRETRIGGER, FRONTEND = (
-    _CAP.tlv["configure"][k] for k in ("mode", "rate", "samples", "segments", "trigger", "pretrigger", "frontend"))
+MODE, RATE, SAMPLES, SEGMENTS, TRIGGER, PRETRIGGER = (
+    _CAP.tlv["configure"][k] for k in ("mode", "rate", "samples", "segments", "trigger", "pretrigger"))
+FRONTEND = _ANA.tlv["configure"]["frontend"]             # analog only
 ACTUAL_RATE, LAYOUT, ACTUAL_SAMPLES, ACTUAL_SEGMENTS, TIMING, SCALE, BLOCKING, SKEW, FRONTEND_USED, REFERENCE, \
     RATE_ACCURACY = (_ANA.tlv["configure_answer"][k] for k in (
         "actual_rate", "layout", "actual_samples", "actual_segments", "timing", "scale", "blocking_ms", "skew",
         "frontend_used", "reference", "rate_accuracy"))
 FACTORY, VREFINT = _ANA.tlv["calibration_answer"]["factory"], _ANA.tlv["calibration_answer"]["vrefint"]
+STATUS_ERROR = _CAP.tlv["status_answer"]["error"]          # status's TLV: why the state is 6
+DATA_GENERATION = _CAP.tlv["data"]["generation"]           # a data frame's TLV: its generation (always in streaming)
+GROUP_GENERATIONS = _GRP.tlv["start_answer"]["generations"]
 REFERENCE_SOURCE = {v: k for k, v in _ANA.enum["reference_source"].items()}
 IGNORED = m.TAG_IGNORED
 CRITICAL = m.TAG_CRITICAL
@@ -38,6 +47,8 @@ ONE_SHOT, REPEAT, STREAMING = (_CAP.enum["mode"][k] for k in ("one_shot", "repea
 IMMEDIATE, LEVEL, EDGE, CROSS_UP, CROSS_DOWN = range(5)
 STATE = _CAP.enum["state"]
 SEGMENT_SLIPPED = _CAP.enum["segment_flag"]["slipped"]
+STATUS_FLAGS = _CAP.enum["status_flag"]                    # dropped, slipped (reset at start)
+ERRORS = {v: k for k, v in _CAP.enum["error"].items()}     # state 6's reason
 # events (oep-core §11, role 0x05)
 EVENT_SEGMENT, EVENT_STOPPED, EVENT_TRIGGERED = (_CAP.event[k] for k in ("segment", "stopped", "triggered"))
 
@@ -46,8 +57,8 @@ def tlvs(payload: bytes) -> list[tuple[int, bytes]]:
     return m.split_tlvs(payload)
 
 
-SEGMENT_BYTES = 33   # serial u32, position u64, samples u32, start_ns u64, start_uncertainty_ns u32, trigger_index u32,
-                     # flags u8
+SEGMENT_BYTES = 37   # serial u32, position u64, samples u32, start_ns u64, start_uncertainty_ns u32, trigger_index u32,
+                     # flags u8, generation u32 (oep-if-capture §2)
 
 
 @dataclass
@@ -59,6 +70,7 @@ class Segment:
     start_uncertainty_ns: int        # +- of start_ns (a guide, not a promise)
     trigger_index: int | None
     flags: int
+    generation: int = 0              # the start this segment belongs to (read / release name it)
 
     @property
     def slipped(self) -> bool:
@@ -67,8 +79,34 @@ class Segment:
 
     @classmethod
     def unpack(cls, b: bytes) -> "Segment":
-        serial, position, samples, start_ns, uncertainty, trig, flags = struct.unpack_from("<IQIQIIB", b)
-        return cls(serial, position, samples, start_ns, uncertainty, None if trig == 0xFFFFFFFF else trig, flags)
+        serial, position, samples, start_ns, uncertainty, trig, flags, generation = struct.unpack_from("<IQIQIIBI", b)
+        return cls(serial, position, samples, start_ns, uncertainty, None if trig == 0xFFFFFFFF else trig, flags,
+                   generation)
+
+
+@dataclass
+class Status:
+    """status's answer (oep-if-capture §3.2). Iterates as (state, serial_done, write_pos, flags), the first shape."""
+    state: int
+    serial_done: int                 # segments finished
+    write_pos: int                   # bytes taken so far (dropped ones counted: the next byte's position)
+    flags: int                       # bit0 dropped, bit1 slipped - since start
+    generation: int
+    error: int | None = None         # state 6: why (ERRORS)
+
+    def __iter__(self):
+        return iter((self.state, self.serial_done, self.write_pos, self.flags))
+
+    def __getitem__(self, i: int):
+        return (self.state, self.serial_done, self.write_pos, self.flags)[i]
+
+    @property
+    def dropped(self) -> bool:
+        return bool(self.flags & STATUS_FLAGS["dropped"])
+
+    @property
+    def error_name(self) -> str | None:
+        return None if self.error is None else ERRORS.get(self.error, f"error 0x{self.error:02x}")
 
 
 @dataclass
@@ -124,17 +162,27 @@ class Received:
     gaps: list[tuple[int, int]] = field(default_factory=list)  # (index in data where it skipped, bytes skipped)
     seq_lost: int = 0                                          # push frames missing by seq
     frames: int = 0
+    stale: int = 0                                             # pushes of an earlier generation, dropped
+
+
+def unpack_push(frame: bytes) -> tuple[int, int, int, bytes, int | None]:
+    """A data frame (core §11.2: role fn seq position(u64) len(u16) data [TLV]) -> (fn, seq, position, data,
+    generation): the TLV 0x01 generation, None when the frame carries none."""
+    fn, seq, position = struct.unpack_from("<HHQ", frame, 1)
+    rd = m.Reader(frame[13:])
+    data = rd.counted("H")
+    g = rd.tail().get(DATA_GENERATION)
+    return fn, seq, position, data, struct.unpack("<I", g)[0] if g is not None and len(g) == 4 else None
 
 
-def take_pushes(link, fn: int) -> list[tuple[int, int, bytes]]:
-    """Remove this fn's data pushes (role 0x06) from the link: [(seq, position, data)], oldest first."""
+def take_pushes(link, fn: int) -> list[tuple[int, int, bytes, int | None]]:
+    """Remove this fn's data pushes (role 0x06) from the link: [(seq, position, data, generation)], oldest first."""
     mine, rest = [], []
     for f in link.pushes:
         (mine if struct.unpack_from("<H", f, 1)[0] == fn else rest).append(f)
     link.pushes.clear()
     link.pushes.extend(rest)
-    # the core header is role fn seq; the capture's payload is position(u64) then data (standard position stream)
-    return [(struct.unpack_from("<H", f, 3)[0], struct.unpack_from("<Q", f, 5)[0], f[13:]) for f in mine]
+    return [unpack_push(f)[1:] for f in mine]
 
 
 def _config(payload: bytes, analog: bool) -> Config:
@@ -183,10 +231,13 @@ class LogicCapture(Interface):
     CONFIGURE, START, STOP, FORCE, STATUS, READ, SEGMENTS, RELEASE, QUERY_OP = (
         _CAP.op[k] for k in ("configure", "start", "stop", "force", "status", "read", "segments", "release", "query"))
 
+    generation: int | None = None         # the current capture's generation (start / status / the group's start)
+
     def __init__(self, hst: h.Host, fn: int | None = None, name: str | None = None):
         super().__init__(hst, name, fn=fn)
         self.config: Config | None = None
         self.armed_s: float | None = None     # time.monotonic() at the last start()
+        self.generation = None
 
     def configure(self, *, rate: int, mode: int = ONE_SHOT, samples: int | None = None, segments: int | None = None,
                   trigger: tuple[int, int, int] | None = None, pretrigger: int | None = None, query: bool = False,
@@ -201,7 +252,7 @@ class LogicCapture(Interface):
         if segments is not None:
             body += tlv(SEGMENTS, struct.pack("<I", segments))
         if trigger is not None:
-            body += tlv(TRIGGER, struct.pack("<BBH", *trigger))
+            body += tlv(TRIGGER, struct.pack("<BBI", *trigger))        # type, role, value (u32)
         if pretrigger is not None:
             body += tlv(PRETRIGGER, struct.pack("<I", pretrigger))
         for role, fe in sorted((frontends or {}).items()):   # analog: the input range per channel (describe frontend)
@@ -225,8 +276,9 @@ class LogicCapture(Interface):
                into: Received | None = None, keepalive_s: float = 1.0) -> Received:
         """Streaming: collect data pushes until `nbytes` have arrived or `seconds` have passed (at least one is needed).
         A position that does not follow the previous push is a probe-side drop (a gap); a seq that skips is a lost frame.
-        The subscription ends with the lock, so the lock is kept alive every `keepalive_s` while collecting (a stream
-        longer than the lease otherwise stopped: 35 MB missing at the end of 10 s at 150 MHz with a 10 s lease)."""
+        A push of another generation than this capture's (a leftover of the start before, oep-if-capture §3.4) is
+        dropped. The subscription ends with the lock, so the lock is kept alive every `keepalive_s` while collecting (a
+        stream longer than the lease otherwise stopped: 35 MB missing at the end of 10 s at 150 MHz with a 10 s lease)."""
         if seconds is None and nbytes is None:
             raise ValueError("stream() needs seconds or nbytes")
         got = into or Received()
@@ -238,7 +290,7 @@ class LogicCapture(Interface):
             for e in link.events:
                 if struct.unpack_from("<H", e, 1)[0] == self.fn:
                     event_seqs.add(struct.unpack_from("<H", e, 3)[0])
-            for seq, position, data in take_pushes(link, self.fn):
+            for seq, position, data, generation in take_pushes(link, self.fn):
                 while expect_seq is not None and expect_seq != seq:
                     if expect_seq in event_seqs:
                         event_seqs.discard(expect_seq)
@@ -246,6 +298,9 @@ class LogicCapture(Interface):
                         got.seq_lost += 1
                     expect_seq = (expect_seq + 1) & 0xFFFF
                 expect_seq = (seq + 1) & 0xFFFF
+                if generation is not None and self.generation is not None and generation != self.generation:
+                    got.stale += 1                              # the generation before: not this capture's bytes
+                    continue
                 if got.start is None:
                     got.start = position
                 else:
@@ -268,7 +323,7 @@ class LogicCapture(Interface):
     def finish(self, link, got: Received, timeout: float = 5.0) -> Received:
         """Streaming, after stop(): collect the pushes still to come, up to the last byte captured (status's write
         position), or until `timeout`."""
-        end = self.status()[2]
+        end = self.status().write_pos
         deadline = time.monotonic() + timeout
         while time.monotonic() < deadline:
             if got.start is not None:
@@ -279,8 +334,10 @@ class LogicCapture(Interface):
         return got
 
     def start(self) -> int:
-        """-> blocking_ms (0: the probe keeps answering while it captures)."""
-        blocking = m.Reader(self._call(self.START).payload).u32()
+        """-> blocking_ms (0: the probe keeps answering while it captures). self.generation: the new capture's."""
+        rd = m.Reader(self._call(self.START).payload)
+        blocking, self.generation = rd.take("II")
+        rd.tail()
         self.armed_s = time.monotonic()
         return blocking
 
@@ -291,19 +348,44 @@ class LogicCapture(Interface):
         """Waiting for the trigger: start now (the segment's trigger_index marks where)."""
         self._call(self.FORCE)
 
-    def status(self) -> tuple[int, int, int, int]:
-        """-> state, segments done, write position, flags."""
-        return m.Reader(self._call(self.STATUS, locked=False).payload).take("BIQB")
-
-    def release(self, serial: int) -> None:
-        """Repeat: segments up to `serial` may be reused."""
-        self._call(self.RELEASE, struct.pack("<I", serial))
-
-    def segments(self, from_serial: int = 0) -> list[Segment]:
+    def status(self) -> Status:
+        """-> Status (state, segments done, write position, flags, generation, error). Lock-free; it also brings the
+        generation a host that did not start the capture needs for read."""
+        rd = m.Reader(self._call(self.STATUS, locked=False).payload)
+        state, done, pos, flags, generation = rd.take("BIQBI")
+        error = rd.tail().get(STATUS_ERROR)
+        self.generation = generation
+        return Status(state, done, pos, flags, generation, error[0] if error else None)
+
+    def release(self, serial: int, generation: int | None = None) -> None:
+        """Repeat: segments up to and including `serial` may be reused (of this generation; another one is rejected
+        unavailable). In state 5 (no free segment) the probe goes on by itself once there is room."""
+        self._call(self.RELEASE, struct.pack("<II", self._generation(generation), serial))
+
+    def _generation(self, generation: int | None) -> int:
+        if generation is not None:
+            return generation
+        if self.generation is None:
+            self.status()                                   # a host that did not start it: ask
+        return self.generation
+
+    def segments_page(self, from_serial: int = 0) -> tuple[list[Segment], bool]:
+        """One answer's segment records from `from_serial` on. -> (segments, more)."""
         rd = m.Reader(self._call(self.SEGMENTS, struct.pack("<I", from_serial), locked=False).payload)
-        out = [Segment.unpack(rd.element().bytes(SEGMENT_BYTES)) for _ in range(rd.u8())]
+        more, count = rd.take("BB")
+        out = [Segment.unpack(rd.element().bytes(SEGMENT_BYTES)) for _ in range(count)]
         rd.tail()
-        return out
+        return out, bool(more)
+
+    def segments(self, from_serial: int = 0) -> list[Segment]:
+        """Every segment record from `from_serial` on, following `more`."""
+        out: list[Segment] = []
+        while True:
+            page, more = self.segments_page(from_serial)
+            out += page
+            if not more or not page:
+                return out
+            from_serial = page[-1].serial + 1
 
     def wait(self, timeout: float = 5.0, keepalive_s: float = 1.0) -> list[Segment]:
         """Poll status until the one-shot is done (or failed). -> its segments. Waiting for a trigger may take longer
@@ -314,11 +396,12 @@ class LogicCapture(Interface):
             if keepalive_s and self.host.session is not None and time.monotonic() - kept >= keepalive_s:
                 self.host.keepalive()
                 kept = time.monotonic()
-            state = self.status()[0]
+            st = self.status()
+            state = st.state
             if state == STATE["done"]:
                 return self.segments()
             if state == STATE["error"]:
-                raise h.Failed(None, "the capture stopped with an error")
+                raise h.Failed(None, f"the capture stopped with an error ({st.error_name or 'unknown'})")
             if state not in STATE.values():
                 raise h.ProtocolError(f"capture state {state} is not one this client knows")
             time.sleep(0.002)
@@ -327,14 +410,25 @@ class LogicCapture(Interface):
     READ_TRIES = 4   # batches of reads sent again after the link's own repeat failed too
     BATCH = 16   # frame-sized reads per pipeline; a keepalive between batches when a session is open
 
-    def read(self, position: int, length: int) -> bytes:
-        """Bytes [position, position+length) of the stream, pipelined in frame-sized reads.
+    READ_HEAD = 13   # the answer's position(u64) flags(u8) len(u32) in front of the data
+
+    @staticmethod
+    def _read_data(payload: bytes) -> bytes:
+        rd = m.Reader(payload)
+        rd.take("QB")
+        return rd.counted("I")                             # position flags len(u32) data [TLV]
+
+    def read(self, position: int, length: int, generation: int | None = None) -> bytes:
+        """Bytes [position, position+length) of the stream, pipelined in frame-sized reads. `generation`: the capture
+        they belong to (default: the one this client saw at start / status); the probe refuses another one as
+        unavailable (cause 6), so an old read never gets the next capture's bytes.
 
         The reads need no lock and go without the session id, so a repeat after a broken reply is simply run again
         (reads are not deduplicated, oep-core §5.2). They do not extend the lease, though: a long read (64 KB over a
         115200 bps UART probe takes seconds) sends a keepalive between batches, or the lease lapsed mid-read, the plan
         went with it (core §9) and the capture read back nothing (2026-09-26, V003 jig)."""
-        chunk = max(1, confirm(self.host)["max_frame"] - 16)
+        g = self._generation(generation)
+        chunk = max(1, confirm(self.host)["max_frame"] - m.RESULT_HEADER - self.READ_HEAD)
         offsets = list(range(0, length, chunk))
         out = bytearray()
         for at in range(0, len(offsets), self.BATCH):
@@ -342,7 +436,8 @@ class LogicCapture(Interface):
                 self.host.keepalive()
             batch = offsets[at:at + self.BATCH]
             for attempt in range(self.READ_TRIES):
-                reqs = [self.request(self.READ, struct.pack("<QI", position + off, min(chunk, length - off))) for off in batch]
+                reqs = [self.request(self.READ, struct.pack("<IQI", g, position + off, min(chunk, length - off)))
+                        for off in batch]
                 try:
                     replies = self.host.pipeline_calls(reqs, locked=False)
                     break
@@ -352,11 +447,11 @@ class LogicCapture(Interface):
                     if attempt == self.READ_TRIES - 1:
                         raise
             for off, r in zip(batch, replies):
-                data = r.payload[9:]                      # after position(u64) flags(u8)
+                data = self._read_data(r.payload)
                 want = min(chunk, length - off)
                 while len(data) < want:                   # a short answer: read on from where it stopped
-                    more = self._call(self.READ, struct.pack("<QI", position + off + len(data), want - len(data)),
-                                      locked=False).payload[9:]
+                    more = self._read_data(self._call(self.READ, struct.pack(
+                        "<IQI", g, position + off + len(data), want - len(data)), locked=False).payload)
                     if not more:
                         raise h.ProtocolError(f"read at {position + off + len(data)} returned nothing")
                     data += more
@@ -364,11 +459,11 @@ class LogicCapture(Interface):
         return bytes(out)
 
     def read_segment(self, segment: Segment) -> bytes:
-        """The segment's bytes; every Host.on_capture callback gets them as a CaptureRecord (a run recorder, e.g.
-        pytest-embedded-wireskein, without this package knowing it)."""
+        """The segment's bytes (of its generation); every Host.on_capture callback gets them as a CaptureRecord (a run
+        recorder, e.g. pytest-embedded-wireskein, without this package knowing it)."""
         c = self.config
         n = (segment.samples * c.width + 7) // 8 if c.width else segment.samples * len(c.order) * c.slot // 8
-        data = self.read(segment.position, n)
+        data = self.read(segment.position, n, segment.generation or None)
         if self.host.on_capture:
             record = CaptureRecord(self.fn, self.name, c, segment, data, self.armed_s, time.monotonic())
             for callback in list(self.host.on_capture):
@@ -408,9 +503,11 @@ class LogicCapture(Interface):
 class Calibration:
     """What the probe knows for turning an analog value into a voltage (oep-if-capture §3.8), raw: the probe applies
     none of it. factory: (frontend or None, scheme, raw bytes) - scheme names how to read raw; vrefint: (raw, ns), the
-    internal reference measured after the last start."""
+    internal reference measured after the last start, and vrefint_nominal_mv its nominal voltage (what the supply is
+    worked back from)."""
     factory: list[tuple[int | None, str, bytes]] = field(default_factory=list)
     vrefint: tuple[int, int] | None = None
+    vrefint_nominal_mv: int | None = None
 
 
 class AnalogCapture(LogicCapture):
@@ -439,11 +536,14 @@ class AnalogCapture(LogicCapture):
     def calibration(self) -> Calibration:
         out = Calibration()
         for tag, v in tlvs(self._call(self.CALIBRATION, locked=False).payload):
-            if tag == FACTORY:
-                n = v[1]
-                out.factory.append((None if v[0] == 0xFF else v[0], v[2:2 + n].decode("utf-8", "replace"), bytes(v[2 + n:])))
-            elif tag == VREFINT:
-                out.vrefint = struct.unpack("<IQ", v)
+            if tag == FACTORY:                               # frontend scheme_len scheme raw_len(u16) raw
+                rd = m.Reader(v)
+                fe = rd.u8()
+                scheme = rd.counted("B").decode("utf-8", "replace")
+                out.factory.append((None if fe == 0xFF else fe, scheme, bytes(rd.counted("H"))))
+            elif tag == VREFINT:                             # raw(u32) ns(u64) nominal_mv(u32)
+                raw, ns, nominal = struct.unpack_from("<IQI", v)
+                out.vrefint, out.vrefint_nominal_mv = (raw, ns), nominal
         return out
 
 
@@ -474,11 +574,17 @@ class CaptureGroup(Interface):
         self._call(self.BIND, body)
 
     def start(self, tracks: list[LogicCapture] = ()) -> tuple[int, int]:
-        """-> (blocking_ms, the group's start_ns). `tracks`: whose armed_s to set (for records)."""
-        blocking, start_ns = m.Reader(self._call(self.START).payload).take("IQ")
+        """-> (blocking_ms, the group's start_ns). `tracks`: whose armed_s and generation to set (the answer's TLV
+        generations names each track's new generation; self.generations keeps them by fn)."""
+        rd = m.Reader(self._call(self.START).payload)
+        blocking, start_ns = rd.take("IQ")
+        gens = rd.tail().get(GROUP_GENERATIONS) or b""
+        self.generations = {fn: g for fn, g in struct.iter_unpack("<HI", gens[:len(gens) // 6 * 6])}
         now = time.monotonic()
         for t in tracks:
             t.armed_s = now
+            if t.fn in self.generations:
+                t.generation = self.generations[t.fn]
         return blocking, start_ns
 
     def stop(self) -> None:
@@ -488,7 +594,9 @@ class CaptureGroup(Interface):
         self._call(self.FORCE)
 
     def status(self) -> GroupStatus:
-        state, start, trig, fn = m.Reader(self._call(self.STATUS, locked=False).payload).take("BQQH")
+        rd = m.Reader(self._call(self.STATUS, locked=False).payload)
+        state, start, trig, fn = rd.take("BQQH")
+        rd.tail()
         none = self.NO_TIME
         return GroupStatus(state, None if start == none else start, None if trig == none else trig, fn or None)