Directory Layout

The repository decomposes work into three top-level trees:

pgp-pcie-apps/
    firmware/
        common/                # Shared RTL by protocol
            pgp2b/
            pgp3/
            pgp4/
            htsp/
            PrbsTester/        # Common PRBS application
        submodules/
            ruckus/            # TCL build system
            surf/              # SLAC RTL library
            axi-pcie-core/     # PCIe DMA + board support
        targets/               # One subdirectory per build target
            shared_config.mk   # PRJ_VERSION, RELEASE
            XilinxVariumC1100/
            XilinxKcu1500/
            ...
    software/
        scripts/               # PyRogue host-side scripts
        setup_env_slac.sh      # SLAC env activation
        cds_env_setup.sh       # PCDS/CDS env activation
    docs/                      # This documentation site

Key Directories

firmware/targets/<Board>/<Target>/: A self-contained build unit for one (Board, Protocol, Rate) tuple. Contains hdl/<Target>.vhd (top-level entity), hdl/<Target>.xdc (pin/timing constraints), ruckus.tcl (build script), Makefile (per-target PRJ_PART), and vivado/promgen.tcl (PROM generation recipe). tb/ is present for DmaLoopback variants.
firmware/common/<proto>/hardware/<Board>/core/Hardware.vhd: Board-specific adapter for one protocol on one board. A thin wrapper over firmware/common/<proto>/shared/rtl/Pgp[Gty]LaneWrapper (or HtspWrapper).
firmware/common/<proto>/shared/rtl/: Protocol-common lane logic — PgpLaneRx, PgpLaneTx, GT-family wrappers in gtyUs+/ (UltraScale+) and gthUs/ (UltraScale).
firmware/common/PrbsTester/: In-hardware PRBS application: PrbsLane, Hardware.vhd, and timing constraints. Used by the *PrbsTester targets.
firmware/submodules/axi-pcie-core/: PCIe DMA + board management RTL and PyRogue device tree. See its own documentation at https://slaclab.github.io/axi-pcie-core/.
software/scripts/: PyRogue host-side test and monitoring scripts — see PyRogue Scripts.

Build Outputs

ruckus splits build artefacts across two locations:

Working tree — firmware/build/<TargetName>/. Contains the Vivado .xpr project, runs/synth_1/, runs/impl_1/, checkpoints, logs. Gitignored.
Image tree — firmware/targets/<Board>/<Target>/images/. Contains the final .bit and .mcs (or .bit.gz / .mcs.gz when the GZIP env vars are set). Also gitignored — bitstreams are not committed; they are shipped via the release pipeline.

Submodule Pinning

Submodule pins live in .gitmodules plus the commit SHA recorded at the submodule path. The submodule version locks enforced by firmware/submodules/axi-pcie-core/shared/ruckus.tcl are:

ruckus >= 4.24.2
surf >= 2.71.0

Bypass via OVERRIDE_SUBMODULE_LOCKS=1 for development only.