Release Candidate v2.72.0

.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# GitHub requests reviews from CODEOWNERS when matching files change.
+# If path-specific rules are added later, include one of these owners on each
+# rule to keep code-owner review required for every PR into pre-release.
+
+* @bengineerd @slacrherbst @ruck314

README.md

@@ -6,6 +6,21 @@ SLAC Ultimate RTL Framework
 
 <!--- ########################################################################################### -->
 
+# Repository Map
+
+- [Agent guidance](AGENTS.md): project layout, coding conventions, and verification notes for contributors and coding agents.
+- [AXI](axi/README.md): AXI-Lite, AXI4, AXI Stream, DMA, bridges, and simulation-link RTL.
+- [Base](base/README.md): foundational packages, CDC, FIFO, RAM, reset, delay, CRC, and generic RTL helpers.
+- [Devices](devices/README.md): vendor and component-specific RTL support.
+- [DSP](dsp/README.md): generic and Xilinx-specific DSP support.
+- [Ethernet](ethernet/README.md): MAC, raw Ethernet, IPv4, UDP, RoCEv2, and high-speed Ethernet cores.
+- [Protocols](protocols/README.md): PGP, SSI, SRP, RSSI, CoaXPress, JESD204B, peripheral buses, and related protocol cores.
+- [Xilinx](xilinx/README.md): Xilinx-family wrappers, primitive integrations, and XVC UDP support.
+- [Python](python/README.md): PyRogue package layout under `python/surf`.
+- [Tests](tests/README.md): cocotb regression layout, methodology, helpers, and simulator conventions.
+
+<!--- ########################################################################################### -->
+
 # Before you clone the GIT repository
 
 Setup for large filesystems on github.  `git-lfs` used for all binary files (example: .dcp)

axi/README.md

@@ -0,0 +1,14 @@
+# AXI
+
+This tree contains reusable AXI-family RTL and wrappers. Top-level `axi/ruckus.tcl` loads the submodules used by SURF builds.
+
+## Layout
+
+- `axi-lite/`: AXI-Lite records, crossbars, endpoints, masters, slaves, monitors, and IP-integrator adapters.
+- `axi-stream/`: AXI Stream records, FIFOs, muxes, monitors, protocol adapters, and stream wrappers.
+- `axi4/`: full AXI4 support blocks and adapters.
+- `bridge/`: bridges between AXI-family buses and SURF protocol records.
+- `dma/`: DMA register, descriptor, FIFO, and stream integration cores.
+- `simlink/`: simulator-link support and C/C++/VHDL pieces used by simulation flows.
+
+Use existing package record types before adding flattened ports. Put durable adapter entities in `ip_integrator/` or `wrappers/`, and keep executable cocotb tests under `tests/axi/`.

axi/axi-lite/rtl/AxiLitePkg.vhd

@@ -262,7 +262,7 @@ package AxiLitePkg is
             connectivity => X"FFFF"));
 
    -------------------------------------------------------------------------------------------------
-   -- Initilize masters with uppder address bits already set to configuration base address
+   -- Initialize masters with upper address bits already set to configuration base address
    -------------------------------------------------------------------------------------------------
    function axiWriteMasterInit (constant config : AxiLiteCrossbarMasterConfigArray) return AxiLiteWriteMasterArray;
    function axiWriteMasterInit (constant config : AxiLiteCrossbarMasterConfigType) return AxiLiteWriteMasterType;

axi/axi-lite/rtl/AxiLiteSequencerRam.vhd

@@ -451,7 +451,7 @@ begin
             end if;
          ----------------------------------------------------------------------
          when SEQ_DONE_S =>
-            -- Set all bits to 1 so SW knowns it done
+            -- Set all bits to 1 so SW knows it done
             v.addr  := (others => '0');
             v.din   := (others => '1');
             v.wstrb := (others => '1');

axi/axi-stream/ip_integrator/AxiStreamFifoV2IpIntegrator.vhd

@@ -66,7 +66,7 @@ entity AxiStreamFifoV2IpIntegrator is
 
       -- Internal FIFO width select, "WIDE", "NARROW" or "CUSTOM"
       -- WIDE uses wider of slave / master. NARROW  uses narrower.
-      -- CUSOTM uses passed FIFO_DATA_WIDTH_G
+      -- CUSTOM uses passed FIFO_DATA_WIDTH_G
       INT_WIDTH_SELECT : string                := "WIDE";
       INT_DATA_WIDTH   : natural range 1 to 16 := 16;
 

axi/axi-stream/rtl/AxiStreamBatchingFifo.vhd

@@ -216,7 +216,7 @@ begin
    ------- END MAIN DATA FIFO -------
    ----------------------------------
 
-   -- These signals are not responsible for hanshakes and can
+   -- These signals are not responsible for handshakes and can
    -- just be forwarded
    combAxisMaster.tData <= axisMasterFifo.tData;
    combAxisMaster.tStrb <= axisMasterFifo.tStrb;

axi/axi-stream/rtl/AxiStreamCompact.vhd

@@ -142,7 +142,7 @@ begin  -- architecture rtl
             -- Reset full flags
             v.fullBus := false;
 
-            -- get tKeet boundaries
+            -- get tKeep boundaries
             tKeepMin   := getTKeepMin(sAxisMaster.tKeep, SLAVE_AXI_CONFIG_G);
             tKeepWidth := getTKeep(sAxisMaster.tKeep, SLAVE_AXI_CONFIG_G);
             tDataWidth := to_integer(shift_left(to_unsigned(tKeepWidth, SLV_BYTES_C), 3));

axi/axi-stream/rtl/AxiStreamConcat.vhd

@@ -4,7 +4,7 @@
 -- Description: Firmware module that AxiStreamConcat multiple AXI stream frames
 --              together.  It will ignore TKEEP and the format of the frame.
 -------------------------------------------------------------------------------
--- Note: This module is similiar to "AxiStreamBatcher.vhd" but does NOT
+-- Note: This module is similar to "AxiStreamBatcher.vhd" but does NOT
 --       have the following features
 --          1) No super header
 --          2) No tail footer

axi/axi-stream/rtl/AxiStreamFifoV2.vhd

@@ -49,7 +49,7 @@ entity AxiStreamFifoV2 is
 
       -- Internal FIFO width select, "WIDE", "NARROW" or "CUSTOM"
       -- WIDE uses wider of slave / master. NARROW  uses narrower.
-      -- CUSOTM uses passed FIFO_DATA_WIDTH_G
+      -- CUSTOM uses passed FIFO_DATA_WIDTH_G
       INT_WIDTH_SELECT_G : string                                          := "WIDE";
       INT_DATA_WIDTH_G   : natural range 1 to AXI_STREAM_MAX_TKEEP_WIDTH_C := 16;
 
@@ -176,7 +176,7 @@ architecture rtl of AxiStreamFifoV2 is
 
 begin
 
-   -- Cant use tkeep_fixed on master side when resizing or if not on slave side
+   -- Can't use tkeep_fixed on master side when resizing or if not on slave side
    assert (not (MASTER_AXI_CONFIG_G.TKEEP_MODE_C = TKEEP_FIXED_C and
                 SLAVE_AXI_CONFIG_G.TKEEP_MODE_C /= TKEEP_FIXED_C))
       report "AxiStreamFifoV2: Can't have TKEEP_MODE = TKEEP_FIXED on master side if not on slave side"
@@ -225,7 +225,7 @@ begin
    -- Is ready enabled?
    fifoReady <= (not fifoAFull) when SLAVE_READY_EN_G else '1';
 
-   -- Output a copy of FIFO WR count incase application needs more than one threshold
+   -- Output a copy of FIFO WR count in case application needs more than one threshold
    fifoWrCnt <= fifoWrCount;
 
    -- Map bits

axi/axi-stream/rtl/AxiStreamFlush.vhd

@@ -2,7 +2,7 @@
 -- Company    : SLAC National Accelerator Laboratory
 -------------------------------------------------------------------------------
 -- Description:
--- Block to flush AXI Stream frames, being mindfull of frame boundaries.
+-- Block to flush AXI Stream frames, being mindful of frame boundaries.
 -- This module is designed to feed into an AxiStreamFifo using pause to determine
 -- backpressure situations.
 -------------------------------------------------------------------------------

axi/axi-stream/rtl/AxiStreamGearbox.vhd

@@ -118,7 +118,7 @@ begin
    assert (SLV_BYTES_C <= MST_BYTES_C or READY_EN_G = true)
       report "READY_EN_G must be true if slave width is great than master" severity failure;
 
-   -- Cant use tkeep_fixed on master side when resizing or if not on slave side
+   -- Can't use tkeep_fixed on master side when resizing or if not on slave side
    assert (not (MASTER_AXI_CONFIG_G.TKEEP_MODE_C = TKEEP_FIXED_C and
                 SLAVE_AXI_CONFIG_G.TKEEP_MODE_C /= TKEEP_FIXED_C))
       report "AxiStreamGearbox: Can't have TKEEP_MODE = TKEEP_FIXED on master side if not on slave side"

axi/axi-stream/rtl/AxiStreamMux.vhd

@@ -47,7 +47,7 @@ entity AxiStreamMux is
       -- Assign a priority for each input stream index.
       -- Higher priority streams will be selected over those with lower priority of both are active.
       -- Format is (index => priority)
-      -- Leave unchanged for equal priority round-robbin
+      -- Leave unchanged for equal priority round-robin
       PRIORITY_G           : IntegerArray            := (0 => 0);
       -- In INDEXED mode, assign slave index to TDEST at this bit offset
       TDEST_LOW_G          : integer range 0 to 7    := 0;
@@ -179,7 +179,7 @@ begin
    end process;
 
    -- When in INDEXED priority mode, tvalid on a given slave side index disables selection
-   -- for all channels with higer index
+   -- for all channels with higher index
    PRIORITY_CONTROL : process (disableSel, sAxisMasters) is
       variable tmp : slv(NUM_SLAVES_G-1 downto 0);
    begin

axi/axi-stream/rtl/AxiStreamResize.vhd

@@ -98,7 +98,7 @@ begin
    assert (SLV_BYTES_C <= MST_BYTES_C or READY_EN_G = true)
       report "READY_EN_G must be true if slave width is great than master" severity failure;
 
-   -- Cant use tkeep_fixed on master side when resizing or if not on slave side
+   -- Can't use tkeep_fixed on master side when resizing or if not on slave side
    assert (not (MASTER_AXI_CONFIG_G.TKEEP_MODE_C = TKEEP_FIXED_C and
                 SLAVE_AXI_CONFIG_G.TKEEP_MODE_C /= TKEEP_FIXED_C))
       report "AxiStreamResize: Can't have TKEEP_MODE = TKEEP_FIXED on master side if not on slave side"

axi/axi-stream/tb/AxiStreamBatchingFifoTb.vhd

@@ -1,7 +1,7 @@
 -------------------------------------------------------------------------------
 -- Company    : SLAC National Accelerator Laboratory
 -------------------------------------------------------------------------------
--- Description: Simulation Testbed for testing the AxiStreamBatchinFifo module
+-- Description: Simulation Testbed for testing the AxiStreamBatchingFifo module
 -------------------------------------------------------------------------------
 -- This file is part of 'SLAC Firmware Standard Library'.
 -- It is subject to the license terms in the LICENSE.txt file found in the

axi/axi4/rtl/AxiReadEmulate.vhd

@@ -146,7 +146,7 @@ begin
       ----------------------------------------------------------------------
       end case;
 
-      -- Combinatoral outputs before reset
+      -- Combinatorial outputs before reset
       intReadSlave <= v.iSlave;
 
       -- Reset

axi/axi4/rtl/AxiReadPathMux.vhd

@@ -139,7 +139,7 @@ begin
             v.master.arcache := selAddr.arcache;
             v.addrState      := S_LAST_C;
 
-         -- Laster transfer
+         -- Last transfer
          when S_LAST_C =>
             if mAxiReadSlave.arready = '1' then
                v.master.arvalid := '0';

axi/axi4/rtl/AxiWritePathMux.vhd

@@ -121,7 +121,7 @@ begin
             v.master.awvalid := '0';
             v.dataReq        := '0';
 
-            -- Aribrate between requesters
+            -- Arbitrate between requesters
             if r.addrValid = '0' then
                arbitrate(addrRequests, r.addrAckNum, v.addrAckNum, v.addrValid, v.addrAcks);
             end if;
@@ -216,7 +216,7 @@ begin
                end if;
             end if;
 
-         -- Laster transfer
+         -- Last transfer
          when S_LAST_C =>
             if mAxiWriteSlave.wready = '1' then
                v.master.wvalid := '0';

axi/axi4/tb/AxiRingBufferTb.vhd

@@ -167,7 +167,7 @@ begin
          axisSlave       => AXI_STREAM_SLAVE_FORCE_C);
 
    --------------------------------------
-   -- Load waveofrm and check the Results
+   -- Load waveform and check the Results
    --------------------------------------
    comb : process (axisMaster, r, rst) is
       variable v : RegType;

axi/dma/ip_integrator/AxiStreamDmaRingReadIpIntegrator.vhd

@@ -23,6 +23,8 @@ use surf.AxiStreamPkg.all;
 use surf.SsiPkg.all;
 
 entity AxiStreamDmaRingReadIpIntegrator is
+   generic (
+      AXI_ADDR_WIDTH_G : positive range 12 to 64 := 16);
    port (
       axilClk         : in  sl;
       axilRst         : in  sl;
@@ -62,7 +64,7 @@ entity AxiStreamDmaRingReadIpIntegrator is
       M_AXIS_TUSER    : out slv(1 downto 0);
       M_AXIS_TREADY   : in  sl;
       M_AXI_ARID      : out slv(0 downto 0);
-      M_AXI_ARADDR    : out slv(15 downto 0);
+      M_AXI_ARADDR    : out slv(AXI_ADDR_WIDTH_G-1 downto 0);
       M_AXI_ARLEN     : out slv(7 downto 0);
       M_AXI_ARSIZE    : out slv(2 downto 0);
       M_AXI_ARBURST   : out slv(1 downto 0);
@@ -101,7 +103,7 @@ architecture rtl of AxiStreamDmaRingReadIpIntegrator is
       tIdBits   => 0);
 
    constant AXI_CONFIG_C : AxiConfigType := axiConfig(
-      ADDR_WIDTH_C => 16,
+      ADDR_WIDTH_C => AXI_ADDR_WIDTH_G,
       DATA_BYTES_C => 4,
       ID_BITS_C    => 1,
       LEN_BITS_C   => 8);
@@ -226,7 +228,7 @@ begin
       generic map (
          EN_ERROR_RESP => true,
          ID_WIDTH      => 1,
-         ADDR_WIDTH    => 16,
+         ADDR_WIDTH    => AXI_ADDR_WIDTH_G,
          DATA_WIDTH    => 32)
       port map (
          M_AXI_ACLK     => axiClk,

axi/dma/ip_integrator/AxiStreamDmaRingWriteIpIntegrator.vhd

@@ -23,6 +23,8 @@ use surf.AxiStreamPkg.all;
 use surf.SsiPkg.all;
 
 entity AxiStreamDmaRingWriteIpIntegrator is
+   generic (
+      AXI_ADDR_WIDTH_G : positive range 12 to 64 := 16);
    port (
       axilClk         : in  sl;
       axilRst         : in  sl;
@@ -69,7 +71,7 @@ entity AxiStreamDmaRingWriteIpIntegrator is
       bufferTriggered : out slv(1 downto 0);
       bufferError     : out slv(1 downto 0);
       M_AXI_AWID      : out slv(0 downto 0);
-      M_AXI_AWADDR    : out slv(15 downto 0);
+      M_AXI_AWADDR    : out slv(AXI_ADDR_WIDTH_G-1 downto 0);
       M_AXI_AWLEN     : out slv(7 downto 0);
       M_AXI_AWSIZE    : out slv(2 downto 0);
       M_AXI_AWBURST   : out slv(1 downto 0);
@@ -112,7 +114,7 @@ architecture rtl of AxiStreamDmaRingWriteIpIntegrator is
       tIdBits   => 0);
 
    constant AXI_CONFIG_C : AxiConfigType := axiConfig(
-      ADDR_WIDTH_C => 16,
+      ADDR_WIDTH_C => AXI_ADDR_WIDTH_G,
       DATA_BYTES_C => 4,
       ID_BITS_C    => 1,
       LEN_BITS_C   => 8);
@@ -239,7 +241,7 @@ begin
       generic map (
          EN_ERROR_RESP => true,
          ID_WIDTH      => 1,
-         ADDR_WIDTH    => 16,
+         ADDR_WIDTH    => AXI_ADDR_WIDTH_G,
          DATA_WIDTH    => 32)
       port map (
          M_AXI_ACLK     => axiClk,

axi/dma/rtl/v1/AxiStreamDmaRingWrite.vhd

@@ -487,7 +487,7 @@ begin
                    statusRamDout, trigRamDout) is
       variable v            : RegType;
       variable axilEndpoint : AxiLiteEndpointType;
-      variable endRamSize   : integer;
+      variable endRamSize   : slv(RAM_DATA_WIDTH_C-1 downto 0);
    begin
       v := r;
 
@@ -571,9 +571,11 @@ begin
             -- Writes always start on a BURST_SIZE_BYTES_G boundary, so can drive low dmaReq.address
             -- bits to zero for optimization.
             v.dmaReq.address(AXI_WRITE_CONFIG_G.ADDR_WIDTH_C-1 downto 0) := v.nextAddr;
-            endRamSize                                                   := conv_integer(endRamDout - v.nextAddr);
+            -- Keep the remaining-bytes math in the vector domain: conv_integer
+            -- overflows for address widths wider than 32 bits.
+            endRamSize                                                   := endRamDout - v.nextAddr;
             if FORCE_WRAP_ALIGN_G and endRamSize < BURST_SIZE_BYTES_G then
-               v.dmaReq.maxSize := toSlv(endRamSize, 32);
+               v.dmaReq.maxSize := resize(endRamSize, 32);
             else
                v.dmaReq.maxSize := toSlv(BURST_SIZE_BYTES_G, 32);
             end if;
@@ -596,10 +598,10 @@ begin
                v.ramWe           := '1';  -- write new values into register ram
 
                -- Increment the stored write pointer by the acknowledged byte
-               -- count. Slice the DMA size back down to the local address
-               -- width so the arithmetic stays range-safe for narrower test
-               -- wrappers and smaller address maps.
-               v.nextAddr := r.nextAddr + dmaAck.size(RAM_DATA_WIDTH_C-1 downto 0);
+               -- count. Resize the DMA size to the local address width so the
+               -- arithmetic stays range-safe for both narrower address maps
+               -- (truncate) and wider than 32-bit address maps (zero-pad).
+               v.nextAddr := r.nextAddr + resize(dmaAck.size, RAM_DATA_WIDTH_C);
                if (v.nextAddr = r.endAddr) then
                   v.status(FULL_C) := '1';
                   if (r.mode(DONE_WHEN_FULL_C) = '1') then

axi/dma/rtl/v1/AxiStreamDmaWrite.vhd

@@ -352,7 +352,7 @@ begin
             if (v.wMaster.awvalid = '0') then
                -- Set the memory address
                v.wMaster.awaddr(AXI_CONFIG_G.ADDR_WIDTH_C-1 downto 0) := r.dmaReq.address(AXI_CONFIG_G.ADDR_WIDTH_C-1 downto 0);
-               -- Bursts after the FIRST are garunteed to be aligned.
+               -- Bursts after the FIRST are guaranteed to be aligned.
                v.wMaster.awlen                                        := AWLEN_C;
                if r.dmaReq.maxSize(31 downto ADDR_LSB_C) < v.wMaster.awlen then
                   v.wMaster.awlen := resize(r.dmaReq.maxSize(ADDR_LSB_C+AXI_CONFIG_G.LEN_BITS_C-1 downto ADDR_LSB_C)-1, 8);

axi/dma/rtl/v2/AxiStreamDmaV2Desc.vhd

@@ -45,7 +45,7 @@ entity AxiStreamDmaV2Desc is
       -- Choose between one-clock arbitration for return descriptors or count and check selection
       DESC_ARB_G : boolean := true;
 
-      -- Choose between infeered or xpm generated descriptor FIFOs
+      -- Choose between inferred or xpm generated descriptor FIFOs
       DESC_SYNTH_MODE_G : string := "inferred";
 
       -- Choose the type of resources for the descriptor FIFOs when DESC_SYNTH_MODE_G="xpm"

axi/dma/rtl/v2/AxiStreamDmaV2Write.vhd

@@ -383,9 +383,28 @@ begin
                   if r.awlen = 0 then
                      -- Set the flag
                      v.wMaster.wlast := '1';
-                     -- If next state has not already been updated go to idle
+                     -- If next state has not already been updated, decide where
+                     -- to go next.
                      if v.state = MOVE_S then
-                        v.state := IDLE_S;
+                        -- If this burst exactly filled the buffer while the
+                        -- frame continues, start the continue here (return the
+                        -- descriptor with continue set) rather than re-entering
+                        -- ADDR_S.  Re-entering ADDR_S with maxSize=0 would issue
+                        -- a stray zero-length burst at the next buffer's base
+                        -- address; on a host DMA that off-by-one write lands
+                        -- past the mapped page and raises an IOMMU page fault.
+                        -- (contEn=0 keeps the legacy overflow/drop path.)
+                        if (v.dmaWrTrack.maxSize(31 downto log2(DATA_BYTES_C)) = 0) and (r.dmaWrTrack.contEn = '1') then
+                           v.continue         := '1';
+                           v.dmaWrTrack.inUse := '0';
+                           if r.dmaWrTrack.metaEnable = '1' then
+                              v.state := META_S;
+                           else
+                              v.state := RETURN_S;
+                           end if;
+                        else
+                           v.state := IDLE_S;
+                        end if;
                      end if;
                   else
                      -- Decrement the transaction counter

base/README.md

@@ -0,0 +1,14 @@
+# Base
+
+This tree contains the foundational RTL used by the rest of SURF. Top-level `base/ruckus.tcl` loads each base library area.
+
+## Layout
+
+- `general/`: common packages and generic utilities such as `StdRtlPkg`, arbiters, muxes, reset pipelines, gearboxes, counters, and watchdog/reset helpers.
+- `sync/`: clock-domain crossing, synchronizers, reset synchronizers, trigger-rate, status, and frequency measurement helpers.
+- `fifo/`: synchronous, asynchronous, muxing, cascade, FWFT, and output-pipeline FIFO blocks.
+- `ram/`: inferred and Xilinx RAM implementations.
+- `delay/`: fixed, RAM-backed, and FIFO-backed delay blocks.
+- `crc/`: CRC packages and implementations.
+
+Most modules use SURF package aliases such as `sl` and `slv`, `_G` generics, `_C` constants, and the local `RegType`/`REG_INIT_C` registered-process style. Reuse these base modules rather than duplicating CDC, FIFO, RAM, reset, or CRC logic in higher-level subsystems.