Yocto Linux for a Zynq MPSoC custom board

If you have built your Linux for AMD (Xilinx) Zynq MPSoC (or SoC), you may have used Petalinux, provided by AMD. Petalinux actually wraps around Yocto, developed by the Yocto Project group (https://www.yoctoproject.org/).

Yocto Project is an open source collaboration project that helps developers create custom Linux-based systems that are designed for embedded products regardless of the product’s hardware architecture.

It started in 2010 and is managed by a member of the Linux Foundation, although it is independent from it. A large number of hardware manufacturers and other parties actively support Yocto Project to create a tool to build and deploy embedded Linux OS.

Recently, AMD anounce the end of support of Petalinux, their Linux-building tool. Although there is a number of alternatives, it is natural and a good choice to move to Yocto for creating Linux for, in this case, Zynq MPSoC FPGAs.

What you will learn here

This project will show you how to build Linux using the Yocto tools starting from the Xilinx Support Archive (XSA) as exported from Vivado after you generate the bitstream.

This project uses the MYD-CZU4EV board from MYIR (https://www.myirtech.com/list.asp?id=613) and you will see how easy is to create a custom layer for a custom board. This project will also show you how to create the boot media (SD card in this case) to boot a custom board.

Tools used in this project

Here I'm using Vivado and Vitis 2024.2 release on Ubuntu 24.04 running on a VirtualBox VM. I have Vivado and Vitis installed as well as XSCT and SDK are used. The Yocto release to be used has to be supported by the Xilinx release used, here you can check the set you can use. For this project, I chose Yocto 5.0 (Scarthgap) and Xilinx branch rel-v2024.2 (rel-v2025.1 failed for me).

Step 1. Create XSA with Vivado

This project is focused on the Linux creation and applies to any Vivado project, therefore I'm just mentioning the final steps to do on Vivado to create the XSA.

Once your Vivado project builds and the bitstream is generated, click on File > Export > Export Hardware

In the dialog next, select "Include bitstream"

And give it a name, here I choose ad9361sdr

The XSA file will be generated in the folder where your Vivado project lives. Note the path for that file as it will be used later.

Step 2. Setup repo and start the proct folder

Install repo as any other app:

sudo apt install -y repo

Note: if you haven't setup git with a name and email, you need to do that:

git config --global user.email "your-email"
git config --global user.name "your-username"

Create a folder that will be your project folder, here I choose ad9361lnx on ~/projects:

cd ~/projects
mkdir ad9361lnx
cd ad9361lnx

Initialize the project with repo and sync it:

repo init -u https://github.com/Xilinx/yocto-manifests.git -b rel-v2024.2
repo sync

Note that the Yocto branch (release) to use is specified after -b above.

Source the Xilinx tools and start sdk:

source /tools/Xilinx/Vivado/2024.2/settings64.sh
source setupsdk

The project folder should look now like this.

Note that after the last command above your console is in the build folder so the following commands should be run there.

Step 3. Generate machine configuration

The gen-machineconf utility is a very versatile one and here it is used to read the XSA and generate the machine configuration that yocto will use.

gen-machineconf parse-xsa --hw-description /home/joan/vivado/ad9361sdr/ad9361sdr.xsa --machine-name myd-czu4ev

In the above note that the XSA name and path as well as the machine name are for this particular project. In your case they may differ.

The configuration will be created in <project folder>/build/conf/machine/include:

Step 4. Set the project configuration

In the previous steps we have created a project and a configuration for this specific board. Now we point the project to this specific configuration.

Each Yocto layer in a folder has a conf folder with a local.conf file

Open this file with your favourite text editor and look for a line like:

MACHINE ??= "zynqmp-generic"

Comment that line out and add the following two lines:

MACHINE ?= "myd-czu4ev"
MACHINE_FEATURES:append = " vcu"

So it will look as below

The line commented out pointed to a generic configuration for Zynq MPSoC that it has been replaced by our custom configuration. You can use any name here, it only has to match the name you used in the gen-machineconfig before.

Last, the 3rd line adds the vcu feature for EV versions of MPSoC. This is apparently automatically added from 2025.1 but not in 2024.2

Step 5. Build it

Now it takes just one command (but quite a while...) to build all the binaries:

bitbake petalinux-image-minimal

Bitbake is a veteran task scheduler and execution system used by Yocto to build Linux.

A note about the "petalinux" target: when the project was created, it fetched a Yocto layer from Xilinx (meta-petalinux), containing specific aspects to build Linux for Zynq, hence the name for the bitbake target. So "petalinux" here is the name for the Linux build, the building tool is Yocto.

For thew curious, here are the layers fetched into the project in the background:

Once the build finishes, the results are in <project_folder>/build/tmp/deploy/images/<machine_name>

Step 6. Prepare the boot media

As usual with Linux systems, you will need an SD card with two partitions:

• A FAT32 partition for binaries
• An Ext4 partition for the root filesystem

If you are old style you can use fdisk command to format a blank SD card, or you can use the Disks app in Linux

Sizes will depend on the build but 1 GB for FAT32 and the rest (8 GB card here) for rootfs work for me.

Once the card is formatted you should see the partitions mounted:

Change into the generated binaries folder and copy the following files:

cd tmp/deploy/images/myd-czu4ev/

cp boot.bin /media/joan/boot
cp boot.scr /media/joan/boot
cp Image /media/joan/boot
cp devicetree/system-top.dtb /media/joan/boot

sudo tar -xf petalinux-image-minimal-myd-czu4ev.tar.gz -C /media/joan/rootfs/

Note that the dtb file is taken from the devicetree subfolder. Mount points for SD card, machine name, etc will be different for your project.

Step 7. Boot it

The moment of the truth has come. Safely remove the SD card and insert it into the board. Remember to set the boot switches appropriately and... power it on!

Here we go: