oep-client-python 0.0.44__py3-none-any.whl → 0.0.45__py3-none-any.whl

oep_client/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.0.44"
+__version__ = "0.0.45"

oep_client/__main__.py

@@ -11,7 +11,7 @@
                                            port, IP; each verified first by confirm + describe's unit_id, host guide
                                            §4.1 - one that fails is dropped with a warning)
   oep speed <probe> [--candidates 921600,500000] [--verify [--flows in:2,out:2]] (port_speed, oep-if-link §3 and the host
-                                           guide §17: try the candidates in order on a UART bridge, report; default
+                                           the port_speed procedure (README): try the candidates in order on a UART bridge, report; default
                                            500000 - a faster rate only when named, after its 1 s verify each way)
   oep linktest <probe> --rates now,921600 --patterns in,out,duplex --inflight 1,2 --sizes 128,496 --frames 300
   oep pins <probe> --power 5 --wire swio  (find the target's debug pins and reset line: classify the channels, scan,
@@ -64,13 +64,13 @@ def main(argv=None) -> int:
     sp.add_argument("--candidates", default="", help="the candidates, comma-separated (default 500000, the default "
                     "ceiling of oep-if-link §3 obligation 7). A rate above 500000 is tried only when named here, and "
                     "is committed only after full frames ran 1 s each way (in, out; duplex too with --verify's "
-                    "default flows) at it (host guide §17.3.3)")
+                    "default flows) at it (the port_speed procedure (README))")
     sp.add_argument("--flows", default="", help="the flows to verify, comma-separated FLOW[:N] (in, out, duplex; N in "
                     "flight, 0 = the most the link keeps; default: all three at that N). Selects --verify")
     form = sp.add_mutually_exclusive_group()
-    form.add_argument("--verify", action="store_true", help="the full form (guide §17.3): baseline, the flows measured "
+    form.add_argument("--verify", action="store_true", help="the full form (the port_speed procedure (README)): baseline, the flows measured "
                       "at every candidate, a failed flow run again one at a time")
-    form.add_argument("--minimal", action="store_true", help="the minimal form (guide §17.2, the default): try, confirm, "
+    form.add_argument("--minimal", action="store_true", help="the minimal form (the port_speed procedure (README), the default): try, confirm, "
                       "commit, no measurement")
     sp.add_argument("--frames", type=int, default=link.FLOW_FRAMES, help="frames per flow when verifying (default 16)")
     sp.add_argument("--no-record", action="store_true", help="do not read or write the record of passed / failed rates "

oep_client/acquire.py

@@ -41,6 +41,8 @@ from dataclasses import dataclass, field
 from fractions import Fraction
 from pathlib import Path
 
+from . import registry as _reg
+
 __all__ = ["Analog", "Bits", "Changes", "OnDisk", "Part", "Request", "Result", "capture", "capture_at"]
 
 TRIGGERS = ("high", "low", "rise", "fall", "both")
@@ -338,13 +340,14 @@ def from_interleaved(data: bytes | bytearray | memoryview, names: list[str], wid
     return out
 
 
-TRIGGER = {"high": (1, 1), "low": (1, 0), "rise": (2, 0), "fall": (2, 1), "both": (2, 2)}   # (type, value), oep-if-capture
-TAG_CHIP, TAG_MODEL, TAG_FIRMWARE, TAG_UNIT_ID = 0x4C, 0x41, 0x40, 0x42     # core describe
+_LEVEL, _EDGE = (_reg.FIXTURE_LOGIC.enum["trigger"][k] for k in ("level", "edge"))
+TRIGGER = {"high": (_LEVEL, 1), "low": (_LEVEL, 0), "rise": (_EDGE, 0), "fall": (_EDGE, 1), "both": (_EDGE, 2)}   # (type, value), capture §3.3
+TAG_CHIP, TAG_MODEL, TAG_FIRMWARE, TAG_UNIT_ID = (_reg.CORE.tlv["describe"][k] for k in ("chip", "model", "firmware", "unit_id"))
 # UART link rates tried by default (port_speed): fastest first. oep-client refuses a rate that breaks and drops back
 # to the boot speed on repeated broken frames, so trying never ends slower than the boot speed; capture_at's
 # fast=[] keeps the boot speed, fast=[RATE, ...] tries those.
 FAST = [1_500_000, 921_600, 500_000]
-PER_SESSION = 2          # candidates tried per open: each costs up to ~1 s, plus a wait when it fails (core §3.5)
+PER_SESSION = 2          # candidates tried per open: each costs up to ~1 s, plus a wait when it fails (oep-if-link §3)
 FLOWS = [("in", 0)]      # a capture reads back: verify probe -> host only, at the link's largest in-flight n
 
 

oep_client/capture.py

@@ -51,12 +51,9 @@ MODE, RATE, SAMPLES, SEGMENTS, TRIGGER, PRETRIGGER, TRIGGER_OPTS, FORMAT, CARRIA
     _CAP.tlv["configure"][k] for k in ("mode", "rate", "samples", "segments", "trigger", "pretrigger", "trigger_opts",
                                        "format", "carriage", "block_max"))
 ANSWER_FORMAT, ANSWER_BLOCK = _CAP.tlv["configure_answer"]["format"], _CAP.tlv["configure_answer"]["block"]
-ANSWER_FORMAT_NAME = _CAP.tlv["configure_answer"]["format_name"]
-# §3.8 / §3.9, optional (a probe declares them in its describe): configure TLVs by name, sent critical
+# §3.8, optional (a probe declares them in its describe): configure TLVs by name, sent critical
 OPTION_TLV = {**_CAP.tlv["configure"], **_ANA.tlv["configure"]}
-LOGIC_USED = {k: _CAP.tlv["configure_answer"][k] for k in ("threshold_used", "glitch_used", "timebase")}
-ANALOG_USED = {k: _ANA.tlv["configure_answer"][k] for k in ("coupling_used", "offset_used", "bandwidth_used",
-                                                            "resolution_used", "oversample_used")}
+LOGIC_USED = {k: _CAP.tlv["configure_answer"][k] for k in ("glitch_used", "timebase")}
 NO_QUALIFIER = 0xFF                                        # clock: qualifier_role none (§3.8)
 STREAM_BUFFER = _CAP.tlv["configure_answer"]["stream_buffer"]
 JUDGE_LATENCY = _CAP.tlv["configure_answer"]["judge_latency_ns"]
@@ -180,7 +177,6 @@ class Config:
     raw_roles: list[int] = field(default_factory=list)         # format 1: the raw channels' roles (as asked)
     event_d: dict[int, int] = field(default_factory=dict)      # format 1: events role -> D (as asked)
     carriage: dict[int, tuple[int, int]] = field(default_factory=dict)   # format 2: role -> (kind, D) (as asked)
-    format_name: str | None = None                             # format 0xFF: the named format in use
     timebase: Fraction | None = None                           # format 3: the delta's tick rate (Hz)
     external_clock: bool = False                               # sampled on a clock line (actual_rate 0 / 1, §3.8)
     used: dict[str, dict[int, int] | int] = field(default_factory=dict)   # §3.8's *_used: name -> group/role -> value
@@ -322,7 +318,7 @@ class Event:
     serial: int | None = None
     trigger_index: int | None = None
     trigger_ns: int | None = None
-    record: int | None = None                # triggered: the trigger record's serial (None: no record, §3.10)
+    record: int | None = None                # triggered: the trigger record's serial (None: no record, §3.9)
     sample: int | None = None                # triggered: the original sample from the generation's start
     uncertainty_ns: int | None = None        # triggered: trigger_ns's +-ns
     trigger_fn: int | None = None            # a group's triggered: the track that judged it (0: force, timer)
@@ -368,7 +364,7 @@ def unpack_event(frame: bytes, group: bool = False) -> Event:
 
 
 NO_RECORD = 0xFFFFFFFF
-TRIGGER_RECORD_BYTES = 24                  # serial u32, sample u64, trigger_ns u64, uncertainty_ns u32 (§3.10)
+TRIGGER_RECORD_BYTES = 24                  # serial u32, sample u64, trigger_ns u64, uncertainty_ns u32 (§3.9)
 
 
 CAPTURE_DROPS = "io.github.open-embedded-probe.capture-drops"
@@ -422,7 +418,7 @@ class CaptureDrops:
 @dataclass(frozen=True)
 class TriggerOpts:
     """configure's trigger_opts (§3.3): `arm` 1 looks once the pretrigger is there (0: at once, a short segment);
-    `rearm` 1 a trigger for every segment (streaming: a record for every event, §2.1, §3.10); `when` 1 a level
+    `rearm` 1 a trigger for every segment (streaming: a record for every event, §2.1, §3.9); `when` 1 a level
     already true at arming counts; `hysteresis` (analog cross, in ADC values) back that far before the next crossing.
     The defaults are every probe's; the others as describe's trigger opts says."""
     arm: int = 1
@@ -433,7 +429,7 @@ class TriggerOpts:
 
 @dataclass(frozen=True)
 class TriggerRecord:
-    """A trigger record (§3.10): serial (from 0 in the generation), the original sample from the generation's start,
+    """A trigger record (§3.9): serial (from 0 in the generation), the original sample from the generation's start,
     trigger_ns and its uncertainty."""
     serial: int
     sample: int
@@ -452,23 +448,18 @@ def take_events(link, fn: int) -> list[bytes]:
 
 
 def _options(options: dict) -> bytes:
-    """§3.8 / §3.9's configure TLVs, critical but overflow (configure's `options`)."""
-    forms = {"threshold": "<iI", "glitch_filter": "<I", "coupling": "<B", "offset": "<i", "bandwidth": "<I"}
+    """§3.8's configure TLVs, critical (configure's `options`)."""
     out = b""
     for name, value in options.items():
-        tag = OPTION_TLV[name] | (0 if name == "overflow" else CRITICAL)   # overflow: §3.3's table, as block_max
-        if name in forms:                                  # per group / role
-            for key, v in sorted(value.items()):
-                out += m.tlv(tag, bytes([key]) + struct.pack(forms[name], *(v if isinstance(v, tuple) else (v,))))
+        tag = OPTION_TLV[name] | CRITICAL
+        if name == "glitch_filter":                        # per group (group 0 only, §3.8)
+            for group, ns in sorted(value.items()):
+                out += m.tlv(tag, bytes([group]) + struct.pack("<I", ns))
         elif name == "clock":
             role, edge, qualifier, level = value
             out += m.tlv(tag, bytes([role, edge, NO_QUALIFIER if qualifier is None else qualifier, level]))
-        elif name == "oversample":
-            out += m.tlv(tag, struct.pack("<H", value))
-        elif name == "data_path":
-            out += m.tlv(tag, bytes(value))
-        else:                                              # resolution, overflow: u8
-            out += m.tlv(tag, bytes([value]))
+        else:
+            raise ValueError(f"capture configure: no option {name!r} (oep-if-capture §3.8)")
     return out
 
 
@@ -514,27 +505,12 @@ def _config(payload: bytes, analog: bool) -> Config:
             c.skew_ns[role] = ns
         elif tag == FRONTEND_USED and analog and len(v) == 2:
             c.frontend[v[0]] = v[1]
-        elif tag == ANSWER_FORMAT_NAME:
-            c.format_name = c.format_name or v.decode("ascii", "replace")
         elif not analog and tag == LOGIC_USED["timebase"] and len(v) == 8:
             num, den = struct.unpack("<II", v)
             c.timebase = Fraction(num, den) if den else None
-        elif not analog and tag == LOGIC_USED["threshold_used"] and len(v) == 9:
-            group, mv, hyst = struct.unpack("<BiI", v)
-            c.used.setdefault("threshold_used", {})[group] = (mv, hyst)
         elif not analog and tag == LOGIC_USED["glitch_used"] and len(v) == 5:
             group, ns = struct.unpack("<BI", v)
             c.used.setdefault("glitch_used", {})[group] = ns
-        elif analog and tag in (ANALOG_USED["coupling_used"], ANALOG_USED["offset_used"], ANALOG_USED["bandwidth_used"]):
-            name = next(k for k, t in ANALOG_USED.items() if t == tag)
-            form = {"coupling_used": "<BB", "offset_used": "<Bi", "bandwidth_used": "<BI"}[name]
-            if len(v) == struct.calcsize(form):
-                role, value = struct.unpack(form, v)
-                c.used.setdefault(name, {})[role] = value
-        elif analog and tag == ANALOG_USED["resolution_used"] and len(v) == 1:
-            c.used["resolution_used"] = v[0]
-        elif analog and tag == ANALOG_USED["oversample_used"] and len(v) == 2:
-            c.used["oversample_used"] = struct.unpack("<H", v)[0]
         elif tag == REFERENCE and analog and len(v) == 6:
             source, mv, how = struct.unpack("<BIB", v)
             # how: nominal False, measured True; an unknown value is shown as it is, not as nominal (core §2.4)
@@ -566,7 +542,7 @@ class LogicCapture(Interface):
                   frontends: dict[int, int] | None = None, trigger_opts: TriggerOpts | None = None,
                   data_format: int = 0, events: dict[int, int] | None = None, roles: list[int] | None = None,
                   block_max: int | None = None, carriage: dict[int, tuple[int, int]] | None = None,
-                  format_name: str | None = None, options: dict | None = None) -> Config:
+                  options: dict | None = None) -> Config:
         """-> the probe's actual values. A value the probe cannot honour is refused: host.Unsupported, .tag = the TLV as
         sent (§3.3). The TLVs go without the critical bit (§3.3). Read Config.samples / .segments: the probe rounds
         samples down.
@@ -575,13 +551,11 @@ class LogicCapture(Interface):
         carried as events (the others raw), `roles` the plan's roles (to name the raw channels), `block_max` the
         longest block (§3.3's table: without the critical bit). Format 2 (analog blocks, §1.4): `carriage` role ->
         (kind, D), kind a bit set of capture_blocks.PACKED / MINMAX / SUM (the roles not named packed). Format 4 (test
-        counter) needs nothing else. Format 0xFF: `format_name`. The others go critical.
+        counter) needs nothing else. The others go critical.
 
-        `options` (§3.8 / §3.9, critical; a probe without one refuses it): "threshold" group -> (mv, hysteresis_mv),
-        "glitch_filter" group -> ns, "clock" (role, edge, qualifier role or None, qualifier level), "coupling" role ->
-        kind, "offset" role -> mV, "bandwidth" role -> Hz, "resolution" bits, "oversample" ratio, "data_path" (path,
-        mux, kind), "overflow" 0 / 1 (plain: §3.3's table). The answer's values in use: Config.used, by the answer TLV's
-        name.
+        `options` (§3.8, critical; a probe without one refuses it): "glitch_filter" group -> ns (group 0 only),
+        "clock" (role, edge, qualifier role or None, qualifier level). The answer's values in use: Config.used, by the
+        answer TLV's name.
 
         §3.3's contract is checked before anything is sent (ValueError): `samples` is needed in one-shot and repeat
         and not taken in streaming, `segments` is repeat's only, `pretrigger` needs a trigger (type other than 0) - a
@@ -617,10 +591,6 @@ class LogicCapture(Interface):
             body += tlv(FRONTEND, bytes([role, fe]))
         if data_format:                                      # critical: a probe without it refuses (§3.3)
             body += m.tlv(FORMAT | CRITICAL, bytes([data_format]))
-        if (data_format == DATA_FORMAT["named"]) != (format_name is not None):
-            raise ValueError("capture configure: format 0xFF goes with its format_name, and only it (oep-if-capture §3.3)")
-        if format_name is not None:
-            body += m.tlv(OPTION_TLV["format_name"] | CRITICAL, format_name.encode("ascii"))
         body += _options(options or {})
         if data_format == DATA_FORMAT["logic_blocks"] and roles is None:
             raise ValueError("capture configure: format 1 needs the plan's roles (to name the raw channels)")
@@ -806,7 +776,7 @@ class LogicCapture(Interface):
         return out, bool(more)
 
     def triggers_page(self, from_serial: int = 0, generation: int | None = None) -> tuple[list[TriggerRecord], bool]:
-        """One answer's trigger records (§3.10) from `from_serial` on, paged as segments are. -> (records, more)."""
+        """One answer's trigger records (§3.9) from `from_serial` on, paged as segments are. -> (records, more)."""
         payload = struct.pack("<II", self._generation(generation), from_serial)
         rd = m.Reader(self._call(self.TRIGGERS, payload, locked=False).payload)
         more, count = rd.take("BB")
@@ -879,7 +849,7 @@ class LogicCapture(Interface):
         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
+        (reads are not deduplicated, oep-core §5.1). 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)."""
         g = self._generation(generation)

oep_client/conformance/__init__.py

@@ -66,7 +66,7 @@ SERIAL_CASES = tuple(('CORE-SERIAL-' + kind.upper(), kind) for kind in
 
 
 RECONNECT_CASES = tuple(('CORE-RECONNECT-' + kind.upper(), kind) for kind in
-                        ('session', 'replay', 'ended', 'lease'))
+                        ('session', 'replay', 'ended', 'lease', 'unread'))
 
 
 TCP_CASES = tuple(('CORE-TCP-' + kind.upper(), kind) for kind in
@@ -75,6 +75,7 @@ TCP_CASES = tuple(('CORE-TCP-' + kind.upper(), kind) for kind in
 
 TCP_PEER_CASES = tuple(('CORE-TCP-PEER-' + kind.upper(), kind) for kind in
                        ('identity', 'lock', 'route', 'partial', 'close', 'oversized'))
+ROUTE_PEER_CASES = tuple(('CORE-ROUTE-PEER-' + kind.upper(), kind) for kind in ('identity', 'lock', 'route'))
 
 
 class NotApplicable(Exception):
@@ -121,7 +122,7 @@ CHECKER_SOURCES = ('__init__.py', 'core_smoke.py', 'session_smoke.py', 'interfac
                    'port_speed.py', 'port_speed_sample.py', 'port_speed_lifecycle.py', 'port_speed_execution.py', 'port_speed_execution_sample.py',
                    'host_tlv.py', 'host_tlv_sample.py', 'host_core.py', 'core_fixed_fields.py', 'probe_input.py', 'probe_input_sample.py', 'refusal_order.py', 'refusal_order_sample.py', 'restart.py', 'restart_sample.py', 'host_wait.py', 'host_wait_sample.py', 'host_deadline.py', 'host_deadline_sample.py', 'host_resend.py', 'host_resend_sample.py', 'tcp_recovery.py', 'tcp_recovery_sample.py', 'host_core_sample.py', 'allocator.py', 'allocator_sample.py', 'discovery.py', 'clock.py', 'clock_sample.py',
                    'notification_sequence.py', 'notification_sequence_sample.py', 'notification_retention.py', 'notification_retention_sample.py', 'serial.py', 'tcp.py',
-                   'tcp_peers.py', 'usb.py', 'usb_cases.py',
+                   'tcp_peers.py', 'usb.py', 'usb_cases.py', 'usb_hw.py', 'force_hw.py', 'notify_hw.py', 'release_hw.py',
                    '../pytest_conformance.py', 'resources.py', 'resource_sample.py',
                    'subscriptions.py', 'subscription_sample.py',
                    'data.py', 'data_sample.py',
@@ -144,7 +145,7 @@ def checker_sources_sha256():
             for name in CHECKER_SOURCES}
 
 
-REVIEWED_CORE_SHA256 = '699f7eb6333b6eb6678ddcf27074c03544f0f0a6ee0ef6ccdf02edd3757f962e'   # oep-spec docs/oep-core.ja.md
+REVIEWED_CORE_SHA256 = 'b90ae1b15f10442ff411929e80d8457e754d5f11f227167d3c142f54ff14768a'   # oep-spec docs/oep-core.ja.md
 
 
 def require_reviewed_contract(registry, spec=None):
@@ -208,10 +209,12 @@ class Checks:
         self.abort = False
         self.wire = None
         self.reopen = None
+        self.post = None          # with reopen: write one framed request and read nothing (the answer is left behind)
         self.tcp_wire = None
         self.usb_wire = None
         self.tcp_peer_open = None
         self.tcp_reopen = None
+        self.route_peer = None    # another route of the same probe: (open, Checks attribute, this route's wire)
 
     def request(self, op, payload=b'', *, session=0, corr=None, fn=0):
         automatic = corr is None
@@ -452,7 +455,17 @@ class Checks:
     def reconnect(self, kind):
         lease = 1000 if kind == 'lease' else 60000
         with self.holding(lease) as sid:
-            request, original = self.clock(sid)
+            if kind == 'unread':
+                # the answer is lost with the connection: the request goes on the old one, nothing read (core §5.1,
+                # transports §3: what was not yet sent on a closed route is dropped)
+                if self.post is None:
+                    raise NotApplicable('no raw write on this route')
+                request, original = self.request(self.core['clock'], session=sid), None
+                self.post(request)
+                time.sleep(0.3)
+                posted = time.monotonic_ns()
+            else:
+                request, original = self.clock(sid)
             if kind == 'ended':
                 tlvs(self.success(self.request(self.core['end'], session=sid)))
                 self.session = None
@@ -491,6 +504,19 @@ class Checks:
                         self.session = sid  # clean up buggy resurrection
                     require(reply[3:5] == bytes((0, self.reasons['no_session'])),
                             'reconnect forgot ended session and allowed reopening')
+                elif kind == 'unread':
+                    # the same request on the new route: the recorded answer or result_lost, never run again - a
+                    # recorded clock answer is older than the time since it was posted, a run again is not
+                    reply = self.exchange(request)
+                    if reply[3:5] != bytes((0, self.reasons['result_lost'])):
+                        require(reply[3:5] == b'\x01\0' and len(reply) >= 17, 'resend after the route closed: '
+                                'neither the recorded answer nor result_lost')
+                        then = int.from_bytes(reply[9:17], 'little')
+                        waited = time.monotonic_ns() - posted
+                        _, now = self.clock()
+                        require(int.from_bytes(now[4:12], 'little') - then >= waited - 50_000_000,
+                                'the request resent on the new route ran again (core §5.1)')
+                    tlvs(self.success(self.request(self.core['keepalive'], session=sid)))
                 elif kind == 'lease':
                     time.sleep(0.6)
                     state = self.success(self.request(self.core['lock_state']))
@@ -987,10 +1013,16 @@ class Checks:
             for name, kind in RECONNECT_CASES:
                 self.check(name, 'transports §3; core §5.1/6.1/9', lambda kind=kind: self.reconnect(kind))
         if self.usb_wire is not None:
-            from .usb_cases import USB_CASES, HID_CASES, run
-            cases = USB_CASES + (HID_CASES if self.usb_wire.kind == 'hid' else ())
+            from .usb_cases import USB_CASES, BULK_CASES, HID_CASES, run
+            cases = USB_CASES + (HID_CASES if self.usb_wire.kind == 'hid' else BULK_CASES)
             for name, kind in cases:
                 self.check(name, 'transports §1/2/3; core §2.4', lambda kind=kind: run(self, kind))
+        if self.route_peer is not None:
+            from .tcp_peers import Peers
+            open_peer, attr, own = self.route_peer
+            routes = Peers(self, open_peer, attr, own)
+            for name, kind in ROUTE_PEER_CASES:
+                self.check(name, 'transports §3; core §6', lambda kind=kind: getattr(routes, kind)())
         if self.tcp_peer_open is not None:
             from .tcp_peers import Peers
             peers = Peers(self)
@@ -1065,6 +1097,8 @@ def main(argv=None):
                                 wire.stream.close()
                                 wire.stream = link.open_serial(args.address)
                             checks.reopen = reopen
+                            from .serial import frame as serial_frame
+                            checks.post = lambda message: wire.stream.write(serial_frame(message))
                             report.update(checks.run())
                         finally:
                             link._exclusive_off(wire.stream)
@@ -1075,6 +1109,13 @@ def main(argv=None):
                         try:
                             checks = Checks(wire.send, registry, args.unit)
                             checks.tcp_wire = wire
+                            from .tcp import frame as tcp_frame
+
+                            def reopen():               # a new connection: the route moves (transports §3)
+                                wire.stream.close()
+                                wire.stream = TcpWire.open(args.address).stream
+                            checks.reopen = reopen
+                            checks.post = lambda message: wire.stream.sendall(tcp_frame(message))
                             if args.tcp_peer:
                                 checks.tcp_peer_open = lambda: TcpWire.open(args.tcp_peer)
                                 def reopen_tcp():

oep_client/conformance/allocator.py

@@ -80,7 +80,7 @@ class AllocatorChecks(ResourceChecks):
         if self.c.results[-1]['status']!='passed':self.c.abort=True
         for name,case in [('BOUNDARY',self.boundary),('END',self.ended_boundary),('EXPIRY',lambda:self.ended_boundary(True)),
                           ('FORCE',self.force_boundary),('REPLAY',self.replay_boundary),('REBOOT',self.reboot_boundary)]:
-            first=len(self.a.trace);self.c.check('CORE-ALLOCATOR-'+name,'core §5.2/6/9',case);self.c.results[-1]['adapter_trace']=self.a.trace[first:]
+            first=len(self.a.trace);self.c.check('CORE-ALLOCATOR-'+name,'core §5.1/6/9',case);self.c.results[-1]['adapter_trace']=self.a.trace[first:]
         rows=self.c.results[start:]
         return dict(status='passed' if all(x['status']=='passed' for x in rows) else 'failed',checks=rows,adapter_trace=self.a.trace,
                     observed=self.c.observed,full_conformance=False,scope='logical seeded u32 allocation boundary and session/reboot invariants',

oep_client/conformance/capture_serial.py

@@ -17,7 +17,7 @@ def refused_stale(reply):
     return reply[3:5]==b'\0\4' and refusal_carries('unavailable',reply[5:],b'\1\1\0\6')
 from .host_deadline import reviewed_identity as core_identity
 
-REVIEWED={'interfaces/oep-if-capture.ja.md':'ffd89a6a1abf006aea788a6b47b270e6ac0e6d8190a716f4123c4f499bd3a61e',
+REVIEWED={'interfaces/oep-if-capture.ja.md':'9bab21bc5e8cdf069448dea059af459b6d7a46757554ca7aee4196b04e1dccd6',
           'interfaces/oep-if-common.ja.md':'25fed0b1b8b7f246a8b71d02cea810249803b1c3c1e9c3df466c04f38687f70c'}
 
 def reviewed_identity(path):

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 = '699f7eb6333b6eb6678ddcf27074c03544f0f0a6ee0ef6ccdf02edd3757f962e'  # oep-spec docs/oep-core.ja.md
+REVIEWED_CORE_SHA256 = 'b90ae1b15f10442ff411929e80d8457e754d5f11f227167d3c142f54ff14768a'  # oep-spec docs/oep-core.ja.md
 
 
 class CoreSmokeChecks:

oep_client/conformance/cut.py

@@ -78,6 +78,6 @@ class CutChecks(DebugChecks):
         if self.c.results[-1]['status']!='passed':self.c.abort=True
         cases=[('REQUEST',self.request_cut),('REQUEST-HALTED',lambda:self.request_cut(True)),('REQUEST-PARTIAL',lambda:self.request_cut(partial=True)),('CONSOLE',self.console_cut),('CONSOLE-HALTED',lambda:self.console_cut(True)),('RECOVERY',self.recovery),('ISOLATED',self.isolated),('REJECTED',self.rejected)]
         for name,case in cases:
-            first=len(self.a.trace);self.c.check('OEP-CUT-'+name,'debug §2; common §1/2; core §5.2/9',case);self.c.results[-1]['adapter_trace']=self.a.trace[first:]
+            first=len(self.a.trace);self.c.check('OEP-CUT-'+name,'debug §2; common §1/2; core §5.1/9',case);self.c.results[-1]['adapter_trace']=self.a.trace[first:]
         rows=self.c.results[start:]
         return dict(status='passed' if all(r['status']=='passed' for r in rows) else 'failed',checks=rows,adapter_trace=self.a.trace,observed=self.c.observed,full_conformance=False,scope='logical response writer before request wire-cut; console line loss and dependent release',unchecked=['physical writer/pins and actual transport delivery','writer concurrency, lease expiry while blocked and alternate budgets','resync/TO/framing marks','poll/wait DMI failure injection and store-trigger writes','production Host integration'])

oep_client/conformance/data.py

@@ -301,7 +301,7 @@ class DataChecks(SubscriptionChecks):
         super().run()
         for name, method in DATA_CASES:
             first = len(self.notifications)
-            self.c.check(name, 'core §11.2/11.3', getattr(self, method))
+            self.c.check(name, 'core §10.2/11.3', getattr(self, method))
             self.c.results[-1]['notification_observations'] = self.notifications[first:]
         rows = self.c.results[start:]
         return {'status': 'passed' if all(row['status'] == 'passed' for row in rows) else 'failed',

oep_client/conformance/dependencies.py

@@ -250,7 +250,7 @@ class DependencyChecks:
         cases += [('MARKS',self.marks),('MALFORMED',lambda:self.refusal(True)),('OWNER',self.refusal),('DETACH',self.detach),('BREAK',lambda:self.detach(True)),('REPLAY',self.replay),('DETACH-REPLAY',self.detach_replay),('SAME-SESSION',self.same_session)]
         cases += [(kind,lambda kind=kind:self.ending(kind)) for kind in ('END','EXPIRY','FORCE')]+[('LOCKS',self.locks)]
         for name,case in cases:
-            first=len(self.a.trace);self.c.check('IF-DEPENDENCY-'+name,'common §1/2; core §5.2/9',case)
+            first=len(self.a.trace);self.c.check('IF-DEPENDENCY-'+name,'common §1/2; core §5.1/9',case)
             self.c.results[-1]['adapter_trace']=self.a.trace[first:]
         rows=self.c.results[start:]
         return {'status':'passed' if all(r['status']=='passed' for r in rows) else 'failed','full_conformance':False,

oep_client/conformance/force_hw.py

@@ -0,0 +1,147 @@
+"""force releases the resources of the session it takes from (core §6.4, §9; debug-common §2), on a real probe.
+
+A session S attaches to a target over a wire (a debug connection: a numbered resource), then a session T of another id
+opens with force. Then: S's connection is gone from connections, a detach of its number is rejected no_resource, S's
+own requests are not completed, and T's attach to the same pins gets a new, larger number (numbers are never re-used
+within a boot). T detaches and ends. The wire, its pins and the speed are named by the user (the target's wiring); the
+route is the probe's USB vendor bulk, opened as conformance.usb_hw opens it. Numbers come from the SPEC registry.
+
+    python -m oep_client.conformance.force_hw --unit UNIT --wire oep.wire.rvswd --swdio 14 --swclk 15 \\
+        --spec SPEC --out NEW.json --lock LOCK
+"""
+import argparse
+import json
+import os
+import secrets
+import struct
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import Checks, checker_sources_sha256, require, spec_identity, tlvs
+from .usb import UsbWire
+
+
+def interface(registry, name):
+    spec = next(i for i in registry['interface'] if i['name'] == name)
+    return {o['name']: o['code'] for o in spec['op']}
+
+
+def connections(check, fn, op):
+    """The live connection numbers of the wire `fn` (lock-free, session 0; paged by first, debug §2.1)."""
+    first, found = 0, []
+    while True:
+        p = check.success(check.request(op, bytes((first,)), fn=fn))
+        require(len(p) >= 2, 'connections fixed part')
+        more, count = p[0], p[1]
+        at = 2
+        for _ in range(count):
+            require(len(p) >= at + 14, 'connections entry')
+            found.append(struct.unpack_from('<I', p, at)[0])
+            tid_len = p[at + 13]
+            at += 14 + tid_len
+        if not more or not count:
+            return found
+        first += count
+
+
+def run(check, *, wire_name, swdio, swclk, speed):
+    ops = interface(check.reg, wire_name)
+    entries = check.list_snapshot()
+    fn = next((e['fn'] for e in entries if e['name'] == wire_name), None)
+    require(fn is not None, f'{wire_name} is not listed')
+    attach_body = struct.pack('<BHHI', 0, swdio, swclk, speed)    # method 0: run, do not halt (debug §1)
+    out = {'wire_fn': fn}
+
+    def open_session(force):
+        sid = secrets.randbelow(0xffffffff) + 1
+        check.corr = 0
+        p = check.success(check.request(check.core['open'], struct.pack('<IB', 60000, force), session=sid))
+        require(len(p) >= 8 and struct.unpack_from('<I', p, 4)[0] == check.boot, 'open boot')
+        check.session = sid
+        return sid
+
+    def attach(sid):
+        p = check.success(check.request(ops['attach'], attach_body, session=sid, fn=fn))
+        require(len(p) >= 13, 'attach fixed part')
+        return struct.unpack_from('<I', p)[0]
+
+    s = open_session(0)
+    first = attach(s)
+    out['s_connection'] = first
+    require(first in connections(check, fn, ops['connections']), 'the attach is not in connections')
+    t = open_session(1)                                        # another id, force: takes the lock from S (core §6.4)
+    out['t_session_differs'] = t != s
+    live = connections(check, fn, ops['connections'])
+    out['after_force'] = live
+    require(first not in live, "force left S's connection open (core §9)")
+    check.rejected(check.request(ops['detach'], struct.pack('<I', first), session=t, fn=fn), 'no_resource')
+    saved, check.corr = check.corr, 1000                           # S's own numbers, far from T's
+    reply = check.exchange(check.request(check.core['keepalive'], session=s))
+    check.corr = saved
+    out['s_keepalive'] = reply[3:5].hex()
+    require(reply[3] == check.reg['resolutions']['rejected'], 'S kept a session after the force')
+    second = attach(t)
+    out['t_connection'] = second
+    require(second != first and second > first, 'a connection number was re-used or went back (core §9)')
+    tlvs(check.success(check.request(ops['detach'], struct.pack('<I', second), session=t, fn=fn)))
+    require(second not in connections(check, fn, ops['connections']), 'detach left the connection')
+    tlvs(check.success(check.request(check.core['end'], session=t)))
+    check.session = None
+    return out
+
+
+def main(argv=None):
+    from .. import __version__
+    from ..hardware import equipment_lock
+    from .usb_hw import BulkBackend, find_device
+    parser = argparse.ArgumentParser(description=__doc__)
+    for name, env in [('unit', 'OEP_CONFORMANCE_UNIT_ID'), ('spec', 'OEP_CONFORMANCE_SPEC'),
+                      ('out', 'OEP_CONFORMANCE_OUT'), ('lock', 'OEP_HW_LOCK')]:
+        parser.add_argument('--' + name, default=os.environ.get(env))
+    parser.add_argument('--wire', required=True, help='the wire interface name, e.g. oep.wire.rvswd')
+    parser.add_argument('--swdio', type=int, required=True, help="the target's SWDIO / SWIO channel")
+    parser.add_argument('--swclk', type=int, default=0xFFFF, help="the target's SWCLK channel (0xFFFF: none)")
+    parser.add_argument('--speed', type=int, default=1_000_000, help='attach max_speed (Hz)')
+    args = parser.parse_args(argv)
+    if not all(getattr(args, name) for name in ('unit', 'spec', 'out', 'lock')):
+        parser.error('explicit unit, SPEC checkout, new output file and existing shared lock required')
+    registry, identity = spec_identity(args.spec)
+    report = {'status': 'failed', 'spec': identity, 'client_version': __version__,
+              'checker_sources_sha256': checker_sources_sha256(), 'expected_unit': args.unit,
+              'wire': args.wire, 'pins': [args.swdio, args.swclk], 'full_conformance': False,
+              'started_at': datetime.now(timezone.utc).isoformat()}
+    with Path(args.out).open('x') as artifact:
+        try:
+            with equipment_lock(args.lock):
+                dev = find_device(registry['usb']['project_vid'], registry['usb']['project_pid'], args.unit)
+                backend = BulkBackend(dev, registry['usb'])
+                try:
+                    wire = UsbWire(backend, 'bulk', **backend.shape)
+                    check = Checks(wire.send, registry, args.unit)
+                    check.usb_wire = wire
+                    check.confirm()
+                    check.identity()
+                    try:
+                        report['observed'] = run(check, wire_name=args.wire, swdio=args.swdio, swclk=args.swclk,
+                                                 speed=args.speed)
+                        report['status'] = 'passed'
+                    finally:
+                        if check.session is not None:          # a failed run: end what this run holds
+                            try:
+                                check.exchange(check.request(check.core['end'], session=check.session))
+                            except Exception:
+                                pass
+                        report['trace'] = check.trace
+                finally:
+                    backend.close()
+        except Exception as exc:
+            report.update(status='failed', error=f'{type(exc).__name__}: {exc}')
+        report['finished_at'] = datetime.now(timezone.utc).isoformat()
+        json.dump(report, artifact, ensure_ascii=False, indent=2, default=str)
+        artifact.write('\n')
+    print(f"{report['status']}: {args.out}" + (f" ({report.get('error')})" if report.get('error') else ''))
+    return int(report['status'] != 'passed')
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

oep_client/conformance/gpio_lifecycle.py

@@ -59,11 +59,11 @@ class GpioLifecycleChecks(GpioChecks):
             specs={s['name']:s for s in self.c.reg['interface']};require(all(specs[n]['revision']==1 for n in self.a.selection.values()),'selected revision differs')
             self.codes={fn:{r['name']:r['code'] for r in specs[name]['op']} for fn,name in self.a.selection.items()};self.assignment=specs['oep.probe.plan']['tlv']['plan_apply']['role_assignment']
             self.c.confirm();self.c.identity();self.c.declarations();entries=self.c.list_snapshot();require(all(any(r['fn']==fn and r['name']==name and r['revision']==1 for r in entries) for fn,name in self.a.selection.items()),'selected fn identity differs');require(self.a.state()['clock_scope']=='explicit-logical-ms','explicit clock required')
-        self.c.check('CORE-GPIO-LIFECYCLE-CONTEXT','core §5.2/6/8/9; logical fixture',context)
+        self.c.check('CORE-GPIO-LIFECYCLE-CONTEXT','core §5.1/6/8/9; logical fixture',context)
         if self.c.results[-1]['status']!='passed':self.c.abort=True
         for kind in self.cases:
             action=(lambda kind=kind:self.expiry(kind)) if kind.startswith('EXPIR') else self.ended_id if kind=='ENDED-ID' else self.same_id if kind=='SAME-ID-OPEN' else (lambda:self.force(False)) if kind=='FORCE' else (lambda:self.force(True)) if kind=='FORCE-OLD' else (lambda:self.renewed(False)) if kind=='KEEPALIVE' else (lambda:self.renewed(True)) if kind=='REJECTED-RENEWAL' else self.nonrenewal
             def isolated(action=action):self.fresh();action()
-            first=len(self.a.trace);self.c.check('CORE-GPIO-LIFECYCLE-'+kind,'core §5.2/6/8/9; GPIO plan resources',isolated);self.c.results[-1]['adapter_trace']=self.a.trace[first:]
+            first=len(self.a.trace);self.c.check('CORE-GPIO-LIFECYCLE-'+kind,'core §5.1/6/8/9; GPIO plan resources',isolated);self.c.results[-1]['adapter_trace']=self.a.trace[first:]
         rows=self.c.results[start:]
         return dict(status='passed' if all(r['status']=='passed' for r in rows) else 'failed',checks=rows,observed=self.c.observed,adapter_trace=self.a.trace,full_conformance=False,scope='core session ownership/expiry/replay with explicit logical GPIO plan resources',unchecked=['physical pin transition timing and persisted config idle/disable','deferred writer/force concurrency with these GPIO resources','other fixture plan role constraints/channel_group','production Host and other standard operation behaviors'])

oep_client/conformance/host_core.py

@@ -4,7 +4,7 @@ from pathlib import Path
 import struct
 from . import require,spec_identity
 
-REVIEWED_CORE_SHA256='699f7eb6333b6eb6678ddcf27074c03544f0f0a6ee0ef6ccdf02edd3757f962e'
+REVIEWED_CORE_SHA256='b90ae1b15f10442ff411929e80d8457e754d5f11f227167d3c142f54ff14768a'
 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/conformance/host_deadline.py

@@ -9,8 +9,8 @@ from pathlib import Path
 from . import require,spec_identity
 
 
-REVIEWED={'docs/oep-core.ja.md':'699f7eb6333b6eb6678ddcf27074c03544f0f0a6ee0ef6ccdf02edd3757f962e',
-          'docs/oep-transports.ja.md':'2117de20712f7dfad6c81e247cf1b0b206ccf7528fcdf70702cbfce1c17dbadc'}
+REVIEWED={'docs/oep-core.ja.md':'b90ae1b15f10442ff411929e80d8457e754d5f11f227167d3c142f54ff14768a',
+          'docs/oep-transports.ja.md':'2e99bf8039a3d8f5b55c80b66ac97ac40ddf7ad4711079177ffc947c5790103f'}
 QUICK_MS=1000  # core_quick_op_max_ms
 
 

oep_client/conformance/host_request_sample.py

@@ -4,8 +4,7 @@ import struct
 from .. import registry
 
 # The request TLVs this example sends critical, by name (core §2.3: ones that must not be ignored; capture §3.3 / §3.8)
-_CAPTURE_CRITICAL = {'format', 'format_name', 'data_path', 'carriage', 'trigger_opts', 'threshold', 'clock',
-                     'glitch_filter', 'coupling', 'offset', 'bandwidth', 'resolution', 'oversample'}
+_CAPTURE_CRITICAL = {'format', 'carriage', 'trigger_opts', 'clock', 'glitch_filter'}
 _POLICY = {
     'scan': {'max_speed', 'idle_clock', 'targetsel'},
     'attach': {'reset', 'idle_clock', 'targetsel'},