bayerlink-fpga 0.3.0__py3-none-any.whl

bayerlink_fpga/__init__.py

@@ -0,0 +1,25 @@
+# Copyright 2026 Serge Rabyking
+# SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1
+"""bayerlink on FPGAs: the receiver and what any board needs around it.
+
+Two layers, the second reusable by any board:
+
+  the receiver       bayerlink_in (hdl/bayerlink_in.v, sized by
+                     receiver.py), the DDC slave that is the receiver's
+                     EDID and control port, and the Verilog around them
+                     (hdl/): link reset and the capture path's AXIS
+                     dressing. Nothing here knows a board.
+  frontends/         what turns a cable into parallel video -- pixel
+                     clock, data enable, vsync, 24 bits -- and the facts
+                     that follow from it, such as which lane carries
+                     which container byte.
+
+Nothing here knows a board. A board's own library says which front end
+its jack uses, how it is configured there, and which pins it lands on.
+Its design names the receiver and the DDC slave as leaves --
+bayerlink_fpga.receiver:bayerlink_in and bayerlink_fpga.ddc:ddc_slave --
+which its build sets from the design's settings.
+"""
+from pathlib import Path
+
+HDL = Path(__file__).resolve().parent / "hdl"

bayerlink_fpga/ddc.py

@@ -0,0 +1,107 @@
+# Copyright 2026 Serge Rabyking
+# SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1
+"""Generate the DDC slave: this receiver's calling card and control port.
+
+The EDID stops being a borrowed monitor identity (a canned 720p file)
+and becomes the receiver's own: the preferred detailed timing IS the
+bayerlink container -- 1920x1081 at 30, one header row above the
+payload -- so a source that honours EDID lands on the right raster
+without being forced, and the monitor name says plainly what answered.
+The same engine serves the register personality at 0x37: the ISP's
+whole register file, readable and writable across the display cable,
+refusal (SLVERR while the file is armed) answered as NACK.
+
+The advertised raster is the build's link mode; the board design wires
+the slave's AXI master to whatever register file it wants reachable.
+"""
+def container_timing(mode: str) -> dict:
+    """The advertised raster, DERIVED from bayerlink's rasters.
+
+    These seven numbers used to be written here as constants, with a
+    comment saying they were "the same numbers scanout and the bridge
+    use" -- which is a promise a comment cannot keep. They are the
+    link_mode's timing with ONE EXTRA ACTIVE LINE: the bayerlink
+    container is the payload with its header row above it, and that row
+    is why a source honouring this EDID sends 1081 lines and not 1080.
+
+    The vertical blanking shrinks by that line rather than the total
+    growing, because the total is what a source locks to.
+    """
+    from bayerlink.rasters import raster
+
+    t = raster(mode)
+    vact = t.v_active + 1                          # + the header row
+    return {
+        "pclk_10khz": round(t.pixel_khz / 10),
+        "hact": t.h_active, "hblank": t.h_total - t.h_active,
+        "vact": vact, "vblank": t.v_total - vact,
+        "hso": t.hs_beg - t.h_active, "hsw": t.hs_end - t.hs_beg,
+        "vso": t.vs_beg - vact, "vsw": t.vs_end - t.vs_beg,
+    }
+
+
+def build_edid(link_mode: str) -> bytes:
+    """The receiver's own EDID, preferring the container of `link_mode`."""
+    t = container_timing(link_mode)
+    PCLK_10KHZ = t["pclk_10khz"]
+    HACT, HBLANK = t["hact"], t["hblank"]
+    VACT, VBLANK = t["vact"], t["vblank"]
+    HSO, HSW = t["hso"], t["hsw"]
+    VSO, VSW = t["vso"], t["vsw"]
+    e = bytearray(128)
+    e[0:8] = bytes([0x00, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x00])
+    # PnP id "BLK" -- three 5-bit letters, A=1
+    pnp = (2 << 10) | (12 << 5) | 11
+    e[8], e[9] = pnp >> 8, pnp & 0xFF
+    e[10:12] = (1).to_bytes(2, "little")     # product: 1 = the rx
+    e[12:16] = (0).to_bytes(4, "little")     # serial
+    e[16], e[17] = 1, 2026 - 1990            # week, year
+    e[18], e[19] = 1, 3                      # EDID 1.3
+    e[20] = 0x80                             # digital input
+    e[21], e[22] = 0x30, 0x1B                # 48x27 cm, honesty optional
+    e[23] = 120                              # gamma 2.2
+    e[24] = 0x0A                             # RGB, preferred timing
+    e[25:35] = bytes([0xEE, 0x91, 0xA3, 0x54, 0x4C, 0x99, 0x26, 0x0F,
+                      0x50, 0x54])           # sRGB-ish chromaticity
+    e[35:38] = bytes(3)                      # no established timings
+    e[38:54] = bytes([0x01, 0x01] * 8)       # no standard timings
+    # The one detailed timing: the container itself.
+    e[54:72] = bytes([
+        PCLK_10KHZ & 0xFF, PCLK_10KHZ >> 8,
+        HACT & 0xFF, HBLANK & 0xFF,
+        ((HACT >> 8) << 4) | (HBLANK >> 8),
+        VACT & 0xFF, VBLANK & 0xFF,
+        ((VACT >> 8) << 4) | (VBLANK >> 8),
+        HSO & 0xFF, HSW & 0xFF,
+        ((VSO & 0xF) << 4) | (VSW & 0xF),
+        ((HSO >> 8) << 6) | ((HSW >> 8) << 4)
+        | ((VSO >> 4) << 2) | (VSW >> 4),
+        0, 0, 0, 0, 0,
+        0x1E,                                # separate sync, +h +v
+    ])
+    e[72:90] = bytes([0, 0, 0, 0xFC, 0]) + b"BAYERLINK RX\n"
+    # the range limits: the container's own rates, a step either side
+    hz = round(t["pclk_10khz"] * 1e4 / ((HACT + HBLANK) * (VACT + VBLANK)))
+    khz = round(t["pclk_10khz"] * 10 / (HACT + HBLANK))
+    mhz10 = -(-t["pclk_10khz"] // 1000)          # max clock, in 10 MHz
+    e[90:108] = (bytes([0, 0, 0, 0xFD, 0, hz - 1, hz + 1, khz - 5, khz + 5,
+                        mhz10, 0, 0x0A]) + b"\x20" * 6)
+    e[108:126] = bytes([0, 0, 0, 0x10, 0]) + bytes(13)
+    e[126] = 0                               # no extension blocks
+    e[127] = (-sum(e[:127])) % 256
+    return bytes(e)
+
+
+def ddc_slave(link_mode: str) -> dict:
+    """The DDC slave: this receiver's EDID at 0x50, its registers at 0x37.
+
+    A leaf a design names (`bayerlink_fpga.ddc:ddc_slave`) with the raster
+    the EDID advertises. Returns np2hw's result, every port published; the
+    EDID is the module's own ROM.
+    """
+    from np2hw import ddc_slave as generate_ddc
+    return generate_ddc(reg_addr7=0x37, edid=build_edid(link_mode),
+                        edid_addr7=0x50)
+
+
+ddc_slave.leaf = True

bayerlink_fpga/frontends/__init__.py

@@ -0,0 +1,17 @@
+# Copyright 2026 Serge Rabyking
+# SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1
+"""Front ends: what turns a cable into the receiver's parallel video.
+
+hdmi_rx.json describes the block -- TMDS in; pixel clock, lock, data
+enable, syncs and 24 data bits out -- and its implementations, each from
+a vendor or of our own, each stating what follows from it: which video
+lane carries which container byte, the frame pulse's polarity, the
+reference clock it calibrates with. Every implementation offers the
+block's ports, so the receiver and the designs above it do not change
+when it does.
+
+How a front end is configured on a particular board, and which pins it
+lands on, is that board's: a board's jack names the block,
+bayerlink_fpga.frontends.hdmi_rx, chooses its implementation and passes
+its configuration.
+"""

bayerlink_fpga/frontends/hdmi_rx.json

@@ -0,0 +1,73 @@
+{
+  "blocks": {
+    "hdmi_rx": {
+      "description": "An HDMI/DVI receiver: a TMDS link in, parallel video out -- pixel clock, lock, data enable, syncs, 24 data bits. Every implementation offers these same ports, so the bayerlink receiver and the designs above it do not change when it does. How it is configured on a board, and which pins it lands on, is that board's.",
+      "parameters": {
+        "implementation": {
+          "default": "'dvi2rgb'",
+          "description": "Which implementation fills this block."
+        },
+        "link_khz": {
+          "description": "The link's pixel clock, in kHz: the rate the source sends, which the implementation's clocking is set for."
+        },
+        "status": {
+          "default": 0,
+          "description": "1: the implementation's own account of the link, on the ports below marked by it -- for an implementation that keeps one."
+        }
+      },
+      "inputs": [
+        {"name": "TMDS", "bus": "tmds", "description": "The link, from the jack's pins."},
+        {"name": "refclk", "description": "The reference clock the implementation calibrates its input delays with; its frequency is the implementation's fact refclk_mhz."},
+        {"name": "rst", "description": "Asynchronous, active high."}
+      ],
+      "outputs": [
+        {"name": "pclk", "description": "The clock recovered from the link: it stops when the cable is pulled."},
+        {"name": "locked"},
+        {"name": "de"},
+        {"name": "hsync"},
+        {"name": "vsync"},
+        {"name": "data", "width": 24, "description": "Lane 0 is data[23:16], lane 1 [15:8], lane 2 [7:0]."},
+        {"name": "bonded", "when": "status", "description": "tmds_rx: the three lanes found in step."},
+        {"name": "clock_locked", "when": "status", "description": "tmds_rx: its clock manager locked to the link's clock."},
+        {"name": "aligned", "width": 3, "when": "status", "description": "tmds_rx: each lane aligned, lane 0 lowest."},
+        {"name": "eye", "width": 15, "when": "status", "description": "tmds_rx: each lane's eye, its taps that misread nothing, 5 bits a lane, lane 0 lowest."},
+        {"name": "slip", "width": 12, "when": "status", "description": "tmds_rx: each lane's bit slip, 4 bits a lane, lane 0 lowest."},
+        {"name": "survey_count", "width": 8, "when": "status", "description": "tmds_rx's survey, an entry at a time, each entry's fields together (hdl/tmds_rx.v): the misread tokens at this lane, slip and tap, 255 for no blank seen."},
+        {"name": "survey_tap", "width": 5, "when": "status", "description": "The survey entry's delay tap."},
+        {"name": "survey_slip", "width": 4, "when": "status", "description": "The survey entry's bit slip."},
+        {"name": "survey_lane", "width": 2, "when": "status", "description": "The survey entry's lane."},
+        {"name": "survey_lane_tap", "width": 5, "when": "status", "description": "The tap that lane samples at."},
+        {"name": "survey_lane_slip", "width": 4, "when": "status", "description": "The bit slip that lane samples at."},
+        {"name": "survey_lane_aligned", "when": "status", "description": "Whether that lane is aligned."}
+      ],
+      "implementations": {
+        "dvi2rgb": {
+          "description": "Digilent's dvi2rgb on a 7-series part: TMDS decoded in the fabric (ISERDESE2, IDELAYE2, an MMCM). Needs Digilent's vivado-library in the IP catalogue. Lane map solved 2026-08-12 on a PYNQ-Z2 with the picam2hdmi source, counting and checker patterns: it follows this IP's bus order, not the board, so it holds on any board receiving through dvi2rgb. kClkRange follows the link: its MMCM multiplies the link clock by 5 x kClkRange and divides by kClkRange, so the five-times serial clock is the same whatever the range, and the range only keeps the VCO inside its 600-1200 MHz specification -- range 1 at a 74.25 MHz link would run it at 371 MHz. Range 2 at 74.25 MHz judged 30/30 frames bit-exact on the PYNQ-Z2 (2026-10-09). Below 25 MHz it has no range.",
+          "vivado": {"ip": "digilentinc.com:ip:dvi2rgb"},
+          "config": {
+            "kEmulateDDC": "'false'", "kAddBUFG": "'true'",
+            "kClkRange": "1 if link_khz >= 120000 else 2 if link_khz >= 60000 else 3 if link_khz >= 40000 else 4 if link_khz >= 30000 else 5"
+          },
+          "ports": {
+            "refclk": "RefClk", "rst": "aRst", "pclk": "PixelClk",
+            "locked": "aPixelClkLckd", "de": "vid_pVDE", "hsync": "vid_pHSync",
+            "vsync": "vid_pVSync", "data": "vid_pData"
+          },
+          "tie": {"pRst": 0},
+          "facts": {"lane_map": [1, 2, 0], "vsync_active_high": 1, "refclk_mhz": 200, "min_link_khz": 25000}
+        },
+        "tmds_rx": {
+          "description": "bayerlink-fpga's own TMDS receiver on a 7-series part (hdl/tmds_rx.v): an MMCM at five times the link clock into BUFIO and BUFR, an IDELAYE2 and a pair of ISERDESE2 a lane, and an alignment made for links that blank every line -- each delay tap of every bit slip given tens of lines to show blanks and count misread tokens, not 50 ms, so a mode change costs a fraction of a second rather than seconds, and each lane samples between the walls of its eye at the least delay -- then the lanes bonded by where their blanking ends, and decoded. Its lanes are the TMDS channels in order. RANGE keeps the MMCM's VCO in specification, as dvi2rgb's kClkRange does.",
+          "vivado": {"module": "tmds_rx"},
+          "sources": ["bayerlink_fpga:hdl/tmds_rx.v", "bayerlink_fpga:hdl/tmds_rx_lane.v", "bayerlink_fpga:hdl/tmds_align.v", "bayerlink_fpga:hdl/tmds_bond.v"],
+          "constraints": [{"file": "bayerlink_fpga:hdl/tmds_rx.xdc", "scoped_to": "tmds_rx"}],
+          "config": {
+            "LINK_KHZ": "link_khz",
+            "RANGE": "1 if link_khz >= 120000 else 2 if link_khz >= 60000 else 3 if link_khz >= 40000 else 4 if link_khz >= 30000 else 5"
+          },
+          "facts": {"lane_map": [0, 1, 2], "vsync_active_high": 1, "refclk_mhz": 200, "min_link_khz": 25000}
+        }
+      }
+    }
+  }
+}

bayerlink_fpga/hdl/axis_spy.v

@@ -0,0 +1,46 @@
+// Copyright 2026 Serge Rabyking
+// SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1
+// Pass-through AXIS spy: wires straight through, remembers what it saw.
+// The status nibble answers the only bring-up question that matters:
+// who is refusing -- the producer (no valid) or the consumer (no ready).
+module axis_spy #(
+    parameter DW = 16
+) (
+    input  wire          clk,
+    input  wire          rst,
+    input  wire          s_axis_tvalid,
+    output wire          s_axis_tready,
+    input  wire [DW-1:0] s_axis_tdata,
+    input  wire [DW/8-1:0] s_axis_tkeep,
+    input  wire          s_axis_tlast,
+    output wire          m_axis_tvalid,
+    input  wire          m_axis_tready,
+    output wire [DW-1:0] m_axis_tdata,
+    output wire [DW/8-1:0] m_axis_tkeep,
+    output wire          m_axis_tlast,
+    output wire [15:0]   status
+);
+    assign m_axis_tvalid = s_axis_tvalid;
+    assign s_axis_tready = m_axis_tready;
+    assign m_axis_tdata  = s_axis_tdata;
+    assign m_axis_tkeep  = s_axis_tkeep;
+    assign m_axis_tlast  = s_axis_tlast;
+
+    reg v_seen, r_seen, beat_seen, last_seen;
+    reg [11:0] beats;
+    always @(posedge clk) begin
+        if (rst) begin
+            v_seen <= 0; r_seen <= 0; beat_seen <= 0; last_seen <= 0;
+            beats <= 0;
+        end else begin
+            if (s_axis_tvalid) v_seen <= 1;
+            if (m_axis_tready) r_seen <= 1;
+            if (s_axis_tvalid && m_axis_tready) begin
+                beat_seen <= 1;
+                beats <= beats + 1;
+            end
+            if (s_axis_tvalid && m_axis_tready && s_axis_tlast) last_seen <= 1;
+        end
+    end
+    assign status = {beats, last_seen, beat_seen, r_seen, v_seen};
+endmodule

bayerlink_fpga/hdl/axis_unpack.v

@@ -0,0 +1,37 @@
+// Copyright 2026 Serge Rabyking
+// SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1
+// The inverse of rx_axis: the 32-bit DMA word format back into the
+// elastic stream, on the far side of a clock converter. Sample in
+// [15:0], eol at 16, sof at 17, last as tlast -- one layout, two
+// directions, rx_axis owns the definition.
+module axis_unpack #(
+    parameter SAMPLE_BITS = 16
+) (
+    (* X_INTERFACE_INFO = "xilinx.com:signal:clock:1.0 clk CLK", X_INTERFACE_PARAMETER = "ASSOCIATED_BUSIF s_axis:out_stream, ASSOCIATED_RESET rst" *)
+    input  wire        clk,
+    (* X_INTERFACE_INFO = "xilinx.com:signal:reset:1.0 rst RST", X_INTERFACE_PARAMETER = "POLARITY ACTIVE_HIGH" *)
+    input  wire        rst,
+    input  wire        s_axis_tvalid,
+    output wire        s_axis_tready,
+    input  wire [31:0] s_axis_tdata,
+    input  wire        s_axis_tlast,
+    (* X_INTERFACE_INFO = "lanserge:interface:np2hw_stream_rtl:1.0 out_stream VALID" *)
+    output wire        out_valid,
+    (* X_INTERFACE_INFO = "lanserge:interface:np2hw_stream_rtl:1.0 out_stream READY" *)
+    input  wire        out_ready,
+    (* X_INTERFACE_INFO = "lanserge:interface:np2hw_stream_rtl:1.0 out_stream DATA" *)
+    output wire [SAMPLE_BITS-1:0] out_data,
+    (* X_INTERFACE_INFO = "lanserge:interface:np2hw_stream_rtl:1.0 out_stream SOF" *)
+    output wire        out_sof,
+    (* X_INTERFACE_INFO = "lanserge:interface:np2hw_stream_rtl:1.0 out_stream EOL" *)
+    output wire        out_eol,
+    (* X_INTERFACE_INFO = "lanserge:interface:np2hw_stream_rtl:1.0 out_stream LAST" *)
+    output wire        out_last
+);
+    assign out_valid     = s_axis_tvalid;
+    assign s_axis_tready = out_ready;
+    assign out_data      = s_axis_tdata[SAMPLE_BITS-1:0];
+    assign out_eol       = s_axis_tdata[16];
+    assign out_sof       = s_axis_tdata[17];
+    assign out_last      = s_axis_tlast;
+endmodule