Release Candidate 4.29.0

.github/workflows/conda_build_lib.yml

@@ -34,11 +34,11 @@ jobs:
     steps:
 
       # This step checks out a copy of your repository.
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: 3.12
 

.github/workflows/conda_build_proj.yml

@@ -38,11 +38,11 @@ jobs:
     steps:
 
       # This step checks out a copy of your repository.
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: 3.12
 

.github/workflows/conda_build_win.yml

@@ -30,11 +30,11 @@ jobs:
     steps:
 
       # This step checks out a copy of your repository.
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: 3.12
 

.github/workflows/docker_build.yml

@@ -33,7 +33,7 @@ jobs:
     steps:
 
       # This step checks out a copy of your repository.
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
 
@@ -45,19 +45,19 @@ jobs:
 
       # Setup docker build environment
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
 
       # Login to GHCR (GitHub Container Registry) / Docker registry
       - name: Login to GHCR / Docker registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
         with:
           registry: ghcr.io
           username: ${{ inputs.gh_username }}
           password: ${{ secrets.GH_TOKEN }}
 
       # Build and push the docker image
       - name: Build and push image to GHCR / Docker registry
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         with:
           context: .
           file: ./docker/${{ inputs.docker_name }}/Dockerfile

.github/workflows/docs.yml

@@ -23,11 +23,11 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: "3.12"
           cache: "pip"
@@ -41,7 +41,7 @@ jobs:
 
       - name: Upload Pages artifact
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        uses: actions/upload-pages-artifact@v5
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
           path: docs/_build/html
 
@@ -60,7 +60,7 @@ jobs:
       # can worsen a wedged Pages backend rather than help it recover.
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v5
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
         continue-on-error: true
 
       - name: Wait before retrying deploy
@@ -70,4 +70,4 @@ jobs:
       - name: Deploy to GitHub Pages (retry)
         id: deployment_retry
         if: steps.deployment.outcome == 'failure'
-        uses: actions/deploy-pages@v5
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

.github/workflows/gen_release.yml

@@ -28,11 +28,11 @@ jobs:
     if: startsWith(github.ref, 'refs/tags/')
     steps:
 
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: 3.12
 

.github/workflows/ruckus_ci.yml

@@ -23,11 +23,11 @@ jobs:
     steps:
 
       # This step checks out a copy of your repository.
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: 3.12
 

docs/how-to/index.rst

@@ -13,6 +13,7 @@ setting up a project for the first time, see
    vitis_hls
    vitis_aie
    ghdl_simulation
+   xsim_rogue_cosim
    cadence_genus
    synopsys_dc
    firmware_release

docs/how-to/xsim_rogue_cosim.rst

@@ -0,0 +1,160 @@
+How to Run the Rogue Co-Simulation in Vivado XSIM
+===================================================
+
+**Goal:** Run the surf Rogue TCP/SideBand co-simulation inside Vivado xsim,
+either interactively in the GUI or in batch mode.
+
+The co-simulation HDL and C sources live in the **surf** submodule under
+``axi/simlink/``; ruckus provides only the build and simulate orchestration
+described here. Any ``axi/simlink/...`` path below is relative to the surf
+submodule root, not ruckus.
+
+.. note::
+
+   This flow is GUI-interactive/local only and requires a licensed Vivado
+   install. It has no CI coverage — verification is manual against a local
+   Vivado + Rogue environment.
+
+Prerequisites
+-------------
+
+- ``libzmq >= 4.1.0`` and ``pkg-config`` on the build machine.
+- A Rogue-environment Python shell for the peer script (it imports
+  ``pyrogue`` / ``rogue``).
+- Vivado 2023.1 or newer — the floor enforced by ``project.tcl``'s
+  ``VersionCheck``. The latest *tested* Vivado release is tracked centrally by
+  ``CheckVivadoVersion`` (see :doc:`../reference/tcl_api`), which warns when the
+  active Vivado is newer; this page intentionally does not restate a version.
+- A surf version that provides the ``axi/simlink/xsim/`` DPI backend. Older
+  surf (legacy ``axi/simlink/sim`` + ``src`` VHPI layout) is VCS-only; use
+  ``make vcs`` there.
+
+Makefile Setup
+--------------
+
+Add the following to your project ``Makefile``:
+
+.. code-block:: makefile
+
+   include $(TOP_DIR)/submodules/ruckus/system_vivado.mk
+
+No additional variables are required. The co-sim hook is registered
+unconditionally by ``project.tcl`` and is a fast no-op for any project that
+doesn't contain a Rogue co-sim source.
+
+.. note::
+
+   ``make xsim`` and ``make gui`` automatically select the surf xsim DPI-C
+   backend (they export ``RUCKUS_SIM_BACKEND=xsim``), so having Synopsys VCS
+   sourced in the same shell alongside Vivado — common in a combined setup
+   script — no longer misroutes the flow to the VCS/VHPI backend. Switching
+   between this xsim flow and ``make vcs`` in the same build directory swaps
+   the backend automatically; no ``make clean`` is needed.
+
+Steps
+-----
+
+1. **Launch the GUI (or run batch xsim):**
+
+   .. code-block:: bash
+
+      make gui
+
+   For a headless batch run, name the demo testbench and let the simulation
+   free-run so the peer can connect and drive it:
+
+   .. code-block:: bash
+
+      make xsim VIVADO_PROJECT_SIM=RogueTcpStreamXsimDemoTb
+
+   The batch path elaborates ``VIVADO_PROJECT_SIM`` (default ``$(PROJECT)``,
+   the synthesis top), so it must name the demo testbench. The run length is
+   ``VIVADO_PROJECT_SIM_TIME``, whose default ``all`` free-runs until the
+   testbench calls ``$finish``/``$stop`` or is interrupted. The demo
+   testbenches have neither, so the run does not self-terminate — background
+   it, wait for the ``Listening on ports N & N+1`` print, start the peer, then
+   stop the simulation once the peer reports its result. To bound a run
+   instead, pass a time value, e.g. ``VIVADO_PROJECT_SIM_TIME="1000 ns"``.
+
+   Either target triggers ruckus's pre-compile hook, which detects any of
+   ``RogueTcpStream.vhd``, ``RogueTcpMemory.vhd``, or ``RogueSideBand.vhd`` in
+   the simulation sources, builds the combined ``RogueTcpDpi.so`` via ``xsc``,
+   and binds it with ``-sv_lib RogueTcpDpi`` — no manual build step.
+
+2. **Watch the console for the build and bind:**
+
+   Confirm the ``pkg-config``/``xsc`` build messages appear with no errors,
+   and, after ``launch_simulation``/``run``, the module's one-time
+   ``Listening on ports N & N+1`` print — that is the ready-for-peer signal.
+
+3. **Start the matching Rogue peer script:**
+
+   .. code-block:: bash
+
+      python3 prbsLoopbackDemo.py
+
+   Run this in a separate terminal, pointed at the same host/port the demo
+   testbench is listening on. Ruckus and the DPI hook are entirely automatic
+   up to this point; starting the peer and, if switching modules, selecting
+   the desired top-level testbench in the target's ``ruckus.tcl``
+   (``set_property top``) are the only manual steps.
+
+4. **Observe the waveform:**
+
+   Data movement between the DPI adapter and the peer confirms the round
+   trip.
+
+Key Variables
+-------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 15 63
+
+   * - Variable
+     - Default
+     - Description
+   * - ``VIVADO_PROJECT_SIM``
+     - ``$(PROJECT)``
+     - Top module for Vivado simulation. Set to the demo testbench (e.g.
+       ``RogueTcpStreamXsimDemoTb``) for a batch ``make xsim`` co-sim run.
+   * - ``VIVADO_PROJECT_SIM_TIME``
+     - ``all``
+     - Simulation run length. The default ``all`` free-runs until the
+       testbench calls ``$finish``/``$stop`` or is interrupted — required for
+       co-sim so the external peer can drive the testbench. Pass a time value
+       (e.g. ``1000 ns``) to bound the run instead.
+
+There is no co-sim-specific variable — the DPI hook auto-registers and
+auto-detects, so the existing simulation variables above are the only ones
+relevant to this flow.
+
+Troubleshooting
+----------------
+
+**"libzmq package was not found"**
+   .. code-block:: text
+
+      libzmq package was not found
+      Please make sure that you have libzmq installed
+      or have sourced the necessary rogue setup scripts
+
+   Install libzmq, or source the Rogue setup scripts that put it on
+   ``PKG_CONFIG_PATH``, then re-run ``make gui``/``make xsim``.
+
+**"no axi/simlink/xsim/ DPI co-simulation backend" at compile**
+   The surf version in your project predates the xsim DPI backend (legacy
+   ``axi/simlink/sim`` + ``src`` VHPI layout). The Vivado xsim co-sim requires
+   a surf that provides ``axi/simlink/xsim/``. Use ``make vcs`` for VCS
+   co-simulation with that surf version, or update surf.
+
+**"DPI function ... not found" at elaboration**
+   The ``.so`` is stale, ``-sv_lib`` was not bound, or the module-detection
+   guard did not fire because none of the three Rogue ``.vhd`` files are
+   present in the simulation sources. Confirm the module's source is in the
+   sim compile order and re-run the build.
+
+**Waveform runs with no data movement**
+   The peer script has not connected. Confirm it is running against the
+   correct host/port pair and that push/pull directions are not swapped —
+   see the port table in ``axi/simlink/README.md`` in surf.

docs/reference/makefile_reference.rst

@@ -29,7 +29,7 @@ Targets
    * - ``dcp``
      - Synthesis + DCP export (sets ``SYNTH_DCP=1``). Exports the post-synthesis checkpoint.
    * - ``gui``
-     - Open the Vivado project in GUI mode.
+     - Open the Vivado project in GUI mode. Automatically detects and builds the Rogue TCP/SideBand co-simulation DPI library when present; see :doc:`../how-to/xsim_rogue_cosim`.
    * - ``interactive``
      - Open Vivado in TCL interactive mode.
    * - ``sources``
@@ -46,10 +46,8 @@ Targets
      - Generate PyRogue tarball.
    * - ``yaml``
      - Generate CPSW YAML tarball.
-   * - ``wis``
-     - Generate ``init_wis.tcl`` for Windows Vivado initialisation.
    * - ``xsim``
-     - Run Vivado XSIM simulation.
+     - Run Vivado XSIM simulation. Automatically detects and builds the Rogue TCP/SideBand co-simulation DPI library when present; see :doc:`../how-to/xsim_rogue_cosim`.
    * - ``vcs``
      - Generate VCS simulation scripts.
    * - ``msim``
@@ -298,15 +296,22 @@ Simulation Variables
 
 .. envvar:: VIVADO_PROJECT_SIM
 
-   Top module name for Vivado simulation.
+   Top module name for Vivado simulation. For a batch Rogue co-sim, set this to
+   the demo testbench (e.g. ``RogueTcpStreamXsimDemoTb``); see
+   :doc:`../how-to/xsim_rogue_cosim`.
 
    :default: ``$(PROJECT)``
 
 .. envvar:: VIVADO_PROJECT_SIM_TIME
 
-   Default simulation run time.
+   Simulation run length. The default ``all`` free-runs until the testbench
+   calls ``$finish``/``$stop`` or is interrupted; a testbench with neither
+   (and a free-running clock) never self-terminates, so a batch ``make xsim``
+   must be stopped manually. Pass a time value (e.g. ``1000 ns``) to bound the
+   run. ``all`` is required for the Rogue co-sim so the external peer can drive
+   the testbench — see :doc:`../how-to/xsim_rogue_cosim`.
 
-   :default: ``1000 ns``
+   :default: ``all``
 
 .. envvar:: SIM_CARGS_VERILOG
 

system_vivado.mk

@@ -106,11 +106,18 @@ export USE_SEGMENTED_CONFIG = 0
 endif
 
 # Vivado Simulation Variables
+# When left undefined, the sim_1 top is auto-picked-up from the project
+# (i.e. the "set_property top ... [get_filesets sim_1]" in the target's
+# ruckus.tcl). Define VIVADO_PROJECT_SIM only to override that top.
 ifndef VIVADO_PROJECT_SIM
-export VIVADO_PROJECT_SIM = $(PROJECT)
+export VIVADO_PROJECT_SIM =
 endif
+# Default sim run length. "all" runs until the testbench calls finish/stop or
+# is interrupted; a time value (e.g. "1000 ns") runs that long. Testbenches
+# without a finish/stop free-run under "all", so a batch "make xsim" there must
+# be stopped manually.
 ifndef VIVADO_PROJECT_SIM_TIME
-export VIVADO_PROJECT_SIM_TIME = 1000 ns
+export VIVADO_PROJECT_SIM_TIME = all
 endif
 
 # Synthesis Variables
@@ -400,12 +407,13 @@ yaml : $(SOURCE_DEPEND)
 	@cd $(OUT_DIR); tclsh $(RUCKUS_DIR)/vivado/cpsw.tcl
 
 ###############################################################
-#### Vivado WIS ###############################################
+#### Rogue Co-Simulation Backend ##############################
 ###############################################################
-.PHONY : wis
-wis : $(SOURCE_DEPEND)
-	$(call ACTION_HEADER,"Generating init_wis.tcl file for Windows OS")
-	@cd $(OUT_DIR); vivado -mode batch -source $(RUCKUS_DIR)/vivado/wis.tcl
+# Tell surf/axi/simlink/ruckus.tcl which Rogue co-sim backend the invoked
+# target wants. Target-specific + exported so it propagates to the shared
+# $(SOURCE_DEPEND) prerequisite recipe and into the vivado subprocess.
+xsim gui : export RUCKUS_SIM_BACKEND := xsim
+vcs      : export RUCKUS_SIM_BACKEND := vcs
 
 ###############################################################
 #### Vivado XSIM Simulation ###################################