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, modifying the standalone application, or adding packages or drivers to the embedded Linux build (PetaLinux or Yocto). It describes how the repository is laid out, how the build flow works, how the Vitis, PetaLinux, and Yocto / EDF sides are organised, 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)
├── EmbeddedSw/                <- Vendored AMD BSP libraries used by the Vitis build
├── PetaLinux/
│   └── bsp/                   <- Per-board BSP fragments
│       └── pz/, uzev/, zc706/, zcu104/, vck190/, …
├── Yocto/
│   ├── scripts/               <- init-workspace / configure-build / build-image / package-output
│   └── bsp/                   <- Per-board meta-user layers
│       └── pz/, uzev/, zc706/, zcu104/, vck190/, …
├── submodules/                <- Vendor board definition files (BDFs)
├── Vivado/
│   ├── scripts/
│   │   ├── build.tcl          <- Project creation + block design assembly
│   │   └── xsa.tcl            <- Synthesis, implementation, XSA export
│   └── src/
│       ├── bd/
│       │   ├── bd_mb.tcl      <- Block design for MicroBlaze targets
│       │   ├── bd_zynq.tcl    <- Block design for Zynq-7000 targets
│       │   ├── bd_zynqmp.tcl  <- Block design for Zynq UltraScale+ targets
│       │   ├── bd_versal.tcl  <- Block design for Versal targets
│       │   └── gt_locs.tcl    <- Per-target GT-quad placement constants
│       └── constraints/
│           └── <target>.xdc   <- One XDC per target (pin assignments, timing)
└── Vitis/
    ├── py/
    │   ├── args.json          <- Repo-specific Vitis flow configuration
    │   ├── build-vitis.py     <- Universal Vitis Python build driver
    │   └── make-boot.py       <- BOOT.BIN / .mcs packaging
    ├── common/
    │   └── src/               <- Standalone application source (PCIe enumerate + VADJ)
    └── <target>_workspace/    <- Per-target Vitis workspace (generated)

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

There is no port-config overlay in this repository — the FPGA Drive FMC has a single PCIe / NVMe interface per design, so there is nothing to factor out into a separate per-port-config fragment.

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 and, for boards with multiple FMC connectors, the connector:

<board>[_<connector>]

Examples: uzev, vck190_fmcp1, zcu106_hpc0, kc705_hpc, zc706_lpc. 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>/ or Yocto/bsp/<board>/ respectively. Boards with multiple connectors therefore share a BSP — for example zcu106_hpc0 and zcu106_hpc1 both use …/bsp/zcu106/.

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, processor family, FMC connector, baremetal-vs-PetaLinux support, 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 / Vitis / 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).
standalone	Create the Vitis workspace, build the baremetal app, package BOOT.BIN / .mcs.
petalinux	Create the PetaLinux project from the XSA, apply the BSP overlays, build and package.
yocto	Generate a custom MACHINE from the XSA (gen-machineconf parse-sdt), apply the meta-user BSP, build with bitbake 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.

Each target is flagged in config/data.json for the stages it supports — the MicroBlaze targets are baremetal-only (no PetaLinux/Yocto), the rest support the embedded-Linux flows as well. 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)
  -> standalone  : vitis builds the platform + app, packages BOOT.BIN / .mcs
  -> petalinux   : petalinux-create -> -config --get-hw-description <XSA>
                   -> copy bsp/<board>/project-spec/* -> petalinux-build -> petalinux-package
     yocto       : init-workspace (repo sync) -> configure-build (SDT + gen-machineconf parse-sdt)
                   -> build-image (bitbake edf-linux-disk-image) -> package-output
  -> 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

The block-design scripts live under Vivado/src/bd/, one per processor family, plus a shared GT-placement helper:

• bd_mb.tcl — MicroBlaze targets.

• bd_zynq.tcl — Zynq-7000 targets.

• bd_zynqmp.tcl — Zynq UltraScale+ targets.

• bd_versal.tcl — Versal targets.

• gt_locs.tcl — Tcl dictionary mapping each target to its PCIe GT coordinates, sourced by the family scripts.

Each script contains per-board conditional blocks where a target needs to deviate from the family defaults — typically for clock-source selection, PS configuration, or FMC connector routing.

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 the 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. If the change applies only to some targets in the family, wrap the additions in the appropriate per-board conditional block.

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 Vitis / 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.

Vitis side

The standalone (baremetal) build runs an NVMe / PCIe enumeration test on the target. The application source is shared but the exact set of source files used depends on which PCIe bridge IP the target’s BD contains — Zynq-7000 and the older MicroBlaze targets use the axipcie IP and its xaxipcie_rc_enumerate_example.c, while ZynqMP, Versal, and a few specific MicroBlaze targets use the xdmapcie IP and its xdmapcie_rc_enumerate_example.c.

Layout

Vitis/
├── py/
│   ├── args.json
│   ├── build-vitis.py        <- Universal Vitis Python build driver
│   └── make-boot.py          <- BOOT.BIN / .mcs packaging
├── common/
│   └── src/                  <- Application source (PCIe enumerate + VADJ)
├── boot/<target>/            <- Per-target packaged boot files
└── <target>_workspace/       <- Generated Vitis workspace per target

args.json

Vitis/py/args.json is the repo-specific configuration that drives the universal build-vitis.py driver. The key fields are:

• bd_name — block-design name (fpgadrv).

• app_name — name of the Vitis application (ssd_test).

• app_template — set to "None", meaning the build driver creates the application as an empty project and adds source files explicitly rather than scaffolding from a Vitis template.

• src — per-processor-family source file list:

  "src": {
      "mb":     {"dir": "common/src", "files": ["xaxipcie_rc_enumerate_example.c"]},
      "zynq":   {"dir": "common/src", "files": ["xaxipcie_rc_enumerate_example.c"]},
      "zynqmp": {"dir": "common/src", "files": ["xdmapcie_rc_enumerate_example.c"]},
      "versal": {"dir": "common/src", "files": ["xdmapcie_rc_enumerate_example.c", "vadj.c", "vadj.h"]}
  }
  

  Versal targets additionally pull in vadj.c / vadj.h for VADJ programming.

• src_overrides — per-target overrides of the family default. The two MicroBlaze targets that have an xdmapcie IP rather than an axipcie IP are listed here:

  "src_overrides": {
      "auboard": {"dir": "common/src", "files": ["xdmapcie_rc_enumerate_example.c"]},
      "vcu118":  {"dir": "common/src", "files": ["xdmapcie_rc_enumerate_example.c"]}
  }
  

• linker_script_mods — "microblaze": "relocate_to_local_mem" relocates the linker sections to MicroBlaze local memory so the baremetal app fits without external memory.

• combine_bit_elf — true, so the build driver combines the bitstream and the ELF into a single download image (<bd_name>_boot.bit) for the MicroBlaze targets.

Modifying the standalone application

Edit Vitis/common/src/*.c directly. The next ./build.sh standalone --target <t> rebuilds the application against the existing platform; if you’ve changed the hardware (XSA) you’ll need a fresh workspace (./build.sh clean --target <t> --stage standalone first).

If a new target uses a different PCIe IP than the family default, add an entry to src_overrides in args.json rather than branching the source.

PetaLinux side

BSP composition

The PetaLinux project for a given target is composed at build time from a single BSP fragment copied into the target’s project directory: the board BSP at PetaLinux/bsp/<board>/ (for example uzev/, zc706/, zcu104/, vck190/). It provides board-specific kernel and U-Boot configuration, the system device-tree fragment, and any board-specific patches.

The mapping from target to board BSP is by first-token match: a target zcu106_hpc0 uses PetaLinux/bsp/zcu106/, a target zc706_lpc uses PetaLinux/bsp/zc706/, and so on. The valid (target, board, template) tuples are defined in config/data.json (and surfaced by ./build.sh list).

There is no port-config overlay in this repository.

Layout of a board BSP

PetaLinux/bsp/<board>/project-spec/
├── configs/
│   ├── config                <- petalinux-config: bootargs, rootfs, 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 Linux DT additions
    │   ├── u-boot/
    │   │   ├── u-boot-xlnx_%.bbappend
    │   │   └── files/
    │   │       ├── bsp.cfg             <- U-Boot Kconfig additions
    │   │       ├── platform-top.h
    │   │       └── *.patch             <- U-Boot source patches
    │   └── embeddedsw/                 <- (zcu104 only)
    │       ├── fsbl-firmware_%.bbappend
    │       └── files/
    │           └── zcu104_vadj_fsbl.patch
    ├── meta-xilinx-tools/
    │   └── recipes-bsp/
    │       └── uboot-device-tree/
    │           ├── uboot-device-tree.bbappend
    │           └── files/
    │               └── system-user.dtsi    <- U-Boot DT overlay
    └── recipes-kernel/
        └── linux/
            ├── linux-xlnx_%.bbappend
            └── linux-xlnx/
                └── bsp.cfg             <- kernel Kconfig additions

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.

3. If the package is not provided by an existing meta-layer, add 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 registers bsp.cfg as a kernel configuration fragment.

Adding a device-tree fragment

Edit bsp/<board>/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.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"
   

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.

Yocto side

The Yocto / EDF flow builds an embedded Linux image with AMD’s Embedded Development Framework — the announced successor to PetaLinux — using the gen-machineconf parse-sdt flow. It is driven by the build runner (./build.sh yocto) and four scripts under Yocto/scripts/:

Script	Role (rough PetaLinux analogue)
init-workspace.sh	repo init + repo sync of the AMD yocto-manifests (≈ petalinux-create)
configure-build.sh	XSA → System Device Tree (sdtgen) → custom MACHINE via gen-machineconf parse-sdt (≈ importing the XSA + petalinux-config)
build-image.sh	bitbake edf-linux-disk-image (≈ petalinux-build)
package-output.sh	gather the flashable artifacts into images/linux/ (≈ petalinux-package)

The step-by-step build instructions are in build_instructions and in Yocto/README.md; this section covers how the per-board customization is organised.

Because the MACHINE is generated from the hardware (parse-sdt runs lopper on the SDT, which carries both the PS config and the PL — the PCIe Root Port IP — straight from the XSA), there is no hand-maintained machine config and no pinned MACHINE. A PS change in Vivado flows through XSA → SDT → machine.conf → device tree automatically.

BSP composition

configure-build.sh adds the board’s meta-user layer at Yocto/bsp/<board>/meta-user/ to bblayers.conf, so its bbappends and recipes are applied on top of the generated MACHINE. The board is selected by first-token match (the same rule as the PetaLinux side), so boards on the same chip share a BSP (vck190_fmcp1/vck190_fmcp2 → bsp/vck190, pz_7015/pz_7030 → bsp/pz); each target still gets its own MACHINE / SDT / device tree from its own XSA.

Layout of a Yocto board BSP

Yocto/bsp/<board>/
├── conf/
│   └── local.conf.append                     <- bootargs (APPEND), hostname, image tweaks
└── meta-user/
    ├── conf/
    │   ├── layer.conf
    │   └── petalinuxbsp.conf
    ├── recipes-bsp/
    │   ├── device-tree/
    │   │   ├── device-tree.bbappend          <- injects system-user.dtsi (Linux domain only)
    │   │   └── files/system-user.dtsi        <- board-specific Linux DT fixups
    │   └── u-boot/                            <- (Versal only) custom boot.scr + bootcmd override
    │       ├── u-boot-edf-scr_%.bbappend  +  files/fpgadrv-boot.cmd
    │       └── u-boot-xlnx_%.bbappend     +  files/fpgadrv-bootcmd.cfg
    ├── recipes-core/images/
    │   └── edf-linux-disk-image.bbappend      <- extra rootfs packages (IMAGE_INSTALL:append)
    └── recipes-kernel/linux/
        ├── linux-xlnx_%.bbappend
        └── linux-xlnx/bsp.cfg                 <- kernel Kconfig additions

Adding a package to the root filesystem

Append to IMAGE_INSTALL:append in bsp/<board>/meta-user/recipes-core/images/edf-linux-disk-image.bbappend:

IMAGE_INSTALL:append = " <package>"

Adding a kernel config option

Append the option to bsp/<board>/meta-user/recipes-kernel/linux/linux-xlnx/bsp.cfg; the adjacent linux-xlnx_%.bbappend registers it as a kernel config fragment.

Adding a device-tree fragment

Edit bsp/<board>/meta-user/recipes-bsp/device-tree/files/system-user.dtsi. It is #included onto the generated Linux device tree via EXTRA_DT_INCLUDE_FILES, guarded to the Linux domain only — applying it to the FSBL/PMU/PLM domain device trees makes dtc fail because those domains do not define the SoC peripheral labels the overrides reference.

What the Yocto BSPs change

The Yocto equivalent of the PetaLinux “what would I lose” list below. On top of the stock EDF flow, the Yocto BSPs layer:

• All boards: hostname (local.conf.append), the reference-design rootfs packages (edf-linux-disk-image.bbappend), and the kernel PCIe/NVMe configs (bsp.cfg).

• Zynq-7000 (pz, zc706): system-user.dtsi restores the root compatible = "xlnx,zynq-7000" (the parse-sdt board merge drops it, which otherwise boots a generic machine and panics in the clock driver), sets /chosen/bootargs (console + earlycon — the zynq DT carries no default bootargs), and disables PS gem0. bsp.cfg adds CONFIG_PCIE_XILINX + NVMe and the CONFIG_VMSPLIT_2G / CONFIG_PAGE_OFFSET=0x80000000 relayout needed to ioremap the 256 MB AXI-PCIe config window.

• Zynq UltraScale+: bsp.cfg adds CONFIG_PCIE_XDMA_PL + NVMe; system-user.dtsi pins the UART port-number/serial aliases (so the console is deterministic) and, on zcu104/uzev, caps the SD controller at high-speed (the level shifter cannot sustain UHS).

• Versal: system-user.dtsi overrides the QDMA PCIe ranges to a 1:1 identity map (the SDT sets the PCI base to 0x0, which faults NVMe BAR access). The U-Boot bbappends add a custom boot.scr (fpgadrv-boot.cmd — with the IR38164 VADJ-enable sequence on VCK190/VMK180/VPK120/VPK180 and earlycon=pl011,mmio32) and override CONFIG_BOOTCOMMAND; the image bbappend places BOOT.BIN and boot.scr onto the FAT esp via IMAGE_EFI_BOOT_FILES so the card boots hands-free.

See the Yocto/bsp/<board>/ sources and their in-file comments for the exact values and the rationale behind each fixup.

Modifications layered on the stock BSPs

This section describes the PetaLinux BSPs; the equivalent Yocto BSP changes are summarised under Yocto side above.

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

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

• Root filesystem additions in configs/rootfs_config: e2fsprogs (mke2fs, badblocks), mtd-utils, util-linux (mount, mkfs, blkid, fdisk), pciutils, bridge-utils, nvme-cli, coreutils (for the full dd rather than the BusyBox stub). Some default packages (canutils, openssh-sftp-server, packagegroup-core-ssh-dropbear) are explicitly disabled to keep the image small.

Zynq-7000 BSPs (pz, zc706)

• 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 configs in linux-xlnx/bsp.cfg:

  • NVMe: CONFIG_NVME_CORE, CONFIG_BLK_DEV_NVME.

  • Address-space relayout to free VMALLOC space for the PCIe CTL interface: CONFIG_ARCH_MMAP_RND_BITS_MAX=15, CONFIG_VMSPLIT_2G=y, CONFIG_PAGE_OFFSET=0x80000000. Without these the kernel runs out of VMALLOC for the axi_pcie BAR mappings.

ZynqMP and Versal BSPs

• SD-card root filesystem configured in configs/config (as above, ZynqMP only — Versal targets use the same template default).

• Kernel configs in linux-xlnx/bsp.cfg: CONFIG_PCI_REALLOC_ENABLE_AUTO, CONFIG_PCIE_XDMA_PL, CONFIG_NVME_CORE, CONFIG_BLK_DEV_NVME, CONFIG_NVME_TARGET.

• U-Boot patch 0001-ubifs-distroboot-support.patch on ZynqMP boards, 0001-xilinx_versal.h-ubifs-distroboot-support.patch on Versal boards.

• meta-xilinx-tools/recipes-bsp/uboot-device-tree/ overlay in every BSP (Zynq-7000, ZynqMP, and Versal), each providing its own system-user.dtsi. It overrides the U-Boot device tree (required because the stock U-Boot device tree does not describe the FMC-side PCIe bridge).

PicoZed FMC Carrier (pz) BSP

• CONFIG_SUBSYSTEM_SDROOT_DEV="/dev/mmcblk1p2" in configs/config and matching CONFIG_SUBSYSTEM_USER_CMDLINE — the PicoZed carrier wires the SD card through mmcblk1.

• Custom U-Boot bsp.cfg with EEPROM / I²C configuration so U-Boot can read the per-board MAC address from the carrier’s on-board EEPROM (CONFIG_CMD_EEPROM, CONFIG_I2C_EEPROM, CONFIG_ZYNQ_MAC_IN_EEPROM, CONFIG_ZYNQ_GEM_I2C_MAC_OFFSET=0xFA).

• Custom system-user.dtsi and kernel configs for the USB ACM / I²C / USB serial peripherals exposed by the PicoZed carrier (CONFIG_USB_ACM, CONFIG_USB_F_ACM, CONFIG_USB_U_SERIAL, CONFIG_USB_CDC_COMPOSITE, CONFIG_I2C_XILINX).

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.

• recipes-core/sysvinit/sysvinit-inittab_%.bbappend sets USE_VT = "0" to suppress the BusyBox “respawning too fast” message on tty1.

• IMAGE_BOOT_FILES:zynqmp = "BOOT.BIN boot.scr Image system.dtb" in petalinuxbsp.conf so the image’s boot partition contains the files the UZ-EV’s U-Boot expects.

ZCU104 BSP

• FSBL patch zcu104_vadj_fsbl.patch in recipes-bsp/embeddedsw/files/, registered via fsbl-firmware_%.bbappend. The ZCU104 FSBL is patched to program the on-board IRPS5401 PMBus regulator to 1.8V before the FMC PHYs come out of reset.

• Standard ZynqMP SD-root + PCIe / NVMe configs and U-Boot ubifs patch.

ZCU106 BSP

• CONFIG_SUBSYSTEM_REMOVE_PL_DTB=n to preserve the PL device-tree nodes (the stock ZCU106 BSP removes them, but the FPGA Drive design needs them).

• CONFIG_SUBSYSTEM_FPGA_MANAGER=n to disable the FPGA manager (the bitstream is loaded via the standard boot flow rather than at runtime).

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).
Vitis/<target>_workspace/	Per-target Vitis workspace (platform + application + BSP).
Vitis/boot/<target>/	Packaged Vitis boot files (BOOT.BIN for Zynq/ZynqMP/Versal, .bit with combined ELF for MicroBlaze).
PetaLinux/<target>/	PetaLinux project. All its bitbake 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.
Yocto/<target>/	Yocto / EDF workspace (.repo, sources, build, images).
Yocto/<target>/images/linux/	BOOT.BIN, kernel (Image or uImage), boot.scr, system.dtb, rootfs.wic.xz, rootfs.tar.gz.
Yocto/<target>/build/	bitbake build directory (tmp/, sstate-cache/, downloads/).
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.