oep-client-python 0.0.4__py3-none-any.whl → 0.0.6__py3-none-any.whl

oep_client/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.0.4"
+__version__ = "0.0.6"

oep_client/__main__.py

@@ -64,6 +64,10 @@ def _config_parser(sub) -> None:
     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("--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",
+                      help="rvswd: SWCLK while the line rests (the target's: low on CH32L103 / V203)")
     slot.add_argument("--lock", help="MASK:VALUE (hex u32) the target_id (WCH DMI 0x7F) must match, e.g. ffffff0f:035e0600")
     slot.add_argument("--save", action="store_true", help="save after the change")
     bind = cs.add_parser("bind", help="what a serial port carries")
@@ -183,7 +187,7 @@ def _config(args) -> int:
                 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.mechanism, lock, args.max_speed, 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)}
@@ -250,6 +254,7 @@ def _show(hst, cfg, as_json: bool) -> int:
             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" 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 = ""

oep_client/config.py

@@ -29,6 +29,7 @@ MECHANISM = {k: v for k, v in reg.TARGET_CONSOLE.enum["mechanism"].items()}
 SLOT_STATE = {v: k.replace("_", "-") for k, v in _CFG.enum["slot_state"].items()}
 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()}
 
 
@@ -79,12 +80,15 @@ class Slot:
     retry_s: int = 0               # at-boot: try again every retry_s while the target is not there (0: never)
     mechanism: str = "dmseq"       # sdi, dmdata, dmseq
     lock: tuple[int, bytes, bytes] | None = None
+    max_speed: int = 0             # the line's ceiling in Hz for the probe's own attach (0: none) - the target's
+    idle_clock: str = "high"       # rvswd: SWCLK while the line rests, high / low - the target's (oep-if-debug §3)
     TAG = ITEM["slot"]
 
     def value(self) -> bytes:
         name = self.name.encode()
-        v = struct.pack("<BHHHBHBB", self.slot, self.wire_fn, *self.pins, ATTACH[self.attach],
-                        self.retry_s if self.attach == "at-boot" else 0, MECHANISM[self.mechanism], len(name)) + name
+        v = struct.pack("<BHHHBHIBBB", self.slot, self.wire_fn, *self.pins, ATTACH[self.attach],
+                        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"
         scheme, mask, value = self.lock
@@ -127,15 +131,16 @@ def decode(tag: int, v: bytes):
         return Label(struct.unpack_from("<H", v)[0], 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]))
-    if tag == ITEM["slot"] and len(v) >= 13:
-        n, wire_fn, swdio, swclk, attach, retry_s, mech, name_len = struct.unpack_from("<BHHHBHBB", v)
-        name = v[12:12 + name_len].decode("ascii", "replace")
-        rest = v[12 + name_len:]
+    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:]
         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)
+        return Slot(n, wire_fn, (swdio, swclk), name, _name(ATTACH, attach), retry_s, _name(MECHANISM, mech), lock,
+                    max_speed, _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)]

oep_client/core.py

@@ -109,7 +109,47 @@ def plan_apply(hst: h.Host, assignments: list[tuple[int, int, int]]) -> None:
     all interfaces accept their roles or nothing changes. The plan is the
     session's resource: kept over an explicit end, released at a lease lapse or a force takeover (oep-core §9)."""
     tlv = b"".join(bytes([TAG_ROLE_ASSIGNMENT, 5]) + struct.pack("<HBH", fn, role, ch) for fn, role, ch in assignments)
-    hst.call(m.CORE_FN, OP_PLAN_APPLY, tlv)
+    try:
+        hst.call(m.CORE_FN, OP_PLAN_APPLY, tlv)
+    except h.Rejected as e:
+        if e.result.detail != m.UNAVAILABLE:
+            raise
+        why = _pin_holders(hst, assignments)
+        if why:
+            raise PinsTaken(e.result, why) from None
+        raise
+
+
+class PinsTaken(h.Rejected):
+    """plan_apply refused (unavailable) and the probe's settings say why: a pin kept by another fn's saved plan or by a
+    slot (oep.probe.config). `holders`: (channel, what holds it)."""
+
+    def __init__(self, result, holders: list[tuple[int, str]]):
+        super().__init__(result)
+        self.holders = holders
+
+    def __str__(self) -> str:
+        return "pins taken: " + "; ".join(f"channel {ch} by {who}" for ch, who in self.holders) + \
+            " (oep config show; oep config remove <probe> plan <fn> frees a saved plan)"
+
+
+def _pin_holders(hst: h.Host, assignments: list[tuple[int, int, int]]) -> list[tuple[int, str]]:
+    """What the settings keep on the channels asked for (best effort: an empty list when there is no oep.probe.config
+    or it cannot be read)."""
+    from . import config
+    try:
+        items = config.ProbeConfig(hst).items()
+    except (LookupError, h.OepError):
+        return []
+    fns = {fn for fn, _, _ in assignments}
+    out = []
+    for fn, role, ch in assignments:
+        for it in items:
+            if isinstance(it, config.Plan) and it.channel == ch and it.fn not in fns:
+                out.append((ch, f"the saved plan of fn {it.fn} (role {it.role})"))
+            elif isinstance(it, config.Slot) and ch in it.pins:
+                out.append((ch, f"slot {it.slot} {it.name}"))
+    return out
 
 
 def plan_release(hst: h.Host, fns: list[int] | tuple[int, ...] = ()) -> None:

oep_client/endpoint.py

@@ -60,6 +60,7 @@ WIRES = ("oep.wire.rvswd", "oep.wire.swio")
 OWNER = reg.CORE.tlv["open"]["owner"]
 SLOT_NAME = re.compile(r"[a-z0-9_-]{1,32}")
 NO_SLOT, NEVER = 0xFF, 0xFFFFFFFF
+PIN_ROLE_RESET = reg.WIRE_RVSWD.enum["pin_role"]["reset"]   # the channels attach_under_reset may take
 
 
 class Reject(Exception):
@@ -180,6 +181,7 @@ class Connection:
     speed: int = 4_000_000
     tid: int | None = None
     users: set = field(default_factory=set)            # "host" and/or ("slot", n)
+    idle_clock: int = 0                                # rvswd: SWCLK while the line rests, 0 high / 1 low
 
 
 @dataclass(frozen=True)
@@ -189,6 +191,8 @@ class Slot:
     pair: tuple[int, int]
     attach: int
     retry_s: int
+    max_speed: int                                     # 0: no ceiling (oep-if-debug §3: the target's, the host's to set)
+    idle_clock: int
     mechanism: int
     name: str
     lock: tuple[int, bytes, bytes] | None              # (scheme, mask, value)
@@ -249,9 +253,13 @@ class Endpoint:
         self.serial_ports = {i for i, k in enumerate(self.transports) if k in fake.SERIAL_KINDS}
         self.pairs: dict[int, list[tuple[int, int]]] = {}  # wire fn -> allowed (swdio, swclk), declared order
         self.max_connections: dict[int, int] = {}
+        self.reset_channels: dict[int, set[int]] = {}     # wire fn -> channels attach_under_reset may take (role 3)
         for fn, name in self.names.items():
             if name in WIRES:
                 self.pairs[fn] = [self._group_pair(name, t) for t in self.static[fn] if t[0] == catalog.CHANNEL_GROUP]
+                self.reset_channels[fn] = {
+                    c for t in self.static[fn] if t[0] == catalog.ROLE_CHANNELS and t[2] == PIN_ROLE_RESET
+                    for c in catalog.bitmap_to_channels(struct.unpack_from("<H", t, 3)[0], t[5:2 + t[1]])}
                 self.max_connections[fn] = next((t[2] for t in self.static[fn] if t[0] == fake.MAX_CONNECTIONS), 1)
         self.targets: dict[tuple[int, tuple[int, int]], FakeTarget] = {
             (fn, p): FakeTarget() for fn in sorted(self.pairs) for p in self.pairs[fn]}
@@ -575,17 +583,18 @@ class Endpoint:
                     got.append(struct.unpack_from("<HBH", value))
                 elif tag & m.TAG_CRITICAL:
                     return m.REJECTED, m.UNSUPPORTED, bytes([tag])
-            self._check_plan(got)
             named = {fn for fn, _, _ in got}
+            if named & self.plan_from_config:                       # the settings' plan is the settings' (core §8)
+                raise Reject(m.UNAVAILABLE)
+            self._check_plan(got)
             self.plan = {a for a in self.plan if a[0] not in named} | set(got)
-            self.plan_from_config -= named
             return m.COMPLETED, m.SUCCESS, b""
         if op == m.OP_PLAN_RELEASE:                                 # n(u8) n x fn(u16); n = 0: every fn
             n = t.take("B")
             fns = {t.take("H") for _ in range(n)}
             t.tail()
-            for fn in {a[0] for a in self.plan if not fns or a[0] in fns}:
-                self._drop_plan(fn)
+            for fn in {a[0] for a in self.plan if not fns or a[0] in fns} - self.plan_from_config:
+                self._drop_plan(fn)                                 # the settings' plans stay, n = 0 too (core §8)
             return m.COMPLETED, m.SUCCESS, b""
         return m.REJECTED, m.UNKNOWN_OPERATION, b""
 
@@ -657,10 +666,14 @@ class Endpoint:
                 if method > 1:
                     raise Reject(m.UNSUPPORTED)
             else:
-                channel, _hold = t.take("HH")
-                if channel not in (0xFFFF, self._channel_named("NRST")):
+                channel, _hold = t.take("HH")                       # no default reset line (oep-if-debug §3)
+                if channel not in self.reset_channels.get(fn, set()) or any(a[2] == channel for a in self.plan):
                     raise Reject(m.UNAVAILABLE)
-            got, ignored = t.tail({0x01, 0x03})
+            rvswd = self.names[fn] == "oep.wire.rvswd"
+            got, ignored = t.tail({0x01, 0x03, 0x04} if rvswd else {0x01, 0x03})
+            if 0x04 in got and (len(got[0x04]) != 1 or got[0x04][0] > 1):
+                raise Reject(m.MALFORMED)
+            idle_clock = got[0x04][0] if 0x04 in got else 0
             pair = self._pick_pair(fn, got)
             tg = self.targets[(fn, pair)]
             speed = min(4_000_000, struct.unpack("<I", got[0x01])[0]) if 0x01 in got else 4_000_000
@@ -676,6 +689,7 @@ class Endpoint:
                 flags |= 2
                 self.conns[cid].speed = min(self.conns[cid].speed, speed)
             c = self.conns[cid]
+            c.idle_clock = idle_clock                              # an existing connection takes the new rest level
             c.users.add("host")
             for n, s in self.slots.items():                        # a new connection for an evicted slot: a new cue
                 if s.wire_fn == fn and s.pair == pair:
@@ -923,7 +937,7 @@ class Endpoint:
                 pos = s.end
             elif frm == 3:
                 hits = [mk for mk in s.marks if arg == 0 or mk[2] == arg]
-                pos = hits[-1][1] if hits else s.base
+                pos = hits[-1][1] if hits else s.end                 # no such mark: from now (common §1.2)
             else:
                 raise Reject(m.UNSUPPORTED)
             flags = 0
@@ -1218,7 +1232,7 @@ class Endpoint:
 
     def _parse_slot(self, v: bytes) -> Slot:
         t = Take(v)
-        n, wire_fn, swdio, swclk, attach, retry_s, mech, name_len = t.take("BHHHBHBB")
+        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:]
@@ -1226,6 +1240,8 @@ class Endpoint:
             raise Reject(m.MALFORMED)
         if retry_s and attach != SLOT_ATTACH["at_boot"]:
             raise Reject(m.MALFORMED)
+        if idle_clock > 1 or (idle_clock and self.names.get(wire_fn) != "oep.wire.rvswd"):
+            raise Reject(m.MALFORMED)
         if not SLOT_NAME.fullmatch(name.decode("ascii", "replace")):
             raise Reject(m.MALFORMED)
         if self.names.get(wire_fn) not in WIRES or (swdio, swclk) not in self.pairs.get(wire_fn, []):
@@ -1239,7 +1255,7 @@ class Endpoint:
             lock = (scheme, rest[:len(rest) // 2], rest[len(rest) // 2:])
         elif rest:
             raise Reject(m.MALFORMED)
-        return Slot(n, wire_fn, (swdio, swclk), attach, retry_s, mech, name.decode(), lock)
+        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)
@@ -1291,7 +1307,9 @@ class Endpoint:
             if not tg.present:
                 return
             try:
-                cid = self._seat(s.wire_fn, s.pair, tg, 4_000_000, evict=False)   # automatic: never evicts
+                speed = min(4_000_000, s.max_speed) if s.max_speed else 4_000_000   # the slot's line settings
+                cid = self._seat(s.wire_fn, s.pair, tg, speed, evict=False)   # automatic: never evicts
+                self.conns[cid].idle_clock = s.idle_clock
             except Reject:
                 return
             tg.havereset = False

oep_client/fake.py

@@ -185,8 +185,8 @@ def esp32_v003() -> FakeProbe:
         _core("3.0.0", "esp32-d0wd", bytes.fromhex("0070070d9394"), 40, reserved, f"{NS}.esp32-v003",
               {16: "SWIO", 23: "NRST", 22: "DUT TX", 21: "DUT RX"},
               _transports([(TRANSPORT["uart_bridge"], 0xFF)])),
-        Offered(1, 1, "oep.wire.swio", (catalog.channel_group(1, [(1, 16)]), catalog.u8(IMPLEMENTATION, 1),
-                                        catalog.u8(MAX_CONNECTIONS, 1))),
+        Offered(1, 1, "oep.wire.swio", (catalog.channel_group(1, [(1, 16)]), catalog.role_channels(3, [23]),
+                                        catalog.u8(IMPLEMENTATION, 1), catalog.u8(MAX_CONNECTIONS, 1))),
         Offered(2, 1, "oep.target.riscv-dm", (catalog.u32(FEATURES, 0b0111), catalog.u8(IMPLEMENTATION, 1),
                                               catalog.u16(MAX_LENGTH, 40))),
         Offered(3, 1, "oep.target.console", (catalog.tlv(MECHANISMS, bytes([0, 1, 2])),)),

oep_client/fake_serve.py

@@ -77,8 +77,8 @@ def build(a: argparse.Namespace) -> endpoint.Endpoint:
         swdio, swclk = ep.pairs[wire][n]
         mech = 2 if 2 in ep.mechanisms else min(ep.mechanisms)
         raw = name.encode()
-        value = struct.pack("<BHHHBHBB", n, wire, swdio, swclk, reg.PROBE_CONFIG.enum["slot_attach"]["at_boot"], 1,
-                            mech, len(raw)) + raw + b"\x00"             # no lock
+        value = struct.pack("<BHHHBHIBBB", n, wire, swdio, swclk, reg.PROBE_CONFIG.enum["slot_attach"]["at_boot"], 1,
+                            0, 0, mech, len(raw)) + raw + b"\x00"       # no speed ceiling, rests high, no lock
         items.append(bytes([_ITEM["slot"], len(value)]) + value)
     if a.bind:
         streams = b"".join(struct.pack("<BH", reg.PROBE_CONFIG.enum["bind_stream"]["slot_console"], n)

oep_client/registry.py

@@ -2,7 +2,7 @@
 
 from types import SimpleNamespace as _NS
 
-REGISTRY_HASH = "7ba704094c2898d2"
+REGISTRY_HASH = "049bd156b4775990"
 SCHEMA = 1
 PROTOCOL_REVISION = 1
 CONFIRM_REQUEST_MAGIC = 'OEP?'
@@ -22,13 +22,13 @@ TIMING = {"resync_quiet_ms": 0x32, "probe_frame_gap_ms": 0xC8, "host_frame_pause
 
 INTERFACES = {}
 CORE = _NS(name="oep.core", revision=1, op={"confirm": 0x01, "list": 0x02, "describe": 0x03, "plan_apply": 0x04, "plan_release": 0x05, "open": 0x10, "end": 0x11, "keepalive": 0x12, "lock_state": 0x13, "subscribe": 0x30, "unsubscribe": 0x32, "link_source": 0x40, "link_sink": 0x41}, lock_free={0x01, 0x02, 0x03, 0x10, 0x13, 0x40, 0x41},
-    closed_tail={0x40}, tlv={"plan_apply": {"role_assignment": 0x90}, "open": {"owner": 0x01}, "lock_state_answer": {"owner": 0x01}, "locked_payload": {"owner": 0x01}, "describe": {"firmware": 0x40, "model": 0x41, "unit_id": 0x42, "channels": 0x43, "reserved": 0x44, "profile": 0x45, "label": 0x46, "resets_on_open": 0x47, "transport": 0x49, "oep_pid": 0x4A}}, event={"heartbeat": 0x01}, enum={"transport_kind": {"uart_bridge": 0x01, "usb_cdc": 0x02, "usb_serial_jtag": 0x03, "vendor_bulk": 0x04, "hid": 0x05, "tcp": 0x06}}, own={})
+    closed_tail={0x40}, tlv={"plan_apply": {"role_assignment": 0x90}, "open": {"owner": 0x01}, "lock_state_answer": {"owner": 0x01}, "locked_payload": {"owner": 0x01}, "describe": {"firmware": 0x40, "model": 0x41, "unit_id": 0x42, "channels": 0x43, "reserved": 0x44, "profile": 0x45, "label": 0x46, "resets_on_open": 0x47, "transport": 0x49, "oep_pid": 0x4A, "plan_roles": 0x4B}}, event={"heartbeat": 0x01}, enum={"transport_kind": {"uart_bridge": 0x01, "usb_cdc": 0x02, "usb_serial_jtag": 0x03, "vendor_bulk": 0x04, "hid": 0x05, "tcp": 0x06}}, own={})
 INTERFACES["oep.core"] = CORE
 WIRE_RVSWD = _NS(name="oep.wire.rvswd", revision=1, op={"scan": 0x01, "attach": 0x02, "detach": 0x03, "attach_under_reset": 0x04, "connections": 0x05}, lock_free={0x05},
-    closed_tail={}, tlv={"describe": {"max_connections": 0x40}, "detach": {"force": 0x01}, "attach": {"max_speed": 0x01, "pins": 0x03}, "attach_under_reset": {"max_speed": 0x01, "pins": 0x03}, "attach_answer": {"target_id": 0x10}}, event={}, enum={"connection_users": {"host_session": 0x01, "slot": 0x02}, "target_id_scheme": {"wch_dmi_7f": 0x01}, "attach_method": {"run": 0x00, "halt": 0x01}, "pin_role": {"swdio": 0x01, "swclk": 0x02}}, own={})
+    closed_tail={}, tlv={"describe": {"max_connections": 0x40}, "detach": {"force": 0x01}, "attach": {"max_speed": 0x01, "pins": 0x03, "idle_clock": 0x04}, "attach_under_reset": {"max_speed": 0x01, "pins": 0x03, "idle_clock": 0x04}, "attach_answer": {"target_id": 0x10}}, event={}, enum={"connection_users": {"host_session": 0x01, "slot": 0x02}, "target_id_scheme": {"wch_dmi_7f": 0x01}, "attach_method": {"run": 0x00, "halt": 0x01}, "pin_role": {"swdio": 0x01, "swclk": 0x02, "reset": 0x03}, "idle_clock": {"high": 0x00, "low": 0x01}}, own={})
 INTERFACES["oep.wire.rvswd"] = WIRE_RVSWD
 WIRE_SWIO = _NS(name="oep.wire.swio", revision=1, op={"scan": 0x01, "attach": 0x02, "detach": 0x03, "attach_under_reset": 0x04, "connections": 0x05}, lock_free={0x05},
-    closed_tail={}, tlv={"describe": {"max_connections": 0x40}, "detach": {"force": 0x01}, "attach": {"max_speed": 0x01, "pins": 0x03}, "attach_under_reset": {"max_speed": 0x01, "pins": 0x03}, "attach_answer": {"target_id": 0x10}}, event={}, enum={"connection_users": {"host_session": 0x01, "slot": 0x02}, "target_id_scheme": {"wch_dmi_7f": 0x01}, "attach_method": {"run": 0x00, "halt": 0x01}, "pin_role": {"swdio": 0x01}}, own={})
+    closed_tail={}, tlv={"describe": {"max_connections": 0x40}, "detach": {"force": 0x01}, "attach": {"max_speed": 0x01, "pins": 0x03}, "attach_under_reset": {"max_speed": 0x01, "pins": 0x03}, "attach_answer": {"target_id": 0x10}}, event={}, enum={"connection_users": {"host_session": 0x01, "slot": 0x02}, "target_id_scheme": {"wch_dmi_7f": 0x01}, "attach_method": {"run": 0x00, "halt": 0x01}, "pin_role": {"swdio": 0x01, "reset": 0x03}}, own={})
 INTERFACES["oep.wire.swio"] = WIRE_SWIO
 WIRE_SWD = _NS(name="oep.wire.swd", revision=1, op={"scan": 0x01, "attach": 0x02, "detach": 0x03, "connections": 0x05}, lock_free={0x05},
     closed_tail={}, tlv={"describe": {"max_connections": 0x40}, "detach": {"force": 0x01}, "attach": {"max_speed": 0x01, "targetsel": 0x02, "pins": 0x03}}, event={}, enum={"connection_users": {"host_session": 0x01, "slot": 0x02}, "pin_role": {"swdio": 0x01, "swclk": 0x02}}, own={})

oep_client/riscv.py

@@ -14,8 +14,8 @@ import struct
 import time
 from dataclasses import dataclass, field
 
-from . import host as h, message as m, registry as reg
-from .core import Interface
+from . import catalog, host as h, message as m, registry as reg
+from .core import Interface, describe
 from .fixture import Gpio
 
 STATUS = reg.STATUS
@@ -109,7 +109,9 @@ class WireBase(Interface):
 class Wire(WireBase):
     """oep.wire.rvswd / oep.wire.swio (CH32 debug links to a RISC-V debug module)."""
     NAME = "oep.wire.rvswd"
-    DEFAULT_RESET = 0xFFFF
+    ROLE_RESET = reg.WIRE_RVSWD.enum["pin_role"]["reset"]
+    TAG_IDLE_CLOCK = reg.WIRE_RVSWD.tlv["attach"]["idle_clock"]
+    IDLE_CLOCK = reg.WIRE_RVSWD.enum["idle_clock"]
     RUN, HALT = reg.WIRE_RVSWD.enum["attach_method"]["run"], reg.WIRE_RVSWD.enum["attach_method"]["halt"]
     TAG_TARGET_ID = reg.WIRE_RVSWD.tlv["attach_answer"]["target_id"]
     SCHEME_WCH_DMI_7F = reg.WIRE_RVSWD.enum["target_id_scheme"]["wch_dmi_7f"]
@@ -125,12 +127,28 @@ class Wire(WireBase):
         v = tail.get(self.TAG_TARGET_ID)
         self.target_id = (v[0], bytes(v[1:])) if v else None
 
-    def attach(self, halt: bool = True, max_speed: int | None = None, pins: tuple[int, int] | None = None) -> tuple[int, int]:
+    def _idle_tlv(self, idle_clock: str | None) -> bytes:
+        # rvswd only, critical: a probe that cannot rest the line that way must refuse (oep-if-debug §3)
+        return b"" if idle_clock is None else m.tlv(self.TAG_IDLE_CLOCK, bytes([self.IDLE_CLOCK[idle_clock]]), critical=True)
+
+    def reset_channels(self) -> list[int]:
+        """The channels attach_under_reset may take (describe role_channels, role reset). There is no default reset
+        line: the host names one every time (oep-if-debug §3)."""
+        out = set()
+        for tag, v in describe(self.host, self.fn):
+            if tag & ~m.TAG_CRITICAL == catalog.ROLE_CHANNELS and v[0] == self.ROLE_RESET:
+                out.update(catalog.bitmap_to_channels(struct.unpack_from("<H", v, 1)[0], v[3:]))
+        return sorted(out)
+
+    def attach(self, halt: bool = True, max_speed: int | None = None, pins: tuple[int, int] | None = None,
+               idle_clock: str | None = None) -> tuple[int, int]:
         """-> (connection, DMSTATUS). Attaching an attached wire returns its connection as it is (self.existing).
         self.had_reset: a pending havereset was acknowledged first (a V00x's DMSTATUS halt / run bits stay frozen
         until then); self.speed_hz: the speed the probe chose; max_speed: a ceiling the probe must keep (critical);
-        self.target_id: (scheme, value) of the target's identity when the probe could read one (oep-if-debug §1)."""
-        body = bytes([self.HALT if halt else self.RUN]) + self._speed_tlv(max_speed) + self._pins_tlv(pins)
+        idle_clock: "high" / "low", how rvswd rests SWCLK (critical). Both are the target's, known by the host
+        (oep-if-debug §3). self.target_id: (scheme, value) of the target's identity when the probe could read one."""
+        body = (bytes([self.HALT if halt else self.RUN]) + self._speed_tlv(max_speed) + self._pins_tlv(pins)
+                + self._idle_tlv(idle_clock))
         rd = m.Reader(self._call(self.ATTACH, body).payload)
         conn, status, flags, self.speed_hz = rd.take("HIBI")
         self.had_reset, self.existing = bool(flags & 1), bool(flags & 2)
@@ -139,12 +157,13 @@ class Wire(WireBase):
         self._take_target_id(tail)
         return conn, status
 
-    def attach_under_reset(self, channel: int | None = None, hold_ms: int = 20,
-                           max_speed: int | None = None, pins: tuple[int, int] | None = None) -> tuple[int, int]:
-        """Hold the target in reset through `channel` (None: the probe's default reset line), attach, release and
-        halt it at once - the way back from firmware that turns the debug pins into GPIOs. -> (connection, dpc)"""
-        body = (struct.pack("<HH", self.DEFAULT_RESET if channel is None else channel, hold_ms) + self._speed_tlv(max_speed)
-                + self._pins_tlv(pins))
+    def attach_under_reset(self, channel: int, hold_ms: int = 20, max_speed: int | None = None,
+                           pins: tuple[int, int] | None = None, idle_clock: str | None = None) -> tuple[int, int]:
+        """Hold the target in reset through `channel` (always named: there is no default reset line; the probe
+        allows reset_channels()), attach, release and halt it at once - the way back from firmware that turns the
+        debug pins into GPIOs. -> (connection, dpc)"""
+        body = (struct.pack("<HH", channel, hold_ms) + self._speed_tlv(max_speed) + self._pins_tlv(pins)
+                + self._idle_tlv(idle_clock))
         rd = m.Reader(self._call(self.ATTACH_UNDER_RESET, body).payload)
         conn, dpc, self.speed_hz = rd.take("HII")
         self._take_target_id(rd.tail())

oep_client/usb_stream.py

@@ -10,6 +10,7 @@ transfer; if its timeout hits first, pyusb raises and the bytes already received
 
 from __future__ import annotations
 
+import atexit
 import threading
 import time
 
@@ -114,15 +115,21 @@ class UsbAsyncStream:
         self.timeout = 0.05
         self._buffer = bytearray()
         self._cond = threading.Condition()
-        self._closed = False
+        self._closed = False           # no more resubmits (close() started)
+        self._stop = False             # the event thread ends (every transfer is back)
         self._transfers = []
+        self._active = 0               # transfers submitted and not yet back for good
         for _ in range(self.DEPTH):
             t = handle.getTransfer()
             t.setBulk(endpoint_in, self.URB_SIZE, callback=self._done, timeout=0)
             t.submit()
             self._transfers.append(t)
+            self._active += 1
         self._events = threading.Thread(target=self._run, daemon=True)
         self._events.start()
+        # Closed at exit too: left to usb1's own finalizers, the context went while the event thread was inside
+        # handleEventsTimeout with transfers out - the process hung at exit or libusb aborted (usbi_mutex_destroy).
+        atexit.register(self.close)
 
     @classmethod
     def open(cls, vid: int, pid: int, serial: str | None = None) -> "UsbAsyncStream":
@@ -158,14 +165,23 @@ class UsbAsyncStream:
                     self._buffer += data
                     self._cond.notify_all()
         if not self._closed and status in (usb1.TRANSFER_COMPLETED, usb1.TRANSFER_TIMED_OUT):
-            transfer.submit()
+            try:
+                transfer.submit()
+                return
+            except usb1.USBError:
+                pass
+        with self._cond:
+            self._active -= 1          # back for good (cancelled, failed, or closing)
+            self._cond.notify_all()
 
     def _run(self) -> None:
-        while not self._closed:
+        while not self._stop:
             try:
                 self.context.handleEventsTimeout(0.1)
             except self._usb1.USBErrorInterrupted:
                 continue
+            except self._usb1.USBError:
+                break
 
     @property
     def in_waiting(self) -> int:
@@ -195,15 +211,27 @@ class UsbAsyncStream:
             self._buffer.clear()
 
     def close(self) -> None:
+        """Cancel the IN transfers and let the event thread take them back before the handle and the context go
+        (closing with transfers still out hung the process or aborted libusb). Safe to call twice (atexit)."""
+        if self._closed:
+            return
         self._closed = True
+        atexit.unregister(self.close)
         for t in self._transfers:
             try:
                 t.cancel()
             except self._usb1.USBError:
                 pass
-        self._events.join(timeout=0.5)
+        deadline = time.monotonic() + 1.0
+        with self._cond:
+            while self._active > 0 and self._events.is_alive() and time.monotonic() < deadline:
+                self._cond.wait(0.05)
+        self._stop = True
+        self._events.join(timeout=1.0)
         try:
             self.handle.releaseInterface(self.interface)
+        except self._usb1.USBError:
+            pass
         finally:
             self.handle.close()
             self.context.close()

{oep_client_python-0.0.4.dist-info → oep_client_python-0.0.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oep-client-python
-Version: 0.0.4
+Version: 0.0.6
 Summary: Open Embedded Probe (OEP) v1 host: serial / USB / TCP transports, the session rules, the standard interfaces, and a fake probe
 Project-URL: Homepage, https://github.com/Open-Embedded-Probe/oep-client-python
 Project-URL: Repository, https://github.com/Open-Embedded-Probe/oep-client-python
@@ -43,7 +43,7 @@ uv run pytest                     # in a checkout
 `oep-client` is another project, so the distribution is named `oep-client-python`.
 
 Releases: run the GitHub Actions workflow Release (workflow_dispatch, version X.Y.Z or X.Y.ZbN). `tools/prepare_release.py`
-sets the version in pyproject.toml and `oep_client.__version__` and turns CHANGELOG.md's Unreleased into that version; after
+sets the version in pyproject.toml, uv.lock and `oep_client.__version__` and turns CHANGELOG.md's Unreleased into that version; after
 the tests and the build it commits, tags, makes the GitHub Release and publishes to PyPI (Trusted Publishing). Record changes
 under Unreleased in CHANGELOG.md, (EN) and (JA).
 

{oep_client_python-0.0.4.dist-info → oep_client_python-0.0.6.dist-info}/RECORD

@@ -1,20 +1,20 @@
-oep_client/__init__.py,sha256=F5if_qpFrTQuYzjKnNr2nZ1QRiCVH8b_c43b3GQbvmQ,163
-oep_client/__main__.py,sha256=Ta7D7jhtg5IhFWuI3KTikbDNYazh9QKCH3FtMMnDMjg,14143
+oep_client/__init__.py,sha256=CDEcbic9y9YJgNsC6CNozMA0QBZA-GHlORfTNcv5LyY,163
+oep_client/__main__.py,sha256=qtVGdpAHULBtLY2SedabJf-uwDZZhMf_YmrbqRzM57U,14669
 oep_client/arm.py,sha256=JLyUhLSPcmsk73schZcaJYoOKuHzrvnU8kPmfrEvVuo,12331
 oep_client/capture.py,sha256=RZgDnWqr8Aqy49U7PqQpnKIQEL18djVuDJFydxrmv-c,17996
 oep_client/catalog.py,sha256=EqAQnSgHFxGbCO2GQ_Ee-uheJKbBBUUpL1-0qHfNMXU,6574
 oep_client/ch32_flash.py,sha256=Fc-6jEj15cQtMSKmfC5dmDetMXJ8hAdAuJ9d9odwrsA,12651
 oep_client/cobs.py,sha256=hqddQI_X7rsBvBvcP_MBE3bXPyB13-Azjqp_9JfdQ1g,2288
-oep_client/config.py,sha256=JhEmQKU-4KjSAoIovgeEwueKEiMLPUIiGVhZcR5ZlVc,9271
+oep_client/config.py,sha256=a8zlxPI0sG0Z8gwUyg9OuKbXHoB5FctCrRDHULHhxCo,9753
 oep_client/console.py,sha256=YYcuc9Qxe3kihla8wynYbDaLVr7wBLEvswrM-cMK3Tk,6859
-oep_client/core.py,sha256=z0-mplQVLOmPyXj1lHc-U7HYl3Gd6o-b5YJhpQTvqKU,8789
+oep_client/core.py,sha256=Cyyaknjipkg6tS76dZe5GMqjmOoQjlfeP0WFtMHkJNs,10403
 oep_client/decode.py,sha256=M-bRARrA2qGZLoJn0BdXeTb4WjL_2Hb2nk_g1IGXIw4,2382
 oep_client/dump.py,sha256=GAnmu2abuDmGmbWcbbEfC3EUuPp5Hady9vQVNcQ-724,6743
-oep_client/endpoint.py,sha256=70eFSDQuu-UffiuooF74e9kS33dhE4DyJeC7yllRR7Y,72248
+oep_client/endpoint.py,sha256=tRx9ZUIiFN0J9NS3OwZ89NorIV7XqmZbYeUMnvJb6bE,74082
 oep_client/esp32_targets.py,sha256=b8tNH-nb2KC-XgNfWg5l3TO0cyhZOF-gJajaVxNVSGQ,4988
-oep_client/fake.py,sha256=UzpB-A42Ma2QqJj0l-JmwCJkMn6DPVHHN77fcemT59U,13104
+oep_client/fake.py,sha256=TJpzwSCFDSco-3HCE2ZHzusMx0r0dtrD1bkGn6aos90,13136
 oep_client/fake_serial.py,sha256=uKl0UNcifhdeykQtm8gnRRhqV7TT4vPwBFuBhbf-9BI,4504
-oep_client/fake_serve.py,sha256=dIuYxhlAixSb8_OQ4b4UXTkWqW5Tpf_F9uuqMNWn0F4,14612
+oep_client/fake_serve.py,sha256=Ke_hGRiOayCyut-uYOa0PaOFzy-zlvPHGwjs4HEZkAQ,14644
 oep_client/fixture.py,sha256=653hCD-Iz0Lfs8dT4Hdg3QyubbbOGs1_xjq_3nb8foU,5564
 oep_client/frames.py,sha256=xjgjnXmXUqNJZ5m0h91r4Cy48WoVK1mEMW4gRg-mlMI,3991
 oep_client/hid_stream.py,sha256=99Dsm4Io1keukuETG_UNqjBGiVYZZeb__Pv4ytaKg9k,10695
@@ -23,14 +23,14 @@ oep_client/interfaces.py,sha256=P4ehrIj4j-9eg4NjaVdV15pawI2vOqucJwVklSdR-As,5472
 oep_client/link.py,sha256=J9VtBWfTgNoIgUQuj8SsH9hHesQM2uEN545IoxKVS8E,19406
 oep_client/message.py,sha256=MEM1UT6KFM7AsT56jvBLt_FJK_6SJ7O_nGAiipW0_zo,9912
 oep_client/names.py,sha256=ztCZFWs__aR-a5G14TnJP-Q4YfLhbyrzvOVOMJuG93k,3653
-oep_client/registry.py,sha256=nRM-sQiAMs1OzuSZIajdsBfdFckYo3OfwgmcLkHzxqw,9867
-oep_client/riscv.py,sha256=E0_C-4mBsrp9FUoZpMiqSH9e8sC8Q4EO5HRjFKE6_pc,21392
+oep_client/registry.py,sha256=3Ydg1851I0ck--BHkrcmlUBz_6gzZU6EXTwm2HX2U20,10000
+oep_client/riscv.py,sha256=PNeo_HXlq08b4h083olOOrGxqejD6ggQ7QzVqkIHEMA,22621
 oep_client/rp2350.py,sha256=7OMyj270k3AY1e3-ljicPwOjf9jOlokbT6QNkA0b0yY,4227
 oep_client/target.py,sha256=R8BvYfFfYNhZF0MysJkNb8b69YgBlmeGXNX8ReZIe5k,1068
 oep_client/uiapduino.py,sha256=IEPG3LbZPksi8g3wmAf6T0CRWSfYKW1_qrH_GBVQdxY,6090
-oep_client/usb_stream.py,sha256=1nvuRNLQkpp8054eG-JutBKh9y0F_8PHGDAfG0ZSbaY,8819
-oep_client_python-0.0.4.dist-info/METADATA,sha256=7HtJZthSGhDIG5Ce8dvLIvdwtQpN5AYve_5YhSk8l5M,7359
-oep_client_python-0.0.4.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-oep_client_python-0.0.4.dist-info/entry_points.txt,sha256=h6_8QX89Ww1ogALEGG5g4kspT3IOV6O51lwKqf5BWco,49
-oep_client_python-0.0.4.dist-info/licenses/LICENSE,sha256=ntlalztb3L1OaNAxmQdHlubu5fVhjMc9oRZi3PeQhXg,1076
-oep_client_python-0.0.4.dist-info/RECORD,,
+oep_client/usb_stream.py,sha256=VJMCxsOlQCk005FcS92pqTh33fRSFBizoL__L0VbUMA,10242
+oep_client_python-0.0.6.dist-info/METADATA,sha256=o7bx6WrdIbetzC9oULMTVkfp2mN4t9xKSukKpIbxzS4,7368
+oep_client_python-0.0.6.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+oep_client_python-0.0.6.dist-info/entry_points.txt,sha256=h6_8QX89Ww1ogALEGG5g4kspT3IOV6O51lwKqf5BWco,49
+oep_client_python-0.0.6.dist-info/licenses/LICENSE,sha256=ntlalztb3L1OaNAxmQdHlubu5fVhjMc9oRZi3PeQhXg,1076
+oep_client_python-0.0.6.dist-info/RECORD,,