Install and Build with Xilinx Yocto

This page details the workflow for building Yocto Linux images for Xilinx development boards. It uses the repo tool for repository management. 

This page is no longer being maintained for version 2023.1 and newer, but is being retained for historical purposes.  Please refer to the new page, Building Linux Images Using Yocto,  for the latest information. 

Table of Contents

Install Xilinx Yocto

Yocto Host Dependencies

Install the standard Yocto dependencies for your host machine per the Yocto Reference Manual.


Repo is a repository management tool that is built on top of Git. Repo unifies the many Git repositories when necessary, and automates parts of the development workflow. Repo is not meant to replace Git, only to make it easier to work with Git in the context of development.The repo command is an executable Python script that you can put anywhere in your path. In working with the source files, you will use Repo for across-network operations. For example, with a single Repo command you can download files from multiple repositories into your local working directory.

For more info about Repo, please see

Install Repo

Here we will simply install the repo script from Google.

# Cd into a directory where you keep utilities and make sure it's in your PATH
$ cd ~/bin/

# Download the repo script
$ curl > repo 

# Make repo executable
$ chmod a+x repo 

# Test repo is working
$ repo --help

Fetch Source

Repo uses a manifest which is an XML file that describes all the required repositories.  It can manage all of your git repositories so they remain in sync.

# Fetch the manifest and checkout the target release version
$ repo init -u -b <current-release>

# Fetch all the source from the repositories in the manifest
$ repo sync 

# OPTIONAL: Create a development branch on each repo
$ repo start <name> --all

Replace <current-release> with the git release tag, e.g. rel-v2018.3, rel-v2019.1

In 2019.2, there is a bug in the tcf-agent bbappend in the meta-petalinux layer.   To work around it, edit the following file:  sources/meta-petalinux/recipes-devtools/tcf-agent/tcf-agent_%.bbappend

Change the following line: 

# Original 
        git://;branch=master;protocol=https \
# Updated
        git://;branch=master;protocol=git \

This is fixed in 2020.1

Configure the Xilinx Yocto Build

This section shows how to do three basic Yocto configurations.

  1. Generate u-boot scripts to control your kernel SD boot
  2. Add an initramfs
  3. Generate a FIT image

Generate U-boot Boot Scripts (recommended)

U-boot is built with default variables that control the boot.  You may use the defaults, modify them by patching the configuration headers during the build or modify them at run-time from the hush shell.  A more flexible way to control the boot is through boot scripts, boot.scr or extlinux.conf.  U-boot 2019.01 defaults to distro boot (2) as the boot mechanism, which searches for things to boot.  Distro boot will look for extlinux.conf, boot.scr and an EFI image in that order.  This section shows how to build extlinux.conf and boot.scr.


2019.1 and earlier versions

This section is only required for 2019.1 and earlier versions.  Boot.scr has been added to each machine configuration in later versions.

Meta-xilinx-bsp provides the "" recipe to generate the boot.scr.  To build boot.scr, add the Yocto variable below to your local.conf.  

EXTRA_IMAGEDEPENDS_append = " u-boot-zynq-scr"


Configuring Yocto for extlinux will generate a extlinux.conf file to control the u-boot environment variables.  Add the Yocto variables below to your local.conf if you want to build extlinux.conf.  These Yocto variables give you granular control over how the u-boot variables are populated.  An advantage of extlinux is that it is well known, cross-platform and ASCII text.  U-boot will search for extlinux.conf in /boot/extlinux/.

UBOOT_EXTLINUX_FDT = "../${MACHINE}-system.dtb"
UBOOT_EXTLINUX_CONSOLE = "console=ttyPS0,${baudrate}"
UBOOT_EXTLINUX_ROOT = "root=/dev/mmcblk0p2"
UBOOT_EXTLINUX_KERNEL_ARGS_append = " earlycon clk_ignore_unused"

Build an Initramfs (optional)

The default Yocto configuration will build images for deploying on a dual partition SD card.  This optional section shows how to build with an initramfs for a single partition SD card.  Edit your local.conf file and add the lines shown below.  This will tell bitbake to create an initramfs image and bundle it with the kernel (2).

# Remove wic image to avoid circular dependency
IMAGE_FSTYPES_remove = "wic.qemu-sd"
INITRAMFS_IMAGE = "petalinux-image-minimal"

Generate a FIT Image (optional)

If you want to build a FIT image, add the variables shown below to your local.conf.  A FIT image contains partitions for all of the images required to boot the kernel.

KERNEL_CLASSES += "kernel-fitimage"
KERNEL_IMAGETYPES_append = " fitImage"

UBOOT_ENTRYPOINT_zynqmp = "0x8000000"
UBOOT_LOADADDRESS_zynqmp = "0x8000000"

UBOOT_ENTRYPOINT_zynq  = "0x8000"
UBOOT_LOADADDRESS_zynq = "0x8000"

Yocto may build two FIT images depending on if you've enabled initramfs or not:

  1. fitimage-<machine>.bin (kernel and dtb)
  2. fitimage-<image>-<machine>.bin (kernel, dtb and initramfs)

You may run "mkimage -l <fitimage>" to view the partitions

This article does not show how to configure the u-boot scripts to boot a FIT image

Build with Xilinx Yocto

Source the Yocto Environment

Setupsdk is a Xilinx script which configures the Xilinx Yocto environment.  Essentially it's a wrapper for the familiar "oe-init-build-env" Yocto script.

$ source setupsdk

Bitbake the Image

Finally bitbake the target image "petalinux-image-minimal".  You can pass the target machine on the command line or add it to your local.conf as the default machine.  When the build is completes, your images are located in "build/tmp/deploy/images/<machine>".  In this example we are building for the ZCU102.

$ MACHINE=zcu102-zynqmp bitbake petalinux-image-minimal

Other available machines, e.g. zcu706-zynqmp, ultra96-zynqmp, zc706-zynq7, can be found under "sources/meta-xilinx/meta-xilinx-bsp/conf/machine"

Install the Images

Finally let's install the images onto an SD card.  The directory structure is slightly different depending on whether you are installing with boot.scr or extlinux.conf, so both are shown below.  Cd into the deploy images directory for the machine you just built.

$ cd tmp/deploy/images/<machine>/

This section assumes the first partition of your SD card is mounted on "boot" and the second partition (if required) is mounted on "rootfs".

Install with Boot.scr

$ cp boot.scr boot/

$ cp boot.bin boot/
$ cp <machine>-system.dtb boot/system.dtb

# If mounting initramfs as rootfs
# For ARM64-based machines
$ cp Image-initramfs-<machine>.bin boot/Image
# For 32b ARM-based machine
$ cp uImage-initramfs-<machine>.bin boot/Image

# If mounting rootfs on mmc partition
# For ARM64-based machines
$ cp Image boot/
# For 32b ARM-based machines
$ cp uImage boot/
$ tar xf petalinux-image-minimal-<machine>.tar.gz -C rootfs/

The default boot.scr expects your device tree blob to be named system.dtb

Install with Extlinux

$ mkdir -p boot/boot/extlinux
$ cp extlinux.conf boot/boot/extlinux/

$ cp boot.bin boot/
$ cp <machine>-system.dtb boot/boot/

# If mounting initramfs as rootfs
# For ARM64-based machines
$ cp Image-initramfs-<machine>.bin boot/boot/Image
# For 32b ARM-based machine
$ cp uImage-initramfs-<machine>.bin boot/boot/Image

# If mounting rootfs on mmc partition
# For ARM64-based machines 
$ cp Image boot/boot/
# For 32b ARM-based machines 
$ cp uImage boot/boot/
$ tar xf petalinux-image-minimal-<machine>.tar.gz -C rootfs/

Device Tree Blobs

There may be multiple dtb files in your machine's deploy directory:

  1. <machine>-system.dtb is the dtb generated by DTG.  This will include device tree nodes that include PCW and PL devices.
  2. <kernel-dts>.dtb is the dtb generated from the dts in the kernel tree.  This is good for debugging if the kernel won't boot with the PL.


  1. U-boot Distro Boot
  2. Yocto Initramfs

© Copyright 2019 - 2022 Xilinx Inc. Privacy Policy