Yocto

The Yocto / EDF flow (AMD’s Embedded Development Framework) is the announced successor to PetaLinux. It can be built for these reference designs with the cross-platform build.py runner at the root of the repository.

Note

For 2025.2 both the PetaLinux and Yocto flows are supported and produce an equivalent image. From the next tool version onward, the PetaLinux flow for this repository will be retired and Yocto will be the only supported flow — see build instructions.

Requirements

To build the Yocto projects you will need a physical or virtual machine running one of the supported Linux distributions, with the Vitis Core Development Kit installed — the flow uses xsct/sdtgen (which ship with Vitis) to generate a System Device Tree from the Vivado XSA. You also need Google’s repo tool on your PATH.

Attention

You cannot build the Yocto projects in the Windows operating system. Windows users are advised to use a Linux virtual machine to build the Yocto projects.

How to build

The build runner locates and sources the Vivado and Vitis settings itself, so there is no need to source them by hand; you only need Google’s repo tool on your PATH (see Requirements above).

From a command terminal, clone the Git repository (with its submodules) and cd into it:

git clone --recurse-submodules https://github.com/fpgadeveloper/fpga-drive-aximm-pcie.git
cd fpga-drive-aximm-pcie

Build the Yocto image for your target by running the following command, replacing <target> with one of the target design labels listed in the build instructions:
```
./build.sh yocto --target <target>
```

This command launches the corresponding Vivado build if that project has not already been built and its hardware exported. The first build of a target downloads several GB of sources (repo sync) and runs bitbake from scratch, so it takes a while; subsequent builds are incremental. The output products are gathered into Yocto/<target>/images/linux/:

File	Description
`BOOT.BIN`	Boot image (FSBL/PLM + bitstream/PDI + U-Boot)
`boot.scr`	U-Boot boot script
`Image` / `uImage`	Linux kernel (`uImage` on Zynq-7000, `Image` on Zynq UltraScale+ and Versal)
`system.dtb`	Linux device tree
`rootfs.wic.xz`	Full SD-card disk image — this is what you flash
`rootfs.tar.gz`	Root filesystem tarball

Boot from SD card

Unlike the PetaLinux flow (which produces separate boot files for a hand-partitioned card), the Yocto flow produces a full SD-card disk image (rootfs.wic.xz) that already contains all partitions. You flash that image to the SD card’s raw device, then — on Zynq-7000 and Zynq UltraScale+ — copy BOOT.BIN onto the first FAT partition.

Prepare the SD card

Warning

Flashing writes directly to a raw block device and cannot be undone. Be absolutely certain you have identified the SD card’s device node before running the commands below — if you use the wrong device you risk destroying data on one of your hard drives.

Identify the SD card device. With the card unplugged, run:
```
lsblk -o NAME,SIZE,RM,TYPE,MOUNTPOINT
```
Insert the card and run the same command again. The new entry — typically /dev/sdX, with RM=1 (removable) and a size matching your card — is your target. Replace sdX with that device, and <target> with your board, throughout the steps below.

Unmount any partitions the desktop auto-mounted:

for p in /dev/sdX?*; do sudo umount "$p" 2>/dev/null; done

Flash the wic image to the raw device. With bmaptool (fast — only writes the blocks that are actually used):

sudo bmaptool copy --bmap Yocto/<target>/images/linux/rootfs.wic.bmap \
                         Yocto/<target>/images/linux/rootfs.wic.xz \
                         /dev/sdX

Or, as a fallback with dd (slower — writes every block):

xzcat Yocto/<target>/images/linux/rootfs.wic.xz \
    | sudo dd of=/dev/sdX bs=4M status=progress conv=fsync

Install BOOT.BIN on the esp partition (Zynq-7000 and Zynq UltraScale+ only). The EDF wic leaves the first FAT partition (esp) empty and installs BOOT.BIN onto the ext4 boot partition, which the BootROM cannot read. Since the BootROM loads BOOT.BIN from the first FAT partition, it must be copied onto esp by hand:
```
sudo partprobe /dev/sdX
cp Yocto/<target>/images/linux/BOOT.BIN /media/<you>/esp/BOOT.BIN
sync
```
If esp did not auto-mount, mount the first partition manually:
```
sudo mkdir -p /mnt/sd_esp
sudo mount /dev/sdX1 /mnt/sd_esp
sudo cp Yocto/<target>/images/linux/BOOT.BIN /mnt/sd_esp/BOOT.BIN
sync
sudo umount /mnt/sd_esp && sudo rmdir /mnt/sd_esp
```
Note

On Versal, skip this step. The Versal wic places BOOT.BIN (and boot.scr) onto the esp automatically, so the flashed card boots with no manual copy.
Eject the card cleanly so pending writes flush:
```
sudo eject /dev/sdX
```

Boot

Plug the SD card into the target board.
Set the board to boot from SD card. The boot-mode DIP-switch settings are the same regardless of the Linux flow — see the per-board switch settings under Boot PetaLinux. (For Versal boards, refer to the board’s documentation for the SD boot-mode setting.)
Connect one or more M.2 NVMe PCIe SSDs to the FPGA Drive FMC Gen4, and connect it to the target board’s FMC connector.
Connect the USB-UART to your PC and open a terminal emulator at 115200 baud (8N1) — see UART terminal.
Connect and power your hardware.

Setup the NVMe SSD

Once Linux has booted and you have logged in at the console, checking and preparing the SSD is identical to the PetaLinux flow — see Setup the NVMe SSD for the lspci, lsblk, fdisk and mkfs walkthrough.

Patches and known issues

The per-board fixups applied in the Yocto flow live in Yocto/bsp/<board>/ — chiefly the system-user.dtsi device-tree overrides and the kernel bsp.cfg fragments. These cover quirks such as the Versal QDMA PCIe ranges identity-map and, on Zynq-7000, the larger VMALLOC (CONFIG_VMSPLIT_2G) needed to map the AXI-PCIe config window. See the BSP sources and advanced for details.