slaclab · ruck314 · May 15, 2026 · May 15, 2026 · May 15, 2026 · May 16, 2026
diff --git a/AGENTS.md b/AGENTS.md
diff --git a/README.md b/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)

diff --git a/axi/README.md b/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/`.
diff --git a/axi/axi-lite/rtl/AxiLitePkg.vhd b/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;

diff --git a/axi/axi-lite/rtl/AxiLiteSequencerRam.vhd b/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');

diff --git a/axi/axi-stream/ip_integrator/AxiStreamFifoV2IpIntegrator.vhd b/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;
 

diff --git a/axi/axi-stream/rtl/AxiStreamBatchingFifo.vhd b/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;

diff --git a/axi/axi-stream/rtl/AxiStreamCompact.vhd b/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));

diff --git a/axi/axi-stream/rtl/AxiStreamConcat.vhd b/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

diff --git a/axi/axi-stream/rtl/AxiStreamFifoV2.vhd b/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

diff --git a/axi/axi-stream/rtl/AxiStreamFlush.vhd b/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.
 -------------------------------------------------------------------------------

diff --git a/axi/axi-stream/rtl/AxiStreamGearbox.vhd b/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"

diff --git a/axi/axi-stream/rtl/AxiStreamMux.vhd b/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

diff --git a/axi/axi-stream/rtl/AxiStreamResize.vhd b/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"

diff --git a/axi/axi-stream/tb/AxiStreamBatchingFifoTb.vhd b/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

diff --git a/axi/axi4/rtl/AxiReadEmulate.vhd b/axi/axi4/rtl/AxiReadEmulate.vhd
@@ -146,7 +146,7 @@ begin
       ----------------------------------------------------------------------
       end case;
 
-      -- Combinatoral outputs before reset
+      -- Combinatorial outputs before reset
       intReadSlave <= v.iSlave;
 
       -- Reset

diff --git a/axi/axi4/rtl/AxiReadPathMux.vhd b/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';

diff --git a/axi/axi4/rtl/AxiWritePathMux.vhd b/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';

diff --git a/axi/axi4/tb/AxiRingBufferTb.vhd b/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;

diff --git a/axi/dma/rtl/v1/AxiStreamDmaWrite.vhd b/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);

diff --git a/axi/dma/rtl/v2/AxiStreamDmaV2Desc.vhd b/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"

diff --git a/base/README.md b/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.
diff --git a/base/delay/rtl/SlvDelayRam.vhd b/base/delay/rtl/SlvDelayRam.vhd
@@ -1,13 +1,34 @@
 -------------------------------------------------------------------------------
 -- Company    : SLAC National Accelerator Laboratory
 -------------------------------------------------------------------------------
--- Description: Shift Register Delay module for std_logic_vector
---              Uses a counter and single port RAM (distributed, block, ultra)
---              Single port RAM setup in read first mode
---              Counter counts 0...maxCount
---              Optional data out register (DO_REG_G) on the RAM
+-- Description: Runtime-configurable delay line for std_logic_vector data.
 --
---              delay = maxCount + ite(DO_REG_G, 3, 2)
+--              SlvDelayRam stores each accepted din sample in an inferred
+--              single-port RAM and reads back the sample located at the
+--              current circular address.  The RAM is used in read-before-write
+--              mode, so the visible output is the sample captured on an
+--              earlier visit to the same address.  The address counter wraps
+--              when it reaches the registered maxCount value, which sets the
+--              requested delay depth.  The en input freezes the address
+--              counter, maxCount register, RAM write, and output update.
+--
+--              DO_REG_G adds an output register after the RAM read data.
+--              With the current implementation, the observable delay is:
+--
+--                 delay = maxCount + ite(DO_REG_G, 3, 2)
+--
+--              maxCount is sampled while en is asserted and is intended to be
+--              programmed during initialization or while the module is held in
+--              reset.  If maxCount is changed while traffic is flowing, the
+--              circular address phase is not automatically realigned.  The
+--              transition samples are therefore undefined, and shrinking
+--              maxCount below the current address can violate the internal
+--              counter range in simulation.  Software or firmware that changes
+--              maxCount at runtime must assert rst afterward and should discard
+--              any pre-reset output history before relying on dout again.  In
+--              practice, allow at least one newly configured delay interval
+--              after reset release before treating dout as aligned to the new
+--              maxCount setting.
 -------------------------------------------------------------------------------
 -- This file is part of 'SLAC Firmware Standard Library'.
 -- It is subject to the license terms in the LICENSE.txt file found in the

diff --git a/base/general/rtl/TextUtilPkg.vhd b/base/general/rtl/TextUtilPkg.vhd
@@ -199,7 +199,7 @@ package body TextUtilPkg is
    -- converts an integer into a character
    -- for 0 to 9 the obvious mapping is used, higher
    -- values are mapped to the characters A-Z
-   -- (this is usefull for systems with base > 10)
+   -- (this is useful for systems with base > 10)
    -- (adapted from Steve Vogwell's posting in comp.lang.vhdl)
    function chr(intValue : integer) return character is
       variable c : character;

diff --git a/base/ram/xilinx/SinglePortRamPrimitive.vhd b/base/ram/xilinx/SinglePortRamPrimitive.vhd
@@ -1,7 +1,7 @@
 -------------------------------------------------------------------------------
 -- Company    : SLAC National Accelerator Laboratory
 -------------------------------------------------------------------------------
--- Description: Manual instantation of RAM32X1S, RAM64X1S, RAM128X1S,
+-- Description: Manual instantiation of RAM32X1S, RAM64X1S, RAM128X1S,
 --                 RAM256X1S, or RAM512X1S.
 -------------------------------------------------------------------------------
 -- This file is part of 'SLAC Firmware Standard Library'.

diff --git a/devices/AnalogDevices/ad9249/7Series/rtl/Ad9249ReadoutGroup.vhd b/devices/AnalogDevices/ad9249/7Series/rtl/Ad9249ReadoutGroup.vhd
@@ -230,17 +230,17 @@ begin
       axiSlaveWaitTxn(axilEp, axilWriteMaster, axilReadMaster, v.axilWriteSlave, v.axilReadSlave);
 
       -- Up to 8 delay registers
-      -- Write delay values to IDELAY primatives
+      -- Write delay values to IDELAY primitives
       -- All writes go to same r.delay register,
-      -- dataDelaySet(i) or frameDelaySet enables the primative write
+      -- dataDelaySet(i) or frameDelaySet enables the primitive write
       for i in 0 to NUM_CHANNELS_G-1 loop
          axiSlaveRegister(axilEp, X"00"+toSlv((i*4), 8), 0, v.delay);
          axiSlaveRegister(axilEp, X"00"+toSlv((i*4), 8), 5, v.dataDelaySet(i), '1');
       end loop;
       axiSlaveRegister(axilEp, X"20", 0, v.delay);
       axiSlaveRegister(axilEp, X"20", 5, v.frameDelaySet, '1');
 
-      -- Override read from r.delay and use curDealy output from delay primative instead
+      -- Override read from r.delay and use curDelay output from delay primitive instead
       for i in 0 to NUM_CHANNELS_G-1 loop
          axiSlaveRegisterR(axilEp, X"00"+toSlv((i*4), 8), 0, axilR.curDelayData(i));
       end loop;

diff --git a/devices/AnalogDevices/ad9249/UltraScale/rtl/Ad9249ReadoutGroup.vhd b/devices/AnalogDevices/ad9249/UltraScale/rtl/Ad9249ReadoutGroup.vhd
@@ -71,7 +71,7 @@ entity Ad9249ReadoutGroup is
       adcStreamClk : in  sl;
       adcStreams   : out AxiStreamMasterArray(NUM_CHANNELS_G-1 downto 0) :=
       (others                                                      => axiStreamMasterInit((false, 2, 8, 0, TKEEP_NORMAL_C, 0, TUSER_NORMAL_C)));
-      -- optional ready to allow evenout samples readout in adcStreamClk
+      -- optional ready to allow even out samples readout in adcStreamClk
       adcReady     : in  slv(NUM_CHANNELS_G-1 downto 0) := (others => '1'));
 end Ad9249ReadoutGroup;
 
@@ -251,17 +251,17 @@ begin
       axiSlaveWaitTxn(axilEp, axilWriteMaster, axilReadMaster, v.axilWriteSlave, v.axilReadSlave);
 
       -- Up to 8 delay registers
-      -- Write delay values to IDELAY primatives
+      -- Write delay values to IDELAY primitives
       -- All writes go to same r.delay register,
-      -- dataDelaySet(i) or frameDelaySet enables the primative write
+      -- dataDelaySet(i) or frameDelaySet enables the primitive write
       for i in 0 to NUM_CHANNELS_G-1 loop
          axiSlaveRegister(axilEp, X"00"+toSlv((i*4), 8), 0, v.delay);
          axiSlaveRegister(axilEp, X"00"+toSlv((i*4), 8), 9, v.dataDelaySet(i), '1');
       end loop;
       axiSlaveRegister(axilEp, X"20", 0, v.delay);
       axiSlaveRegister(axilEp, X"20", 9, v.frameDelaySet, '1');
 
-      -- Override read from r.delay and use curDealy output from delay primative instead
+      -- Override read from r.delay and use curDelay output from delay primitive instead
       for i in 0 to NUM_CHANNELS_G-1 loop
          axiSlaveRegisterR(axilEp, X"00"+toSlv((i*4), 8), 0, curDelayData(i));
       end loop;

diff --git a/devices/AnalogDevices/ad9249/UltraScale/rtl/Ad9249ReadoutGroup2.vhd b/devices/AnalogDevices/ad9249/UltraScale/rtl/Ad9249ReadoutGroup2.vhd
@@ -304,7 +304,7 @@ begin
 
       axiSlaveWaitTxn(axilEp, axilWriteMaster, axilReadMaster, v.axilWriteSlave, v.axilReadSlave);
 
-      -- Write delay values to IDELAY primatives
+      -- Write delay values to IDELAY primitives
       -- Overriding gearbox aligner
       -- All writes go to same r.delay register,
       axiSlaveRegister(axilEp, X"00", 0, v.delay);