oep-client-python 0.0.33__tar.gz → 0.0.34__tar.gz

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.0.34
+- (JA) oep-spec bc52327（debug §2 の閉じた後の保持、§2.2 holds、probe.config の wire-hold、core §8 の例外）に追従。仮想ベンチは、線切れ以外で
+  接続を閉じたらその口の休みの状態を保持し、ピンを取られる、wire-hold が off、idle / disable の項目、で保持を終える。駆動が止まると halt を失う
+  target（`VirtualTarget.needs_drive`、CH32L103）を表せる。クライアントは `WireBase.holds()`、`config.WireHold`、`oep config wire-hold PROBE CH on|off`。
+
 ## 0.0.33
 - (JA) oep-spec ba4e8ee（debug §3.1、core §12 規則 8、probe.config の rvswd-rest）に追従。rvswd の線の休ませ方は、attach の idle_clock が無ければ
   probe が決める（その SWCLK の channel の設定 rvswd-rest、無ければ target_id の系統: CH32L103 は low）。仮想ベンチはそのとおりに休ませ、attach の応答と

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/PKG-INFO

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

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/pyproject.toml

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

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/src/oep_client/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.0.33"
+__version__ = "0.0.34"

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/src/oep_client/__main__.py

@@ -359,6 +359,12 @@ def _config_parser(sub) -> None:
     rest.add_argument("channel", type=int, help="the port's SWCLK channel")
     rest.add_argument("mode", choices=sorted(config.REST_MODE))
     rest.add_argument("--save", action="store_true")
+    hold = cs.add_parser("wire-hold", help="whether a debug wire's lines stay held at their rest after a close "
+                                           "(on, the default) or go free at once (off; debug §2)")
+    hold.add_argument("probe")
+    hold.add_argument("channel", type=int, help="the port's SWDIO channel")
+    hold.add_argument("mode", choices=sorted(config.HOLD_MODE))
+    hold.add_argument("--save", action="store_true")
     dis = cs.add_parser("disable", help="channels the probe never drives or sets up (not on this board)")
     dis.add_argument("probe")
     dis.add_argument("channels", type=int, nargs="+")
@@ -441,6 +447,8 @@ def _config(args) -> int:
             _change(hst, cfg, [config.Label(channel=args.channel, text=args.text)], args.save)
         elif args.action == "idle":
             _change(hst, cfg, [config.Idle(channel=args.channel, mode=args.mode)], args.save)
+        elif args.action == "wire-hold":
+            _change(hst, cfg, [config.WireHold(channel=args.channel, mode=args.mode)], args.save)
         elif args.action == "rvswd-rest":
             _change(hst, cfg, [config.RvswdRest(channel=args.channel, mode=args.mode)], args.save)
         elif args.action == "disable":

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/src/oep_client/config.py

@@ -37,6 +37,7 @@ ITEM = {k.replace("-", "_"): i + 1 for i, k in enumerate(NAMES)}
 DESCRIBE = _CFG.tlv["describe"]
 IDLE = {k.replace("_", "-"): v for k, v in _CFG.enum["idle_mode"].items()}
 REST_MODE = dict(_CFG.enum["rvswd_rest_mode"])          # rvswd-rest: auto / high / low (debug §3.1)
+HOLD_MODE = dict(_CFG.enum["wire_hold_mode"])           # wire-hold: off / on (debug §2)
 STORAGE_STATE = {v: k for k, v in _CFG.enum["storage_state"].items()}
 UNREADABLE = {v: k for k, v in _CFG.enum["storage_unreadable"].items()}
 FORM = _CFG.enum["setting_form"]
@@ -162,6 +163,26 @@ class RvswdRest:
         return bytes([REST_MODE[self.mode]])
 
 
+@dataclass
+class WireHold:
+    """Whether a debug wire's lines on the port whose SWDIO is `channel` stay held at their rest after its connection
+    closes (debug §2): on - also with no item - or off (back to the free state at once)."""
+    channel: int
+    mode: str = "on"
+    NAME = "wire-hold"
+
+    def key(self) -> int:
+        return self.channel
+
+    def value(self) -> bytes:
+        return struct.pack("<H", self.key()) + self.data()
+
+    def data(self) -> bytes:
+        if self.mode not in HOLD_MODE:
+            raise ValueError(f"wire-hold mode {self.mode!r}: one of {', '.join(HOLD_MODE)}")
+        return bytes([HOLD_MODE[self.mode]])
+
+
 @dataclass(kw_only=True)
 class ConsolePassthrough:
     """Serial port `port` carries the target's debug console - read by the probe itself over `wire_fn` on (swdio, swclk)
@@ -315,6 +336,8 @@ def decode(name: str, key: int, d: bytes, setting: Setting | None = None, netifs
     try:
         if name == "label":
             return Label(channel=key, text=d.decode("utf-8", "replace"))
+        if name == "wire-hold" and len(d) == 1 and d[0] in HOLD_MODE.values():
+            return WireHold(channel=key, mode={v: k for k, v in HOLD_MODE.items()}[d[0]])
         if name == "rvswd-rest" and len(d) == 1 and d[0] in REST_MODE.values():
             return RvswdRest(channel=key, mode={v: k for k, v in REST_MODE.items()}[d[0]])
         if name == "idle" and len(d) == 1:

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/src/oep_client/endpoint.py

@@ -117,7 +117,8 @@ RESET_MODE = _RV.enum["reset_mode"]
 READ_FROM = reg.COMMON.enum["read_from"]                  # position, oldest, now, last_mark (common §1.2)
 STEP_LEFT = _RV.tlv["step_answer"]["step_left"]            # step's answer: the hart could not be halted again (§4.2)
 ITEM = {k.replace("-", "_"): k for k in cfgmod.NAMES}       # the standard items by name (probe.config §1, core §7.7)
-CHANNEL_ITEMS = (ITEM["label"], ITEM["idle"], ITEM["disable"], ITEM["rvswd_rest"])   # keyed by a channel (probe.config §1)
+CHANNEL_ITEMS = (ITEM["label"], ITEM["idle"], ITEM["disable"], ITEM["rvswd_rest"], ITEM["wire_hold"])   # keyed by a channel
+HOLD_MODE = cfgmod.HOLD_MODE
 REST_MODE = cfgmod.REST_MODE
 IDLE_MODE = _CFG.enum["idle_mode"]
 CFG_DESCRIBE = cfgmod.DESCRIBE
@@ -327,6 +328,7 @@ class VirtualTarget:
     havereset: bool = True
     resume_misses: int = 0                             # resumes that do not take (status state, dpc unchanged)
     present: bool = True                               # something answers on this pin pair (scan, attach)
+    needs_drive: bool = False                          # loses its halt once the probe stops driving the line (a CH32L103)
     target_id: int | None = None                       # the dmi_7f target_id attach reports (None: none)
     # run(pc, regs) -> (stopped, dpc, elapsed_us); default: halts 0x10 past the start
     run_hook: Callable | None = None
@@ -554,7 +556,7 @@ class Connection:
 
 
 ITEM_SIZES = {ITEM["idle"]: 1, ITEM["disable"]: 0, ITEM["passthrough"]: 9,     # the data of a fixed length (probe.config §1)
-              ITEM["console_passthrough"]: 13, ITEM["ipv4"]: 14, ITEM["rvswd_rest"]: 1}
+              ITEM["console_passthrough"]: 13, ITEM["ipv4"]: 14, ITEM["rvswd_rest"]: 1, ITEM["wire_hold"]: 1}
 PASSTHROUGHS = (ITEM["passthrough"], ITEM["console_passthrough"])
 
 
@@ -784,6 +786,7 @@ class Endpoint:
         self.session_ports: set[int] = set()   # the transports the lock holder's requests came on (probe.config §1.1)
         self.passthrough_out: dict[int, bytearray] = {}   # a serial port's pass-through bytes not sent yet
         self.resident: dict[int, bool] = {}       # console_passthrough's own connection per port: attached (config §1.2)
+        self.holds: dict[tuple[int, tuple[int, int]], int] = {}   # (wire fn, pair) -> rest: lines held after a close (debug §2)
         self.last: int | None = None         # S: the id that holds or last held the lock (the resend table's, §5.2)
         self.owner: bytes | None = None      # the holder's owner, while the lock is held (core §6.4)
         self.lease_ms = self.lease_default_ms
@@ -1561,7 +1564,7 @@ class Endpoint:
         connections closed (an unknown `cid`: none)."""
         gone = [c for c in (list(self.conns) if cid is None else [cid]) if c in self.conns]
         for c in gone:
-            self._close_conn(c)
+            self._close_conn(c, lost=True)
         return gone
 
     # ---- core -----------------------------------------------------------------------------------
@@ -2334,6 +2337,11 @@ class Endpoint:
                 raise wrong_kind()                                 # another wire's connection
             self._close_conn(cid)
             return m.COMPLETED, m.SUCCESS, b""
+        if op == O["holds"]:                                       # lock-free, paged by first (debug §2.2)
+            first = t.take("B")
+            t.tail()
+            rows = [struct.pack("<HHB", *pair, rest) for pair, rest in self.held_ports(fn)]
+            return m.COMPLETED, m.SUCCESS, self._paged(rows, first)
         if op == O["connections"]:                                 # lock-free, paged by first (debug §2.1)
             first = t.take("B")
             t.tail()
@@ -2409,14 +2417,45 @@ class Endpoint:
         self.conns[cid] = Connection(fn, pair, self._order, speed, tid)
         return cid
 
-    def _close_conn(self, cid: int) -> None:
-        """The connection goes, its console streams first (common §2); its pins go back to their idle state."""
+    def _close_conn(self, cid: int, lost: bool = False) -> None:
+        """The connection goes, its console streams first (common §2). Its lines stay held at its rest unless the line
+        was lost, the port's wire-hold is off or a pin has an idle / disable item (debug §2); else to their idle state,
+        and a target that needs the drive loses its halt."""
         for sid in [k for k, st in self.streams.items() if st.conn == cid]:
             self._close_stream(sid)
         gone = self.conns.pop(cid, None)
         self.resources.pop(cid, None)
-        if gone is not None:
-            self._park(gone.pair)
+        if gone is None:
+            return
+        if not lost and self._may_hold(gone.pair):
+            self.holds[(gone.fn, gone.pair)] = gone.idle_clock if self.names[gone.fn] == "oep.wire.rvswd" else 0
+            return
+        self._park(gone.pair)
+        tg = self.targets.get((gone.fn, gone.pair))
+        if tg is not None and tg.needs_drive:
+            tg.halted = False                                      # its debug module dropped the link: the hart runs
+
+    def _may_hold(self, pair: tuple[int, int]) -> bool:
+        """debug §2: wire-hold on (no item: on) for the port's SWDIO, and no idle / disable item on its pins."""
+        mode = self.config.get((ITEM["wire_hold"], pair[0]), bytes([HOLD_MODE["on"]]))[0]
+        pins = [p for p in pair if p != 0xFFFF]
+        return (mode == HOLD_MODE["on"] and not any((ITEM["idle"], p) in self.config for p in pins)
+                and not any(p in self.disabled for p in pins))
+
+    def held_ports(self, fn: int) -> list[tuple[tuple[int, int], int]]:
+        """The ports wire `fn` holds now (debug §2.2): a hold ends once its pins are taken (a plan, a connection), its
+        wire-hold goes off or an idle / disable item lands on them; an ended hold's pins go to their free state."""
+        busy = {a[2] for a in self.plan if not self._listens(a[0])} | {p for c in self.conns.values() for p in c.pair}
+        for key in list(self.holds):
+            hfn, pair = key
+            if any(p in busy for p in pair if p != 0xFFFF) or not self._may_hold(pair):
+                del self.holds[key]
+                if not any(p in busy for p in pair if p != 0xFFFF):
+                    self._park(pair)
+                    tg = self.targets.get(key)
+                    if tg is not None and tg.needs_drive:
+                        tg.halted = False
+        return [(pair, rest) for (hfn, pair), rest in self.holds.items() if hfn == fn]
 
     def _cleanup_failed(self, cid: int, done: int, payload: bytes) -> tuple[int, int, bytes]:
         """A block op whose restore of DATA0 / DATA1 failed: partial when done > 0 (all words included), else failed,
@@ -3301,6 +3340,8 @@ class Endpoint:
                     return True
             if name == ITEM["rvswd_rest"] and d[0] not in REST_MODE.values():
                 return True                                        # a mode the definition leaves unused (§1)
+            if name == ITEM["wire_hold"] and d[0] not in HOLD_MODE.values():
+                return True
         return False
 
     def _shown(self, name: str, d: bytes) -> bytes:

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/src/oep_client/registry.py

@@ -3,7 +3,7 @@
 
 from types import SimpleNamespace as _NS
 
-REGISTRY_HASH = "66b19f04290391f3"
+REGISTRY_HASH = "32b9f952338089a5"
 SCHEMA = 1
 PROTOCOL_REVISION = 1
 CONFIRM_REQUEST_MAGIC = 'OEP?'
@@ -41,15 +41,15 @@ PROBE_LINK = _NS(name="oep.probe.link", revision=1, target=None, op={"source": 0
     tlv={}, event={}, enum={"port_speed_step": {"try": 0x00, "commit": 0x01, "revert": 0x02}, "port_state": {"boot": 0x00, "trying": 0x01, "committed": 0x02, "recovery_pending": 0x03}}, own={},
     line_names={}, names={})
 INTERFACES["oep.probe.link"] = PROBE_LINK
-WIRE_RVSWD = _NS(name="oep.wire.rvswd", revision=1, target="RISC-V targets whose debug module is reached over the two-wire RVSWD line", op={"scan": 0x10, "attach": 0x11, "detach": 0x12, "connections": 0x13}, lock_free={0x13},
+WIRE_RVSWD = _NS(name="oep.wire.rvswd", revision=1, target="RISC-V targets whose debug module is reached over the two-wire RVSWD line", op={"scan": 0x10, "attach": 0x11, "detach": 0x12, "connections": 0x13, "holds": 0x14}, lock_free={0x13, 0x14},
     tlv={"describe": {"max_connections": 0x40}, "scan": {"max_speed": 0x01, "idle_clock": 0x03}, "attach": {"idle_clock": 0x03, "reset": 0x04}, "attach_answer": {"target_id": 0x01, "dpc": 0x02, "idle_clock": 0x03}, "connections_answer": {"idle_clock": 0x02}, "unavailable_payload": {"index": 0x40}, "unsupported_payload": {"index": 0x40}}, event={}, enum={"scan_kind": {"riscv_dm": 0x01}, "attach_flags": {"havereset_acked": 0x01, "halted": 0x08}, "features": {"attach_halt": 0x01}, "attach_method": {"run": 0x00, "halt": 0x01}, "pin_role": {"swdio": 0x01, "swclk": 0x02, "reset": 0x03}, "idle_clock": {"high": 0x00, "low": 0x01}, "target_id_family": {"shift": 0x14}, "idle_low_family": {"ch32l103": 0x103}}, own={},
     line_names={}, names={})
 INTERFACES["oep.wire.rvswd"] = WIRE_RVSWD
-WIRE_SWIO = _NS(name="oep.wire.swio", revision=1, target="RISC-V targets whose debug module is reached over the one-wire SWIO line", op={"scan": 0x10, "attach": 0x11, "detach": 0x12, "connections": 0x13}, lock_free={0x13},
+WIRE_SWIO = _NS(name="oep.wire.swio", revision=1, target="RISC-V targets whose debug module is reached over the one-wire SWIO line", op={"scan": 0x10, "attach": 0x11, "detach": 0x12, "connections": 0x13, "holds": 0x14}, lock_free={0x13, 0x14},
     tlv={"describe": {"max_connections": 0x40}, "scan": {"max_speed": 0x01}, "attach": {"reset": 0x04}, "attach_answer": {"target_id": 0x01, "dpc": 0x02}, "unavailable_payload": {"index": 0x40}, "unsupported_payload": {"index": 0x40}}, event={}, enum={"scan_kind": {"riscv_dm": 0x01}, "attach_flags": {"havereset_acked": 0x01, "halted": 0x08}, "features": {"attach_halt": 0x01}, "attach_method": {"run": 0x00, "halt": 0x01}, "pin_role": {"swdio": 0x01, "reset": 0x03}}, own={},
     line_names={}, names={})
 INTERFACES["oep.wire.swio"] = WIRE_SWIO
-WIRE_SWD = _NS(name="oep.wire.swd", revision=1, target="ARM targets with an SWD debug port", op={"scan": 0x10, "attach": 0x11, "detach": 0x12, "connections": 0x13}, lock_free={0x13},
+WIRE_SWD = _NS(name="oep.wire.swd", revision=1, target="ARM targets with an SWD debug port", op={"scan": 0x10, "attach": 0x11, "detach": 0x12, "connections": 0x13, "holds": 0x14}, lock_free={0x13, 0x14},
     tlv={"describe": {"max_connections": 0x40}, "scan": {"max_speed": 0x01, "targetsel": 0x02}, "attach": {"targetsel": 0x02, "reset": 0x04}, "attach_answer": {"target_id": 0x01}, "connections_answer": {"selected_target": 0x01}, "unavailable_payload": {"index": 0x40}, "unsupported_payload": {"index": 0x40}}, event={}, enum={"scan_kind": {"arm_adi": 0x02}, "attach_flags": {"dormant_woken": 0x04}, "features": {}, "attach_method": {"run": 0x00}, "pin_role": {"swdio": 0x01, "swclk": 0x02, "reset": 0x03}}, own={},
     line_names={}, names={})
 INTERFACES["oep.wire.swd"] = WIRE_SWD
@@ -94,6 +94,6 @@ FIXTURE_CAPTURE_GROUP = _NS(name="oep.fixture.capture-group", revision=1, target
     line_names={}, names={})
 INTERFACES["oep.fixture.capture-group"] = FIXTURE_CAPTURE_GROUP
 PROBE_CONFIG = _NS(name="oep.probe.config", revision=1, target=None, op={"get": 0x10, "set": 0x11, "save": 0x12, "erase": 0x13, "unset": 0x14, "state": 0x15, "network": 0x16}, lock_free={0x10, 0x15, 0x16},
-    tlv={"describe": {"storage": 0x40, "setting": 0x41, "netif": 0x42}}, event={}, enum={"idle_mode": {"hi_z": 0x00, "pull_up": 0x01, "pull_down": 0x02, "output_low": 0x03, "output_high": 0x04}, "rvswd_rest_mode": {"auto": 0x00, "high": 0x01, "low": 0x02}, "ipv4_mode": {"dhcp": 0x00, "static": 0x01}, "network_state": {"off": 0x00, "connecting": 0x01, "up": 0x02, "waiting": 0x03}, "network_reason": {"none": 0x00, "not_found": 0x01, "auth": 0x02, "no_address": 0x03, "other": 0x04}, "setting_form": {"named": 0x00, "bytes": 0x01, "text": 0x02, "u32": 0x03, "ipv4": 0x04, "bool": 0x05}, "setting_flag": {"secret": 0x01, "restart": 0x02}, "storage_state": {"none": 0x00, "applied": 0x01, "unreadable": 0x02, "partial": 0x03}, "storage_unreadable": {"none": 0x00, "form": 0x01, "item": 0x02, "capacity": 0x03}}, own={},
-    line_names={'swdio': 'the debug data line (2 wires: rvswd, swd) (Host only)', 'swclk': 'the debug clock line (2 wires: rvswd, swd) (Host only)', 'swio': 'the one debug wire (swio) (Host only)', 'rx': 'the fixture UART receive, wired to the target TX (Host only)', 'tx': 'the fixture UART transmit, wired to the target RX (Host only)', 'nrst': 'the target reset line (Host only)', 'power_hi': 'target power on when high (Host only)', 'power_lo': 'target power on when low (Host only)'}, names={'setting': {'label': 'key channel; text 1-32 bytes', 'idle': 'key channel; mode(u8)', 'disable': 'key channel; no data', 'passthrough': 'key port; fn(u16) rx(u16) baud(u32) format(u8)', 'console-passthrough': 'key port; wire_fn(u16) swdio(u16) swclk(u16) max_speed(u32) console_fn(u16) mechanism(u8)', 'wifi': 'key entry; ssid_len(u8) ssid pass_len(u8) passphrase; passphrase write-only', 'ipv4': 'key netif; mode(u8) address(4) prefix(u8) gateway(4) dns(4)', 'rvswd-rest': "key channel (the port's SWCLK); mode(u8): rvswd_rest_mode"}, 'netif': {'wifi': 'Wi-Fi station', 'ethernet': 'wired Ethernet'}})
+    tlv={"describe": {"storage": 0x40, "setting": 0x41, "netif": 0x42}}, event={}, enum={"idle_mode": {"hi_z": 0x00, "pull_up": 0x01, "pull_down": 0x02, "output_low": 0x03, "output_high": 0x04}, "rvswd_rest_mode": {"auto": 0x00, "high": 0x01, "low": 0x02}, "wire_hold_mode": {"off": 0x00, "on": 0x01}, "ipv4_mode": {"dhcp": 0x00, "static": 0x01}, "network_state": {"off": 0x00, "connecting": 0x01, "up": 0x02, "waiting": 0x03}, "network_reason": {"none": 0x00, "not_found": 0x01, "auth": 0x02, "no_address": 0x03, "other": 0x04}, "setting_form": {"named": 0x00, "bytes": 0x01, "text": 0x02, "u32": 0x03, "ipv4": 0x04, "bool": 0x05}, "setting_flag": {"secret": 0x01, "restart": 0x02}, "storage_state": {"none": 0x00, "applied": 0x01, "unreadable": 0x02, "partial": 0x03}, "storage_unreadable": {"none": 0x00, "form": 0x01, "item": 0x02, "capacity": 0x03}}, own={},
+    line_names={'swdio': 'the debug data line (2 wires: rvswd, swd) (Host only)', 'swclk': 'the debug clock line (2 wires: rvswd, swd) (Host only)', 'swio': 'the one debug wire (swio) (Host only)', 'rx': 'the fixture UART receive, wired to the target TX (Host only)', 'tx': 'the fixture UART transmit, wired to the target RX (Host only)', 'nrst': 'the target reset line (Host only)', 'power_hi': 'target power on when high (Host only)', 'power_lo': 'target power on when low (Host only)'}, names={'setting': {'label': 'key channel; text 1-32 bytes', 'idle': 'key channel; mode(u8)', 'disable': 'key channel; no data', 'passthrough': 'key port; fn(u16) rx(u16) baud(u32) format(u8)', 'console-passthrough': 'key port; wire_fn(u16) swdio(u16) swclk(u16) max_speed(u32) console_fn(u16) mechanism(u8)', 'wifi': 'key entry; ssid_len(u8) ssid pass_len(u8) passphrase; passphrase write-only', 'ipv4': 'key netif; mode(u8) address(4) prefix(u8) gateway(4) dns(4)', 'rvswd-rest': "key channel (the port's SWCLK); mode(u8): rvswd_rest_mode", 'wire-hold': "key channel (the port's SWDIO); mode(u8): wire_hold_mode"}, 'netif': {'wifi': 'Wi-Fi station', 'ethernet': 'wired Ethernet'}})
 INTERFACES["oep.probe.config"] = PROBE_CONFIG

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/src/oep_client/riscv.py

@@ -188,7 +188,7 @@ class WireBase(Interface):
     """oep.wire.<link>: scan / attach / detach / connections (oep-if-debug §0-§2). The shared part; each link's attach
     takes its own arguments. A failed scan, attach or detach is completed failed with `status(u8) [TLV]` (common §3).
     attach names its pins in the fixed part (§1): `pins` None takes the wire's one candidate pair (candidate_pairs)."""
-    SCAN, ATTACH, DETACH, CONNECTIONS = (_WIRE.op[k] for k in ("scan", "attach", "detach", "connections"))
+    SCAN, ATTACH, DETACH, CONNECTIONS, HOLDS = (_WIRE.op[k] for k in ("scan", "attach", "detach", "connections", "holds"))
     REVISION = 1
     TAG_RESET = _WIRE.tlv["attach"]["reset"]           # channel(u16) hold_ms(u16), critical: attach under reset (§3)
     TAG_SCAN_MAX_SPEED = _WIRE.tlv["scan"]["max_speed"]
@@ -299,6 +299,19 @@ class WireBase(Interface):
         """Close the connection and its streams (oep-if-debug §2)."""
         self._call(self.DETACH, struct.pack("<I", conn))
 
+    def holds(self) -> list[tuple[tuple[int, int], int]]:
+        """The ports this wire holds at their rest after a close (oep-if-debug §2.2, lock-free; paged like connections):
+        [((swdio, swclk), rest)] - rest: rvswd's idle_clock value (0 high, 1 low), 0 on other wires. Not connections."""
+        out: list[tuple[tuple[int, int], int]] = []
+        while True:
+            rd = m.Reader(self._call(self.HOLDS, bytes([len(out)]), locked=False).payload)
+            more, count = rd.take("BB")
+            page = [((d, c), r) for d, c, r in (rd.take("HHB") for _ in range(count))]
+            rd.tail()
+            out += page
+            if not more or not count or len(out) > 0xFF:
+                return out
+
     def connections(self) -> list["ConnectionInfo"]:
         """The wire's live connections, in the order they were made (oep-if-debug §2.1, lock-free; paged: the request
         is first(u8), the answer more count entries [TLV], followed until more is 0). swd's selected_target TLVs

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/src/oep_client/virtual_attach_model.py

@@ -36,7 +36,7 @@ class Attachments(Dependencies):
         return bytes(page)
     def describe(self,fn):
         if fn==4:return (tlv(DC['ops'],pack_ops(set(COP.values()))),*(tlv(CD['mechanism'],name.encode()) for name in self.mechanisms))
-        rows=[tlv(DC['ops'],pack_ops({WOP['attach'],WOP['detach'],WOP['connections']})),tlv(WT['describe']['max_connections'],b'\x02'),tlv(DC['min_clock_hz'],struct.pack('<I',1000))]
+        rows=[tlv(DC['ops'],pack_ops({WOP['attach'],WOP['detach'],WOP['connections'],WOP['holds']})),tlv(WT['describe']['max_connections'],b'\x02'),tlv(DC['min_clock_hz'],struct.pack('<I',1000))]
         for index,pair in enumerate(self.pairs[fn]):
             members=[(WE['pin_role']['swdio'],pair[0])] if fn==2 else [(WE['pin_role']['swdio'],pair[0]),(WE['pin_role']['swclk'],pair[1])]
             rows.append(tlv(DC['channel_group'],bytes((index,len(members)))+b''.join(struct.pack('<BH',*row) for row in members)))
@@ -79,6 +79,7 @@ class Attachments(Dependencies):
     def dispatch_request(self,fn,op,payload,tags):
         if fn<=3:
             if op==WOP['connections']:return self.connection_page(fn,payload[0])
+            if op==WOP['holds']:return b'\0\0'+extension()   # no port held in this model (debug §2.2)
             if op==WOP['detach']:
                 rid=struct.unpack('<I',payload)[0];self.resource(rid,'connection')
                 if self.connections[rid]['fn']!=fn:raise Reject(R['unavailable'],cause('wrong_state'))
@@ -131,7 +132,7 @@ class AttachModel(DependencyModel):
         if len(request)>=6 and struct.unpack_from('<H',request,3)[0]==4:
             e.fixed={COP['open']:5,COP['read']:15,COP['marks']:8,COP['clear']:4,COP['mark']:5,COP['write']:6,COP['close']:4,COP['streams']:2};e.free={COP['read'],COP['marks'],COP['streams']}
             if request[5]==COP['write'] and len(request)>=16:e.fixed[COP['write']]=6+struct.unpack_from('<H',request,14)[0]
-        else:e.fixed={WOP['attach']:9,WOP['detach']:4,WOP['connections']:1};e.free={WOP['connections']}
+        else:e.fixed={WOP['attach']:9,WOP['detach']:4,WOP['connections']:1,WOP['holds']:1};e.free={WOP['connections'],WOP['holds']}
         try:return self.ep.handle(request)
         finally:e.fixed,e.free=fixed,free
     def restart_fixture(self):

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/src/oep_client/virtual_bench.py

@@ -262,7 +262,7 @@ def _setting(name: str, keys: int, form: int = 0, max_len: int = 0, flags: int =
 
 
 def _config(fn: int, instance: int, storage: int = 4096, *, channels: int = 64, ports: int = 4, netifs=(), wifi_entries: int = 4,
-            own=(), rvswd: bool = False) -> Offered:
+            own=(), rvswd: bool = False, hold: bool = True) -> Offered:
     """oep.probe.config's declarations (probe.config §4): the standard items label / idle / disable (keys: the
     channels), passthrough / console-passthrough (keys: the transports), with `netifs` (names) wifi / ipv4 and the
     network op; `own`: the probe's own items as (name, form, keys, max_len, flags) (§1.6). storage 0 = none - no storage
@@ -276,6 +276,8 @@ def _config(fn: int, instance: int, storage: int = 4096, *, channels: int = 64,
         settings.append(_setting("ipv4", len(netifs) + 1))
     if rvswd:                                              # its automatic rest can be turned off per port (debug §3.1)
         settings.append(_setting("rvswd-rest", channels))
+    if hold:                                               # a debug wire's hold after a close, per port (debug §2)
+        settings.append(_setting("wire-hold", channels))
     settings += [_setting(name, keys, form, max_len, flags) for name, form, keys, max_len, flags in own]
     return Offered(fn, instance, "oep.probe.config", ops_of("oep.probe.config", *drop)
         + ((catalog.u32(_CFG["storage"], storage),) if storage else ()) + tuple(settings)

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/src/oep_client/virtual_oep_declaration_model.py

@@ -24,7 +24,7 @@ class OepDeclarations(Resources):
 
     def describe(self, fn):
         if fn==4:return (tlv(DC['ops'],pack_ops(set(COP.values()))),tlv(CD['mechanism'],b'dmdata'))
-        rows=[tlv(DC['ops'],pack_ops({WOP['attach'],WOP['detach'],WOP['connections']}))]
+        rows=[tlv(DC['ops'],pack_ops({WOP['attach'],WOP['detach'],WOP['connections'],WOP['holds']}))]
         if fn==1:rows.append(tlv(WT['describe']['max_connections'],b'\x02'))
         if fn==2:rows.append(tlv(DC['min_clock_hz'],struct.pack('<I',1000000)))
         role=WE['pin_role']
@@ -35,7 +35,7 @@ class OepDeclarations(Resources):
         return tuple(rows)
 
     def dispatch(self, fn, op, payload):
-        if (fn!=4 and op==WOP['connections']) or (fn==4 and op==COP['streams']):return b'\0\0'+extension()
+        if (fn!=4 and op in (WOP['connections'],WOP['holds'])) or (fn==4 and op==COP['streams']):return b'\0\0'+extension()
         raise Reject(R['no_resource'])  # declarations only: no simulated attach or target work
 
 
@@ -50,6 +50,6 @@ class OepDeclarationModel(ResourceModel):
         if len(request)>=6:
             fn=struct.unpack_from('<H',request,3)[0]
             if fn==4:e.fixed={COP['open']:5,COP['read']:15,COP['marks']:8,COP['clear']:4,COP['mark']:5,COP['write']:6,COP['close']:4,COP['streams']:2};e.free={COP['read'],COP['marks'],COP['streams']}
-            else:e.fixed={WOP['attach']:9,WOP['detach']:4,WOP['connections']:1};e.free={WOP['connections']}
+            else:e.fixed={WOP['attach']:9,WOP['detach']:4,WOP['connections']:1,WOP['holds']:1};e.free={WOP['connections'],WOP['holds']}
         try:return super().handle(request)
         finally:e.fixed,e.free=fixed,free

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/src/oep_client/virtual_registered_ops_model.py

@@ -8,7 +8,7 @@ from . import registry as _reg
 # Each interface's mandatory ops, by name (looked up in the registry: never literal numbers).
 _MANDATORY={
     'oep.probe.plan':('plan_apply','plan_release'),'oep.probe.restart':('restart',),'oep.probe.link':('source','sink'),
-    **{w:('attach','detach','connections') for w in ('oep.wire.rvswd','oep.wire.swio','oep.wire.swd')},
+    **{w:('attach','detach','connections','holds') for w in ('oep.wire.rvswd','oep.wire.swio','oep.wire.swd')},
     'oep.target.riscv-dm':('dmi',),'oep.target.arm-adi':('transfer',),
     'oep.target.console':('open','read','close','streams'),
     'oep.fixture.gpio':('set','read'),'oep.fixture.uart':('configure','read','status'),

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/src/oep_client/virtual_scan_options_model.py

@@ -14,7 +14,7 @@ KIND = _reg.WIRE_RVSWD.enum["scan_kind"] | _reg.WIRE_SWD.enum["scan_kind"]
 
 class ScanOptions(WireOptions):
     def __init__(self,ep):super().__init__(ep);self.scan_limit=2;self.identities={};self.scan_live=set();self.scan_events=[]
-    def describe(self,fn):return tuple(tlv(DC['ops'],pack_ops({WOP['scan'],WOP['attach'],WOP['detach'],WOP['connections']})) if fn<=3 and row[0]==DC['ops'] else row for row in super().describe(fn))
+    def describe(self,fn):return tuple(tlv(DC['ops'],pack_ops({WOP['scan'],WOP['attach'],WOP['detach'],WOP['connections'],WOP['holds']})) if fn<=3 and row[0]==DC['ops'] else row for row in super().describe(fn))
     def request_tags(self,fn,op,data):
         if fn>3 or op!=WOP['scan']:return super().request_tags(fn,op,data)
         known={SC['max_speed']:4}

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/tests/spec/oep-v1.toml

@@ -266,6 +266,7 @@ op = [
   { code = 0x11, name = "attach", lock = true },
   { code = 0x12, name = "detach", lock = true },
   { code = 0x13, name = "connections", lock = false },  # first(u8) -> more, count x entry
+  { code = 0x14, name = "holds", lock = false },  # first(u8) -> more, count x (swdio, swclk, rest): ports held after close (debug §2.2)
 ]
 
 [interface.tlv.describe]
@@ -322,6 +323,7 @@ op = [
   { code = 0x11, name = "attach", lock = true },
   { code = 0x12, name = "detach", lock = true },
   { code = 0x13, name = "connections", lock = false },
+  { code = 0x14, name = "holds", lock = false },
 ]
 
 [interface.tlv.describe]
@@ -365,6 +367,7 @@ op = [
   { code = 0x11, name = "attach", lock = true },
   { code = 0x12, name = "detach", lock = true },
   { code = 0x13, name = "connections", lock = false },
+  { code = 0x14, name = "holds", lock = false },
 ]
 
 [interface.tlv.describe]
@@ -805,6 +808,7 @@ console-passthrough = "key port; wire_fn(u16) swdio(u16) swclk(u16) max_speed(u3
 wifi = "key entry; ssid_len(u8) ssid pass_len(u8) passphrase; passphrase write-only"
 ipv4 = "key netif; mode(u8) address(4) prefix(u8) gateway(4) dns(4)"
 rvswd-rest = "key channel (the port's SWCLK); mode(u8): rvswd_rest_mode"
+wire-hold = "key channel (the port's SWDIO); mode(u8): wire_hold_mode"
 [interface.line_names]          # Host conventions only (host-development-guide §5.3)
 swdio = "the debug data line (2 wires: rvswd, swd) (Host only)"
 swclk = "the debug clock line (2 wires: rvswd, swd) (Host only)"
@@ -827,6 +831,9 @@ ethernet = "wired Ethernet"
 auto = 0                        # the probe's automatic choice from target_id (also when no item)
 high = 1
 low = 2
+[interface.enum.wire_hold_mode] # wire-hold: the debug wire's lines held at their rest after a close (oep-if-debug §2)
+off = 0
+on = 1                          # also when no item
 [interface.enum.ipv4_mode]
 dhcp = 0
 static = 1

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/tests/test_config.py

@@ -118,7 +118,7 @@ def test_describe_and_a_probe_without_storage():
     ep, hst = open_bench()
     d = config.ProbeConfig(hst).describe()
     assert d.storage_bytes == 4096 and d.items == ["label", "idle", "disable", "passthrough", "console-passthrough",
-                                                 "rvswd-rest"]
+                                                 "rvswd-rest", "wire-hold"]
     probe = virtual_bench.VirtualProbe("no-storage", 1024, [virtual_bench._config(o.fn, 0, storage=0)
                                        if o.name == "oep.probe.config" else o for o in virtual_bench.p4_bench().offered])
     ep = endpoint.Endpoint(probe, Clock())

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/tests/test_conformance_oep_declarations.py

@@ -91,7 +91,8 @@ def test_scan_is_optional_and_the_mechanisms_are_counted():
 
 
 def test_future_registry_mandatory_op_is_not_silently_ignored():
-    _,c=setup();c.reg['interface'][0]['op'].append({'name':'future_required','code':20})
+    _,c=setup();ops=c.reg['interface'][0]['op']
+    ops.append({'name':'future_required','code':max(o['code'] for o in ops)+1})   # a code no probe offers yet
     assert OepDeclarationChecks(c,SELECTION).run()['status']=='failed'
 
 

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/tests/test_request_tails.py

@@ -131,6 +131,7 @@ def drive_wire_dm_console(hst, wire_name):
     wire.scan()
     conn, _ = wire.attach(halt=True)
     wire.connections()
+    wire.holds()                                          # debug §2.2, lock-free
     dm = riscv.RiscvDm(hst, conn)
     dm.dmi([dm.step_read(0x11)])
     dm.halt()

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/tests/test_trace_debug.py

@@ -619,7 +619,7 @@ def test_every_op_but_connections_needs_the_lock_and_two_connections_share_one_l
     c0 = struct.unpack_from("<I", attach(hv, p0).payload)[0]
     c1 = struct.unpack_from("<I", attach(hv, p1).payload)[0]
     for op in W.values():
-        if op != W["connections"]:
+        if op not in (W["connections"], W["holds"]):            # both lock-free (debug §2.1, §2.2)
             r = hv.raw(1, op, fixed(ep.pairs[1][2]), session=False)
             assert (r.resolution, r.detail) == (m.REJECTED, m.SESSION_REQUIRED), op
     for op in RV.values():

oep_client_python-0.0.34/tests/test_wire_hold.py

@@ -0,0 +1,59 @@
+"""debug §2: a connection closed other than by line loss leaves its lines held at its rest (a CH32L103 keeps its
+halt across processes); probe.config wire-hold turns it off per port; holds (§2.2) lists the held ports; the hold is a
+kind of free state - taken like a free pin, never refused for it."""
+import time
+
+import pytest
+
+from oep_client import config, core, endpoint, host as h, riscv, virtual_bench
+
+
+def bench():
+    start = time.monotonic()
+    ep = endpoint.Endpoint(virtual_bench.p4_x035(), lambda: int((time.monotonic() - start) * 1000))
+    hst = h.Host(ep.handle)
+    core.take(hst, 10000)
+    fn = core.find(hst, "oep.wire.rvswd")
+    (pair,) = [p for (f, p) in ep.targets if f == fn]
+    ep.targets[(fn, pair)].needs_drive = True                 # a CH32L103: the halt goes once the line is not driven
+    return ep, hst, riscv.Wire(hst, "oep.wire.rvswd"), pair
+
+
+def halt_then_end(ep, hst, wire, pair):
+    conn, _ = wire.attach(halt=True, pins=pair)
+    hst.end()                                                  # the process ends: its connection closes (core §9)
+    core.take(hst, 10000)
+
+
+def test_the_halt_survives_another_session_by_default():
+    ep, hst, wire, pair = bench()
+    halt_then_end(ep, hst, wire, pair)
+    assert [p for p, _ in wire.holds()] == [pair]
+    assert wire.connections() == []                            # a hold is no connection
+    wire.attach(halt=False, pins=pair)                         # taken like a free pin (never cause 1 / 5)
+    assert wire.halted is False and ep.targets[(core.find(hst, "oep.wire.rvswd"), pair)].halted
+    assert wire.holds() == []                                  # the taker carries on
+
+
+def test_wire_hold_off_lets_the_lines_go_and_the_target_loses_its_halt():
+    ep, hst, wire, pair = bench()
+    config.ProbeConfig(hst).set([config.WireHold(channel=pair[0], mode="off")])
+    assert config.WireHold(channel=pair[0], mode="off") in config.ProbeConfig(hst).items()
+    halt_then_end(ep, hst, wire, pair)
+    assert wire.holds() == []
+    assert not ep.targets[(core.find(hst, "oep.wire.rvswd"), pair)].halted
+
+
+def test_a_lost_line_is_not_held():
+    ep, hst, wire, pair = bench()
+    wire.attach(halt=True, pins=pair)
+    ep.lose()
+    assert wire.holds() == []
+
+
+def test_an_idle_item_on_a_held_pin_ends_the_hold():
+    ep, hst, wire, pair = bench()
+    halt_then_end(ep, hst, wire, pair)
+    assert wire.holds()
+    config.ProbeConfig(hst).set([config.Idle(channel=pair[1], mode="pull-down")])
+    assert wire.holds() == []

oep_client_python-0.0.34/tests/vectors/SPEC_COMMIT

@@ -0,0 +1 @@
+bc523272c4b90bc3593cf524dd8ab65f628466aa

{oep_client_python-0.0.33 → oep_client_python-0.0.34}/tests/vectors/SPEC_SHA256

@@ -1,5 +1,5 @@
-79e50bedcaaecae9ec692418a1f44d5c7d32f2c005917f2c46d9b073bf866630  src/oep_client/registry.py
-66b19f04290391f363330fa672edb63e59045b217f0af0ea9c8f5ed7f08ffeaf  tests/spec/oep-v1.toml
+f329daad8ca30b9e08b83e393e05c0cf1224a44b3d972f90017dae656224d6a2  src/oep_client/registry.py
+32b9f952338089a5d0cd6bd07192b854f7942816e3b88a9838468c3b0e4d84fc  tests/spec/oep-v1.toml
 546ddf20d11b86faa23afe2fa1e3c38c514c157db4d5a5c8d92edf48647d61f1  tests/vectors/checks.json
 9950576fcf803299386d0b2e61bf154402f306102311312d49dec6a87a34ced5  tests/vectors/cobs.json
 c981ca124e3393ba68ce3ce3ee92970827f399202c7688bb6e02b66bb6190806  tests/vectors/confirm.json

oep_client_python-0.0.33/tests/vectors/SPEC_COMMIT

@@ -1 +0,0 @@
-ba4e8ee9a3ae21dda84938dd793544b9f72ad768