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

oep_client/v1/capture.py

@@ -0,0 +1,365 @@
+"""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`.
+
+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)."""
+
+from __future__ import annotations
+
+import struct
+import time
+import zipfile
+from dataclasses import dataclass, field
+from fractions import Fraction
+
+from . import cobs, host as h, message as m, registry as reg
+from .frames import FramingLost
+from .core import Interface, confirm
+
+_CAP = reg.FIXTURE_CAPTURE
+# 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"))
+IGNORED = m.TAG_IGNORED
+CRITICAL = m.TAG_CRITICAL
+ONE_SHOT, REPEAT, STREAMING = (_CAP.enum["mode"][k] for k in ("one_shot", "repeat", "streaming"))
+IMMEDIATE, LEVEL, EDGE, CROSS_UP, CROSS_DOWN = range(5)
+STATE = _CAP.enum["state"]
+SEGMENT_SLIPPED = _CAP.enum["segment_flag"]["slipped"]
+# events (oep-core §11, role 0x05)
+EVENT_SEGMENT, EVENT_STOPPED, EVENT_TRIGGERED = (_CAP.event[k] for k in ("segment", "stopped", "triggered"))
+
+
+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
+
+
+@dataclass
+class Segment:
+    serial: int
+    position: int
+    samples: int
+    start_us: int
+    trigger_index: int | None
+    flags: int
+
+    @property
+    def slipped(self) -> bool:
+        """flags bit2: the time base bent inside the segment (samples later than the timing answer, oep-if-capture §2)."""
+        return bool(self.flags & SEGMENT_SLIPPED)
+
+    @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)
+
+
+@dataclass
+class Config:
+    """What configure answered: the probe's actual values (logic-capture §5.3)."""
+    rate: Fraction = Fraction(0)
+    width: int = 0                               # logic: bits per sample (w)
+    positions: list[int] = field(default_factory=list)   # logic: bit of channel k within a sample
+    slot: int = 0                                # analog: s, o, b, order
+    offset: int = 0
+    bits: int = 0
+    order: list[int] = field(default_factory=list)
+    samples: int = 0
+    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
+    blocking_ms: int = 0
+    ignored: list[int] = field(default_factory=list)
+
+    @property
+    def bytes(self) -> int:
+        """Length of one segment in the stream (§3.0 rule 4)."""
+        if self.width:
+            return (self.samples * self.width + 7) // 8
+        return self.samples * len(self.order) * self.slot // 8
+
+
+@dataclass
+class CaptureRecord:
+    """One segment as it was read, for whoever records runs (Host.on_capture): the probe's own words - no pin names,
+    no target (the recorder's caller knows those). armed_s / read_s: time.monotonic() at start() and at the read."""
+    fn: int
+    name: str
+    config: Config
+    segment: Segment
+    data: bytes
+    armed_s: float | None
+    read_s: float
+
+
+@dataclass
+class Received:
+    """What stream() collected: the bytes in arrival order, where the stream skipped (probe-side drops) and lost frames."""
+    data: bytearray = field(default_factory=bytearray)
+    start: int | None = None                                   # stream position of data[0]
+    gaps: list[tuple[int, int]] = field(default_factory=list)  # (index in data where it skipped, bytes skipped)
+    seq_lost: int = 0                                          # push frames missing by seq
+    frames: int = 0
+
+
+def take_pushes(link, fn: int) -> list[tuple[int, int, bytes]]:
+    """Remove this fn's data pushes (role 0x06) from the link: [(seq, position, data)], oldest first."""
+    mine, rest = [], []
+    for f in link.pushes:
+        (mine if struct.unpack_from("<H", f, 1)[0] == fn else rest).append(f)
+    link.pushes.clear()
+    link.pushes.extend(rest)
+    # the core header is role fn seq; the capture's payload is position(u64) then data (standard position stream)
+    return [(struct.unpack_from("<H", f, 3)[0], struct.unpack_from("<Q", f, 5)[0], f[13:]) for f in mine]
+
+
+def _config(payload: bytes, analog: bool) -> Config:
+    c = Config()
+    for tag, v in tlvs(payload):
+        if tag == ACTUAL_RATE:
+            num, den = struct.unpack("<II", v)
+            c.rate = Fraction(num, den)
+        elif tag == LAYOUT and not analog:
+            c.width, n = v[0], v[1]
+            c.positions = list(v[2:2 + n])
+        elif tag == LAYOUT and analog:
+            c.slot, c.offset, c.bits, n = v[0], v[1], v[2], v[3]
+            c.order = list(v[4:4 + n])
+        elif tag == ACTUAL_SAMPLES:
+            c.samples = struct.unpack("<I", v)[0]
+        elif tag == ACTUAL_SEGMENTS:
+            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 == BLOCKING:
+            c.blocking_ms = struct.unpack("<I", v)[0]
+        elif tag == IGNORED:
+            c.ignored = list(v)
+    return c
+
+
+class LogicCapture(Interface):
+    """Basic logic capture. Channels are the plan's roles 0..C-1."""
+    NAME = "oep.fixture.capture"
+    REVISION = 1
+    ANALOG = False
+    CONFIGURE, START, STOP, FORCE, STATUS, READ, SEGMENTS, RELEASE, QUERY_OP = (
+        _CAP.op[k] for k in ("configure", "start", "stop", "force", "status", "read", "segments", "release", "query"))
+
+    def __init__(self, hst: h.Host, fn: int | None = None, name: str | None = None):
+        super().__init__(hst, name, fn=fn)
+        self.config: Config | None = None
+        self.armed_s: float | None = None     # time.monotonic() at the last start()
+
+    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:
+        """-> 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:
+            return bytes([tag | (CRITICAL if tag in critical else 0), len(value)]) + value
+        body = tlv(MODE, bytes([mode])) + tlv(RATE, struct.pack("<I", rate))
+        if samples is not None:
+            body += tlv(SAMPLES, struct.pack("<I", samples))
+        if segments is not None:
+            body += tlv(SEGMENTS, struct.pack("<I", segments))
+        if trigger is not None:
+            body += tlv(TRIGGER, struct.pack("<BBH", *trigger))
+        if pretrigger is not None:
+            body += tlv(PRETRIGGER, struct.pack("<I", pretrigger))
+        # 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)
+        if not query:
+            self.config = c
+        return c
+
+    def subscribe(self, min_bytes: int = 0, max_delay_ms: int = 0) -> None:
+        """Events, and in streaming the data pushes (oep-core §11): send when min_bytes are ready or max_delay_ms after the
+        first byte (0, 0: as soon as there is anything)."""
+        self.host.subscribe(self.fn, min_bytes, max_delay_ms)
+
+    def unsubscribe(self) -> None:
+        self.host.unsubscribe(self.fn)
+
+    def stream(self, link, *, seconds: float | None = None, nbytes: int | None = None,
+               into: Received | None = None, keepalive_s: float = 1.0) -> Received:
+        """Streaming: collect data pushes until `nbytes` have arrived or `seconds` have passed (at least one is needed).
+        A position that does not follow the previous push is a probe-side drop (a gap); a seq that skips is a lost frame.
+        The subscription ends with the lock, so the lock is kept alive every `keepalive_s` while collecting (a stream
+        longer than the lease otherwise stopped: 35 MB missing at the end of 10 s at 150 MHz with a 10 s lease)."""
+        if seconds is None and nbytes is None:
+            raise ValueError("stream() needs seconds or nbytes")
+        got = into or Received()
+        deadline = time.monotonic() + seconds if seconds is not None else None
+        kept = time.monotonic()
+        expect_seq = getattr(got, "_seq", None)
+        event_seqs = getattr(got, "_events", set())   # events share the fn's seq (they stay on the link for the caller)
+        while True:
+            for e in link.events:
+                if struct.unpack_from("<H", e, 1)[0] == self.fn:
+                    event_seqs.add(struct.unpack_from("<H", e, 3)[0])
+            for seq, position, data in take_pushes(link, self.fn):
+                while expect_seq is not None and expect_seq != seq:
+                    if expect_seq in event_seqs:
+                        event_seqs.discard(expect_seq)
+                    else:
+                        got.seq_lost += 1
+                    expect_seq = (expect_seq + 1) & 0xFFFF
+                expect_seq = (seq + 1) & 0xFFFF
+                if got.start is None:
+                    got.start = position
+                else:
+                    expected = got.start + len(got.data) + sum(n for _, n in got.gaps)   # u64 positions: no wrap
+                    skipped = position - expected
+                    if skipped:
+                        got.gaps.append((len(got.data), skipped))
+                got.data += data
+                got.frames += 1
+            got._seq, got._events = expect_seq, event_seqs
+            if keepalive_s and time.monotonic() - kept >= keepalive_s:
+                self.host.keepalive()
+                kept = time.monotonic()
+            if nbytes is not None and len(got.data) >= nbytes:
+                return got
+            if deadline is not None and time.monotonic() >= deadline:
+                return got
+            link.pump(0.02, until_one=True)
+
+    def finish(self, link, got: Received, timeout: float = 5.0) -> Received:
+        """Streaming, after stop(): collect the pushes still to come, up to the last byte captured (status's write
+        position), or until `timeout`."""
+        end = self.status()[2]
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if got.start is not None:
+                reached = got.start + len(got.data) + sum(n for _, n in got.gaps)
+                if reached == end:
+                    return got
+            self.stream(link, seconds=min(0.1, max(0.0, deadline - time.monotonic())), into=got)
+        return got
+
+    def start(self) -> int:
+        """-> blocking_ms (0: the probe keeps answering while it captures)."""
+        blocking = m.Reader(self._call(self.START).payload).u32()
+        self.armed_s = time.monotonic()
+        return blocking
+
+    def stop(self) -> None:
+        self._call(self.STOP)
+
+    def status(self) -> tuple[int, int, int, int]:
+        """-> state, segments done, write position, flags."""
+        return m.Reader(self._call(self.STATUS, locked=False).payload).take("BIQB")
+
+    def release(self, serial: int) -> None:
+        """Repeat: segments up to `serial` may be reused."""
+        self._call(self.RELEASE, struct.pack("<I", serial))
+
+    def segments(self, from_serial: int = 0) -> list[Segment]:
+        rd = m.Reader(self._call(self.SEGMENTS, struct.pack("<I", from_serial), locked=False).payload)
+        out = [Segment.unpack(rd.bytes(SEGMENT_BYTES)) for _ in range(rd.u8())]
+        rd.tail()
+        return out
+
+    def wait(self, timeout: float = 5.0) -> list[Segment]:
+        """Poll status until the one-shot is done (or failed). -> its segments."""
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            state = self.status()[0]
+            if state == STATE["done"]:
+                return self.segments()
+            if state == STATE["error"]:
+                raise h.Failed(None, "the capture stopped with an error")
+            if state not in STATE.values():
+                raise h.ProtocolError(f"capture state {state} is not one this client knows")
+            time.sleep(0.002)
+        raise TimeoutError("capture did not finish")
+
+    READ_TRIES = 4   # batches of reads sent again after the link's own repeat failed too
+    BATCH = 16   # frame-sized reads per pipeline; a keepalive between batches when a session is open
+
+    def read(self, position: int, length: int) -> bytes:
+        """Bytes [position, position+length) of the stream, pipelined in frame-sized reads.
+
+        The reads need no lock and go without the session id, so a repeat after a broken reply is simply run again
+        (reads are not deduplicated, oep-core §5.2). They do not extend the lease, though: a long read (64 KB over a
+        115200 bps UART probe takes seconds) sends a keepalive between batches, or the lease lapsed mid-read, the plan
+        went with it (core §9) and the capture read back nothing (2026-09-26, V003 jig)."""
+        chunk = max(1, confirm(self.host)["max_frame"] - 16)
+        offsets = list(range(0, length, chunk))
+        out = bytearray()
+        for at in range(0, len(offsets), self.BATCH):
+            if at and self.host.session is not None:
+                self.host.keepalive()
+            batch = offsets[at:at + self.BATCH]
+            for attempt in range(self.READ_TRIES):
+                reqs = [self.request(self.READ, struct.pack("<QI", position + off, min(chunk, length - off))) for off in batch]
+                try:
+                    replies = self.host.pipeline_calls(reqs, locked=False)
+                    break
+                except (cobs.CorruptFrame, TimeoutError, FramingLost):
+                    # the link sent the batch once more already; a read changes nothing, so the whole batch can go
+                    # again (the V003 jig's CP2102 dropped bytes twice in one 60 KB read, 2026-09-29)
+                    if attempt == self.READ_TRIES - 1:
+                        raise
+            for off, r in zip(batch, replies):
+                data = r.payload[9:]                      # after position(u64) flags(u8)
+                want = min(chunk, length - off)
+                while len(data) < want:                   # a short answer: read on from where it stopped
+                    more = self._call(self.READ, struct.pack("<QI", position + off + len(data), want - len(data)),
+                                      locked=False).payload[9:]
+                    if not more:
+                        raise h.ProtocolError(f"read at {position + off + len(data)} returned nothing")
+                    data += more
+                out += data
+        return bytes(out)
+
+    def read_segment(self, segment: Segment) -> bytes:
+        """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)
+        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):
+                callback(record)
+        return data
+
+    # ---- the §3.0 layout ---------------------------------------------------------------------------------
+    def channel(self, data: bytes, k: int, samples: int | None = None) -> list[int]:
+        """Channel k's values, one per sample (§3.0 rules 1-3)."""
+        c = self.config
+        n = samples if samples is not None else len(data) * 8 // c.width
+        bit0 = c.positions[k]
+        return [(data[(i * c.width + bit0) >> 3] >> ((i * c.width + bit0) & 7)) & 1 for i in range(n)]
+
+    def to_sr(self, path: str, data: bytes, samples: int, names: list[str] | None = None) -> None:
+        """A sigrok session file: one byte per sample, bit k = channel k (so up to 8 channels here)."""
+        c = self.config
+        n_ch = len(c.positions)
+        if n_ch > 8:
+            raise ValueError("to_sr writes one byte per sample; more than 8 channels need unitsize 2")
+        names = names or [f"D{k}" for k in range(n_ch)]
+        chans = [self.channel(data, k, samples) for k in range(n_ch)]
+        out = bytes(sum(chans[k][i] << k for k in range(n_ch)) for i in range(samples))
+        rate = c.rate.numerator // c.rate.denominator
+        meta = ["[global]", "sigrok version=0.5.2", "", "[device 1]", "capturefile=logic-1",
+                f"total probes={n_ch}", f"samplerate={rate} Hz", "total analog=0"]
+        meta += [f"probe{k + 1}={nm}" for k, nm in enumerate(names)] + ["unitsize=1", ""]
+        with zipfile.ZipFile(path, "w") as z:
+            z.writestr("version", "2")
+            z.writestr("metadata", "\n".join(meta))
+            z.writestr("logic-1-1", out)

oep_client/v1/catalog.py

@@ -0,0 +1,181 @@
+"""Draft wire forms for capability discovery by name (oep-spec docs/capability-declaration-model.ja.md).
+
+list request : flags(u8) first(u16) prefix_len(u8) prefix     flags bit0 = exact
+list result  : total(u16) count(u8) entries [TLV tail]         oep.core (fn 0) is the first entry
+list entry   : fn(u16) instance(u16) revision(u8) flags(u8) name_len(u8) name
+describe     : request fn(u16) first(u16); result more(u8) then TLV bytes (tag u8, len u8, value;
+               tag bit 7 = critical). more = 1: TLVs remain after this page, ask again from first + count
+(oep-spec oep-core §7.2; the entry revision decides the interface's payload shapes, §2.7)
+
+Common TLV tags 0x01..0x3F mean the same for every interface; 0x40..0x7F belong to the interface.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, field
+
+from .message import Reader, split_tlvs
+
+LIST_EXACT = 0x01
+
+# Common describe tags.
+ROLE_CHANNELS = 0x01     # role(u8) base(u16) bitmap(bytes): channels usable for that role
+MAX_CLOCK_HZ = 0x02      # u32
+MAX_LENGTH = 0x03        # u16
+MIN_CLOCK_HZ = 0x05      # u32
+FEATURES = 0x06          # u32, bits defined by the interface
+IMPLEMENTATION = 0x07    # u8: 0 unspecified, 1 software, 2 peripheral, 3 peripheral + DMA/PIO
+CHANNEL_GROUP = 0x08     # group(u8) then (role(u8), channel(u16)) repeated: a fixed pin set
+CRITICAL = 0x80
+INTERFACE_TAG_FIRST = 0x40
+
+IMPLEMENTATIONS = {0: "unspecified", 1: "software (bit-bang)", 2: "peripheral", 3: "peripheral + DMA/PIO"}
+
+
+# ---- list ----------------------------------------------------------------
+
+@dataclass(frozen=True)
+class ListEntry:
+    fn: int
+    instance: int
+    revision: int
+    flags: int
+    name: str
+
+
+def pack_list_request(prefix: str = "", exact: bool = False, first: int = 0) -> bytes:
+    raw = prefix.encode("ascii")
+    return struct.pack("<BHB", LIST_EXACT if exact else 0, first, len(raw)) + raw
+
+
+def unpack_list_request(payload: bytes) -> tuple[str, bool, int, bytes]:
+    """-> (prefix, exact, first, the request's TLV tail)."""
+    if len(payload) < 4:
+        raise ValueError("list request shorter than its fixed part")
+    flags, first, n = struct.unpack_from("<BHB", payload)
+    if len(payload) < 4 + n:
+        raise ValueError("list request: prefix length does not match")
+    return payload[4:4 + n].decode("ascii"), bool(flags & LIST_EXACT), first, payload[4 + n:]
+
+
+def pack_entry(e: ListEntry) -> bytes:
+    raw = e.name.encode("ascii")
+    return struct.pack("<HHBBB", e.fn, e.instance, e.revision, e.flags, len(raw)) + raw
+
+
+def pack_list_result(total: int, entries: list[ListEntry]) -> bytes:
+    return struct.pack("<HB", total, len(entries)) + b"".join(pack_entry(e) for e in entries)
+
+
+def unpack_list_result(payload: bytes) -> tuple[int, list[ListEntry]]:
+    """-> (total, this page's entries). What follows the counted entries is a §0 TLV tail: skipped."""
+    rd = Reader(payload)
+    total, count = rd.take("HB")
+    out = []
+    for _ in range(count):
+        fn, instance, revision, flags, n = rd.take("HHBBB")
+        out.append(ListEntry(fn, instance, revision, flags, rd.bytes(n).decode("ascii", "replace")))
+    rd.tail()
+    return total, out
+
+
+def pack_describe_request(fn: int, first: int) -> bytes:
+    return struct.pack("<HH", fn, first)
+
+
+# ---- describe TLVs -------------------------------------------------------
+
+def tlv(tag: int, value: bytes) -> bytes:
+    if len(value) > 255:
+        raise ValueError(f"TLV 0x{tag:02x}: value of {len(value)} bytes does not fit")
+    return bytes((tag, len(value))) + value
+
+
+def split_tlv(data: bytes) -> list[tuple[int, bytes]]:
+    return split_tlvs(data)
+
+
+def channels_to_bitmap(channels) -> tuple[int, bytes]:
+    chans = sorted(set(channels))
+    if not chans:
+        return 0, b""
+    base = chans[0]
+    bits = bytearray((chans[-1] - base) // 8 + 1)
+    for c in chans:
+        bits[(c - base) // 8] |= 1 << ((c - base) % 8)
+    return base, bytes(bits)
+
+
+def bitmap_to_channels(base: int, bitmap: bytes) -> list[int]:
+    return [base + i * 8 + b for i, byte in enumerate(bitmap) for b in range(8) if byte >> b & 1]
+
+
+def role_channels(role: int, channels) -> bytes:
+    base, bits = channels_to_bitmap(channels)
+    return tlv(ROLE_CHANNELS, struct.pack("<BH", role, base) + bits)
+
+
+def channel_group(group: int, pins: list[tuple[int, int]]) -> bytes:
+    return tlv(CHANNEL_GROUP, bytes([group]) + b"".join(struct.pack("<BH", r, c) for r, c in pins))
+
+
+def u8(tag: int, v: int) -> bytes:
+    return tlv(tag, struct.pack("<B", v))
+
+
+def u16(tag: int, v: int) -> bytes:
+    return tlv(tag, struct.pack("<H", v))
+
+
+def u32(tag: int, v: int) -> bytes:
+    return tlv(tag, struct.pack("<I", v))
+
+
+def text(tag: int, s: str) -> bytes:
+    return tlv(tag, s.encode("ascii"))
+
+
+@dataclass
+class Description:
+    """Common tags decoded; interface-specific and unknown tags kept raw, in order."""
+
+    roles: dict[int, list[int]] = field(default_factory=dict)
+    groups: dict[int, list[tuple[int, int]]] = field(default_factory=dict)
+    max_clock_hz: int | None = None
+    min_clock_hz: int | None = None
+    max_length: int | None = None
+    features: int | None = None
+    implementation: int | None = None
+    specific: list[tuple[int, bytes]] = field(default_factory=list)
+    unknown_critical: list[int] = field(default_factory=list)
+
+
+def decode_description(data: bytes) -> Description:
+    d = Description()
+    for tag, value in split_tlv(data):
+        t = tag & ~CRITICAL
+        if t == ROLE_CHANNELS:
+            role, base = struct.unpack_from("<BH", value)
+            d.roles.setdefault(role, []).extend(bitmap_to_channels(base, value[3:]))
+        elif t == CHANNEL_GROUP:
+            group = value[0]
+            d.groups[group] = [struct.unpack_from("<BH", value, 1 + 3 * i) for i in range((len(value) - 1) // 3)]
+        elif t == MAX_CLOCK_HZ:
+            d.max_clock_hz = struct.unpack("<I", value)[0]
+        elif t == MIN_CLOCK_HZ:
+            d.min_clock_hz = struct.unpack("<I", value)[0]
+        elif t == MAX_LENGTH:
+            d.max_length = struct.unpack("<H", value)[0]
+        elif t == FEATURES:
+            d.features = struct.unpack("<I", value)[0]
+        elif t == IMPLEMENTATION:
+            d.implementation = value[0]
+        elif t >= INTERFACE_TAG_FIRST:
+            d.specific.append((tag, value))
+        elif tag & CRITICAL:
+            d.unknown_critical.append(tag)
+        # an unknown non-critical common tag is skipped
+    for role in d.roles:
+        d.roles[role] = sorted(set(d.roles[role]))
+    return d