oep-client-python 0.0.26__py3-none-any.whl → 0.0.28__py3-none-any.whl

oep_client/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.0.26"
+__version__ = "0.0.28"

oep_client/__main__.py

@@ -9,7 +9,11 @@
   oep config uart <probe> oep.fixture.uart#1 115200 --format 8N1
   oep config disable <probe> 3 4           (channels the probe never uses or touches; remove disable CH re-enables)
   oep config remove <probe> bind 1        oep config save <probe>        oep config erase <probe>
-  oep speed <probe> 1500000,921600,500000 (port_speed, core §3.5: try the rates in order on a UART bridge, report)
+  oep speed <probe> [--candidates 921600,500000] [--verify [--flows in:2,out:2]] (port_speed, core §3.5 and the host
+                                           guide §7: try the candidates in order on a UART bridge, report)
+  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,
+                                           identify, hold-low + attach under reset; prints a slot, --save writes it)
 
 <probe>: a serial port, tcp://HOST:PORT or usb[:VID:PID[:SERIAL]]. A change takes the lock (owner "oep config") and
 ends the session after it; it takes effect at once, and stays over a restart only after `save` (or --save).
@@ -30,14 +34,50 @@ def main(argv=None) -> int:
     parser = argparse.ArgumentParser(prog="oep", description="Open Embedded Probe: what a probe offers, its settings")
     sub = parser.add_subparsers(dest="command", required=True)
     _config_parser(sub)
-    sp = sub.add_parser("speed", help="port_speed (core §3.5): try faster rates on a UART bridge, print the report")
+    sp = sub.add_parser("speed", help="port_speed (core §3.5, host guide §7): try faster rates on a UART bridge, "
+                        "print the report")
     sp.add_argument("probe", help="the probe's serial port (a UART bridge this host opens)")
-    sp.add_argument("rates", help="comma-separated, in order of preference (the first that passes is kept)")
+    sp.add_argument("rates", nargs="?", default="", help="the candidates, comma-separated, in order of preference "
+                    "(the first that passes is kept; default 500000). Same as --candidates")
+    sp.add_argument("--candidates", default="", help="the candidates, comma-separated (default 500000)")
+    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 §7.3): 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 §7.2, 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 "
+                    "(~/.cache/oep-client/link-speed.json, 30 days; on by default here, off in the library)")
     sp.add_argument("--baud", type=int, default=link.BASE_BAUD, help="the boot speed (default 115200)")
-    sp.add_argument("--verify-bytes", type=int, default=32768)
-    sp.add_argument("--verify-s", type=float, default=1.0)
-    sp.add_argument("--duplex-s", type=float, default=1.0, help="both ways at once for this long (default 1)")
     sp.add_argument("--json", action="store_true")
+    lt = sub.add_parser("linktest", help="measure the link: traffic patterns at rates the host asks for, what breaks")
+    lt.add_argument("probe", help="a probe: a serial port, tcp://HOST:PORT or usb[:VID:PID]")
+    lt.add_argument("--rates", default="", help="comma-separated rates to switch to with port_speed and measure at "
+                    "(each on its own; 0 or 'now' = the speed in force). Default: only the speed in force")
+    lt.add_argument("--patterns", default="in,out,duplex", help="in (probe->host), out (host->probe), duplex")
+    lt.add_argument("--inflight", default="1", help="comma-separated in-flight counts (above the probe's max: skipped)")
+    lt.add_argument("--sizes", default="", help="comma-separated frame payload sizes (default: a whole frame)")
+    lt.add_argument("--frames", type=int, default=300, help="frames per cell (default 300)")
+    lt.add_argument("--seconds", type=float, default=None, help="per cell for this long instead of --frames")
+    lt.add_argument("--timeout", type=float, default=0.3, help="seconds to wait for one answer (default 0.3)")
+    lt.add_argument("--baud", type=int, default=link.BASE_BAUD, help="the boot speed to open at (default 115200)")
+    lt.add_argument("--low-latency", choices=("on", "off"), default="on", help="the serial driver's low-latency mode")
+    lt.add_argument("--json", action="store_true", help="one JSON object per cell")
+    pn = sub.add_parser("pins", help="find where a target is wired: classify the channels, scan the wire, find the "
+                        "reset line, suggest a slot (writes nothing without --save)")
+    pn.add_argument("probe", help="a probe: a serial port, tcp://HOST:PORT or usb[:VID:PID[:SERIAL]]")
+    pn.add_argument("--power", type=int, help="the gpio channel that powers the target: switched off, then on, to "
+                    "see which channels follow it (never touched without this)")
+    pn.add_argument("--exclude", default="", help="channels never to read, scan or hold, comma-separated")
+    pn.add_argument("--wire", choices=("swio", "rvswd", "swd"), default="swio")
+    pn.add_argument("--steps", default="classify,hold,scan,identify,reset,slot",
+                    help="the steps to run, comma-separated (default all: classify, hold, scan, identify, reset, slot)")
+    pn.add_argument("--save", action="store_true", help="write the suggested slot (config set, then save)")
+    pn.add_argument("--slot", type=int, default=0, help="--save: the slot number (default 0)")
+    pn.add_argument("--name", help="--save: the slot's name (default: the target family, else 'target')")
+    pn.add_argument("--json", action="store_true", help="the report as JSON (the steps' lines go to stderr)")
     d = sub.add_parser("dump", help="list and describe every interface a probe offers")
     src = d.add_mutually_exclusive_group(required=True)
     src.add_argument("--fake", choices=sorted(fake.PROFILES), help="in-process example probe")
@@ -50,6 +90,10 @@ def main(argv=None) -> int:
         return _config(args)
     if args.command == "speed":
         return _speed(args)
+    if args.command == "linktest":
+        return _linktest(args)
+    if args.command == "pins":
+        return _pins_cmd(args)
 
     if args.fake:
         call = fake.PROFILES[args.fake]().call
@@ -61,17 +105,97 @@ def main(argv=None) -> int:
     return 0
 
 
+# ---- oep pins -----------------------------------------------------------------------------------------------------
+
+def _pins_cmd(args) -> int:
+    from . import pins
+    exclude = [int(x, 0) for x in args.exclude.replace(" ", "").split(",") if x]
+    say = (lambda t: print(t, file=sys.stderr, flush=True)) if args.json else (lambda t: print(t, flush=True))  # noqa: E731
+    hst = link.open_host(args.probe)
+    try:
+        core.take(hst, 10000, owner="oep pins")
+        finder = pins.PinFinder(hst, wire=args.wire, power=args.power, exclude=exclude, say=say, probe=args.probe,
+                                save=args.save, slot=args.slot, name=args.name)
+        report = finder.run(steps=tuple(s for s in args.steps.split(",") if s))
+        say(f"done in {report.elapsed_s:.1f} s")
+        if args.json:
+            print(json.dumps(report.as_dict(), indent=2))
+        try:
+            hst.end()
+        except host.OepError:
+            pass
+    except host.Rejected as e:
+        print(f"refused: {e}", file=sys.stderr)
+        return 2
+    finally:
+        hst.link.close()
+    return 0 if report.found else 1
+
+
+# ---- oep linktest -------------------------------------------------------------------------------------------------
+
+def _linktest(args) -> int:
+    """Every parameter on the command line: no fixed numbers in the measurement."""
+    import dataclasses
+    import json
+    from . import linktest
+    ints = lambda text: [int(v) for v in text.split(",") if v.strip()]   # noqa: E731
+    rates = [None if v.strip() in ("0", "now") else int(v) for v in args.rates.split(",") if v.strip()] or [None]
+    hst = link.open_host(args.probe, baud=args.baud) if args.probe.startswith("/") or ":" not in args.probe \
+        else link.open_host(args.probe)
+    stream = getattr(hst.link, "stream", None)
+    if hasattr(stream, "set_low_latency_mode"):
+        try:
+            stream.set_low_latency_mode(args.low_latency == "on")
+        except (OSError, ValueError, NotImplementedError):
+            pass
+    try:
+        core.take(hst, 30000, owner="oep linktest")
+        for result in linktest.matrix(hst, rates=rates, patterns=[p for p in args.patterns.split(",") if p],
+                                      inflight=ints(args.inflight), sizes=ints(args.sizes) or None,
+                                      frames=args.frames, seconds=args.seconds, timeout=args.timeout):
+            if args.json:
+                for c in result.cells:
+                    print(json.dumps({**dataclasses.asdict(c), "actual": result.actual, "low_latency": args.low_latency}), flush=True)
+                if result.why:
+                    print(json.dumps({"rate": result.rate, "why": result.why}), flush=True)
+            else:
+                print(result.text(), flush=True)
+        try:
+            hst.end()
+        except Exception:
+            pass
+    finally:
+        hst.link.close()
+    return 0
+
+
 # ---- oep speed ----------------------------------------------------------------------------------------------------
 
+def _flows(text: str) -> list[tuple[str, int]] | None:
+    """--flows "in:2,out,duplex:1" -> [("in", 2), ("out", 0), ("duplex", 1)]; "" -> None (the default flows)."""
+    out = []
+    for item in text.replace(" ", "").split(","):
+        if not item:
+            continue
+        name, _, n = item.partition(":")
+        out.append((name, int(n) if n else 0))
+    return out or None
+
+
 def _speed(args) -> int:
-    """Take the lock, raise_speed, print the report; the session's end puts the port back at its boot speed."""
+    """Take the lock, raise_speed by the host guide's procedure, print the report; the session's end puts the port
+    back at its boot speed. The record of passed / failed rates is on unless --no-record."""
     import dataclasses
-    rates = [int(r) for r in args.rates.replace(" ", "").split(",") if r]
+    text = args.candidates or args.rates
+    candidates = [int(r) for r in text.replace(" ", "").split(",") if r] or list(link.DEFAULT_CANDIDATES)
+    flows = _flows(args.flows)
+    verify = True if args.verify or flows else (False if args.minimal else None)
     hst = link.open_host(args.probe, baud=args.baud)
     try:
         core.take(hst, 5000, owner="oep speed")
-        report = link.raise_speed(hst, rates, verify_bytes=args.verify_bytes, verify_s=args.verify_s,
-                                   duplex_s=args.duplex_s)
+        report = link.raise_speed(hst, candidates, flows=flows, verify=verify, frames=args.frames,
+                                   record=not args.no_record)
         if args.json:
             sys.stdout.write(json.dumps(dataclasses.asdict(report), indent=2) + "\n")
         else:

oep_client/arm.py

@@ -10,7 +10,7 @@ import struct
 
 from . import host as h, message as m, registry as reg
 from .core import Interface
-from .riscv import OK, TargetError, WireBase, check, ran, status_name  # noqa: F401
+from .riscv import OK, BlockLength, TargetError, WireBase, check, ran, status_name  # noqa: F401
 
 DP_DPIDR = DP_ABORT = 0x0
 DP_CTRL_STAT = 0x4
@@ -60,7 +60,9 @@ def transfer_reads(steps: bytes) -> list[bool]:
     return out
 
 
-class ArmAdi(Interface):
+class ArmAdi(Interface, BlockLength):
+    """oep.target.arm-adi on one connection. `max_length` / `max_words` bound read_block / write_block (from the
+    probe's describe, oep-if-debug §6: mandatory there)."""
     NAME = "oep.target.arm-adi"
     REVISION = 1
     TRANSFER, READ_BLOCK, WRITE_BLOCK = _ADI.op["transfer"], _ADI.op["read_block"], _ADI.op["write_block"]
@@ -70,6 +72,7 @@ class ArmAdi(Interface):
         self.conn = conn
         self.adiv6 = adiv6
         self._select: int | None = None
+        self._max_length = None
 
     # ---- raw transfers ----
     @staticmethod
@@ -140,10 +143,8 @@ class MemAp:
         csw = adi.ap_read(ap, self.base)
         adi.ap_write(ap, self.base, (((csw & ~0x37) | 0x12) | csw_set) & ~csw_clear)   # 32 bits, AddrInc single
         adi._ap_select(ap, self.base)                        # the bank the block operations assume
-        # Words per block operation, from the probe's frame limit: request header 6 + session 4 + connection 2 +
-        # address 4 + count 2 on the way in (the answer's 5 + done 2 + status 1 is smaller).
-        from .core import confirm
-        self.chunk = max(1, (confirm(adi.host)["max_frame"] - 18) // 4)
+        # Words per block operation: the probe's declared max_length (oep-if-debug §6), never computed from max_frame
+        self.chunk = adi.max_words
 
     def write_many(self, pairs: list[tuple[int, int]]) -> None:
         """Scattered single-word writes in one transfer list (TAR, DRW per word, RDBUFF at the end so the last one

oep_client/ch32_flash.py

@@ -17,7 +17,7 @@ import struct
 import time
 from dataclasses import dataclass, field
 
-from . import core, host as h, riscv
+from . import host as h, riscv
 
 # oep-spec experiments/flash-primitives/x035_loader.S, assembled at 0x20000000 (riscv32-esp-elf binutils)
 FAST_PAGE_LOADER = bytes.fromhex(
@@ -91,11 +91,10 @@ LOADER, FAST_BUFFER, FAST_DONE = 0x20000000, 0x20000400, 0x200000B0
 V003_INPUT, V003_STACK, V003_EBREAK, V003_RUN = 0x20000200, 0x20000800, 0x2000015C, 1024
 
 
-def _block_size(hst: h.Host) -> int:
-    info = core.confirm(hst)
-    # request header 6 + session 4 + connection 1 + address 4 + count 2 (the read answer's 5 + done 2 + status 1 is
-    # smaller); a little slack for the result header
-    return (info["max_frame"] - 5 - 6 - 4 - 1 - 4 - 2) // 4 * 4
+def _block_size(dm: riscv.RiscvDm) -> int:
+    """Bytes per read_block / write_block: the probe's declared max_length (oep-if-debug §4.5), never a value computed
+    from max_frame (riscv.NoMaxLength when the probe declares none)."""
+    return dm.max_words * 4
 
 
 def _write_requests(dm: riscv.RiscvDm, address: int, data: bytes, block: int) -> list[tuple[int, int, bytes]]:
@@ -142,7 +141,7 @@ def program(hst: h.Host, dm: riscv.RiscvDm, image: bytes, profile: FlashProfile)
     image = image + b"\xff" * (-len(image) % profile.page)
     if profile.size and len(image) > profile.size:
         raise ValueError(f"image of {len(image)} bytes exceeds {profile.size}")
-    block = _block_size(hst)
+    block = _block_size(dm)
     t = {}
     t0 = time.perf_counter()
     if profile.method == "fast-page":

oep_client/cobs.py

@@ -71,3 +71,8 @@ def unframe(raw: bytes) -> bytes:
     if crc16(body) != got:
         raise CorruptFrame("CRC mismatch")
     return body
+
+def frame_max(message_len: int) -> int:
+    """The longest frame a message of this length makes: CRC16, a COBS code per 254 bytes and one more, the delimiter."""
+    n = message_len + 2
+    return n + (n + 253) // 254 + 1 + 1

oep_client/config.py

@@ -73,14 +73,23 @@ class Label:
 
 @dataclass(kw_only=True)
 class Idle:
+    """The state of a channel no plan or connection uses (probe.config §1): at boot and after every release. mode:
+    hi-z, pull-up, pull-down, output-low, output-high (output_low / output_high too). An output mode keeps driving that
+    level while the channel is free - a target's power switch kept on - and a gpio plan that takes the channel keeps
+    it until its first set (fixture §1); a probe that cannot drive the channel refuses it unsupported."""
     channel: int
-    mode: str = "pull-up"          # hi-z, pull-up, pull-down
+    mode: str = "pull-up"          # hi-z, pull-up, pull-down, output-low, output-high
     TAG = ITEM["idle"]
 
+    def __post_init__(self):
+        self.mode = self.mode.replace("_", "-")
+
     def key(self) -> tuple:
         return (self.channel,)
 
     def value(self) -> bytes:
+        if self.mode not in IDLE:
+            raise ValueError(f"idle mode {self.mode!r}: one of {', '.join(IDLE)}")
         return struct.pack("<HB", self.channel, IDLE[self.mode])
 
 
@@ -395,3 +404,50 @@ class ProbeConfig(Interface):
                 return st
             first_slot += n_slots
             first_bind += n_binds
+
+
+# The label names of a target's power and reset lines (host-development-guide §8.1): `nrst` its reset, `power_hi` high
+# powers it, `power_lo` low powers it. On a probe with several slots they are `<slot name>.<name>`.
+LINE_NAMES = ("nrst", "power_hi", "power_lo")
+
+
+class AmbiguousLine(LookupError):
+    """find_line could not tell which channel is meant; `candidates` holds (label text, channel)."""
+
+    def __init__(self, message: str, candidates: list[tuple[str, int]]):
+        super().__init__(message)
+        self.candidates = candidates
+
+
+def find_line(hst_or_items, name: str, slot: int | str | None = None) -> int | None:
+    """The channel labelled for `name` (nrst, power_hi, power_lo: host-development-guide §8.1), or None when there is
+    none. hst_or_items: a Host (its settings are read: `ProbeConfig.items()`, no lock) or the decoded items. slot: the
+    slot's name or number; None picks the probe's one slot.
+
+    `<slot>.<name>` first, then the bare `name` - the bare name only when the settings hold at most one slot (a bare
+    name is for a one-slot probe). With several slots and no `slot`, or two channels with the same label, it raises
+    AmbiguousLine listing the candidates."""
+    items = hst_or_items if isinstance(hst_or_items, (list, tuple)) else ProbeConfig(hst_or_items).items()
+    labels = [(it.text, it.channel) for it in items if isinstance(it, Label)]
+    slots = [it for it in items if isinstance(it, Slot)]
+    if isinstance(slot, int):
+        named = [s.name for s in slots if s.slot == slot]
+        if not named:
+            raise LookupError(f"no slot {slot} in the probe's settings")
+        slot = named[0]
+    if slot is None and len(slots) > 1:
+        candidates = sorted((t, c) for t, c in labels if t == name or t.endswith("." + name))
+        if candidates:
+            listed = ", ".join(f"{t} (channel {c})" for t, c in candidates)
+            raise AmbiguousLine(f"{name}: {len(slots)} slots and no slot given; candidates: {listed}", candidates)
+        return None
+    if slot is None and slots:
+        slot = slots[0].name
+    texts = ([f"{slot}.{name}"] if slot is not None else []) + ([name] if len(slots) <= 1 else [])
+    for text in texts:
+        found = sorted(c for t, c in labels if t == text)
+        if len(found) > 1:
+            raise AmbiguousLine(f"{text}: on {len(found)} channels", [(text, c) for c in found])
+        if found:
+            return found[0]
+    return None