oep-client-python 0.0.3__tar.gz → 0.0.4__tar.gz

{oep_client_python-0.0.3 → oep_client_python-0.0.4}/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.0.4
+- (EN) Fake serial port: a candidate that is only its 0x00 is not raw after the 200 ms gap (the probe firmware had the same bug: a stray 0x00 reached the target's console).
+- (JA) 偽のシリアルの口: 0x00 だけの候補は、200 ms の後も生のバイトにしない（probe の firmware にも同じバグがあり、target のコンソールに 0x00 が届いていた）。
+- (EN) `oep config slot` takes the probe's only RISC-V wire when `--wire` is left out (a SWIO-only probe needed `--wire swio`).
+- (JA) `oep config slot` は `--wire` を省くと、probe の唯一の RISC-V の線を使う（SWIO だけの probe で `--wire swio` が要っていた）。
+- (EN) `oep config plan <probe> <fn | name#k> ROLE=CH ...` (role names from the registry: rx, tx, line...), `oep config label` and `oep config idle`.
+- (JA) `oep config plan <probe> <fn | 名前#k> ROLE=CH ...`（role の名前は registry から: rx、tx、line など）、`oep config label`、`oep config idle`。
+
 ## 0.0.3
 - (EN) `oep_client.config` (oep.probe.config: slots, binds, plan / label / idle items, get / set / save / erase, the live slot and bind state) and the `oep config show | slot | bind | remove | save | erase` command. An English README.md, also the PyPI page.
 - (JA) `oep_client.config`（oep.probe.config: スロット、bind、plan / label / idle の項目、get / set / save / erase、スロットと bind の今の状態）と、`oep config show | slot | bind | remove | save | erase` の命令。英語の README.md（PyPI のページも）。

{oep_client_python-0.0.3 → oep_client_python-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oep-client-python
-Version: 0.0.3
+Version: 0.0.4
 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

{oep_client_python-0.0.3 → oep_client_python-0.0.4}/pyproject.toml

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

{oep_client_python-0.0.3 → oep_client_python-0.0.4}/src/oep_client/__init__.py

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

{oep_client_python-0.0.3 → oep_client_python-0.0.4}/src/oep_client/__main__.py

@@ -4,6 +4,7 @@
   oep config show <probe>
   oep config slot <probe> --name x035 --wire rvswd --pins 2,54 --attach at-boot --retry 1 --mechanism dmseq
   oep config bind <probe> --port 1 --mode last-reset --stream slot:x035
+  oep config plan <probe> oep.fixture.uart#2 rx=48 tx=49       (the fn's whole plan; fn number or name#instance)
   oep config remove <probe> bind 1        oep config save <probe>        oep config erase <probe>
 
 <probe>: a serial port, tcp://HOST:PORT or usb[:VID:PID[:SERIAL]]. A change takes the lock (owner "oep config") and
@@ -58,7 +59,7 @@ def _config_parser(sub) -> None:
     slot.add_argument("probe")
     slot.add_argument("--slot", type=int, default=0, help="the slot number (default 0)")
     slot.add_argument("--name", required=True, help="1-32 of a-z 0-9 - _ (the oep://<probe>/<name> address)")
-    slot.add_argument("--wire", default="rvswd", help="rvswd or swio (or an fn)")
+    slot.add_argument("--wire", help="rvswd or swio (or an fn); default: the probe's only wire")
     slot.add_argument("--pins", help="swdio,swclk (one pin on swio); default: the wire's only pin set")
     slot.add_argument("--attach", choices=sorted(config.ATTACH), default="host")
     slot.add_argument("--retry", type=int, default=0, help="at-boot: try again every N s while absent (0: never)")
@@ -72,6 +73,21 @@ def _config_parser(sub) -> None:
     bind.add_argument("--stream", action="append", required=True, help="slot:NAME, slot:N or uart:FN (repeatable)")
     bind.add_argument("--select", type=int, default=0, help="manual: the stream it carries (index in --stream)")
     bind.add_argument("--save", action="store_true")
+    plan = cs.add_parser("plan", help="the pins an interface keeps (its whole plan, kept as a setting)")
+    plan.add_argument("probe")
+    plan.add_argument("fn", help="an fn, or an interface name with #k for its k-th instance (1 = the first)")
+    plan.add_argument("roles", nargs="+", help="ROLE=CHANNEL, ROLE a number or the interface's role name (rx, tx, line...)")
+    plan.add_argument("--save", action="store_true")
+    label = cs.add_parser("label", help="name a channel (shown in oep.core's describe)")
+    label.add_argument("probe")
+    label.add_argument("channel", type=int)
+    label.add_argument("text")
+    label.add_argument("--save", action="store_true")
+    idle = cs.add_parser("idle", help="the state of a free pin")
+    idle.add_argument("probe")
+    idle.add_argument("channel", type=int)
+    idle.add_argument("mode", choices=sorted(config.IDLE))
+    idle.add_argument("--save", action="store_true")
     rm = cs.add_parser("remove", help="remove one item: slot N, bind PORT, plan FN, label CH, idle CH")
     rm.add_argument("probe")
     rm.add_argument("kind", choices=["slot", "bind", "plan", "label", "idle"])
@@ -95,8 +111,40 @@ def _pins(hst, fn: int, text: str | None, wire: str) -> tuple[int, int]:
     return groups[0]
 
 
-def _wire_fn(hst, wire: str) -> int:
-    return int(wire) if wire.isdigit() else core.find(hst, wire if wire.startswith("oep.") else f"oep.wire.{wire}")
+def _plan_fn(hst, spec: str) -> tuple[int, dict[str, int]]:
+    """fn and its role names (from the registry) for `spec`: an fn number, or name[#k] (k-th instance, 1-based)."""
+    from . import registry as reg
+    if spec.isdigit():
+        fn = int(spec)
+        name = next((e.name for e in core.list_entries(hst) if e.fn == fn), "")
+    else:
+        name, _, k = spec.partition("#")
+        fns = core.find_all(hst, name)
+        if not fns:
+            raise SystemExit(f"the probe offers no {name}")
+        index = int(k) - 1 if k else 0
+        if not 0 <= index < len(fns):
+            raise SystemExit(f"{name}: {len(fns)} instance(s), fns {fns}")
+        fn = fns[index]
+    iface = reg.INTERFACES.get(name)
+    roles = dict(iface.enum.get("role", {})) if iface else {}
+    return fn, roles
+
+
+def _wire_fn(hst, wire: str | None) -> int:
+    if wire is None:
+        wires = [e for e in core.list_entries(hst, "oep.wire") if e.name in ("oep.wire.rvswd", "oep.wire.swio")]
+        if len(wires) != 1:
+            raise SystemExit("this probe has " + (", ".join(f"{e.name} (fn {e.fn})" for e in wires) or "no RISC-V wire")
+                             + ": name one with --wire")
+        return wires[0].fn
+    name = wire if wire.startswith("oep.") else f"oep.wire.{wire}"
+    if wire.isdigit():
+        return int(wire)
+    try:
+        return core.find(hst, name)
+    except LookupError:
+        raise SystemExit(f"this probe does not offer {name}") from None
 
 
 def _stream(spec: str, slots: dict[str, int]) -> tuple[str, int]:
@@ -129,6 +177,7 @@ def _config(args) -> int:
             return _show(hst, cfg, args.json)
         if args.action == "slot":
             fn = _wire_fn(hst, args.wire)
+            args.wire = args.wire or str(fn)
             lock = None
             if args.lock:
                 mask, _, value = args.lock.partition(":")
@@ -140,6 +189,22 @@ def _config(args) -> int:
             slots = {it.name: it.slot for it in cfg.items() if isinstance(it, config.Slot)}
             it = config.Bind(args.port, args.mode, [_stream(s, slots) for s in args.stream], args.select)
             _change(hst, cfg, [it], args.save)
+        elif args.action == "plan":
+            fn, roles = _plan_fn(hst, args.fn)
+            items = []
+            for spec in args.roles:
+                role, _, ch = spec.partition("=")
+                if not ch:
+                    raise SystemExit(f"{spec}: want ROLE=CHANNEL")
+                number = int(role) if role.isdigit() else roles.get(role.lower())
+                if number is None:
+                    raise SystemExit(f"{role}: not a role of fn {fn} (roles: {', '.join(sorted(roles)) or 'numbers only'})")
+                items.append(config.Plan(fn, number, int(ch, 0)))
+            _change(hst, cfg, items, args.save)
+        elif args.action == "label":
+            _change(hst, cfg, [config.Label(args.channel, args.text)], args.save)
+        elif args.action == "idle":
+            _change(hst, cfg, [config.Idle(args.channel, args.mode)], args.save)
         elif args.action == "remove":
             _change(hst, cfg, [config.remove(args.kind, args.key)], args.save)
         else:

{oep_client_python-0.0.3 → oep_client_python-0.0.4}/src/oep_client/fake_serial.py

@@ -5,7 +5,8 @@
 
 - a candidate runs from a 0x00 to the next 0x00; if it decodes and its CRC matches it is a request, otherwise it
   (with its leading 0x00) is raw bytes, and the closing 0x00 starts the next candidate; bytes outside a candidate
-  are raw at once; a candidate that stops for 200 ms (`tick`) is raw; an empty candidate (0x00 0x00) is nothing
+  are raw at once; a candidate that stops for 200 ms (`tick`) is raw; a candidate that is only its 0x00 (0x00 0x00,
+  or the closing 0x00 of a frame when nothing follows) is nothing
 - raw bytes go to the endpoint's bind for this port (`Endpoint.port_input`)
 - answers go out as 0x00 <COBS> 0x00, ahead of raw chunks (`Endpoint.port_output`); one writer, never a raw byte
   inside a frame
@@ -80,7 +81,8 @@ class FakeSerialPort:
     def _gap(self, now: int) -> None:
         if self.cand is not None and now - self.last_ms >= GAP_MS:
             raw, self.cand = bytes(self.cand), None
-            self._raw(bytearray(raw))
+            if len(raw) > 1:                         # only its 0x00: a delimiter (a frame's closing 0x00), not raw
+                self._raw(bytearray(raw))
 
     def _raw(self, raw: bytearray) -> None:
         if raw:

{oep_client_python-0.0.3 → oep_client_python-0.0.4}/tests/test_config.py

@@ -65,3 +65,35 @@ def test_the_command(capsys, monkeypatch):
     assert cli.main(["config", "show", "x"]) == 0
     out = capsys.readouterr().out
     assert "0 x035: fn 1 pins 2,3 at-boot retry 1 s dmseq" in out and "port 0 (usb_serial_jtag): last-reset [slot:x035]" in out
+
+
+def test_plan_label_idle_from_the_command(capsys, monkeypatch):
+    ep, hst = open_bench()
+
+    class FakeLink:
+        def close(self):
+            pass
+    hst.link = FakeLink()
+    hst.end()
+    monkeypatch.setattr(cli.link, "open_host", lambda target: hst)
+    assert cli.main(["config", "plan", "x", "oep.fixture.uart", "rx=20", "tx=21"]) == 0
+    assert cli.main(["config", "label", "x", "20", "DUT TX"]) == 0
+    assert cli.main(["config", "idle", "x", "21", "pull-up", "--save"]) == 0
+    assert {(5, 1, 20), (5, 2, 21)} <= ep.plan and 5 in ep.plan_from_config
+    items = config.ProbeConfig(hst).items()
+    assert config.Label(20, "DUT TX") in items and config.Idle(21, "pull-up") in items
+    assert ep.saved is not None
+
+
+def test_slot_takes_the_only_wire_by_default(monkeypatch):
+    ep = endpoint.Endpoint(fake.esp32_v003(), Clock())               # oep.wire.swio only
+    hst = h.Host(lambda b: ep.handle(b, 0))
+
+    class FakeLink:
+        def close(self):
+            pass
+    hst.link = FakeLink()
+    monkeypatch.setattr(cli.link, "open_host", lambda target: hst)
+    assert cli.main(["config", "slot", "x", "--name", "v003", "--attach", "at-boot", "--retry", "1"]) == 0
+    (slot,) = [i for i in config.ProbeConfig(hst).items() if isinstance(i, config.Slot)]
+    assert slot.wire_fn == 1 and slot.pins == (16, 0xFFFF)

{oep_client_python-0.0.3 → oep_client_python-0.0.4}/tests/test_fake_spec.py

@@ -370,3 +370,16 @@ def test_fake_serve_uart_plan_and_rx():
     finally:
         proc.stdin.close()
         proc.wait(timeout=5)
+
+
+def test_the_closing_0x00_of_a_frame_is_not_raw_after_the_gap():
+    clock = Clock()
+    ep = endpoint.Endpoint(fake.p4_bench(), clock)
+    p = ep.pairs[1]
+    ep.load_config([slot_item(0, 1, p[0]), bind_item(0, MODE["manual"], [(KIND["slot_console"], 0)])])
+    port = fake_serial.FakeSerialPort(ep, 0)
+    port.feed(framed(m.Request(1, 0, m.OP_LOCK_STATE, b"")))       # lock-free: the port is not held
+    clock.t += 250
+    port.tick()
+    sid = ep.stream_keys[(ep._conn_at(1, p[0]), 2)]
+    assert bytes(ep.streams[sid].written) == b""                   # no stray 0x00 at the target

{oep_client_python-0.0.3 → oep_client_python-0.0.4}/tests/test_link_serial.py

@@ -82,9 +82,13 @@ def test_open_host_on_a_serial_port_with_console_bytes_and_tiocexcl():
         if os.geteuid() != 0:
             with pytest.raises(link.PortBusy):
                 link.open_host(where[1])                              # exclusive: one host at a time
+        import time
+        deadline = time.monotonic() + 3                               # lock-free reads among the console bytes,
+        while hst.link.noise == 0 and time.monotonic() < deadline:   # before a session holds the port's raw side
+            assert [k for _, k, _ in core.transports(hst)] == [1]     # a UART bridge
+            time.sleep(0.02)
         opened = core.take(hst, 3000, owner="test")                   # the only way in: by force at once
         assert opened.lease_ms == 3000
-        assert [k for _, k, _ in core.transports(hst)] == [1]         # a UART bridge
         for _ in range(20):                                           # requests among the console bytes
             hst.keepalive()
         hst.end()
@@ -100,7 +104,8 @@ def test_the_same_host_over_tcp_length_frames_and_a_holder_that_keeps_its_lease_
     try:
         a = link.open_host(f"tcp://127.0.0.1:{where[1]}", timeout=1.0)
         a.open(60000, owner="ch32rv monitor")
-        assert a.lock_owner() == (True, a.lock_owner()[1], "ch32rv monitor")
+        locked, remaining, owner = a.lock_owner()                     # one read: the lease ticks down between two
+        assert locked and 0 < remaining <= 60000 and owner == "ch32rv monitor"
         b = h.Host(a.link.send)                                       # another host on the same link (a broker's client)
         b.link = a.link
         b.revision = 1