oep-client-python 0.0.1__py3-none-any.whl

oep_client/v1/fake_serve.py

@@ -0,0 +1,299 @@
+"""Serve a fake probe (`endpoint.Endpoint`) on a pty or a TCP port, for other programs' tests.
+
+    python -m oep_client.v1.fake_serve [--pty | --tcp PORT] [options]
+
+--pty (the default) opens a pseudo terminal that is the probe's serial port (oep-core §3.4): COBS frames
+0x00 <COBS> 0x00 and the raw bytes of the port's bind on one line. The host opens the printed path itself (and
+should set TIOCEXCL on it, as on a real port; this program never opens the slave side). --tcp PORT (0 = any free
+one) serves one connection at a time: --framing cobs is the serial port again, --framing length is
+length(u16) message as on vendor bulk / TCP (no raw bytes).
+
+The first line on stdout says where to open: `PTY /dev/pts/N` or `PORT n`. The program ends when stdin closes
+(so a test's child never stays behind), or with --once when the first TCP connection closes.
+
+Options:
+  --profile NAME        p4-x035 (default), esp32-v003 or p4-bench (p4_x035 style names work too)
+  --port-index N        which serial port of the profile the pty / cobs TCP is (default: the first one)
+  --noise TEXT          raw bytes written in front of every answer (the host must skip them)
+  --drop N              the N-th answer (1-based) is not sent, once (the request did run: a resend gets the
+                        remembered result)
+  --corrupt N           the N-th answer goes out once with a broken CRC
+  --console FMT         what the targets write to their consoles, %d = a counter, {t} = the target's index
+  --every MS            how often (default 100; "100ms" works too)
+  --slot NAME           register a slot at boot (repeatable; the n-th on the n-th pin pair of the first wire, at boot,
+                        retry 1 s, mechanism dmseq), as if saved
+  --bind MODE           bind the serial port to every --slot: last-reset, manual or mixed
+  --target-id HEX       the target_id every target's attach reports (wch_dmi_7f)
+  --absent N            the N-th pin pair of the first wire has no target (repeatable)
+  --run-hook SPEC       what riscv-dm run does on every target: SPEC is module:function or path/file.py:function,
+                        called as function(target, pc, regs) -> (stopped, dpc, elapsed_us). `target` is the
+                        endpoint.FakeTarget (mem = word address -> value, regs = regno -> value, halted, dpc), so a
+                        host's loader can be played by the host's own test code (the fake knows no loader).
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import importlib.util
+import os
+import re
+import select
+import socket
+import struct
+import sys
+import time
+import tty
+
+from . import endpoint, fake, fake_serial, registry as reg
+
+_ITEM = reg.PROBE_CONFIG.tlv["item"]
+_MODES = reg.PROBE_CONFIG.enum["bind_mode"]
+
+
+def _ms(text: str) -> int:
+    return int(re.fullmatch(r"(\d+)\s*(ms)?", text.strip()).group(1))
+
+
+def build(a: argparse.Namespace) -> endpoint.Endpoint:
+    profile = fake.PROFILES.get(a.profile) or fake.PROFILES[a.profile.replace("_", "-")]
+    start = time.monotonic()
+    ep = endpoint.Endpoint(profile(), lambda: int((time.monotonic() - start) * 1000))
+    wire = min(ep.pairs) if ep.pairs else None
+    if a.target_id is not None:
+        for tg in ep.targets.values():
+            tg.target_id = int(a.target_id, 16)
+    if a.run_hook:
+        hook = _load_hook(a.run_hook)
+        for tg in ep.targets.values():
+            tg.run_hook = (lambda t: lambda pc, regs: hook(t, pc, regs))(tg)
+    for n in a.absent:
+        ep.targets[(wire, ep.pairs[wire][n])].present = False
+    items = []
+    for n, name in enumerate(a.slot):
+        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
+        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)
+                           for n in range(len(a.slot)))
+        value = struct.pack("<BBBB", a.port_index, _MODES[a.bind.replace("-", "_")], 0, len(a.slot)) + streams
+        items.append(bytes([_ITEM["bind"], len(value)]) + value)
+    if items:
+        ep.load_config(items, saved=True)
+    return ep
+
+
+def _load_hook(spec: str):
+    where, _, name = spec.rpartition(":")
+    if not where or not name:
+        raise SystemExit(f"--run-hook {spec}: want module:function or file.py:function")
+    if where.endswith(".py") or os.sep in where:
+        loader = importlib.util.spec_from_file_location("fake_run_hook", where)
+        module = importlib.util.module_from_spec(loader)
+        loader.loader.exec_module(module)
+    else:
+        module = importlib.import_module(where)
+    return getattr(module, name)
+
+
+def _filter(a: argparse.Namespace):
+    done = set()
+
+    def answer(n: int, result: bytes) -> bytes | None:
+        from . import cobs
+        if n == a.drop and "drop" not in done:
+            done.add("drop")
+            return None
+        wire = cobs.frame(result)
+        if n == a.corrupt and "corrupt" not in done:
+            done.add("corrupt")
+            body = bytearray(cobs.decode(wire[1:-1]))
+            body[-1] ^= 0xFF                             # the CRC's high byte
+            wire = b"\x00" + cobs.encode(bytes(body)) + b"\x00"
+        return a.noise.encode() + wire if a.noise else wire
+    return answer
+
+
+class Console:
+    def __init__(self, ep: endpoint.Endpoint, fmt: str | None, every_ms: int):
+        self.ep, self.fmt, self.every = ep, fmt, every_ms
+        self.next_ms, self.count = 0, 0
+
+    def tick(self) -> None:
+        if not self.fmt or self.ep.now() < self.next_ms:
+            return
+        self.next_ms = self.ep.now() + self.every
+        for i, tg in enumerate(self.ep.targets.values()):
+            text = self.fmt.replace("{t}", str(i))
+            if "%d" in text:
+                text = text.replace("%d", str(self.count))
+            self.ep.target_says(text.encode().decode("unicode_escape").encode("latin-1"), tg)
+        self.count += 1
+
+
+def _stdin_closed(readable) -> bool:
+    if sys.stdin in readable:
+        try:
+            return not os.read(sys.stdin.fileno(), 4096)
+        except OSError:
+            return True
+    return False
+
+
+def serve_pty(a, ep, console) -> None:
+    master, slave = os.openpty()
+    tty.setraw(slave)                                    # no echo, no line discipline between host and probe
+    print(f"PTY {os.ttyname(slave)}", flush=True)
+    os.close(slave)
+    os.set_blocking(master, False)
+    port = fake_serial.FakeSerialPort(ep, a.port_index, _filter(a))
+    pending = bytearray()
+    watch = [master] + ([sys.stdin] if not sys.stdin.closed else [])
+    while True:
+        readable, _, _ = select.select(watch, [], [], 0.005)
+        if _stdin_closed(readable):
+            return
+        if master in readable:
+            try:
+                data = os.read(master, 65536)
+            except OSError:                              # nobody has the port open (EIO)
+                data = b""
+            if data:
+                port.feed(data)
+        console.tick()
+        port.tick()
+        if len(pending) < 1024:
+            pending += port.output()
+        if pending:
+            try:
+                pending = pending[os.write(master, pending):]
+            except (BlockingIOError, OSError):
+                pass                                     # full or not open: keep it (the stream positions hold)
+
+
+def serve_tcp(a, ep, console) -> None:
+    srv = socket.socket()
+    srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    srv.bind(("127.0.0.1", a.tcp))
+    srv.listen(1)
+    print(f"PORT {srv.getsockname()[1]}", flush=True)
+    watch_stdin = [sys.stdin] if not sys.stdin.closed else []
+    while True:
+        readable, _, _ = select.select([srv] + watch_stdin, [], [], 0.05)
+        if _stdin_closed(readable):
+            return
+        console.tick()
+        ep.tick()
+        if srv not in readable:
+            continue
+        conn, _ = srv.accept()
+        conn.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+        if _serve_conn(a, ep, console, conn, watch_stdin):
+            return
+        conn.close()
+        if a.once:
+            return
+
+
+def _serve_conn(a, ep, console, conn, watch_stdin) -> bool:
+    """One TCP connection; True = stdin closed (end the program)."""
+    conn.setblocking(False)
+    if a.framing == "cobs":
+        port = fake_serial.FakeSerialPort(ep, a.port_index, _filter(a))
+    else:
+        index = next((i for i, k in enumerate(ep.transports) if i not in ep.serial_ports), 0)
+        buf, answers, filt = bytearray(), 0, _filter(a)
+    while True:
+        readable, _, _ = select.select([conn] + watch_stdin, [], [], 0.005)
+        if _stdin_closed(readable):
+            return True
+        if conn in readable:
+            try:
+                data = conn.recv(65536)
+            except BlockingIOError:
+                data = None
+            except ConnectionResetError:
+                data = b""
+            if data == b"":
+                return False
+            if data:
+                if a.framing == "cobs":
+                    port.feed(data)
+                else:
+                    buf += data
+                    while len(buf) >= 2:
+                        n = struct.unpack_from("<H", buf)[0]
+                        if n == 0:
+                            del buf[:2]
+                            continue
+                        if len(buf) < 2 + n:
+                            break
+                        msg = bytes(buf[2:2 + n])
+                        del buf[:2 + n]
+                        try:
+                            result = ep.handle(msg, index)
+                        except ValueError:
+                            continue
+                        if result is None:
+                            continue
+                        answers += 1
+                        if a.drop == answers and filt(answers, result) is None:
+                            continue
+                        conn.sendall(a.noise.encode() + struct.pack("<H", len(result)) + result)
+        console.tick()
+        if a.framing == "cobs":
+            port.tick()
+            out = port.output()
+            if out:
+                conn.setblocking(True)
+                conn.sendall(out)
+                conn.setblocking(False)
+        else:
+            ep.tick()
+
+
+def main(argv: list[str] | None = None) -> None:
+    ap = argparse.ArgumentParser(prog="python -m oep_client.v1.fake_serve", description=__doc__.split("\n\n")[0])
+    where = ap.add_mutually_exclusive_group()
+    where.add_argument("--pty", action="store_true")
+    where.add_argument("--tcp", type=int, metavar="PORT")
+    ap.add_argument("--framing", choices=["cobs", "length"], default="cobs")
+    ap.add_argument("--profile", default="p4-x035")
+    ap.add_argument("--port-index", type=int)
+    ap.add_argument("--noise", default="")
+    ap.add_argument("--drop", type=int, default=0)
+    ap.add_argument("--corrupt", type=int, default=0)
+    ap.add_argument("--console")
+    ap.add_argument("--every", default="100")
+    ap.add_argument("--slot", action="append", default=[])
+    ap.add_argument("--bind", choices=["last-reset", "manual", "mixed"])
+    ap.add_argument("--target-id")
+    ap.add_argument("--absent", type=int, action="append", default=[])
+    ap.add_argument("--run-hook")
+    ap.add_argument("--once", action="store_true")
+    a = ap.parse_args(argv)
+    if a.tcp is None and a.framing == "length":
+        ap.error("--framing length is for --tcp")
+    profile = fake.PROFILES.get(a.profile) or fake.PROFILES.get(a.profile.replace("_", "-"))
+    if profile is None:
+        ap.error(f"unknown profile {a.profile}; one of {', '.join(sorted(fake.PROFILES))}")
+    if a.port_index is None:
+        probe_ep = endpoint.Endpoint(profile(), lambda: 0)
+        a.port_index = min(probe_ep.serial_ports) if probe_ep.serial_ports else 0
+    ep = build(a)
+    console = Console(ep, a.console, _ms(a.every))
+    try:
+        if a.tcp is None:
+            serve_pty(a, ep, console)
+        else:
+            serve_tcp(a, ep, console)
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

oep_client/v1/fixture.py

@@ -0,0 +1,121 @@
+"""oep.fixture.gpio and oep.fixture.uart, revision 1 (oep-spec oep-if-fixture). The capture is in `capture`
+(oep.fixture.capture revision 1 = logic-capture's basic set).
+
+Plan roles stay as they were: gpio 1 = line; uart 1 = RX, 2 = TX. Only channels the plan assigned can be used.
+"""
+
+from __future__ import annotations
+
+import struct
+import time
+
+from . import host as h, message as m, registry as reg
+from .console import PositionStream, StreamIO
+from .core import Interface
+
+_GPIO, _UART = reg.FIXTURE_GPIO, reg.FIXTURE_UART
+_MODE = _GPIO.enum["mode"]
+
+
+class Gpio(Interface):
+    """oep.fixture.gpio. `set` applies (channel, mode) pairs in order in one request (pull NRST, then release it); a
+    channel the plan did not assign or a mode the probe lacks rejects the whole list as unavailable (payload: its
+    index). The open-drain modes never drive a line high: the way to move a target's reset line."""
+    NAME = "oep.fixture.gpio"
+    REVISION = 1
+    SET, READ = _GPIO.op["set"], _GPIO.op["read"]
+    INPUT, INPUT_PULLUP, INPUT_PULLDOWN = _MODE["input"], _MODE["input_pullup"], _MODE["input_pulldown"]
+    OUTPUT_LOW, OUTPUT_HIGH = _MODE["output_low"], _MODE["output_high"]
+    OPEN_DRAIN_LOW, OPEN_DRAIN_RELEASE = _MODE["open_drain_low"], _MODE["open_drain_release"]
+    INPUT_PULLUP_PULLDOWN = _MODE["input_pullup_pulldown"]   # both pulls: a weak mid level
+
+    def __init__(self, hst: h.Host, fn: int | None = None, name: str | None = None):
+        super().__init__(hst, name, fn=fn)
+
+    @staticmethod
+    def set_body(pairs: list[tuple[int, int]]) -> bytes:
+        return struct.pack("<B", len(pairs)) + b"".join(struct.pack("<HB", ch, mode) for ch, mode in pairs)
+
+    def set(self, pairs: list[tuple[int, int]]) -> None:
+        """[(channel, mode)], applied in order."""
+        self._call(self.SET, self.set_body(pairs))
+
+    def configure(self, channel: int, mode: int) -> None:
+        self.set([(channel, mode)])
+
+    def read(self, channels: list[int]) -> list[int]:
+        """-> one level (0 / 1) per channel. Lock-free."""
+        rd = m.Reader(self._call(self.READ, struct.pack("<B", len(channels))
+                                 + b"".join(struct.pack("<H", c) for c in channels), locked=False).payload)
+        levels = list(rd.bytes(len(channels)))
+        rd.tail()
+        return levels
+
+    def pull_low(self, channel: int) -> None:
+        self.set([(channel, self.OPEN_DRAIN_LOW)])
+
+    def release(self, channel: int) -> None:
+        self.set([(channel, self.OPEN_DRAIN_RELEASE)])
+
+    def request_release(self, channel: int) -> tuple[int, int, bytes]:
+        """The release as a raw request, to pipeline with whatever must follow it at once."""
+        return self.request(self.SET, self.set_body([(channel, self.OPEN_DRAIN_RELEASE)]))
+
+    def pulse_low(self, channel: int, low_s: float = 0.02) -> None:
+        """Open-drain low, then released to Hi-Z (never driven high)."""
+        self.pull_low(channel)
+        try:
+            time.sleep(low_s)
+        finally:
+            self.release(channel)
+
+
+class FixtureUart(PositionStream):
+    """oep.fixture.uart: one position stream per fn, like the console without a stream byte. Received bytes are kept
+    from configure until plan_release, whatever the session; reads are lock-free and do not consume. TX idles high
+    before configure and after plan_release."""
+    NAME = "oep.fixture.uart"
+    REVISION = 1
+    CONFIGURE = _UART.op["configure"]
+    TAG_FORMAT = _UART.tlv["configure"]["format"]
+    # format bits: data bits (0 = 8, 1 = 7), parity (0 none, 1 even, 2 odd) << 2, stop bits (0 = 1, 1 = 2) << 4
+    EIGHT_N_1 = 0x00
+
+    def __init__(self, hst: h.Host, fn: int | None = None, name: str | None = None):
+        super().__init__(hst, name, fn=fn)
+
+    @staticmethod
+    def format_byte(data_bits: int = 8, parity: str = "N", stop_bits: int = 1) -> int:
+        return ({8: 0, 7: 1}[data_bits] | {"N": 0, "E": 1, "O": 2}[parity.upper()] << 2 | {1: 0, 2: 1}[stop_bits] << 4)
+
+    def configure(self, baud: int, fmt: int | None = None) -> int:
+        """-> the actual baud. fmt (format_byte()) goes as a critical TLV: a probe that cannot set it refuses rather
+        than running 8N1; None leaves the default 8N1."""
+        body = struct.pack("<I", baud)
+        if fmt is not None:
+            body += m.tlv(self.TAG_FORMAT, bytes([fmt]), critical=True)
+        rd = m.Reader(self._call(self.CONFIGURE, body).payload)
+        actual = rd.u32()
+        rd.tail()
+        return actual
+
+
+class FixtureUartIO(StreamIO):
+    """oep.fixture.uart as a plain byte stream, after a plan gave it RX / TX: configure() starts reading from the
+    stream's position at that moment (earlier bytes are skipped); write() splits and waits for the UART."""
+    MAX_READ, MAX_WRITE = 480, 256            # fit the smallest probe frame in use (V003: 512 bytes)
+
+    def __init__(self, hst: h.Host, fn: int | None = None, name: str | None = None):
+        self.uart = FixtureUart(hst, fn, name)
+        self.source, self.position, self.lost = self.uart, None, 0
+        self.baud = 0
+
+    def configure(self, baud: int, fmt: int | None = None) -> int:
+        self.baud = self.uart.configure(baud, fmt)
+        self.position = self.uart.read(PositionStream.FROM_NOW, 0, 0).start
+        return self.baud
+
+    def read(self, n: int = 512) -> bytes:
+        if self.position is None:                  # not configured here: read from the oldest byte kept
+            self.position = self.uart.read(PositionStream.FROM_OLDEST, 0, 0).start
+        return super().read(n)

oep_client/v1/frames.py

@@ -0,0 +1,91 @@
+"""Length-prefixed frames on a reliable byte stream (USB CDC, USB-Serial/JTAG, USB vendor bulk): u16 length, then the
+message (oep-spec oep-core §3). No CRC: a length that cannot be right, or a frame that stops half way, means
+the boundaries are lost - FramingLost, and the link resyncs."""
+
+from __future__ import annotations
+
+import struct
+import time
+
+from . import registry as reg
+
+STALL_S = reg.TIMING["probe_frame_gap_ms"] / 1000   # a frame whose bytes stop this long is not coming
+
+
+class FramingLost(ConnectionError):
+    """The frame boundaries are lost: an impossible length, a frame that stalled half way, a result for another
+    request. The link reads and discards until the input is quiet, then confirms (oep-core §5.1)."""
+
+
+class LengthFrames:
+    def __init__(self, stream, max_frame: int = 0xFFFF):
+        self._stream = stream
+        self._buffer = bytearray()
+        self._last_rx = time.monotonic()
+        self.max_frame = max_frame
+
+    def send_many(self, messages) -> None:
+        """Several frames in one write (each frame whole in one write: the probe restarts its reader when a frame
+        pauses, and separate writes over usbipd can be 100 ms apart)."""
+        chunk = bytearray()
+        for message in messages:
+            if not message or len(message) > self.max_frame:
+                raise ValueError(f"message length {len(message)} outside 1..{self.max_frame}")
+            chunk += struct.pack("<H", len(message)) + message
+        if chunk:
+            self._stream.write(bytes(chunk))
+
+    def _fill(self, deadline: float) -> bool:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            return False
+        self._stream.timeout = min(remaining, 0.05)
+        data = self._stream.read(1)
+        if not data:
+            return False
+        waiting = getattr(self._stream, "in_waiting", 0)
+        if waiting:
+            data += self._stream.read(waiting)
+        self._buffer += data
+        self._last_rx = time.monotonic()
+        return True
+
+    def recv(self, timeout: float) -> bytes | None:
+        """The next message, or None when nothing arrived by the timeout. Raises FramingLost for a length above
+        max_frame or a frame whose bytes stopped for STALL_S (length 0 is the reserved keepalive: skipped)."""
+        deadline = time.monotonic() + timeout
+        while True:
+            if len(self._buffer) >= 2:
+                length = self._buffer[0] | (self._buffer[1] << 8)
+                if length == 0:
+                    del self._buffer[:2]
+                    continue
+                if length > self.max_frame:
+                    raise FramingLost(f"frame length {length} exceeds {self.max_frame}")
+                if len(self._buffer) >= 2 + length:
+                    message = bytes(self._buffer[2:2 + length])
+                    del self._buffer[:2 + length]
+                    return message
+            if not self._fill(deadline):
+                if self._buffer and time.monotonic() - self._last_rx >= STALL_S:
+                    raise FramingLost(f"a frame stopped after {len(self._buffer)} bytes")
+                if time.monotonic() >= deadline:
+                    if self._buffer:
+                        raise FramingLost(f"a frame stopped after {len(self._buffer)} bytes")
+                    return None
+
+    def discard_until_quiet(self, quiet_s: float, limit_s: float) -> bool:
+        """Read and throw away until nothing arrives for quiet_s. -> False if the input never went quiet in limit_s."""
+        self._buffer.clear()
+        end = time.monotonic() + limit_s
+        while time.monotonic() < end:
+            self._stream.timeout = quiet_s
+            if not self._stream.read(max(1, getattr(self._stream, "in_waiting", 0))):
+                return True
+        return False
+
+    def discard_input(self) -> None:
+        self._buffer.clear()
+        reset = getattr(self._stream, "reset_input_buffer", None)
+        if reset:
+            reset()