oep-client-python 0.0.8__tar.gz → 0.0.10__tar.gz

{oep_client_python-0.0.8 → oep_client_python-0.0.10}/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.0.10
+- (EN) Captures' times are ns on the probe's one clock with an uncertainty (oep-if-capture): `Segment.start_ns` / `start_uncertainty_ns` replace `start_us` (a segment is 33 bytes), the triggered event carries `trigger_ns`, and `Config.rate_measured` / `rate_ppm` say how sure the rate is. Analog captures: `AnalogCapture` (raw `values()`, the probe's `millivolts()`, `calibration()` - factory data and Vrefint, raw), with the answer read per channel (`zero`, `scale_nv`, `skew_ns`, `frontend`) and `reference`; `configure(frontends=)`. `CaptureGroup` binds tracks, starts them together with one trigger, and gives the group's `start_ns` and `trigger_ns`. The fake has them all (p4-x035: an analog on the ADC1 and a group), and describes a `chip`.
+- (JA) キャプチャの時刻は、probe の 1 本の時計の ns と不確かさになった（oep-if-capture）: `start_us` は `Segment.start_ns` / `start_uncertainty_ns` になり（区画は 33 byte）、出来事 triggered は `trigger_ns` を持ち、`Config.rate_measured` / `rate_ppm` がレートの確かさを示す。アナログ: `AnalogCapture`（生の `values()`、probe の 1 次式の `millivolts()`、`calibration()`: 出荷時の値と Vrefint を生のまま）。答えはチャネルごとに読む（`zero`、`scale_nv`、`skew_ns`、`frontend`）、`reference` も。`configure(frontends=)`。`CaptureGroup` はトラックを束ね、1 つのトリガで一緒に始め、組の `start_ns` と `trigger_ns` を返す。偽の probe はこれらをすべて持つ（p4-x035: ADC1 のアナログと組）。core の describe の `chip` も出す。
+
+## 0.0.9
+- (EN) The fake probe has `oep.fixture.capture` (logic, `fake_capture`): one-shot, repeat (a ring and release), streaming (data pushes), level / edge triggers with a pretrigger, events, and a known waveform (sample i = the counter i, channel k = its bit k) in the profile's layout (P4: w 1-16; classic ESP32: w 8). A capture shares pins with other interfaces (it only listens). `Endpoint.pushes()` gives the frames the probe sends by itself; fake_serve sends them on the pty and TCP. `--capture-slipped` sets flags bit2 on every segment.
+- (JA) 偽の probe に `oep.fixture.capture`（ロジック、`fake_capture`）を入れた: ワンショット、リピート（リングと release）、ストリーミング（データの push）、レベル / エッジのトリガとプリトリガ、出来事。取れる波形は決まっている（サンプル i = カウンタ i、チャネル k = そのビット k）。layout は profile のもの（P4: w 1〜16、classic ESP32: w 8）。capture はほかのインターフェースとピンを共有できる（聞くだけ）。`Endpoint.pushes()` が probe の送り出すフレームを返し、fake_serve は pty と TCP に流す。`--capture-slipped` は区画すべてに flags bit2 を立てる。
+- (EN) The fake: an attach without pins joins the wire's one live connection, also on a wire whose pins the host chooses (oep-if-debug §1).
+- (JA) 偽の probe: pins の無い attach は、その線の生きている接続が 1 つならそれに乗る。host がピンを選ぶ線でも同じ（oep-if-debug §1）。
+
 ## 0.0.8
 - (EN) Wires whose pins the host chooses (oep-if-debug §1, role_channels): the fake takes any allowed free pair, skips the pairs whose pins something holds in a count-0 scan, holds a live connection's pins against plans, and has a profile for it (`rp2350-pins`). `Wire.scan()` goes through the whole list (at most 255 pairs a request; count 0 continues with the new skip TLV until tried = 0).
 - (JA) host がピンを選ぶ wire（oep-if-debug §1、role_channels）: 偽の probe は、許された空いている組ならどれでも受け、count = 0 の scan では何かが持っているピンの組を飛ばし、生きている接続のピンを plan から守る。そのための profile（`rp2350-pins`）を足した。`Wire.scan()` は並びを最後まで回る（1 回 255 組まで。count = 0 は新しい skip の TLV で tried = 0 まで続ける）。

{oep_client_python-0.0.8 → oep_client_python-0.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oep-client-python
-Version: 0.0.8
+Version: 0.0.10
 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
@@ -107,8 +107,19 @@ A run on hardware: ArduinoCore-CH32's `tests/manual/oep_smoke/` (`oep_smoke.py`,
 
 `endpoint.Endpoint` is a fake probe that answers as oep-spec says; ch32rv, this client and the probe firmware are checked
 against it (when the spec changes, this is brought in line before the firmware). `fake` holds example declarations (profiles
-`p4-x035`, `esp32-v003`, `p4-bench` = a made-up jig with three slots and two seats), `fake_serial` the byte side of a serial
-port (COBS candidates, raw bytes and binds, held during a session and resumed after it).
+`p4-x035`, `esp32-v003`, `p4-bench` = a made-up jig with three slots and two seats, `rp2350-pins` = a wire whose pins the host
+chooses), `fake_serial` the byte side of a serial port (COBS candidates, raw bytes and binds, held during a session and
+resumed after it).
+
+`fake_capture` is `oep.fixture.capture` (logic): one-shot, repeat (segments with the clock at the actual rate, a ring,
+release) and streaming (data pushes while subscribed), level / edge triggers with a pretrigger, and events. What it
+captures is known: sample i is the counter i, channel k its bit k (a square wave of period 2^(k+1) samples), in the layout
+the profile allows (`p4-x035`: w 1-16 as the P4's PARLIO, three channels in w 4; `esp32-v003`: w 8 as the classic ESP32's
+sampler, one-shot only). A capture only listens, so it may be planned on pins other interfaces hold. `p4-x035` also has
+`oep.fixture.analog` (4 channels of the P4's ADC1 on GPIO16-23: an even channel k a square wave, an odd one a sine, of
+period 64 (k // 2 + 1) samples, 12-bit values in 16-bit slots; ESP32-style frontends; a made-up two-point calibration and a
+Vrefint) and `oep.fixture.capture-group` binding the logic and the analog: started together, the analog 5 us later
+(+-2 us), the trigger of one marked on both. Times are ns on the probe's one clock.
 
 Other programs' tests run `fake_serve` as a child process:
 
@@ -122,4 +133,5 @@ The pty is a serial port (the host opens it with TIOCEXCL); `--tcp PORT` is `--f
 `--framing length` (the vendor bulk / TCP form). Faults: `--drop N` (the N-th answer is not sent, once; the request did run,
 so a resend gets the remembered result), `--noise TEXT` (noise before every answer), `--corrupt N` (the N-th answer's CRC
 broken once). `--uart-plan` / `--uart-rx` give the first fixture UART a plan and RX bytes, `--run-hook` a host's own model of
-riscv-dm run. The rest: `--help`.
+riscv-dm run, `--capture-slipped` flags bit2 on every capture segment. Events and data pushes go out on the pty and on TCP
+(both framings). The rest: `--help`.

{oep_client_python-0.0.8 → oep_client_python-0.0.10}/README.ja.md

@@ -80,8 +80,17 @@ oep config save <probe>                      # 再起動の後も残す（remove
 
 `endpoint.Endpoint` は oep-spec の規範どおりに答える偽の probe で、ch32rv・この client・probe の firmware を突き合わせる
 「動く spec」として使う（spec が変わったら、probe の firmware より先にここを合わせる）。`fake` は宣言の例（profile:
-`p4-x035`、`esp32-v003`、`p4-bench` = スロット 3 か所と席 2 つの架空の治具）、`fake_serial` はシリアルの口のバイトの側（COBS の
-候補、生のバイトと bind、セッション中の停止と再開）。
+`p4-x035`、`esp32-v003`、`p4-bench` = スロット 3 か所と席 2 つの架空の治具、`rp2350-pins` = host がピンを選ぶ wire）、`fake_serial` は
+シリアルの口のバイトの側（COBS の候補、生のバイトと bind、セッション中の停止と再開）。
+
+`fake_capture` は `oep.fixture.capture`（ロジック）: ワンショット、リピート（実際のレートで時計どおりに区画ができ、リング、release）、
+ストリーミング（購読している間のデータの push）、レベル / エッジのトリガとプリトリガ、出来事。取れるものは決まっている: サンプル i は
+カウンタの値 i で、チャネル k はそのビット k（周期 2^(k+1) サンプルの方形波）。layout は profile が許す形（`p4-x035`: P4 の
+PARLIO と同じ w 1〜16、3 本なら w 4。`esp32-v003`: classic ESP32 の sampler と同じ w 8、ワンショットだけ）。capture は聞くだけ
+なので、ほかのインターフェースが持つピンにも plan できる。`p4-x035` には `oep.fixture.analog`（P4 の ADC1 の 4 チャネル、GPIO16〜23。
+偶数のチャネル k は方形波、奇数は正弦波で、周期は 64 (k // 2 + 1) サンプル。16 ビットの枠に 12 ビットの値。ESP32 と同じ形の
+frontend、作り物の 2 点の較正と Vrefint）と、ロジックとアナログを束ねる `oep.fixture.capture-group` もある（一緒に始まり、
+アナログは 5 µs 遅れ（±2 µs）、片方のトリガが両方に印される）。時刻は probe の 1 本の時計の ns。
 
 外のプログラムの試験には `fake_serve` を子プロセスで使う:
 
@@ -93,6 +102,7 @@ uv run python -m oep_client.fake_serve --pty --profile p4-bench --slot x035 --bi
 
 pty がシリアルの口（host が TIOCEXCL を掛けて開く）、`--tcp PORT` は `--framing cobs`（シリアルの口）か `--framing length`
 （vendor bulk / TCP の形）。故障の注入は `--drop N`（N 番目の答えを 1 回出さない。要求は実行済みなので送り直しは覚えた答えを
-受ける）、`--noise TEXT`（答えの前に雑音）、`--corrupt N`（N 番目の答えの CRC を 1 回壊す）。ほかは `--help`。
+受ける）、`--noise TEXT`（答えの前に雑音）、`--corrupt N`（N 番目の答えの CRC を 1 回壊す）。`--capture-slipped` は capture の
+区画すべてに flags bit2 を立てる。出来事とデータの push は pty にも TCP（両方の framing）にも出る。ほかは `--help`。
 
 v0 の client（`oep_client.v0`）は 2026-09-26 に消した（git の履歴に残る）。v0 を話す probe はもう無い。

{oep_client_python-0.0.8 → oep_client_python-0.0.10}/README.md

@@ -85,8 +85,19 @@ A run on hardware: ArduinoCore-CH32's `tests/manual/oep_smoke/` (`oep_smoke.py`,
 
 `endpoint.Endpoint` is a fake probe that answers as oep-spec says; ch32rv, this client and the probe firmware are checked
 against it (when the spec changes, this is brought in line before the firmware). `fake` holds example declarations (profiles
-`p4-x035`, `esp32-v003`, `p4-bench` = a made-up jig with three slots and two seats), `fake_serial` the byte side of a serial
-port (COBS candidates, raw bytes and binds, held during a session and resumed after it).
+`p4-x035`, `esp32-v003`, `p4-bench` = a made-up jig with three slots and two seats, `rp2350-pins` = a wire whose pins the host
+chooses), `fake_serial` the byte side of a serial port (COBS candidates, raw bytes and binds, held during a session and
+resumed after it).
+
+`fake_capture` is `oep.fixture.capture` (logic): one-shot, repeat (segments with the clock at the actual rate, a ring,
+release) and streaming (data pushes while subscribed), level / edge triggers with a pretrigger, and events. What it
+captures is known: sample i is the counter i, channel k its bit k (a square wave of period 2^(k+1) samples), in the layout
+the profile allows (`p4-x035`: w 1-16 as the P4's PARLIO, three channels in w 4; `esp32-v003`: w 8 as the classic ESP32's
+sampler, one-shot only). A capture only listens, so it may be planned on pins other interfaces hold. `p4-x035` also has
+`oep.fixture.analog` (4 channels of the P4's ADC1 on GPIO16-23: an even channel k a square wave, an odd one a sine, of
+period 64 (k // 2 + 1) samples, 12-bit values in 16-bit slots; ESP32-style frontends; a made-up two-point calibration and a
+Vrefint) and `oep.fixture.capture-group` binding the logic and the analog: started together, the analog 5 us later
+(+-2 us), the trigger of one marked on both. Times are ns on the probe's one clock.
 
 Other programs' tests run `fake_serve` as a child process:
 
@@ -100,4 +111,5 @@ The pty is a serial port (the host opens it with TIOCEXCL); `--tcp PORT` is `--f
 `--framing length` (the vendor bulk / TCP form). Faults: `--drop N` (the N-th answer is not sent, once; the request did run,
 so a resend gets the remembered result), `--noise TEXT` (noise before every answer), `--corrupt N` (the N-th answer's CRC
 broken once). `--uart-plan` / `--uart-rx` give the first fixture UART a plan and RX bytes, `--run-hook` a host's own model of
-riscv-dm run. The rest: `--help`.
+riscv-dm run, `--capture-slipped` flags bit2 on every capture segment. Events and data pushes go out on the pty and on TCP
+(both framings). The rest: `--help`.

{oep_client_python-0.0.8 → oep_client_python-0.0.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oep-client-python"
-version = "0.0.8"
+version = "0.0.10"
 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.8 → oep_client_python-0.0.10}/src/oep_client/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.0.8"
+__version__ = "0.0.10"

{oep_client_python-0.0.8 → oep_client_python-0.0.10}/src/oep_client/capture.py

@@ -1,5 +1,9 @@
-"""oep.fixture.capture / oep.fixture.analog revision 1 (oep-spec docs/oep-if-capture.ja.md: §1 layouts, §2 segments,
-§3 operations). Numbers from `registry`.
+"""oep.fixture.capture / oep.fixture.analog / oep.fixture.capture-group revision 1 (oep-spec docs/oep-if-capture.ja.md:
+§1 layouts, §2 segments, §3 operations, §3.8 calibration, §4 groups). Numbers from `registry`.
+
+Times are the probe's one clock (ns since its boot, comparable within one boot_id): estimates with an uncertainty, the
+probe's known corrections applied. Analog values are always raw; the probe's 1st-order scale, its calibration data and
+its reference are for the host to choose from.
 
 configure: a TLV the probe cannot honour is refused (rejected unsupported, 0x0B, payload = the tag) when the host marked
 it critical, and otherwise ignored and listed in the answer's ignored TLV (0x7F, oep-core §2.3)."""
@@ -17,12 +21,17 @@ from .frames import FramingLost
 from .core import Interface, confirm
 
 _CAP = reg.FIXTURE_CAPTURE
+_ANA = reg.FIXTURE_ANALOG
+_GRP = reg.FIXTURE_CAPTURE_GROUP
 # configure TLVs; bit 7 of a tag = critical (the probe must reject what it cannot do)
 MODE, RATE, SAMPLES, SEGMENTS, TRIGGER, PRETRIGGER, FRONTEND = (
     _CAP.tlv["configure"][k] for k in ("mode", "rate", "samples", "segments", "trigger", "pretrigger", "frontend"))
-ACTUAL_RATE, LAYOUT, ACTUAL_SAMPLES, ACTUAL_SEGMENTS, TIMING, SCALE, BLOCKING = (
-    _CAP.tlv["configure_answer"][k] for k in ("actual_rate", "layout", "actual_samples", "actual_segments", "timing",
-                                              "scale", "blocking_ms"))
+ACTUAL_RATE, LAYOUT, ACTUAL_SAMPLES, ACTUAL_SEGMENTS, TIMING, SCALE, BLOCKING, SKEW, FRONTEND_USED, REFERENCE, \
+    RATE_ACCURACY = (_ANA.tlv["configure_answer"][k] for k in (
+        "actual_rate", "layout", "actual_samples", "actual_segments", "timing", "scale", "blocking_ms", "skew",
+        "frontend_used", "reference", "rate_accuracy"))
+FACTORY, VREFINT = _ANA.tlv["calibration_answer"]["factory"], _ANA.tlv["calibration_answer"]["vrefint"]
+REFERENCE_SOURCE = {v: k for k, v in _ANA.enum["reference_source"].items()}
 IGNORED = m.TAG_IGNORED
 CRITICAL = m.TAG_CRITICAL
 ONE_SHOT, REPEAT, STREAMING = (_CAP.enum["mode"][k] for k in ("one_shot", "repeat", "streaming"))
@@ -37,7 +46,8 @@ def tlvs(payload: bytes) -> list[tuple[int, bytes]]:
     return m.split_tlvs(payload)
 
 
-SEGMENT_BYTES = 29   # serial u32, position u64, samples u32, start_us u64, trigger_index u32, flags u8
+SEGMENT_BYTES = 33   # serial u32, position u64, samples u32, start_ns u64, start_uncertainty_ns u32, trigger_index u32,
+                     # flags u8
 
 
 @dataclass
@@ -45,7 +55,8 @@ class Segment:
     serial: int
     position: int
     samples: int
-    start_us: int
+    start_ns: int                    # the first sample's time on the probe's clock (an estimate)
+    start_uncertainty_ns: int        # +- of start_ns (a guide, not a promise)
     trigger_index: int | None
     flags: int
 
@@ -56,8 +67,8 @@ class Segment:
 
     @classmethod
     def unpack(cls, b: bytes) -> "Segment":
-        serial, position, samples, start_us, trig, flags = struct.unpack_from("<IQIQIB", b)
-        return cls(serial, position, samples, start_us, None if trig == 0xFFFFFFFF else trig, flags)
+        serial, position, samples, start_ns, uncertainty, trig, flags = struct.unpack_from("<IQIQIIB", b)
+        return cls(serial, position, samples, start_ns, uncertainty, None if trig == 0xFFFFFFFF else trig, flags)
 
 
 @dataclass
@@ -74,9 +85,13 @@ class Config:
     segments: int = 0
     jitter_kind: int = 0
     jitter_ns: int = 0
-    skew_ns: list[int] = field(default_factory=list)
-    zero: int = 0
-    scale_nv: int = 0
+    rate_measured: bool = False                  # rate_accuracy: the rate was measured (else computed from a divider)
+    rate_ppm: int = 0                            # its uncertainty (0: unknown)
+    skew_ns: dict[int, int] = field(default_factory=dict)      # analog, per channel (role)
+    zero: dict[int, int] = field(default_factory=dict)         # analog, per channel
+    scale_nv: dict[int, int] = field(default_factory=dict)     # analog, nV per value, per channel
+    frontend: dict[int, int] = field(default_factory=dict)     # analog: the frontend each channel took
+    reference: tuple[str, int, bool] | None = None             # analog: (source, mV, measured)
     blocking_ms: int = 0
     ignored: list[int] = field(default_factory=list)
 
@@ -140,9 +155,19 @@ def _config(payload: bytes, analog: bool) -> Config:
             c.segments = struct.unpack("<I", v)[0]
         elif tag == TIMING:
             c.jitter_kind, c.jitter_ns = v[0], struct.unpack_from("<I", v, 1)[0]
-            c.skew_ns = [struct.unpack_from("<I", v, 5 + 4 * i)[0] for i in range((len(v) - 5) // 4)]
-        elif tag == SCALE:
-            c.zero, c.scale_nv = struct.unpack("<II", v)
+        elif tag == RATE_ACCURACY:
+            c.rate_measured, c.rate_ppm = v[0] == 1, struct.unpack_from("<I", v, 1)[0]
+        elif tag == SCALE and analog:
+            role, zero, scale = struct.unpack("<BII", v)
+            c.zero[role], c.scale_nv[role] = zero, scale
+        elif tag == SKEW and analog:
+            role, ns = struct.unpack("<BI", v)
+            c.skew_ns[role] = ns
+        elif tag == FRONTEND_USED and analog:
+            c.frontend[v[0]] = v[1]
+        elif tag == REFERENCE and analog:
+            source, mv, how = struct.unpack("<BIB", v)
+            c.reference = (REFERENCE_SOURCE.get(source, str(source)), mv, how == 1)
         elif tag == BLOCKING:
             c.blocking_ms = struct.unpack("<I", v)[0]
         elif tag == IGNORED:
@@ -165,7 +190,7 @@ class LogicCapture(Interface):
 
     def configure(self, *, rate: int, mode: int = ONE_SHOT, samples: int | None = None, segments: int | None = None,
                   trigger: tuple[int, int, int] | None = None, pretrigger: int | None = None, query: bool = False,
-                  critical: set[int] = frozenset()) -> Config:
+                  critical: set[int] = frozenset(), frontends: dict[int, int] | None = None) -> Config:
         """-> the probe's actual values (Config.ignored: tags the probe ignored). `critical`: tags the probe must honour
         or reject (host.Unsupported, .tag = the one it cannot)."""
         def tlv(tag: int, value: bytes) -> bytes:
@@ -179,6 +204,8 @@ class LogicCapture(Interface):
             body += tlv(TRIGGER, struct.pack("<BBH", *trigger))
         if pretrigger is not None:
             body += tlv(PRETRIGGER, struct.pack("<I", pretrigger))
+        for role, fe in sorted((frontends or {}).items()):   # analog: the input range per channel (describe frontend)
+            body += tlv(FRONTEND, bytes([role, fe]))
         # query is its own operation: the lock is decided per operation, before the payload is looked at
         op = self.QUERY_OP if query else self.CONFIGURE
         c = _config(self._call(op, body, locked=not query).payload, self.ANALOG)
@@ -331,7 +358,8 @@ class LogicCapture(Interface):
         """The segment's bytes; every Host.on_capture callback gets them as a CaptureRecord (a run recorder, e.g.
         pytest-embedded-wireskein, without this package knowing it)."""
         c = self.config
-        data = self.read(segment.position, (segment.samples * c.width + 7) // 8)
+        n = (segment.samples * c.width + 7) // 8 if c.width else segment.samples * len(c.order) * c.slot // 8
+        data = self.read(segment.position, n)
         if self.host.on_capture:
             record = CaptureRecord(self.fn, self.name, c, segment, data, self.armed_s, time.monotonic())
             for callback in list(self.host.on_capture):
@@ -365,3 +393,105 @@ class LogicCapture(Interface):
             z.writestr("version", "2")
             z.writestr("metadata", "\n".join(meta))
             z.writestr("logic-1-1", out)
+
+
+@dataclass
+class Calibration:
+    """What the probe knows for turning an analog value into a voltage (oep-if-capture §3.8), raw: the probe applies
+    none of it. factory: (frontend or None, scheme, raw bytes) - scheme names how to read raw; vrefint: (raw, ns), the
+    internal reference measured after the last start."""
+    factory: list[tuple[int | None, str, bytes]] = field(default_factory=list)
+    vrefint: tuple[int, int] | None = None
+
+
+class AnalogCapture(LogicCapture):
+    """Basic analog capture (oep.fixture.analog): the same operations as the logic one; values are raw (§1.2)."""
+    NAME = "oep.fixture.analog"
+    ANALOG = True
+    CALIBRATION = _ANA.op["calibration"]
+
+    def values(self, data: bytes, k: int, samples: int | None = None) -> list[int]:
+        """Channel k's raw values (§1.2: slot s bits little endian, the value in bits o .. o+b-1, frames in `order`)."""
+        c = self.config
+        width = c.slot // 8
+        frame = width * len(c.order)
+        n = samples if samples is not None else len(data) // frame
+        m_ = c.order.index(k)
+        mask = (1 << c.bits) - 1
+        return [(int.from_bytes(data[i * frame + m_ * width:i * frame + (m_ + 1) * width], "little") >> c.offset) & mask
+                for i in range(n)]
+
+    def millivolts(self, k: int, value: int) -> float:
+        """The probe's own 1st-order reading of a raw value of channel k, (value - zero) x scale_nv (a nominal
+        reference: see reference and calibration() for others)."""
+        c = self.config
+        return (value - c.zero.get(k, 0)) * c.scale_nv.get(k, 0) / 1_000_000
+
+    def calibration(self) -> Calibration:
+        out = Calibration()
+        for tag, v in tlvs(self._call(self.CALIBRATION, locked=False).payload):
+            if tag == FACTORY:
+                n = v[1]
+                out.factory.append((None if v[0] == 0xFF else v[0], v[2:2 + n].decode("utf-8", "replace"), bytes(v[2 + n:])))
+            elif tag == VREFINT:
+                out.vrefint = struct.unpack("<IQ", v)
+        return out
+
+
+@dataclass
+class GroupStatus:
+    state: int
+    start_ns: int | None
+    trigger_ns: int | None
+    trigger_fn: int | None
+
+
+class CaptureGroup(Interface):
+    """oep.fixture.capture-group (§4): tracks (LogicCapture / AnalogCapture, each configured as usual) started together,
+    one of them the trigger. Each track is read as usual; a track's offset is its first segment's start_ns minus the
+    group's start_ns, and every track's segment marks the trigger's instant (trigger_index)."""
+    NAME = "oep.fixture.capture-group"
+    REVISION = 1
+    BIND, START, STOP, FORCE, STATUS = (_GRP.op[k] for k in ("bind", "start", "stop", "force", "status"))
+    TAG_TRIGGER_TRACK = _GRP.tlv["bind"]["trigger_track"]
+    EVENT_TRIGGERED, EVENT_STOPPED = _GRP.event["triggered"], _GRP.event["stopped"]
+    NO_TIME = 0xFFFFFFFFFFFFFFFF
+
+    def bind(self, tracks: list[LogicCapture], trigger: LogicCapture | None = None) -> None:
+        """Bind these (configured) tracks; [] unbinds. `trigger`: the track whose configure trigger starts them all."""
+        body = struct.pack(f"<B{len(tracks)}H", len(tracks), *(t.fn for t in tracks))
+        if trigger is not None:
+            body += m.tlv(self.TAG_TRIGGER_TRACK, struct.pack("<H", trigger.fn), critical=True)
+        self._call(self.BIND, body)
+
+    def start(self, tracks: list[LogicCapture] = ()) -> tuple[int, int]:
+        """-> (blocking_ms, the group's start_ns). `tracks`: whose armed_s to set (for records)."""
+        blocking, start_ns = m.Reader(self._call(self.START).payload).take("IQ")
+        now = time.monotonic()
+        for t in tracks:
+            t.armed_s = now
+        return blocking, start_ns
+
+    def stop(self) -> None:
+        self._call(self.STOP)
+
+    def force(self) -> None:
+        self._call(self.FORCE)
+
+    def status(self) -> GroupStatus:
+        state, start, trig, fn = m.Reader(self._call(self.STATUS, locked=False).payload).take("BQQH")
+        none = self.NO_TIME
+        return GroupStatus(state, None if start == none else start, None if trig == none else trig, fn or None)
+
+    def wait(self, timeout: float = 5.0) -> GroupStatus:
+        """Poll until every track is done (one-shot)."""
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            st = self.status()
+            if st.state == STATE["done"]:
+                return st
+            if st.state == STATE["error"]:
+                raise h.Failed(None, "the group's capture stopped with an error")
+            time.sleep(0.002)
+        raise TimeoutError("the group's capture did not finish")
+

{oep_client_python-0.0.8 → oep_client_python-0.0.10}/src/oep_client/endpoint.py

@@ -39,7 +39,7 @@ from collections import OrderedDict
 from dataclasses import dataclass, field
 from typing import Callable
 
-from . import catalog, fake, message as m, registry as reg
+from . import catalog, fake, fake_capture, message as m, registry as reg
 
 TOY_WRITE, TOY_READ = 0x01, 0x02
 OK, WAIT, LINE, FAULT, TIMEOUT, STATE = (reg.STATUS[k] for k in ("ok", "wait", "line", "fault", "timeout", "state"))
@@ -275,6 +275,11 @@ class Endpoint:
             first = self._role_pairs(fn)[0]
             self.targets[(fn, first)] = FakeTarget()
         self.target = next(iter(self.targets.values()), FakeTarget())
+        self.captures: dict[int, fake_capture.FakeCapture] = {
+            fn: self._capture_from(self.static[fn]) for fn, name in self.names.items()
+            if name in ("oep.fixture.capture", "oep.fixture.analog")}
+        self.groups: dict[int, fake_capture.FakeGroup] = {
+            fn: self._group_from(self.static[fn]) for fn, name in self.names.items() if name == "oep.fixture.capture-group"}
         self.mechanisms = set()
         for fn, name in self.names.items():
             if name == "oep.target.console":
@@ -302,6 +307,9 @@ class Endpoint:
         self.dropped = 0                     # requests a v0 endpoint dropped (role 0x81)
         self.requests: list[m.Request] = []
         self.subscribed: set[int] = set()
+        self.push_seq: dict[int, int] = {}              # fn -> the next event / data seq (core §11.2)
+        self.outbox: list[bytes] = []                   # events and data frames waiting to go out (pushes())
+        self.capture_slipped = False                    # every capture segment says flags bit2 (a pace that fell behind)
         self.plan: set[tuple[int, int, int]] = set()   # (fn, role, channel), from plan_apply and the config
         self.plan_from_config: set[int] = set()        # fns whose plan came from the config (not a session's)
         self.resend: OrderedDict[int, tuple[int, int, int, bytes | None]] = OrderedDict()
@@ -340,6 +348,155 @@ class Endpoint:
     def target_id(self, value: int | None) -> None:
         self.target.target_id = value
 
+    @staticmethod
+    def _capture_from(tlvs: list[bytes]) -> fake_capture.FakeCapture:
+        """A capture as its describe declares it (modes, the w allowed, the rate range, max_read, the ring)."""
+        d = reg.FIXTURE_CAPTURE.tlv["describe"]
+        modes, widths, lo, hi, ring, most, fronts = set(), {8}, 1, 1_000_000, 1, 1024, {}
+        for t in tlvs:
+            tag, v = t[0], t[2:2 + t[1]]
+            if tag == d["frontend"]:                               # analog: frontend min_mv max_mv attenuation_mdb
+                fe, lo_mv, hi_mv, mdb = struct.unpack("<BiiI", v)
+                fronts[fe] = (lo_mv, hi_mv, mdb)
+            elif tag == d["mode"]:
+                modes.add(v[0])
+            elif tag == d["channels"]:
+                widths = {1 << i for i in range(6) if v[1] >> i & 1}
+            elif tag == catalog.MIN_CLOCK_HZ:
+                lo = struct.unpack("<I", v)[0]
+            elif tag == catalog.MAX_CLOCK_HZ:
+                hi = struct.unpack("<I", v)[0]
+            elif tag == d["segment_ring"]:
+                ring = struct.unpack("<H", v)[0]
+            elif tag == d["max_read"]:
+                most = struct.unpack("<I", v)[0]
+        return fake_capture.FakeCapture(modes or {fake_capture.MODE["one_shot"]}, widths, lo, hi, ring, most, fronts)
+
+    @staticmethod
+    def _group_from(tlvs: list[bytes]) -> fake_capture.FakeGroup:
+        d = reg.FIXTURE_CAPTURE_GROUP.tlv["describe"]
+        tracks, most, budgets = [], 1, []
+        for t in tlvs:
+            tag, v = t[0], t[2:2 + t[1]]
+            if tag == d["tracks"]:
+                tracks = list(struct.unpack(f"<{len(v) // 2}H", v))
+            elif tag == d["max_tracks"]:
+                most = v[0]
+            elif tag == d["budget"]:
+                budgets.append((struct.unpack_from("<I", v)[0], list(struct.unpack_from(f"<{(len(v) - 4) // 2}H", v, 4))))
+        return fake_capture.FakeGroup(tracks, most, budgets)
+
+    def _next_seq(self, fn: int) -> int:
+        seq = self.push_seq.get(fn, 0)
+        self.push_seq[fn] = (seq + 1) & 0xFFFF
+        return seq
+
+    def _events(self, fn: int, events: list[bytes]) -> None:
+        """Events (kind(u8) payload) of `fn` to go out while it is subscribed; unsubscribed, they are not sent."""
+        for e in events:
+            if fn in self.subscribed:
+                self.outbox.append(bytes([m.ROLE_EVENT]) + struct.pack("<HH", fn, self._next_seq(fn)) + e)
+
+    def pushes(self) -> list[bytes]:
+        """The frames the probe sends by itself now (core §11): events, and a streaming capture's data. A serving loop
+        frames and sends them; a test takes them from here."""
+        self.tick()
+        for fn, cap in self.captures.items():
+            if fn in self.subscribed:
+                self.outbox += cap.pushes(fn, lambda fn=fn: self._next_seq(fn), self.probe.max_frame)
+        out, self.outbox = self.outbox, []
+        return out
+
+    def _capture(self, fn: int, op: int, t: Take) -> tuple[int, int, bytes]:
+        cap, O = self.captures[fn], fake_capture.OP
+        self._events(fn, cap.tick(self.now()))                     # what the clock captured up to this request
+        roles = sorted(a[1] for a in self.plan if a[0] == fn)
+        budget = self.probe.max_frame - m.RESULT_HEADER
+        try:
+            if op in (O["configure"], O["query"]):
+                rest = t.data[t.at:]
+                analog = self.names[fn] == "oep.fixture.analog"
+                known = set(fake_capture.TLV.values()) - (set() if analog else {fake_capture.TLV["frontend"]})
+                got, ignored = t.tail(known)
+                # the frontend TLV comes once per channel: read them all
+                fronts = [tuple(v[:2]) for tag, v in m.split_tlvs(rest) if tag & 0x7F == fake_capture.TLV["frontend"]] \
+                    if analog else []
+                settled = cap.settle(got, t.critical, len(roles), fronts)
+                if op == O["configure"]:
+                    cap.apply(settled)
+                    cap.slipped = self.capture_slipped
+                return self._answer(cap.answer(settled), ignored)
+            if op in (O["start"], O["stop"], O["force"]) and cap.group is not None:
+                raise Reject(m.UNAVAILABLE)                        # bound: the group starts and stops it
+            if op == O["start"]:
+                t.tail()
+                self._events(fn, cap.start(self.now()))
+                return m.COMPLETED, m.SUCCESS, struct.pack("<I", 0)
+            if op == O["stop"]:
+                t.tail()
+                self._events(fn, cap.stop())
+                return m.COMPLETED, m.SUCCESS, b""
+            if op == O["force"]:
+                t.tail()
+                return m.COMPLETED, m.SUCCESS, b""                  # nothing waits: a trigger is found at start
+            if op == O["status"]:
+                t.tail()
+                return m.COMPLETED, m.SUCCESS, cap.status()
+            if op == O["read"]:
+                position, most = t.take("QI")
+                return m.COMPLETED, m.SUCCESS, cap.read(position, most, budget)
+            if op == O["segments"]:
+                first = t.take("I")
+                t.tail()
+                return m.COMPLETED, m.SUCCESS, cap.segment_list(first, budget)
+            if op == O["release"]:
+                serial = t.take("I")
+                t.tail()
+                cap.release(serial, self.now())
+                return m.COMPLETED, m.SUCCESS, b""
+            if op == fake_capture.ANA.op["calibration"] and cap.analog:
+                t.tail()
+                return m.COMPLETED, m.SUCCESS, cap.calibration()
+        except fake_capture.Reject as e:
+            raise Reject(e.reason, e.payload)
+        return m.REJECTED, m.UNKNOWN_OPERATION, b""
+
+    def _group(self, fn: int, op: int, t: Take) -> tuple[int, int, bytes]:
+        grp, O = self.groups[fn], fake_capture.GRP.op
+        try:
+            if op == O["bind"]:
+                n = t.take("B")
+                fns = [t.take("H") for _ in range(n)]
+                got, ignored = t.tail({fake_capture.GRP.tlv["bind"]["trigger_track"]})
+                src = got.get(fake_capture.GRP.tlv["bind"]["trigger_track"])
+                grp.bind(self.captures, fns, struct.unpack("<H", src)[0] if src else 0)
+                return self._answer(b"", ignored)
+            if op == O["start"]:
+                t.tail()
+                per, own = grp.start(self.captures, self.now())
+                for track, events in per:
+                    self._events(track, events)
+                self._events(fn, own)
+                return m.COMPLETED, m.SUCCESS, struct.pack("<IQ", 0, grp.start_ns)
+            if op == O["stop"]:
+                t.tail()
+                per, own = grp.stop(self.captures)
+                for track, events in per:
+                    self._events(track, events)
+                self._events(fn, own)
+                return m.COMPLETED, m.SUCCESS, b""
+            if op == O["force"]:
+                t.tail()
+                return m.COMPLETED, m.SUCCESS, b""
+            if op == O["status"]:
+                t.tail()
+                for track in grp.tracks:
+                    self._events(track, self.captures[track].tick(self.now()))
+                return m.COMPLETED, m.SUCCESS, grp.status(self.captures)
+        except fake_capture.Reject as e:
+            raise Reject(e.reason, e.payload)
+        return m.REJECTED, m.UNKNOWN_OPERATION, b""
+
     def _role_pairs(self, fn: int) -> list[tuple[int, int]]:
         """A role_channels wire's pairs in the count = 0 order (oep-if-debug §1): swdio ascending, then swclk."""
         roles = self.pin_roles[fn]
@@ -361,7 +518,7 @@ class Endpoint:
     def _held(self, fn: int | None = None, pair: tuple[int, int] | None = None) -> set[int]:
         """Channels something holds (core §8.1): the plan, the slots' pairs, the live connections' pairs - except
         wire `fn`'s own connection on `pair` (attaching there again, or scanning through it)."""
-        held = {a[2] for a in self.plan}
+        held = {a[2] for a in self.plan if a[0] not in self.captures}   # a capture only listens
         held |= {p for s in self.slots.values() for p in s.pair if p != 0xFFFF and not (s.wire_fn == fn and s.pair == pair)}
         held |= {p for c in self.conns.values() for p in c.pair if p != 0xFFFF and not (c.fn == fn and c.pair == pair)}
         return held
@@ -613,6 +770,7 @@ class Endpoint:
             if fn != 0 and fn not in self.names:
                 return m.REJECTED, m.UNAVAILABLE, b""
             self.subscribed.add(fn)
+            self.push_seq[fn] = 0                                  # seq from 0 at every subscribe (core §11.2)
             return m.COMPLETED, m.SUCCESS, b""
         if op == m.OP_UNSUBSCRIBE:
             fn = t.take("H")
@@ -644,14 +802,24 @@ class Endpoint:
     def _check_plan(self, got: list[tuple[int, int, int]]) -> None:
         """plan_apply's all-or-nothing check: the roles each fn has, and no pin another fn (or a slot) holds."""
         named = {fn for fn, _, _ in got}
-        kept = {a for a in self.plan if a[0] not in named}
+        # a capture only listens: it shares pins with anything, and nothing is kept from a pin by it (core §8.1)
+        kept = {a for a in self.plan if a[0] not in named and a[0] not in self.captures}
         slot_pins = {p for s in self.slots.values() for p in s.pair if p != 0xFFFF}
         slot_pins |= {p for c in self.conns.values() for p in c.pair if p != 0xFFFF}   # a live connection's pins too
         for fn, role, ch in got:
+            if fn in self.captures:
+                if role not in self._declared_roles(fn, ch):
+                    raise Reject(m.UNAVAILABLE)
+                continue
             roles = {"oep.fixture.gpio": {1}, "oep.fixture.uart": {1, 2}}.get(self.names.get(fn, ""), set())
             if role not in roles or any(k[2] == ch for k in kept) or ch in slot_pins:
                 raise Reject(m.UNAVAILABLE)
 
+    def _declared_roles(self, fn: int, channel: int) -> set[int]:
+        """The roles fn's describe offers on `channel` (role_channels)."""
+        return {t[2] for t in self.static[fn] if t[0] == catalog.ROLE_CHANNELS
+                and channel in catalog.bitmap_to_channels(struct.unpack_from("<H", t, 3)[0], t[5:2 + t[1]])}
+
     def _drop_plan(self, fn: int) -> None:
         for a in [a for a in self.plan if a[0] == fn]:
             self.gpio_modes.pop(a[2], None)
@@ -787,8 +955,11 @@ class Endpoint:
             if not self._allows(fn, pair) or set(pair) & self._held(fn, pair):
                 raise Reject(m.UNAVAILABLE)                        # not allowed here, or its pins are held (§8.1)
             return pair
+        live = [c.pair for c in self.conns.values() if c.fn == fn]
+        if len(live) == 1:
+            return live[0]                                         # no pins: the wire's one live connection
         allowed = self._allowed_pairs(fn)
-        if len(allowed) != 1:
+        if live or len(allowed) != 1:
             raise Reject(m.UNAVAILABLE)                            # the host chooses among several
         return allowed[0]
 
@@ -1399,9 +1570,11 @@ class Endpoint:
                         self.flows[(port, key)] = Flow(sid, 0)
 
     def tick(self) -> None:
-        """Time passes: the lease, at-boot retries, mixed lines closed by quiet."""
+        """Time passes: the lease, at-boot retries, mixed lines closed by quiet, the captures."""
         self._lapse()
         now = self.now()
+        for fn, cap in self.captures.items():
+            self._events(fn, cap.tick(now))
         for n, s in self.slots.items():
             rt = self.slot_rt[n]
             if (s.attach == SLOT_ATTACH["at_boot"] and s.retry_s and not rt.evicted
@@ -1549,4 +1722,5 @@ class Endpoint:
 
 SIMS = {"oep.wire.rvswd": "wire", "oep.wire.swio": "wire", "oep.target.riscv-dm": "dm",
         "oep.target.console": "console", "oep.fixture.gpio": "gpio", "oep.fixture.uart": "uart",
-        "oep.probe.config": "config_op"}
+        "oep.probe.config": "config_op", "oep.fixture.capture": "capture", "oep.fixture.analog": "capture",
+        "oep.fixture.capture-group": "group"}