Integrate axi-pcie-core as a Git Submodule

This page covers the bare integration recipe: adding axi-pcie-core to a downstream firmware project as a git submodule and wiring it into the ruckus build system. For an end-to-end build walkthrough that shows the result in action, see First Build.

Add the Submodule

Add axi-pcie-core at the conventional path used by SLAC firmware projects:

git submodule add https://github.com/slaclab/axi-pcie-core firmware/submodules/axi-pcie-core
git submodule update --init --recursive

The git submodule update --init --recursive step also initialises the transitive submodules that axi-pcie-core depends on (surf, ruckus).

Wire it into ruckus.tcl

In your project’s board-level ruckus.tcl, source the ruckus environment then load axi-pcie-core for the target board. The snippet below follows the pattern used by existing board targets (see hardware/XilinxKcu1500/ruckus.tcl for a worked example):

# Load RUCKUS environment and library
source $::env(RUCKUS_PROC_TCL)

# Load axi-pcie-core shared RTL, protocol, and board support
loadRuckusTcl "$::DIR_PATH/../submodules/axi-pcie-core/hardware/<BoardName>"

# Load your project's top-level RTL into the axi_pcie_core library
loadSource -lib axi_pcie_core -dir "$::DIR_PATH/rtl"

Replace <BoardName> with the directory name matching your PCIe carrier (for example XilinxKcu1500, XilinxVariumC1100, XilinxAlveoU200). The full list of supported board directory names is in Supported Boards.

The loadRuckusTcl call chains into hardware/<BoardName>/ruckus.tcl, which in turn sources shared/ruckus.tcl (shared/ruckus.tcl). That shared script loads all board-agnostic RTL (AxiPcieDma, AxiPcieReg, AxiPcieCrossbar, and related modules) into the axi_pcie_core VHDL library. Your project’s loadSource -lib axi_pcie_core line then adds your board-level wrapper on top.

Submodule Version Locks

shared/ruckus.tcl calls SubmoduleCheck to enforce minimum versions of the other SLAC firmware submodules:

  • surf >= 2.71.0

  • ruckus >= 4.24.2

If your project’s pinned submodule revisions do not satisfy these constraints, the build will exit with an error from SubmoduleCheck. To bypass the check during development, set the environment variable OVERRIDE_SUBMODULE_LOCKS=1 before invoking make. This override is not recommended for production builds.

See Also

  • First Build — end-to-end build walkthrough on XilinxVariumC1100 using pgp-pcie-apps as the downstream consumer

  • Board Support — explanation of the per-board directory layout (hardware/<Board>/ruckus.tcl chain, PCIe variant subdirectories, DDR/HBM optional modules) and the ruckus integration pattern