bayertap 0.1.0__tar.gz

bayertap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Serge Rabyking
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bayertap-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: bayertap
+Version: 0.1.0
+Summary: Passive conformance tap for bayerlink links: capture, decode, judge
+Author: Serge Rabyking
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bayerlink/bayertap
+Project-URL: Source, https://github.com/bayerlink/bayertap
+Project-URL: Issues, https://github.com/bayerlink/bayertap/issues
+Keywords: bayer,raw,hdmi,capture,v4l2,fpga,conformance,tc358743
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video :: Capture
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: bayerlink>=0.2.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# bayertap
+
+**A passive conformance tap for bayerlink links.**
+
+In a streaming netlist, a *tap* is a sink that observes a stream without
+stalling it. This is that concept as bench equipment: point it at any V4L2
+capture device carrying a [bayerlink](https://github.com/bayerlink/bayerlink)
+source and it tells you whether the bytes survive — judged with the same
+published codec the source encoded with, so the two ends cannot disagree
+about what conformance means.
+
+```bash
+bayertap probe                          # which byte-lane permutation is this rig?
+bayertap --lane-map 2,1,0 check --pattern counting     # every sample, judged
+bayertap --via tunnel check --pattern counting          # through a cheap dongle
+bayertap --from-file frame.npy check    # no hardware at all
+```
+
+## Capture tiers
+
+| Tier | Hardware | Path | Fidelity |
+| --- | --- | --- | --- |
+| **Trusted** | TC358743 HDMI→CSI-2 bridge (~$25, the PiKVM part) on any Pi or Jetson | `--via direct`, RGB888 | byte-exact |
+| **Cheap** | MS2130S / MS2131S USB3 stick (~$15) on any Linux box | `--via direct`, RGB24 | byte-exact **if** the stick's pipeline is transparent — `check` answers that in minutes |
+| **Drawer** | MS2109-class USB2 stick | `--via tunnel`, YUYV | **bit-exact at 1/6 capacity**, via the luma tunnel — run the source with `--luma-tunnel` |
+| Rejected | any USB2 stick, direct | MJPEG / starved YUYV | physics: USB2 cannot carry uncompressed 1080p, and MJPEG is lossy. Refused in code, not just here |
+
+The drawer tier deserves its sentence: a $10 dongle you already own becomes a
+working conformance receiver **today**, because bayerlink's luma tunnel
+carries the unchanged container as grey levels with a pilot line the decoder
+learns the channel from. Slow, and completely sufficient for proving bytes.
+
+## The two bring-up commands
+
+**`probe`** resolves the byte-lane permutation — which captured channel holds
+container byte k — by trying all six against the header's magic and CRC. Its
+output is directly the `lane_map` for this tool's `check` *and* for the
+FPGA-side receiver (`np2hw.bayerlink_in`). One command instead of a scope.
+
+**`check --pattern X`** regenerates the pattern locally (patterns are pure
+functions — nothing travels out of band) and compares **every sample**,
+watches `frame_seq` for gaps, tolerates scanout repeats (protocol-legal),
+and exits nonzero on any discrepancy. Point CI at it if you like.
+
+For the TC358743 tier, remember the bridge needs an EDID loaded
+(`v4l2-ctl --set-edid`) before it captures — and that EDID is *leverage*: it
+is what the source reads, so advertise only RGB 4:4:4 at your one mode and
+the source is steered into the only format the protocol accepts.
+
+## Status
+
+Everything except the ioctl layer is proven off-target: struct sizes pinned
+against the kernel uapi, both decode paths (direct with lane maps, tunnel
+with pilot learning) tested end-to-end from files. First runs against real
+capture silicon are the bench session; the known-good device table starts
+there.
+
+## Licence
+
+MIT.

bayertap-0.1.0/README.md

@@ -0,0 +1,60 @@
+# bayertap
+
+**A passive conformance tap for bayerlink links.**
+
+In a streaming netlist, a *tap* is a sink that observes a stream without
+stalling it. This is that concept as bench equipment: point it at any V4L2
+capture device carrying a [bayerlink](https://github.com/bayerlink/bayerlink)
+source and it tells you whether the bytes survive — judged with the same
+published codec the source encoded with, so the two ends cannot disagree
+about what conformance means.
+
+```bash
+bayertap probe                          # which byte-lane permutation is this rig?
+bayertap --lane-map 2,1,0 check --pattern counting     # every sample, judged
+bayertap --via tunnel check --pattern counting          # through a cheap dongle
+bayertap --from-file frame.npy check    # no hardware at all
+```
+
+## Capture tiers
+
+| Tier | Hardware | Path | Fidelity |
+| --- | --- | --- | --- |
+| **Trusted** | TC358743 HDMI→CSI-2 bridge (~$25, the PiKVM part) on any Pi or Jetson | `--via direct`, RGB888 | byte-exact |
+| **Cheap** | MS2130S / MS2131S USB3 stick (~$15) on any Linux box | `--via direct`, RGB24 | byte-exact **if** the stick's pipeline is transparent — `check` answers that in minutes |
+| **Drawer** | MS2109-class USB2 stick | `--via tunnel`, YUYV | **bit-exact at 1/6 capacity**, via the luma tunnel — run the source with `--luma-tunnel` |
+| Rejected | any USB2 stick, direct | MJPEG / starved YUYV | physics: USB2 cannot carry uncompressed 1080p, and MJPEG is lossy. Refused in code, not just here |
+
+The drawer tier deserves its sentence: a $10 dongle you already own becomes a
+working conformance receiver **today**, because bayerlink's luma tunnel
+carries the unchanged container as grey levels with a pilot line the decoder
+learns the channel from. Slow, and completely sufficient for proving bytes.
+
+## The two bring-up commands
+
+**`probe`** resolves the byte-lane permutation — which captured channel holds
+container byte k — by trying all six against the header's magic and CRC. Its
+output is directly the `lane_map` for this tool's `check` *and* for the
+FPGA-side receiver (`np2hw.bayerlink_in`). One command instead of a scope.
+
+**`check --pattern X`** regenerates the pattern locally (patterns are pure
+functions — nothing travels out of band) and compares **every sample**,
+watches `frame_seq` for gaps, tolerates scanout repeats (protocol-legal),
+and exits nonzero on any discrepancy. Point CI at it if you like.
+
+For the TC358743 tier, remember the bridge needs an EDID loaded
+(`v4l2-ctl --set-edid`) before it captures — and that EDID is *leverage*: it
+is what the source reads, so advertise only RGB 4:4:4 at your one mode and
+the source is steered into the only format the protocol accepts.
+
+## Status
+
+Everything except the ioctl layer is proven off-target: struct sizes pinned
+against the kernel uapi, both decode paths (direct with lane maps, tunnel
+with pilot learning) tested end-to-end from files. First runs against real
+capture silicon are the bench session; the known-good device table starts
+there.
+
+## Licence
+
+MIT.

bayertap-0.1.0/bayertap/__init__.py

@@ -0,0 +1,9 @@
+"""bayertap -- a passive conformance tap for bayerlink links.
+
+In a revela/np2hw netlist, a tap is a sink that observes a stream without
+stalling it. This is that concept as bench equipment: point it at any V4L2
+capture device carrying a bayerlink source and it tells you whether the
+bytes survive. It judges with the same published codec the source encoded
+with, so the two ends cannot disagree about what conformance means.
+"""
+__version__ = "0.1.0"

bayertap-0.1.0/bayertap/cli.py

@@ -0,0 +1,186 @@
+"""bayertap: a passive conformance tap for bayerlink links.
+
+Point it at any V4L2 capture device carrying a bayerlink source and it
+tells you whether the bytes survive. Three subcommands, one per question:
+
+  check       does every frame decode, does the pattern match, does
+              frame_seq advance without gaps?
+  probe       which byte-lane permutation is this platform pair using?
+  save        keep decoded raw frames for offline analysis.
+
+Two capture paths, chosen by --via:
+
+  direct      RGB3/BGR3 capture (TC358743 bridge, S-variant USB3 stick):
+              the container arrives as bytes, possibly lane-permuted --
+              which probe resolves and check accepts via --lane-map.
+  tunnel      YUYV capture (MS2109-class USB2 dongles): only luma survives
+              that hardware, so the source must run --luma-tunnel, and the
+              container is recovered from grey levels via the pilot line.
+
+Everything also runs from a saved .npy instead of a device (--from-file),
+so the whole validation path is testable -- and tested -- with no capture
+hardware at all.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+import numpy as np
+
+from bayerlink import decode_frame, detect_lane_map, pattern, tunnel
+from bayerlink.protocol import Header
+
+
+def _validate(container: np.ndarray, expect_pattern: str | None,
+              last_seq: int | None):
+    """One container -> (Header, list of problem strings)."""
+    problems = []
+    try:
+        header, raw = decode_frame(container)
+    except ValueError as error:
+        return None, [f"decode: {error}"]
+    if last_seq is not None:
+        gap = (header.frame_seq - last_seq) & 0xFFFFFFFF
+        if gap == 0:
+            return header, ["duplicate (same frame_seq; scanout repeat)"]
+        if gap != 1:
+            problems.append(f"frame_seq gap: {last_seq} -> {header.frame_seq}")
+    if expect_pattern is not None:
+        if not header.is_test_pattern:
+            problems.append("header does not claim a test pattern")
+        expected = pattern.generate(expect_pattern, header.width, header.height)
+        if not np.array_equal(raw, expected):
+            wrong = int((raw != expected).sum())
+            first = tuple(int(v) for v in np.argwhere(raw != expected)[0])
+            problems.append(
+                f"{wrong} of {raw.size} samples differ from {expect_pattern}; "
+                f"first at (row, col) {first}")
+    return header, problems
+
+
+def _containers(args):
+    """Yield (tag, container) from the device or the file, per --via."""
+    if args.from_file:
+        physical = np.load(args.from_file)
+        if args.via == "tunnel":
+            luma = physical[:, :, 0] if physical.ndim == 3 else physical
+            _, inner_h = tunnel.inner_display(luma.shape[1], luma.shape[0])
+            yield 0, tunnel.decode(luma, inner_height=inner_h)
+        else:
+            frame = physical[:, :, list(args.lane_map)]
+            yield 0, frame
+        return
+
+    from . import v4l2
+
+    device = v4l2.Device(args.device)
+    print(f"{device.path}: {device.card} ({device.driver}), "
+          f"offers {device.formats()}")
+    width, height = args.capture
+    if args.via == "tunnel":
+        for sequence, luma in device.frames(width, height, v4l2.FORMAT_YUYV):
+            _, inner_h = tunnel.inner_display(width, height)
+            try:
+                yield sequence, tunnel.decode(luma, inner_height=inner_h)
+            except ValueError as error:
+                yield sequence, error
+    else:
+        pixelformat = v4l2.FORMAT_BGR3 if args.bgr else v4l2.FORMAT_RGB3
+        for sequence, frame in device.frames(width, height, pixelformat):
+            yield sequence, frame[:, :, list(args.lane_map)]
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="bayertap",
+        description="Passive conformance tap for bayerlink links.")
+    parser.add_argument("--device", default="/dev/video0")
+    parser.add_argument("--from-file", default=None,
+                        help=".npy physical frame instead of a device")
+    parser.add_argument("--via", choices=["direct", "tunnel"], default="direct",
+                        help="direct: RGB capture; tunnel: YUYV luma capture "
+                             "of a --luma-tunnel source")
+    parser.add_argument("--capture", type=lambda s: tuple(
+                            int(v) for v in s.split("x")), default=(1280, 720),
+                        help="capture geometry WxH (default 1280x720)")
+    parser.add_argument("--lane-map", type=lambda s: tuple(
+                            int(v) for v in s.split(",")), default=(0, 1, 2),
+                        help="byte permutation for direct capture; find it "
+                             "with `bayertap probe`")
+    parser.add_argument("--bgr", action="store_true",
+                        help="capture BGR3 instead of RGB3")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    check = sub.add_parser("check", help="validate frames continuously")
+    check.add_argument("--pattern", default=None,
+                       choices=sorted(pattern.PATTERNS),
+                       help="regenerate this pattern locally and compare "
+                            "every sample")
+    check.add_argument("--frames", type=int, default=0,
+                       help="stop after N NEW frames (0 = forever)")
+
+    sub.add_parser("probe", help="resolve the byte-lane permutation "
+                                 "(direct capture of one frame)")
+
+    save = sub.add_parser("save", help="write decoded raw frames as .npy")
+    save.add_argument("--out", required=True)
+    save.add_argument("--frames", type=int, default=1)
+
+    args = parser.parse_args(argv)
+
+    if args.command == "probe":
+        if args.via == "tunnel":
+            parser.error("probe needs direct RGB capture: the tunnel is "
+                         "greyscale, so lanes are indistinguishable there")
+        args.lane_map = (0, 1, 2)               # probe must see raw order
+        for _, frame in _containers(args):
+            if isinstance(frame, Exception):
+                continue
+            permutation, header = detect_lane_map(frame)
+            print(f"lane_map = {permutation}   "
+                  f"(container byte k is on captured channel lane_map[k])")
+            print(f"header: {header.fourcc} {header.width}x{header.height} "
+                  f"seq {header.frame_seq}")
+            return 0
+        return 1
+
+    seen = last_seq = None
+    good = bad = saved = 0
+    for tag, container in _containers(args):
+        if isinstance(container, Exception):
+            bad += 1
+            print(f"[{tag}] tunnel: {container}")
+            continue
+        header, problems = _validate(
+            container, getattr(args, "pattern", None), last_seq)
+        if header is not None and problems == ["duplicate (same frame_seq; "
+                                               "scanout repeat)"]:
+            continue                            # repeats are protocol-legal
+        if problems:
+            bad += 1
+            print(f"[{tag}] " + "; ".join(problems))
+        else:
+            good += 1
+            last_seq = header.frame_seq
+            if args.command == "save":
+                _, raw = decode_frame(container)
+                path = f"{args.out.rstrip('/')}/frame_{header.frame_seq:08d}.npy"
+                np.save(path, raw)
+                saved += 1
+                print(f"saved {path}")
+            elif good % 30 == 1:
+                print(f"[{tag}] ok: {header.fourcc} {header.width}x"
+                      f"{header.height} seq {header.frame_seq}"
+                      + (f", pattern {args.pattern} exact"
+                         if getattr(args, 'pattern', None) else ""))
+        limit = getattr(args, "frames", 0)
+        if limit and (good if args.command == "check" else saved) >= limit:
+            break
+
+    print(f"\n{good} good, {bad} bad")
+    return 0 if bad == 0 and good > 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bayertap-0.1.0/bayertap/v4l2.py

@@ -0,0 +1,210 @@
+"""V4L2 capture via raw ioctls: open, negotiate, mmap, stream.
+
+The same zero-dependency posture as picam2hdmi's KMS layer, for the same
+reason: an appliance should not carry a bindings package for the nine
+ioctls it uses, and the V4L2 uapi is a stable kernel ABI. Every struct is
+pinned against its known uapi size by the tests -- a mislaid ctypes field
+fails as one assert here instead of as corruption on a bench.
+
+This layer knows nothing about bayerlink. It negotiates a pixel format,
+maps buffers, and yields frames; what the frames MEAN belongs to the
+caller. That split is what lets one tool serve every capture tier -- a
+TC358743 bridge delivering RGB888, an S-variant USB3 stick delivering
+RGB24, an MS2109 delivering YUY2 for the luma tunnel -- they are all just
+V4L2 devices with different formats.
+"""
+from __future__ import annotations
+
+import ctypes
+import fcntl
+import mmap as _mmap
+import os
+import select
+
+import numpy as np
+
+u8, u32, u64 = ctypes.c_uint8, ctypes.c_uint32, ctypes.c_uint64
+
+
+class Capability(ctypes.Structure):
+    _fields_ = [("driver", ctypes.c_char * 16), ("card", ctypes.c_char * 32),
+                ("bus_info", ctypes.c_char * 32), ("version", u32),
+                ("capabilities", u32), ("device_caps", u32),
+                ("reserved", u32 * 3)]                       # 104 bytes
+
+
+class PixFormat(ctypes.Structure):
+    _fields_ = [("width", u32), ("height", u32), ("pixelformat", u32),
+                ("field", u32), ("bytesperline", u32), ("sizeimage", u32),
+                ("colorspace", u32), ("priv", u32), ("flags", u32),
+                ("ycbcr_enc", u32), ("quantization", u32),
+                ("xfer_func", u32)]                          # 48 bytes
+
+
+class Format(ctypes.Structure):
+    _fields_ = [("type", u32), ("pad", u32),
+                ("fmt", ctypes.c_uint8 * 200)]               # 208 bytes
+
+    @property
+    def pix(self) -> PixFormat:
+        return PixFormat.from_buffer(self, 8)
+
+
+class RequestBuffers(ctypes.Structure):
+    _fields_ = [("count", u32), ("type", u32), ("memory", u32),
+                ("capabilities", u32), ("flags", u8),
+                ("reserved", u8 * 3)]                        # 20 bytes
+
+
+class Timeval(ctypes.Structure):
+    _fields_ = [("sec", ctypes.c_long), ("usec", ctypes.c_long)]
+
+
+class Timecode(ctypes.Structure):
+    _fields_ = [("type", u32), ("flags", u32), ("frames", u8), ("seconds", u8),
+                ("minutes", u8), ("hours", u8), ("userbits", u8 * 4)]
+
+
+class Buffer(ctypes.Structure):
+    _fields_ = [("index", u32), ("type", u32), ("bytesused", u32),
+                ("flags", u32), ("field", u32), ("pad", u32),
+                ("timestamp", Timeval), ("timecode", Timecode),
+                ("sequence", u32), ("memory", u32),
+                ("m_offset", u64),        # union: offset/userptr/planes/fd
+                ("length", u32), ("reserved2", u32),
+                ("request_fd", u32)]                          # 88 bytes (LP64)
+
+
+class FmtDesc(ctypes.Structure):
+    _fields_ = [("index", u32), ("type", u32), ("flags", u32),
+                ("description", ctypes.c_char * 32), ("pixelformat", u32),
+                ("mbus_code", u32), ("reserved", u32 * 3)]   # 64 bytes
+
+
+def _ioc(direction: int, nr: int, size: int) -> int:
+    return (direction << 30) | (size << 16) | (ord("V") << 8) | nr
+
+
+IOCTL_QUERYCAP = _ioc(2, 0, ctypes.sizeof(Capability))
+IOCTL_ENUM_FMT = _ioc(3, 2, ctypes.sizeof(FmtDesc))
+IOCTL_S_FMT = _ioc(3, 5, ctypes.sizeof(Format))
+IOCTL_REQBUFS = _ioc(3, 8, ctypes.sizeof(RequestBuffers))
+IOCTL_QUERYBUF = _ioc(3, 9, ctypes.sizeof(Buffer))
+IOCTL_QBUF = _ioc(3, 15, ctypes.sizeof(Buffer))
+IOCTL_DQBUF = _ioc(3, 17, ctypes.sizeof(Buffer))
+IOCTL_STREAMON = _ioc(1, 18, 4)
+IOCTL_STREAMOFF = _ioc(1, 19, 4)
+
+CAPTURE = 1                       # V4L2_BUF_TYPE_VIDEO_CAPTURE
+MEMORY_MMAP = 1
+
+
+def fourcc(text: str) -> int:
+    return int.from_bytes(text.encode("ascii"), "little")
+
+
+FORMAT_YUYV = fourcc("YUYV")
+FORMAT_RGB3 = fourcc("RGB3")      # RGB24: memory R,G,B per pixel
+FORMAT_BGR3 = fourcc("BGR3")      # memory B,G,R per pixel
+FORMAT_MJPG = fourcc("MJPG")      # rejected for payload: lossy
+
+
+def frame_array(data: np.ndarray, pixelformat: int, width: int,
+                height: int, bytesperline: int) -> np.ndarray:
+    """Raw captured bytes -> a channel-shaped array, per format.
+
+    YUYV yields the LUMA plane (height, width) -- the only channel the luma
+    tunnel needs, extracted here so callers never index interleaved bytes.
+    RGB3/BGR3 yield (height, width, 3) in MEMORY byte order, untouched:
+    which byte is which lane is detect_lane_map()'s question, not this
+    layer's.
+    """
+    rows = data[:height * bytesperline].reshape(height, bytesperline)
+    if pixelformat == FORMAT_YUYV:
+        return rows[:, :width * 2][:, 0::2].copy()
+    if pixelformat in (FORMAT_RGB3, FORMAT_BGR3):
+        return rows[:, :width * 3].reshape(height, width, 3).copy()
+    raise ValueError(
+        f"unhandled pixelformat {pixelformat:#010x}; this tool captures "
+        "YUYV (luma tunnel) and RGB3/BGR3 (direct), and refuses MJPEG "
+        "outright -- lossy compression cannot carry a byte container.")
+
+
+class Device:
+    """One V4L2 capture device, negotiated and streaming."""
+
+    def __init__(self, path: str = "/dev/video0"):
+        self.path = path
+        self.fd = os.open(path, os.O_RDWR | os.O_NONBLOCK)
+        cap = Capability()
+        fcntl.ioctl(self.fd, IOCTL_QUERYCAP, cap)
+        self.driver = cap.driver.decode(errors="replace")
+        self.card = cap.card.decode(errors="replace")
+        self._maps: list = []
+
+    def formats(self) -> list[str]:
+        """The fourccs the device offers, for diagnostics and refusals."""
+        found = []
+        index = 0
+        while True:
+            desc = FmtDesc(index=index, type=CAPTURE)
+            try:
+                fcntl.ioctl(self.fd, IOCTL_ENUM_FMT, desc)
+            except OSError:
+                return found
+            found.append(int(desc.pixelformat).to_bytes(4, "little")
+                         .decode(errors="replace"))
+            index += 1
+
+    def set_format(self, width: int, height: int, pixelformat: int):
+        """Negotiate; RETURNS what the device actually granted.
+
+        V4L2 is a negotiation, not a command: the driver may adjust every
+        field. The caller compares granted against requested and refuses a
+        substitute -- silently capturing at the wrong geometry is how a
+        bench lies.
+        """
+        request = Format(type=CAPTURE)
+        pix = request.pix
+        pix.width, pix.height = width, height
+        pix.pixelformat = pixelformat
+        pix.field = 1                                # V4L2_FIELD_NONE
+        fcntl.ioctl(self.fd, IOCTL_S_FMT, request)
+        granted = request.pix
+        if (granted.width, granted.height) != (width, height) or \
+                granted.pixelformat != pixelformat:
+            got = int(granted.pixelformat).to_bytes(4, "little").decode(
+                errors="replace")
+            want = int(pixelformat).to_bytes(4, "little").decode(errors="replace")
+            raise RuntimeError(
+                f"{self.path} granted {granted.width}x{granted.height} {got} "
+                f"instead of {width}x{height} {want}; it offers formats "
+                f"{self.formats()}. Refusing the substitute.")
+        return granted.width, granted.height, granted.bytesperline
+
+    def frames(self, width: int, height: int, pixelformat: int, buffers: int = 4):
+        """Yield frames forever: (sequence, array) per :func:`frame_array`."""
+        width, height, bytesperline = self.set_format(width, height, pixelformat)
+
+        request = RequestBuffers(count=buffers, type=CAPTURE, memory=MEMORY_MMAP)
+        fcntl.ioctl(self.fd, IOCTL_REQBUFS, request)
+        for index in range(request.count):
+            buffer = Buffer(index=index, type=CAPTURE, memory=MEMORY_MMAP)
+            fcntl.ioctl(self.fd, IOCTL_QUERYBUF, buffer)
+            self._maps.append(_mmap.mmap(self.fd, buffer.length,
+                                         offset=buffer.m_offset))
+            fcntl.ioctl(self.fd, IOCTL_QBUF, buffer)
+
+        fcntl.ioctl(self.fd, IOCTL_STREAMON, ctypes.c_int(CAPTURE))
+        try:
+            while True:
+                select.select([self.fd], [], [])
+                buffer = Buffer(type=CAPTURE, memory=MEMORY_MMAP)
+                fcntl.ioctl(self.fd, IOCTL_DQBUF, buffer)
+                data = np.frombuffer(self._maps[buffer.index], np.uint8,
+                                     count=buffer.bytesused)
+                yield buffer.sequence, frame_array(
+                    data, pixelformat, width, height, bytesperline)
+                fcntl.ioctl(self.fd, IOCTL_QBUF, buffer)
+        finally:
+            fcntl.ioctl(self.fd, IOCTL_STREAMOFF, ctypes.c_int(CAPTURE))

bayertap-0.1.0/bayertap.egg-info/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: bayertap
+Version: 0.1.0
+Summary: Passive conformance tap for bayerlink links: capture, decode, judge
+Author: Serge Rabyking
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bayerlink/bayertap
+Project-URL: Source, https://github.com/bayerlink/bayertap
+Project-URL: Issues, https://github.com/bayerlink/bayertap/issues
+Keywords: bayer,raw,hdmi,capture,v4l2,fpga,conformance,tc358743
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video :: Capture
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: bayerlink>=0.2.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# bayertap
+
+**A passive conformance tap for bayerlink links.**
+
+In a streaming netlist, a *tap* is a sink that observes a stream without
+stalling it. This is that concept as bench equipment: point it at any V4L2
+capture device carrying a [bayerlink](https://github.com/bayerlink/bayerlink)
+source and it tells you whether the bytes survive — judged with the same
+published codec the source encoded with, so the two ends cannot disagree
+about what conformance means.
+
+```bash
+bayertap probe                          # which byte-lane permutation is this rig?
+bayertap --lane-map 2,1,0 check --pattern counting     # every sample, judged
+bayertap --via tunnel check --pattern counting          # through a cheap dongle
+bayertap --from-file frame.npy check    # no hardware at all
+```
+
+## Capture tiers
+
+| Tier | Hardware | Path | Fidelity |
+| --- | --- | --- | --- |
+| **Trusted** | TC358743 HDMI→CSI-2 bridge (~$25, the PiKVM part) on any Pi or Jetson | `--via direct`, RGB888 | byte-exact |
+| **Cheap** | MS2130S / MS2131S USB3 stick (~$15) on any Linux box | `--via direct`, RGB24 | byte-exact **if** the stick's pipeline is transparent — `check` answers that in minutes |
+| **Drawer** | MS2109-class USB2 stick | `--via tunnel`, YUYV | **bit-exact at 1/6 capacity**, via the luma tunnel — run the source with `--luma-tunnel` |
+| Rejected | any USB2 stick, direct | MJPEG / starved YUYV | physics: USB2 cannot carry uncompressed 1080p, and MJPEG is lossy. Refused in code, not just here |
+
+The drawer tier deserves its sentence: a $10 dongle you already own becomes a
+working conformance receiver **today**, because bayerlink's luma tunnel
+carries the unchanged container as grey levels with a pilot line the decoder
+learns the channel from. Slow, and completely sufficient for proving bytes.
+
+## The two bring-up commands
+
+**`probe`** resolves the byte-lane permutation — which captured channel holds
+container byte k — by trying all six against the header's magic and CRC. Its
+output is directly the `lane_map` for this tool's `check` *and* for the
+FPGA-side receiver (`np2hw.bayerlink_in`). One command instead of a scope.
+
+**`check --pattern X`** regenerates the pattern locally (patterns are pure
+functions — nothing travels out of band) and compares **every sample**,
+watches `frame_seq` for gaps, tolerates scanout repeats (protocol-legal),
+and exits nonzero on any discrepancy. Point CI at it if you like.
+
+For the TC358743 tier, remember the bridge needs an EDID loaded
+(`v4l2-ctl --set-edid`) before it captures — and that EDID is *leverage*: it
+is what the source reads, so advertise only RGB 4:4:4 at your one mode and
+the source is steered into the only format the protocol accepts.
+
+## Status
+
+Everything except the ioctl layer is proven off-target: struct sizes pinned
+against the kernel uapi, both decode paths (direct with lane maps, tunnel
+with pilot learning) tested end-to-end from files. First runs against real
+capture silicon are the bench session; the known-good device table starts
+there.
+
+## Licence
+
+MIT.

bayertap-0.1.0/bayertap.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+bayertap/__init__.py
+bayertap/cli.py
+bayertap/v4l2.py
+bayertap.egg-info/PKG-INFO
+bayertap.egg-info/SOURCES.txt
+bayertap.egg-info/dependency_links.txt
+bayertap.egg-info/entry_points.txt
+bayertap.egg-info/requires.txt
+bayertap.egg-info/top_level.txt
+tests/test_bayertap.py

bayertap-0.1.0/bayertap.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bayertap-0.1.0/bayertap.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bayertap = bayertap.cli:main

bayertap-0.1.0/bayertap.egg-info/requires.txt

@@ -0,0 +1,5 @@
+numpy
+bayerlink>=0.2.0
+
+[test]
+pytest

bayertap-0.1.0/bayertap.egg-info/top_level.txt

@@ -0,0 +1 @@
+bayertap

bayertap-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bayertap"
+version = "0.1.0"
+description = "Passive conformance tap for bayerlink links: capture, decode, judge"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Serge Rabyking" }]
+requires-python = ">=3.9"
+keywords = ["bayer", "raw", "hdmi", "capture", "v4l2", "fpga", "conformance", "tc358743"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Video :: Capture",
+    "Topic :: Software Development :: Embedded Systems",
+]
+dependencies = ["numpy", "bayerlink>=0.2.0"]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/bayerlink/bayertap"
+Source = "https://github.com/bayerlink/bayertap"
+Issues = "https://github.com/bayerlink/bayertap/issues"
+
+[project.scripts]
+bayertap = "bayertap.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["bayertap*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

bayertap-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bayertap-0.1.0/tests/test_bayertap.py

@@ -0,0 +1,84 @@
+"""Everything that does not need capture hardware, which is everything but
+the ioctls: struct sizes pinned to the uapi, frame_array per format, and the
+whole check pipeline end to end from files -- the same code paths a device
+feeds, minus the device.
+"""
+import ctypes
+
+import numpy as np
+import pytest
+from bayerlink import encode_frame, pattern, tunnel
+from bayerlink.protocol import FLAG_TEST_PATTERN
+
+from bayertap import cli, v4l2
+
+
+def test_struct_sizes_match_the_kernel_uapi():
+    expected = {v4l2.Capability: 104, v4l2.PixFormat: 48, v4l2.Format: 208,
+                v4l2.RequestBuffers: 20, v4l2.Buffer: 88, v4l2.FmtDesc: 64}
+    for struct, size in expected.items():
+        assert ctypes.sizeof(struct) == size, struct.__name__
+
+
+def test_frame_array_extracts_luma_from_yuyv_and_passes_rgb_untouched():
+    height, width, stride = 4, 8, 8 * 2 + 4          # padded line
+    yuyv = np.arange(height * stride, dtype=np.uint8)
+    luma = v4l2.frame_array(yuyv, v4l2.FORMAT_YUYV, width, height, stride)
+    assert luma.shape == (height, width)
+    assert np.array_equal(luma[0], yuyv[:width * 2:2])
+
+    stride = 8 * 3
+    rgb = np.arange(height * stride, dtype=np.uint8)
+    frame = v4l2.frame_array(rgb, v4l2.FORMAT_RGB3, width, height, stride)
+    assert frame.shape == (height, width, 3)
+    assert np.array_equal(frame.reshape(-1), rgb)
+
+    with pytest.raises(ValueError, match="refuses MJPEG"):
+        v4l2.frame_array(rgb, v4l2.FORMAT_MJPG, width, height, stride)
+
+
+def _direct_file(tmp_path, lane_perm=(0, 1, 2), seq=4):
+    raw = pattern.generate("corners", 32, 8)
+    container = encode_frame(raw, "RGGB", frame_seq=seq, display=(32, 12),
+                             flags=FLAG_TEST_PATTERN)
+    scrambled = np.empty_like(container)
+    for k in range(3):
+        scrambled[:, :, lane_perm[k]] = container[:, :, k]
+    path = tmp_path / "direct.npy"
+    np.save(path, scrambled)
+    return path
+
+
+def test_check_from_file_direct_passes_and_fails_honestly(tmp_path, capsys):
+    path = _direct_file(tmp_path)
+    code = cli.main(["--from-file", str(path), "check", "--pattern", "corners"])
+    assert code == 0 and "1 good, 0 bad" in capsys.readouterr().out
+
+    code = cli.main(["--from-file", str(path), "check", "--pattern", "checker"])
+    out = capsys.readouterr().out
+    assert code == 1 and "differ from checker" in out
+
+
+def test_check_applies_the_lane_map(tmp_path, capsys):
+    path = _direct_file(tmp_path, lane_perm=(2, 0, 1))
+    # Without the map: not a bayerlink frame at all.
+    assert cli.main(["--from-file", str(path), "check"]) == 1
+    capsys.readouterr()
+    # detect_lane_map's answer, applied: (container byte k is on channel...)
+    assert cli.main(["--from-file", str(path), "--lane-map", "2,0,1",
+                     "check", "--pattern", "corners"]) == 0
+
+
+def test_check_from_file_via_tunnel(tmp_path, capsys):
+    display = (192, 40)
+    inner_w, inner_h = tunnel.inner_display(*display)
+    raw = pattern.generate("counting", inner_w * 2, 20)
+    container = encode_frame(raw, "BGGR", frame_seq=0,
+                             display=(inner_w, inner_h),
+                             flags=FLAG_TEST_PATTERN)
+    grey = tunnel.encode(container, display)
+    path = tmp_path / "tunnel.npy"
+    np.save(path, grey)
+    code = cli.main(["--from-file", str(path), "--via", "tunnel",
+                     "check", "--pattern", "counting"])
+    assert code == 0 and "1 good, 0 bad" in capsys.readouterr().out