Booting Certified Ubuntu for Xilinx Devices

The page provides information about the boot process used by the Certified Ubuntu for Xilinx Devices release for the ZCU102, ZCU104, and ZCU106 evaluation boards. While this boot process is hard-coded into the design of the Certified Ubuntu for Xilinx Devices it can be useful for debug.

Table of Contents


The Certified Ubuntu for Xilinx Devices release contains both a full Ubuntu operating system as well as reference PL bitstream configurations for the ZCU102, ZU104, and ZCU106 evaluation boards. The release is provided as a single SD card image that can be used with any of the three boards.  This article details how the common image functions so that users can understand it and modify it for their own requirements.

Initial Boot Image Selection

The boot process of the Certified Ubuntu for Xilinx Devices release makes extensive of the MultiBoot feature of the Zynq UltraScale+ MPSoC device. At power-on (or complete restart via POR_B), the Zynq UltraScale+ MPSoC BootROM first senses the state of the device mode pins (see Boot Modes in Chapter 11 of the Zynq UltraScale+ TRM). When the BootROM detects that it is booting from SD card it searches for a file called BOOT.BIN on the first FAT/FAT32 partition of the SD card (booting from other boot modes is unsupported). If a file is found by that name it will be used to boot the system.  If a file named BOOT.BIN is not found, the BootROM will append a numeric value starting with 1 to the end of the file name (example: BOOT1.BIN) and try again. This will continue until a matching file is found, or the maximum tries of 8191 is reached.

For the Certified Ubuntu for Xilinx Devices image, the initial BOOT.BIN on the SD card is unique in that it includes only a single payload partition - a customized First Stage Bootloader (FSBL)  binary instead of typical collection of boot artifacts (eg, bitstream, ATF, PMUFW, etc).  The binary contained in the initial BOOT.BIN file is referred to as the Image Selector (ImgSel) application. You can find the source code for the Image Selector application in the embeddedsw Xilinx Github repository

ImgSel is a minimal application which is used to determine which evaluation board it is running on and then hand off to a robust version of the FSBL tailored for the current board. Each evaluation board has a unique identifier programmed in its EEPROM at manufacturing time.  The ImgSel application reads this value and then sets the MultiBoot register based on the value read. In SD card boot modes the MultiBoot register value sets the suffix that the BootROM should append to the BOOT.BIN file name search (ie, BOOT1020.BIN).

Once the appropriate value has been written to the MultiBoot register, the Image Selector issues a soft system reset (eg, SRST_B), causing the BootROM to restart and execute a second time.  Since the MultiBoot register is non-zero, the BootROM specifically searches for an Active Image file with the intended name (see the Boot Image Name section). The Image Selector application sets the numeric suffix to be a lower value than the Golden Image filename (see the Boot Image Name section) so that the Active Image will always before the Golden Image. Keep in mind that booting without using the ImgSel BOOT.BIN file is not supported for the Certified Ubuntu on Xilinx Devices release.


Golden Images

The Certified Ubuntu for Xilinx Devices image includes a special Golden Image for each of the supported evaluation boards. The Golden Image is a known working image that is safe to fall back to in case the Active Image is corrupt or unavailable. The name of the Golden Image should always include a value higher than the Active Image. By default, the value is boot10X1.bin (see the Boot Image Name section). If you wish to have more than one fallback image, you can modify the filename so long as it does not collide with with the reserved naming scheme for the other images.

The Certified Ubuntu for Xilinx Devices release includes a tool called xlnx-config which manages boot configuration collateral. When a new demo package is installed on a running system, the xlnx-config utility generates a new boot10x0.bin file and installs it into the FAT partition. Then, xlnx-config updates the multiboot register so that the system can be rebooted into the new configuration. For more details on this process, see the xlnx-config page.

U-Boot Operation

The provided U-Boot bootloader is configured to use Distro Boot. Distro Boot uses a file called boot.scr to provide a dynamic scriptable boot process that can be modified without needing to recompile U-Boot. The boot.scr provided allows for developers to override the bitstream and device tree loaded during boot. This can be useful if a you want to test out a small change to the device tree without updating the complete Active Image. 

Before loading the default device tree (.dtb) loaded by FSBL, the boot.scr script looks for a system.dtb on the FAT partition, and use that one if found. Additionally, boot.scr looks for a PL image named system.bit on the FAT partition and loads it into the programmable logic before continuing the boot process.  Returning to the default Active Image payload simply requires removing the .bit/.dtb from the FAT filesystem prior to rebooting the system. If you delete the Golden Image file from the SD card you may prevent your board from booting into a safe state.  Additionally, when using the override flow, it’s important to make sure the bitstream, device tree, and FSBL are all compatible with each other and your target board. This should only be used for testing minor tweaks during development.

Hand-Off to Linux

After U-Boot has executed the commands in the Distro Boot script (eg, boot.scr), it loads a FIT image ( from the FAT32 partition of the SD card. The FIT image contains the Linux kernel and a simple initramfs image. Unlike the U-Boot binary, the FIT image is common to all of the ZCU10x evaluation boards. When loading the Linux kernel, U-Boot boots the Linux kernel using the device tree (.dtb) file that was loaded either by the FSBL or via the Distro Boot process (see the U-Boot Operation section). After basic system initialization occurs inside the initramfs the Ubuntu switches its root filesystem from the initramfs to the ext4 filesystem that resides in partition 2 of the SD card. Since this is a real partition on disk (rather than a ramdisk image), changes that occur in this partition are persistent across reboots.

Boot Image Name & Contents

The ZCU10x evaluation boards boot via an active configuration file called BOOT10x0.BIN (fallback to golden image called BOOT10x1.BIN).


Multi-Boot Value

Active Image Filename

Golden Image Filename


Multi-Boot Value

Active Image Filename

Golden Image Filename





















The contents of the active configuration file are described in the table below.

File Name

Load Address


File Name

Load Address




Zynq UltraScale+ MPSoC First Stage Boot Loader (FSBL)



Arm Trusted Firmware (ATF). Loads into EL3.


N/A (loaded to PMU)

Platform Management Unit (PMU) Firmware (PMUFW)



U-Boot Second Stage boot loader. Built by Canonical (located at /usr/lib/u-boot/xilinx_zynqmp_virt/u-boot.elf)


N/A (programmed to PL)

The Programmable Logic (PL) bitstream



The Linux device tree that matches the contents of the bitstream

The device tree and bitstream image must match in order to ensure all required drivers are properly loaded

If you are manually loading a Linux device tree (or overriding which one is loaded), be sure to load it to the same address so that the automatic boot process will reference its load address properly when booting Linux

© Copyright 2019 - 2022 Xilinx Inc. Privacy Policy