Advanced: project structure and customization

This section is intended for users who want to modify the reference designs — adding IP to the block design, changing constraints, adding packages or drivers to the PetaLinux project, and so on. It describes how the repository is laid out, how the build flow works, how the PetaLinux BSPs are composed from layered fragments, and what modifications have been added on top of the stock AMD BSPs.

The actual build instructions are in build_instructions; this section is about understanding the project well enough to modify it.

Repository layout

.
├── build.py                   <- Cross-platform build runner (the build logic)
├── build.sh / build.bat       <- Shims that invoke build.py (Linux/git bash, Windows)
├── Makefile                   <- Deprecated thin wrapper around build.sh (removed next version)
├── README.md
├── config/                    <- Source-of-truth design metadata and auto-generation
│   ├── data.json
│   └── update.py
├── docs/                      <- This documentation (Sphinx + Read the Docs)
├── PetaLinux/
│   └── bsp/                   <- Per-board and per-port-config BSP fragments
│       ├── uzev/, vck190/, …  <-   board-specific overlays
│       └── ports-0/, ports-0123/, ports-versal-0123/   <- port-config overlays
└── Vivado/
    ├── scripts/
    │   ├── build.tcl          <- Project creation + block design assembly
    │   └── xsa.tcl            <- Synthesis, implementation, XSA export
    └── src/
        ├── bd/
        │   ├── bd_zynqmp.tcl  <- Block design for all ZynqMP targets
        │   └── bd_versal.tcl  <- Block design for all Versal targets
        └── constraints/
            └── <target>.xdc   <- One XDC per target (pin assignments, timing)

Per-target build outputs are written to Vivado/<target>/ and PetaLinux/<target>/; packaged boot-image zips are written to bootimages/. None of these are committed.

Target naming

A target label is the canonical handle for a single design and is passed to every build command via --target. It encodes the board, the FMC connector (where the board has more than one), and the line rate where ambiguous:

<board>[_<connector>][_25g]

Examples: uzev, vck190_fmcp1, zcu102_hpc0, vpk120_25g. The absence of a _25g suffix means 10G. The first underscore-delimited token is taken as the target board and is what the build runner uses to select the BSP under PetaLinux/bsp/<board>/.

The complete list of valid targets comes from config/data.json; run ./build.sh list (or ./build.sh labels for one per line) to print it.

config/data.json and config/update.py

config/data.json is the canonical source of truth for the set of supported designs and their per-target metadata (board name, board URL, line rate, FMC connector, GT lane mapping, etc.). The build.py runner reads it directly at runtime, so the target list is never hand-maintained.

config/update.py reads data.json and regenerates the auto-managed documentation and metadata that is not read at runtime: the target tables in the top-level README.md, the .gitignore, and the per-board sections still embedded in PetaLinux/Makefile — each delimited by UPDATER START / UPDATER END comment markers.

When adding or modifying a target, edit data.json and re-run update.py. Do not hand-edit content between the UPDATER START / UPDATER END markers; it will be overwritten on the next regeneration.

Build runner

All build stages are driven by the cross-platform build.py runner at the root of the repository, invoked through the build.sh shim on Linux / git bash or build.bat on Windows (identical arguments). It reads the target list and per-target attributes straight from config/data.json, builds whatever a requested stage depends on automatically, skips anything already built, and locates and sources the AMD tools itself — so there is no need to source the Vivado / PetaLinux settings scripts beforehand.

The build is organised into stages, each available as a sub-command:

Command

Stage

project

Create the Vivado project (.xpr) and block design.

xsa

Synthesise, implement and export the hardware (.xsa).

petalinux

Create the PetaLinux project from the XSA, apply the BSP overlays, build and package.

package

Gather the built boot artifacts into bootimages/*.zip.

all

Build every stage the target supports, then package.

Run ./build.sh list to see the targets and their attributes, ./build.sh status --target <t> for per-stage artifact state, and ./build.sh --help for the full command list.

Because each stage builds its prerequisites first, a single ./build.sh all --target <t> cascades the whole pipeline:

./build.sh all --target t
  -> xsa         : vivado creates the project (build.tcl), then synth/impl/XSA export (xsa.tcl)
  -> petalinux   : petalinux-create --template <zynqMP|versal> -> -config --get-hw-description <XSA>
                   -> copy bsp/<board>/project-spec/* + bsp/<port-config>/project-spec/* overlay
                   -> petalinux-build -> petalinux-package
  -> package     : zip the boot files into bootimages/

Build a single stage on its own with ./build.sh <stage> --target <t>; the runner still builds any missing prerequisite stages first.

Per-target lock files (.<target>.lock at the repository root) prevent two concurrent builds of the same target from clobbering each other — so two terminals can safely both run ./build.sh all --target all.

Vivado side

Block design

There is one block-design TCL per processor family:

  • Vivado/src/bd/bd_zynqmp.tcl — used by all ZynqMP targets.

  • Vivado/src/bd/bd_versal.tcl — used by all Versal targets.

Each script is parameterised by the target name (selected via config/data.json’s lanes and linkspeed fields), and contains per-board conditional blocks (if {$is_vpk120 || $is_vpk180} etc.) where a target needs to deviate from the family defaults — typically for clock-source selection, PS configuration, or GT-quad placement.

After sourcing the BD script, scripts/build.tcl runs validate_bd_design -force, which triggers parameter propagation and fills in connection automation rules. As a result the final implemented design may contain nets that aren’t visible in the BD TCL source — to see the actual netlist as built, inspect the saved .bd file under Vivado/<target>/<target>.srcs/sources_1/bd/<bd_name>/ or use write_bd_tcl to export a complete script from an open project.

Constraints

Vivado/src/constraints/<target>.xdc contains pin assignments and any target-specific timing constraints. Constraints common to all targets of a given family are not factored out — each target’s XDC is self-contained.

Build scripts

  • Vivado/scripts/build.tcl creates the Vivado project, adds the target’s XDC, sources the appropriate bd_*.tcl, and validates the block design. Invoked via ./build.sh project --target <t>.

  • Vivado/scripts/xsa.tcl opens the existing project, runs synthesis and implementation, exports the XSA, and writes the bitstream into the implementation run directory. Invoked via ./build.sh xsa --target <t>.

Both scripts check XILINX_VIVADO to confirm the installed Vivado version matches the version_required constant at the top of the file. Bumping a project to a new Vivado release means changing those constants and re-testing — the BD TCL APIs are not stable across major releases.

Modifying the block design

Edit the block-design script for the appropriate processor family directly:

  • Vivado/src/bd/bd_zynqmp.tcl for ZynqMP targets, or

  • Vivado/src/bd/bd_versal.tcl for Versal targets.

If the change applies only to some targets in the family, wrap the additions in the appropriate per-board conditional block (for example if {$is_vpk120 || $is_vpk180} { … }).

Note

On Versal (GTY/GTYP), bd_versal.tcl explicitly forces TX_PLL_TYPE / RX_PLL_TYPE to RPLL on the GT_Quad PROT0_LR0 settings. Vivado 2025.2’s GT_Quad IP auto-selects LCPLL for the 10G/25G Ethernet preset, which prevents block lock on these designs; if you regenerate the GT_Quad customisation or copy presets from another design, make sure the PLL type stays at RPLL. The ZynqMP GTH XXV-Ethernet IP uses the shared QPLL and has no equivalent choice in the BD.

Once the script is edited, delete any existing per-target Vivado project directory (rm -rf Vivado/<target>) and re-run the Vivado build:

./build.sh xsa --target <target>

This re-creates the project, sources the modified BD script, runs validate_bd_design, synthesises, implements, and re-exports the XSA. Downstream PetaLinux / boot-image steps will pick up the new XSA on the next build.

Adding or modifying constraints

Edit Vivado/src/constraints/<target>.xdc directly. If a constraint applies to all targets in a family, it still needs to be replicated to each target’s XDC — there is no shared XDC.

PetaLinux side

BSP composition

The PetaLinux project for a given target is composed at build time from two BSP fragments copied into the target’s project directory:

  1. A board BSP at PetaLinux/bsp/<board>/ (for example uzev/, vck190/, zcu102/). Provides board-specific kernel and U-Boot configuration, the system device-tree fragment for the board, and any board-specific patches.

  2. A port-config overlay at PetaLinux/bsp/<port-config>/ (one of ports-0/, ports-0123/, or ports-versal-0123/). Provides port-config.dtsi — the device-tree fragment that wires up the SFP cages, the AXI Ethernet MAC nodes, and the SFP module-presence GPIOs for the FMC ports active on this target.

The mapping from target to (board BSP, port-config overlay) is encoded in PetaLinux/Makefile’s UPDATER block:

vck190_fmcp1_target := versal 0 0 ports-versal-0123
zcu102_hpc0_target  := zynqMP 0 0 ports-0123
zcu104_target       := zynqMP 0 0 ports-0

The first column is the PetaLinux template (zynqMP or versal); the last is the port-config overlay name. The board BSP is derived from the first token of the target name (vck190, zcu102, zcu104).

At build time both directories’ project-spec/ trees are copied into the target’s PetaLinux project, with the port-config overlay copied after the board BSP so its files take precedence on collision (in practice the two BSPs touch disjoint files, so this is academic).

Layout of a board BSP

PetaLinux/bsp/<board>/project-spec/
├── configs/
│   ├── config                <- petalinux-config: bootargs, root filesystem, hostname
│   ├── rootfs_config         <- petalinux-config -c rootfs: included packages
│   ├── init-ifupdown/
│   │   └── interfaces        <- /etc/network/interfaces
│   └── busybox/
│       └── inetd.conf
└── meta-user/
    ├── conf/
    │   ├── user-rootfsconfig <- declares additional rootfs config options
    │   ├── petalinuxbsp.conf
    │   └── layer.conf
    └── recipes-bsp/
        ├── device-tree/
        │   ├── device-tree.bbappend
        │   └── files/
        │       └── system-user.dtsi      <- board-specific DT additions
        └── u-boot/
            ├── u-boot-xlnx_%.bbappend
            └── files/
                ├── bsp.cfg               <- U-Boot Kconfig additions
                ├── platform-top.h        <- U-Boot platform header overrides
                └── *.patch               <- U-Boot source patches
    └── recipes-kernel/
        └── linux/
            ├── linux-xlnx_%.bbappend
            └── linux-xlnx/
                ├── bsp.cfg               <- kernel Kconfig additions
                └── *.patch               <- kernel source patches

The board BSPs in this repository are derived from the corresponding stock AMD reference BSPs, but with substantial additions — see Modifications layered on the stock BSPs below.

Layout of a port-config overlay

PetaLinux/bsp/<port-config>/project-spec/meta-user/recipes-bsp/device-tree/files/
└── port-config.dtsi

That is the entire overlay — a single device-tree fragment that is included from system-user.dtsi (/include/ "port-config.dtsi"). Three variants exist:

  • ports-0 — single-port designs (zcu104, zcu106_hpc1).

  • ports-0123 — four-port ZynqMP designs (uzev, zcu102_hpc0, etc.). Uses the ZynqMP label scheme xxv_ethernet_0, xxv_ethernet_0_1, xxv_ethernet_0_2, xxv_ethernet_0_3 (one XXV-Ethernet IP with four channels).

  • ports-versal-0123 — four-port Versal designs. Uses the Versal label scheme sfp_port0_xxv_ethernet through sfp_port3_xxv_ethernet (one XXV-Ethernet IP per port).

The split exists because the SDT (system device-tree) generator produces different label hierarchies for the two families, so a single overlay can’t reference both. See PetaLinux/bsp/ports-versal-0123/project-spec/meta-user/recipes-bsp/device-tree/files/port-config.dtsi for an annotated example.

Adding a package to the root filesystem

  1. Append the new option to bsp/<board>/project-spec/configs/rootfs_config:

    CONFIG_<package>=y

  2. If the package is not in the default petalinux-config -c rootfs menu, also append a declaration line to bsp/<board>/project-spec/meta-user/conf/user-rootfsconfig:

    CONFIG_<package>

    This makes the option visible in the rootfs configuration menu and exposes it for rootfs_config to enable.

  3. If the package is not provided by an existing meta-layer (i.e. it does not appear in petalinux-config -c rootfs even after the declaration), add it via a recipe under bsp/<board>/project-spec/meta-user/recipes-apps/<package>/<package>.bb.

Adding a kernel config option

Append the option to bsp/<board>/project-spec/meta-user/recipes-kernel/linux/linux-xlnx/bsp.cfg:

CONFIG_<name>=y

The corresponding bbappend at recipes-kernel/linux/linux-xlnx_%.bbappend is what causes bsp.cfg to be picked up as a kernel configuration fragment (KERNEL_FEATURES:append = " bsp.cfg"). Configs added to bsp.cfg take effect on the next petalinux-build.

Adding a device-tree fragment

If the fragment is per-board, edit bsp/<board>/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi. The file is included verbatim into the final device tree.

If the fragment is per-port-config (i.e. it relates to the SFP cages or the AXI Ethernet ports), edit the corresponding bsp/<port-config>/project-spec/meta-user/recipes-bsp/device-tree/files/port-config.dtsi.

If you add new files, ensure they are listed in SRC_URI:append in device-tree.bbappend.

Adding a kernel patch or out-of-tree driver

  1. Drop the patch file into bsp/<board>/project-spec/meta-user/recipes-kernel/linux/linux-xlnx/.

  2. Add a line to recipes-kernel/linux/linux-xlnx_%.bbappend:

    SRC_URI:append = " file://<your-patch>.patch"

  3. Re-run the build. The patch is applied during the kernel do_patch task.

The existing PetaLinux/bsp/uzev/project-spec/meta-user/recipes-kernel/linux/linux-xlnx/0001-xxv-qpllreset-gpio.patch is a working example.

Modifying U-Boot

The same pattern as the kernel, under bsp/<board>/project-spec/meta-user/recipes-bsp/u-boot/. bsp.cfg adds U-Boot Kconfig options; platform-top.h overrides the U-Boot platform header; patches are listed in SRC_URI:append in u-boot-xlnx_%.bbappend.

Modifications layered on the stock BSPs

The board BSPs in this repository started as the corresponding stock AMD reference BSPs and have been modified in the following ways. This list is the answer to “what would I lose if I overwrote the BSP with the stock one?” — it is what to re-apply if you ever do that.

All BSPs

  • Root filesystem additions in configs/rootfs_config: ethtool, iperf3, phytool (and on ZynqMP, additionally ethtool-dev, ethtool-dbg).

  • Hostname / product name set in configs/config via CONFIG_SUBSYSTEM_HOSTNAME and CONFIG_SUBSYSTEM_PRODUCT.

  • system-user.dtsi includes port-config.dtsi. The matching device-tree.bbappend adds both files to SRC_URI:append.

  • Kernel configs in linux-xlnx/bsp.cfg: CONFIG_AMD_PHY, CONFIG_XILINX_PHY, plus the SFP framework (CONFIG_SFP, CONFIG_MDIO_I2C) and PHY drivers for 10G copper SFP modules (CONFIG_AQUANTIA_PHY, CONFIG_MARVELL_10G_PHY, CONFIG_BCM84881_PHY, CONFIG_MARVELL_88X2222_PHY). Without the SFP framework, phylink ignores the sfp = <&...> properties in port-config.dtsi and falls back to in-band-status; without the PHY drivers, 10GBASE-T copper SFP modules fail phylink validation.

ZynqMP BSPs

  • SD-card root filesystem configured in configs/config: CONFIG_SUBSYSTEM_ROOTFS_EXT4, CONFIG_SUBSYSTEM_SDROOT_DEV, CONFIG_SUBSYSTEM_USER_CMDLINE (with cma=1536M for the AXI DMA buffers).

  • Kernel patch 0001-xxv-qpllreset-gpio.patch in linux-xlnx/, registered via SRC_URI:append in the bbappend. Patches the xilinx_axienet driver to pulse an optional GPIO connected to the XXV-Ethernet IP’s qpllreset_in_0 port during axienet_device_reset(), so the GTH QPLL re-locks after the Si5328 reference clock is reprogrammed during Linux boot. The GPIO is named in the device tree via the qpllreset-gpios property on each xxv_ethernet_* node in bsp/ports-0*/port-config.dtsi.

  • DMA-engine kernel configs: CONFIG_XILINX_DMA_ENGINES, CONFIG_XILINX_DPDMA, CONFIG_XILINX_ZYNQMP_DMA.

  • U-Boot patch 0001-ubifs-distroboot-support.patch in u-boot/files/, registered via SRC_URI:append in the bbappend. Adds UBIFS distroboot fallback to the ZynqMP U-Boot bootcmd.

ZCU104 BSP (additional)

  • FSBL patch zcu104_vadj_fsbl.patch in recipes-bsp/embeddedsw/files/, staged into the xlnx-embeddedsw recipe by fsbl-firmware_%.bbappend. The patch fixes the FSBL’s FMC VADJ autodetect on the ZCU104: the stock 2025.2 FSBL reads from the carrier-board EEPROM (I2C addr 0x54) instead of the FMC EEPROM (0x50), selects the wrong MUX channel, and reads only 32 bytes, which is too few to reach the VADJ voltage record. Without this patch VADJ is never programmed on the ZCU104 and the Quad SFP28 FMC does not power up cleanly. The bbappend uses apply=no and inserts a manual do_apply_vadj_patch task between do_copy_shared_src and do_configure — this is necessary because 2025.2’s xlnx-embeddedsw.bbclass runs do_patch before do_copy_shared_src, so SRC_URI-attached patches would otherwise be applied to an empty workdir.

UltraZed-EV (uzev) BSP

  • CONFIG_YOCTO_MACHINE_NAME="zynqmp-generic" in configs/config (the UZ-EV is not a stock Xilinx eval board).

  • SD-card device set to /dev/mmcblk1p2 rather than the ZynqMP default mmcblk0p2.

  • PRIMARY_SD_PSU_SD_1_SELECT=y to route the boot SD interface through PSU SD1 instead of SD0.

  • Custom system-user.dtsi with UZ-EV-specific peripheral configuration (overwrites the file copied in from a stock UZ-EV BSP).

Versal BSPs (vck190, vmk180, vpk120, vpk180, vhk158, vek280)

  • meta-xilinx-tools/recipes-bsp/uboot-device-tree/ overlay that overrides the U-Boot device tree (uboot-device-tree.bbappend + system-user.dtsi). This is required because the stock U-Boot device tree does not describe the SFP-side AXI Ethernet ports.

  • U-Boot patch 0001-xilinx_versal.h-ubifs-distroboot-support.patch.

  • No qpllreset-gpios patch — the Versal GTY/CPM5 transceiver doesn’t have the same QPLL re-lock issue as the ZynqMP GTH. The port-config overlay used by Versal targets (bsp/ports-versal-0123/) correspondingly omits the qpllreset-gpios property and instead uses an input-only AXI GPIO for the four MOD_ABS lines.

Port-config overlays

The three overlays in PetaLinux/bsp/ports-*/ are not derived from any stock BSP — they exist solely to add the device-tree fragment that wires up the SFP cages. They contain a single port-config.dtsi file (and the directory structure needed to make Yocto pick it up via device-tree.bbappend in the board BSP, which has the SRC_URI:append = " file://port-config.dtsi" line).

Where build outputs land

Path

Contents

Vivado/<target>/

Vivado project. <bd_name>_wrapper.xsa is the export.

Vivado/<target>/<target>.runs/impl_1/<bd_name>_wrapper.bit

Bitstream.

Vivado/logs/

Per-target Vivado build logs (xpr + xsa).

PetaLinux/<target>/

PetaLinux project. All Yocto build state lives here.

PetaLinux/<target>/images/linux/

BOOT.BIN, image.ub, boot.scr, rootfs.tar.gz, etc.

PetaLinux/<target>/build/build.log

PetaLinux build log.

bootimages/

Per-target zipped boot files (<prj>_<target>_petalinux-<ver>.zip and <prj>_<target>_standalone-<ver>.zip).

None of these directories are committed to the repository.