Release Candidate v2.74.0

.github/workflows/surf_ci.yml

@@ -165,10 +165,15 @@ jobs:
             --ignore=tests/simlink
           )
 
+          # Import once before either run mode. The compliance check consumes
+          # the same ruckus source inventory as the cocotb runner and fails
+          # fast on new structural violations before expensive simulations.
+          make MODULES=$PWD import
+          python -m tests.common.compliance_audit check tests
+
           # Full integration/release runs build and simulate on apt mcode GHDL
           # and collect the coverage consumed by Codecov.
           if [[ "${{ steps.mode.outputs.value }}" == "full" ]]; then
-            make MODULES=$PWD import
             python -m pytest --cov -v -n auto --dist=worksteal "${full_ignores[@]}" "${full_targets[@]}"
             exit 0
           fi
@@ -192,7 +197,6 @@ jobs:
           fi
 
           echo "${selector_output}"
-          make MODULES=$PWD import
 
           if [[ "${selector_rc}" -ne 0 ]] || grep -qx "FORCE_FULL" <<< "${selector_output}"; then
             echo "Directory selector forced a full run (rc=${selector_rc})"
@@ -289,6 +293,41 @@ jobs:
           SIMLINK_ROGUE_PYTHON="$(command -v python)" \
             python -m pytest -q -n 0 tests/simlink/rogue/test_RogueTcpMemoryRogue.py
 
+# ----------------------------------------------------------------------------
+
+  adc_ddr_rogue:
+    name: ADC DDR Rogue Tests
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    defaults:
+      run:
+        shell: bash -el {0}
+
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Setup Miniforge
+        uses: conda-incubator/setup-miniconda@8ee1f361103df19b6f8c8655fd3967a8ecb162d5 # v4.0.1
+        with:
+          miniforge-variant: Miniforge3
+          miniforge-version: latest
+          activate-environment: surf-rogue-test
+          environment-file: conda-rogue.yml
+          auto-activate: false
+          conda-remove-defaults: true
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r pip_requirements.txt
+
+      - name: Run ADC DDR Rogue tests
+        run: |
+          python -c "import rogue, pyrogue; print(rogue.Version.current())"
+          PYTHONPATH="$PWD/python" python -m pytest -q -n 0 \
+            tests/devices/analog_devices/test_AdcDdrCalibration.py \
+            tests/devices/analog_devices/test_AdcDdrModel.py
+
 # ----------------------------------------------------------------------------
 
   docs:
@@ -317,7 +356,7 @@ jobs:
 # ----------------------------------------------------------------------------
 
   gen_release:
-    needs: [lint, test, simlink_rogue, docs]
+    needs: [lint, test, simlink_rogue, adc_ddr_rogue, docs]
     if: startsWith(github.ref, 'refs/tags/')
     uses: slaclab/ruckus/.github/workflows/gen_release.yml@main
     with:
@@ -328,7 +367,7 @@ jobs:
 # ----------------------------------------------------------------------------
 
   conda_build_lib:
-    needs: [lint, test, simlink_rogue, docs]
+    needs: [lint, test, simlink_rogue, adc_ddr_rogue, docs]
     if: startsWith(github.ref, 'refs/tags/')
     uses: slaclab/ruckus/.github/workflows/conda_build_lib.yml@main
     with:

AGENTS.md

@@ -16,7 +16,18 @@ Start with [README.md](README.md) for user-facing links and the source tree inde
 - [protocols/README.md](protocols/README.md) for PGP, SSI, SRP, RSSI, CoaXPress, JESD204B, I2C/SPI/UART, and related protocol cores.
 - [xilinx/README.md](xilinx/README.md) for Xilinx-family primitives, wrappers, and XVC UDP support.
 - [python/README.md](python/README.md) for the PyRogue package under `python/surf`.
-- [tests/README.md](tests/README.md) for cocotb regression layout, methodology comments, helper reuse, and simulator conventions.
+- [tests/README.md](tests/README.md) for the authoritative cocotb regression
+  methodology, coding style, coverage expectations, layout, and simulator
+  conventions.
+- [tests/common/README.md](tests/common/README.md) for the shared pytest/GHDL
+  runner, parameter and environment handling, build isolation, and reusable
+  regression helpers.
+- [tests/protocols/README.md](tests/protocols/README.md) for protocol-oracle,
+  layering, malformed-traffic, ready/valid, and integration-test guidance; then
+  read the nearest subsystem README, such as
+  [tests/protocols/batcher/README.md](tests/protocols/batcher/README.md) or
+  [tests/protocols/rssi/README.md](tests/protocols/rssi/README.md), when working
+  in that area.
 - [docs/plans/README.md](docs/plans/README.md) for substantial task planning, progress notes, and handoff conventions.
 
 Top-level `ruckus.tcl` loads `axi`, `base`, `dsp`, `devices`, `ethernet`, `protocols`, and `xilinx`. Module-level `ruckus.tcl` files should continue to be the source of truth for which HDL files and submodules are part of a build.
@@ -41,6 +52,8 @@ SURF RTL generally follows the two-process style popularized by Gaisler: one com
 - Put registered state in a `RegType` record. Use a `REG_INIT_C` constant for reset/default state, and declare `r` and `rin` signals for current and next state.
 - Name the combinational process `comb` and the sequential process `seq` unless the surrounding file has a stronger local convention.
 - At the top of `comb`, declare `variable v : RegType;` and immediately assign `v := r;`. Make all next-state updates to `v`.
+- Minimize additional process variables. Prefer adding intermediate state or diagnostic values to `RegType` and operating on `v.<field>` directly, even when the registered value is not currently consumed. This keeps the next-state path uniform and makes a useful value straightforward to expose through AXI-Lite later.
+- Use a process-local variable only when it is genuinely clearer or required by a helper, such as `AxiLiteEndpointType`. Give every such scratch variable an unconditional default immediately after `v := r;` before any conditional logic, unless the called helper initializes the complete object before its first use. Never depend on mutually exclusive branches to imply a combinational default; incomplete assignment can infer a latch in synthesis even when simulation and lint pass.
 - Assign `rin <= v;` near the end of `comb`. Drive module outputs from `r` for registered outputs and from `v` only when the local design intentionally exposes next-cycle/combinational behavior.
 - Include all combinational inputs read by the process in the sensitivity list. Existing files often use explicit lists rather than `process(all)`; match nearby style.
 - Apply synchronous reset in `comb` by assigning `v := REG_INIT_C` when `RST_ASYNC_G = false` and reset is asserted.
@@ -169,7 +182,9 @@ C, C++, and C header files should use the same license text with `//` comment de
 
 Tcl, shell, YAML, and other hash-comment files should use the Python-style `#-----------------------------------------------------------------------------` license block when they are maintained SURF source. For executable scripts with a shebang, keep the shebang first and place the license block immediately after it.
 
-Checked-in cocotb regression files must also include the `Test methodology` block described in [tests/README.md](tests/README.md), immediately after the license header.
+New or substantially edited cocotb regression files must also include the
+module-specific `Test methodology` block described in
+[tests/README.md](tests/README.md), immediately after the license header.
 
 ## Python Conventions
 
@@ -200,12 +215,19 @@ Checked-in cocotb regression files must also include the `Test methodology` bloc
 
 ## Tests And Verification
 
-- For RTL regressions, use the guidance in [tests/README.md](tests/README.md). The expected stack is `pytest + cocotb + GHDL + ruckus`.
+- For RTL regressions, start with [tests/README.md](tests/README.md). Use
+  [tests/common/README.md](tests/common/README.md) for runner/build mechanics,
+  [tests/protocols/README.md](tests/protocols/README.md) for protocol tests, and
+  the nearest test-subsystem README for local commands or exceptions. The
+  expected default stack is `pytest + cocotb + GHDL + ruckus`.
 - For docs-only changes, no RTL or Python tests are required, but check links and headings if the edit adds navigation.
 - For ruckus or source-list changes, run `make MODULES="$PWD" import` when practical.
 - For edited VHDL, run `./.venv/bin/vsg -c vsg-linter.yml path/to/file.vhd` and the most focused relevant cocotb/pytest target when practical.
 - For Python/PyRogue changes, run a focused import or pytest that exercises the changed module. Avoid packaging commands unless the task specifically requires packaging validation.
 - For cocotb tests, prefer `./.venv/bin/python -m pytest -q tests/<subsystem-or-file>`. Use `-n 0` when serial simulator logs are needed.
+- Select or explicitly skip cocotb scenarios that do not apply to a parameter case; do not return early and record an unexercised scenario as a pass.
+- Use `extra_vhdl_sources` only for design units absent from the ruckus import, and keep finite cocotb tasks awaited or lifetime agents explicitly owned by the bench.
+- For bug regressions, demonstrate failure on the known-bad RTL when practical, or document the defect-catching assertion and why the comparison could not be run.
 - For protocol or bus behavior changes, include tests or a clear verification note covering sidebands, backpressure, reset behavior, and boundary/error cases relevant to the change.
 - Avoid hand-editing generated or cache directories such as `build/`, `tests/sim_build/`, `.pytest_cache/`, `docs/_build/`, and `docs/_generated/`.
 
@@ -225,7 +247,14 @@ Before considering an RTL change done, check:
 
 ## Documentation Updates
 
-When adding a new subsystem, add or update the closest `README.md` if the layout or usage is not obvious. Keep README files short and navigational: describe what belongs in the folder, important subdirectories, and any local build/test conventions, then link upward through the parent README chain.
+When adding a new subsystem, add or update the closest `README.md` if the layout
+or usage is not obvious. Keep README files short and navigational: describe what
+belongs in the folder, important subdirectories, and any local build/test
+conventions, then link upward through the parent README chain. Test-subsystem
+READMEs should link to [tests/README.md](tests/README.md), and protocol-test
+READMEs should also link to
+[tests/protocols/README.md](tests/protocols/README.md), so local instructions
+extend rather than duplicate the shared methodology.
 
 Add deeper README files as substantial areas are touched, especially in high-traffic module families such as `axi/axi-stream`, `axi/axi-lite`, `protocols/pgp`, `protocols/coaxpress`, `protocols/ssi`, `protocols/srp`, `ethernet/IpV4Engine`, `ethernet/UdpEngine`, and `ethernet/EthMacCore`. Prefer adding the README in the same change that introduces new layout or conventions for that area.
 

axi/README.md

@@ -4,7 +4,7 @@ This tree contains reusable AXI-family RTL and wrappers. Top-level `axi/ruckus.t
 
 ## Layout
 
-- `axi-lite/`: AXI-Lite records, crossbars, endpoints, masters, slaves, monitors, and IP-integrator adapters.
+- [`axi-lite/`](axi-lite/README.md): 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.

axi/axi-lite/README.md

@@ -0,0 +1,52 @@
+# AXI-Lite
+
+This directory contains reusable AXI-Lite records, interconnects, endpoints,
+clock-domain bridges, and IP-integrator adapters.
+
+## Layout
+
+- `rtl/`: AXI-Lite packages and synthesizable cores.
+- `ip_integrator/`: flattened wrappers for block-design and simulator-facing
+  integration.
+- `tb/`: legacy VHDL testbenches.
+
+Executable cocotb regressions live under
+[`tests/axi/axi_lite/`](../../tests/axi/axi_lite/README.md).
+
+## `AxiLiteAsync` Contract
+
+`AxiLiteAsync` directly connects the slave and master interfaces when
+`COMMON_CLK_G = true`. Otherwise, five asynchronous FIFOs carry the read
+request, read response, write address, write data, and write response channels.
+
+The asynchronous bridge permits one read and one write in flight. The write
+address and data channels remain independent, so either may arrive first, but
+each channel accepts only one pending beat until the write response completes.
+The bridge enforces this limit with its READY outputs. External masters that
+pipeline requests are therefore backpressured rather than buffered to the FIFO
+depth.
+
+All five FIFOs share a registered reset request and are flushed when either AXI
+domain resets. Reset handling follows these rules:
+
+- A slave/source-domain reset abandons outstanding source transactions; no
+  response is owed after that reset.
+- A master/destination-domain reset while the slave domain remains active
+  completes each accepted read locally with `AXI_ERROR_RESP_G`.
+- A locally completed write returns `AXI_ERROR_RESP_G` only after both its AW
+  and W beats have been accepted.
+- Transactions discarded by reset are not replayed when the master domain
+  recovers, and stale responses do not survive a slave-domain reset.
+
+A slave/source-domain reset can flush only transactions still held by the
+bridge. It cannot retract a write-address or write-data beat that the
+downstream slave has already accepted. If a system must prevent a partially
+accepted downstream write from surviving reset, it must quiesce AXI-Lite
+traffic before resetting or coordinate reset of the destination domain.
+
+If a clock is unavailable, its corresponding reset must remain asserted. The
+clock must be stable before reset is released, and traffic must remain inactive
+until synchronized reset release completes.
+
+`AxiLiteAsyncIpIntegrator.vhd` exposes the same clocks, resets, and response
+codes through flattened AXI-Lite ports.