Relation to axi-pcie-core

pgp-pcie-apps is a downstream consumer of axi-pcie-core. This page draws the boundary so you know which repo to look at for a given question.

What Lives Where

axi-pcie-core (the library, submodule)

Everything in firmware/submodules/axi-pcie-core/ is owned by the slaclab/axi-pcie-core repository. It provides:

• PCIe PHY wrapping — per-board pre-compiled Vivado .dcp checkpoints under hardware/<Board>/pcie/.

• AXI-Stream DMA engine — AxiPcieDma + AxiStreamDmaV2, shared across all boards.

• BAR0 register crossbar — AxiPcieReg plus PROM access (SPI, BPI), sysmon, I2C, AxiVersion.

• Board-management Python — the axipcie PyRogue package (AxiPcieCore, AxiPcieRoot, CmsSubsystem, etc.).

Look at the axi-pcie-core documentation for questions about:

• “How does the DMA engine work?” → explanation/pcie_dma_model.

• “What does BAR0 look like?” → reference/register_map.

• “How do I open a connection from Python?” → how-to/use_pyrogue.

• “What boards does axi-pcie-core support, and what are their PCIe gen/lane/memory profiles?” → reference/supported_boards.

• “How do I add a new board to axi-pcie-core itself?” → how-to/add_new_board.

pgp-pcie-apps (this repo)

Everything outside firmware/submodules/ belongs here. It provides:

• Per-board, per-protocol build targets under firmware/targets/<Board>/<Target>/.

• Shared protocol RTL under firmware/common/<proto>/ (PGP2b, PGP3, PGP4, HTSP).

• PrbsTester application under firmware/common/PrbsTester/.

• PyRogue test scripts under software/scripts/ that drive PGP/HTSP/PRBS traffic through the axi-pcie-core DMA engine.

Look at this documentation for questions about:

• “How do I build a bitstream for my board?” → First Build — XilinxVariumC1100DmaLoopback.

• “How do I change protocol or line rate on an existing target?” → Select a Protocol — PGP2b vs PGP3 vs PGP4 vs HTSP and Add a New Line Rate.

• “Which target directory should I copy from?” → Supported Targets.

• “What does the PGP RX/TX path look like?” → Data Flow.

• “What scripts are in software/scripts/ and what do they do?” → PyRogue Scripts.

How They Interact

The target top-level VHDL (in firmware/targets/<Board>/<Target>/hdl/) instantiates both sides:

-- from axi-pcie-core: PCIe DMA + board management
U_Core : entity axi_pcie_core.XilinxVariumC1100Core
   generic map (
      BUILD_INFO_G      => BUILD_INFO_C,
      DMA_AXIS_CONFIG_G => DMA_AXIS_CONFIG_C,
      DMA_SIZE_G        => 1)
   port map ( ... );

-- from pgp-pcie-apps: the protocol layer
U_Hardware : entity work.Hardware
   generic map (
      DMA_AXIS_CONFIG_G => DMA_AXIS_CONFIG_C,
      RATE_G            => "6.25Gbps")
   port map ( ... );

The DMA streams from U_Core connect to U_Hardware; the application AXI-Lite master pair from U_Core is routed through the top-level crossbar to U_Hardware and any utility slaves.

When to Update Which Repo

• Fixing a DMA, PROM, AxiVersion, or PCIe PHY bug → axi-pcie-core.

• Fixing a PGP framing, QPLL, or per-VC FIFO bug → pgp-pcie-apps (firmware/common/<proto>/shared/rtl/).

• Adding a new board with a new PCIe variant → axi-pcie-core first, then add per-protocol hardware/<Board>/ adapters and target directories in pgp-pcie-apps.

• Adding a new line rate for an existing (board, protocol) pair → pgp-pcie-apps only (clone an existing target).

Version Coordination

pgp-pcie-apps pins axi-pcie-core to a specific commit via .gitmodules. Bumping the pin is a deliberate, atomic operation:

cd firmware/submodules/axi-pcie-core
git fetch origin
git checkout <tag>
cd -
git add firmware/submodules/axi-pcie-core
git commit -m "updating to axi-pcie-core (<tag>)"

The repository’s recent commit history shows examples of this pattern. shared/ruckus.tcl inside axi-pcie-core enforces minimum versions of ruckus and surf — bumping the axi-pcie-core pin may require also bumping those.