PetaLinux on Zynq UltraScale+: Complete Tutorial

Getting Zynq UltraScale+ Linux running reliably takes more than following documentation—it requires understanding the build system, troubleshooting obscure errors, and knowing when to use PetaLinux versus a pure Xilinx Yocto approach. After bringing up Linux on numerous MPSoC boards, I’ve learned the hard way which steps matter and which pitfalls to avoid.

This comprehensive tutorial covers everything from PetaLinux installation through custom image creation, with practical guidance for the Yocto Zynq workflow that underlies PetaLinux. Whether you’re targeting a ZCU102 evaluation board or a custom production platform, this guide provides the foundation for reliable embedded Linux development.

Understanding the Linux Build Options

Before diving into installation, it’s worth understanding your options for building Zynq UltraScale+ Linux systems.

PetaLinux vs Pure Yocto

AMD provides two primary paths for building Linux:

Approach	Best For	Complexity	Flexibility
PetaLinux	Rapid development, BSP-based projects	Lower	Moderate
Pure Yocto	Production systems, custom distributions	Higher	Maximum

PetaLinux is essentially a Yocto-based build environment with AMD-specific wrappers that simplify common tasks. Under the hood, PetaLinux uses the same Xilinx Yocto layers (meta-xilinx, meta-xilinx-tools) that you’d use in a pure Yocto build. The petalinux-* commands wrap BitBake operations with device-specific defaults.

Pure Yocto using the meta-xilinx layers provides maximum flexibility but requires deeper understanding of the build system. For production systems requiring fine-grained control, the Yocto Zynq workflow offers advantages despite its steeper learning curve.

This tutorial focuses primarily on PetaLinux while explaining the underlying Yocto concepts, enabling you to transition to pure Yocto when needed.

System Requirements and Prerequisites

PetaLinux has specific host requirements that must be met exactly—unlike Vivado which often works on unsupported configurations, PetaLinux builds frequently fail in strange ways on non-supported systems.

Supported Host Operating Systems

Version	Ubuntu	RHEL/CentOS
2024.1	22.04 LTS	8.x, 9.x
2023.2	22.04 LTS	8.x
2022.2	18.04, 20.04 LTS	7.x, 8.x
2022.1	18.04, 20.04 LTS	7.x, 8.x

Using an unsupported OS often leads to cryptic build failures that waste hours of debugging time. If your development machine runs a different distribution, use a virtual machine or container with a supported OS.

Hardware Requirements

Resource	Minimum	Recommended
RAM	8 GB	32 GB
Storage	100 GB free	200+ GB SSD
CPU Cores	4	8+
Build Time	4+ hours	1-2 hours

PetaLinux builds are highly I/O intensive. An SSD dramatically reduces build times compared to mechanical drives.

Required Dependencies

Install all dependencies before running the PetaLinux installer. For Ubuntu 22.04:

sudo dpkg-reconfigure dash  # Select “No” to use bash instead of dash

sudo dpkg –add-architecture i386

sudo apt update

sudo apt install -y iproute2 gawk python3 build-essential gcc git make \

  net-tools libncurses5-dev tftpd zlib1g-dev libssl-dev flex bison \

  libselinux1 gnupg wget diffstat chrpath socat xterm autoconf libtool \

  tar unzip texinfo zlib1g-dev gcc-multilib automake zlib1g:i386 screen \

  pax gzip cpio python3-pip python3-pexpect xz-utils debianutils \

  iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev \

  pylint libtinfo5 libncurses5

The /bin/sh symlink must point to bash, not dash. This is critical—many build failures trace back to this requirement being ignored.

Read more Xilinx FPGA Series:

Installing PetaLinux

Download the PetaLinux installer from the AMD website (requires free account). The installer is a large self-extracting archive (approximately 2-3 GB).

Installation Steps

# Make installer executable

chmod +x petalinux-v2024.1-xxxxx-installer.run

# Create installation directory

mkdir -p ~/petalinux/2024.1

# Run installer (must be non-root user)

./petalinux-v2024.1-xxxxx-installer.run -d ~/petalinux/2024.1

The installer extracts PetaLinux tools and the embedded Xilinx Yocto SDK. This process takes 15-30 minutes depending on storage speed.

Setting Up the Environment

After installation, source the settings script to configure the environment:

source ~/petalinux/2024.1/settings.sh

Add this line to your ~/.bashrc to automatically configure the environment in new terminals:

echo “source ~/petalinux/2024.1/settings.sh” >> ~/.bashrc

Verify the installation:

petalinux-create –help

If you see the help output, PetaLinux is correctly installed.

Creating Your First Zynq UltraScale+ Linux Project

PetaLinux projects can be created from a BSP (Board Support Package) or from scratch using a hardware description file (XSA) from Vivado.

Creating a Project from BSP

For evaluation boards, AMD provides ready-made BSPs:

# Download ZCU102 BSP from AMD website

# Create project from BSP

petalinux-create -t project -s xilinx-zcu102-v2024.1-final.bsp -n zcu102_project

This creates a complete project with default configurations for the ZCU102 board.

Creating a Project from XSA

For custom hardware, create a project using your Vivado-exported XSA file:

# Create blank project for Zynq UltraScale+

petalinux-create -t project –template zynqMP -n my_custom_project

# Import hardware description

cd my_custom_project

petalinux-config –get-hw-description=/path/to/your/design.xsa

The –get-hw-description command reads the XSA and configures device tree entries, boot components, and peripheral support based on your hardware design.

Configuring the Zynq UltraScale+ Linux System

PetaLinux provides multiple configuration interfaces that ultimately modify the underlying Yocto Zynq configuration.

System-Level Configuration

petalinux-config

This opens a menuconfig interface for system-level settings:

Category	Key Settings
Linux Components Selection	Enable/disable FSBL, U-Boot, kernel
Auto Config Settings	Automatic device tree generation
Subsystem AUTO Hardware Settings	Memory, serial console, flash
DTG Settings	Device tree generation options
u-boot Configuration	Boot device, boot arguments
Image Packaging Configuration	Root filesystem type, boot image format

For Zynq UltraScale+ Linux systems, the most critical settings include:

• Primary boot device: SD card, QSPI, eMMC
• Root filesystem type: INITRAMFS (RAM disk), SD/eMMC, NFS
• Serial console: PS UART0 or UART1

Kernel Configuration

petalinux-config -c kernel

This opens the Linux kernel menuconfig. Common modifications include:

• Enabling/disabling driver modules
• Configuring networking options
• Setting kernel command line parameters
• Enabling debug features

Root Filesystem Configuration

petalinux-config -c rootfs

The rootfs configuration allows adding packages to the filesystem:

Package Group	Contents
Filesystem Packages	Utilities, libraries, development tools
PetaLinux Package Groups	Pre-configured package sets
User Packages	Custom applications
Modules	Kernel modules to include

For development systems, consider enabling:

• packagegroup-petalinux-utils – Standard Linux utilities
• packagegroup-petalinux-networking – Network tools
• gdb and gdbserver – Debugging support
• openssh – Remote access

Building the Zynq UltraScale+ Linux Image

With configuration complete, build the entire system:

petalinux-build

The first build takes 1-4 hours depending on your system. Subsequent builds with unchanged components are much faster due to Yocto’s sstate cache.

Understanding Build Output

Build artifacts appear in images/linux/:

File	Purpose
BOOT.BIN	First-stage boot image (FSBL, PMU firmware, ATF, U-Boot)
image.ub	FIT image containing kernel and device tree
boot.scr	U-Boot boot script
rootfs.tar.gz	Root filesystem archive
rootfs.cpio.gz	Initramfs filesystem
zynqmp_fsbl.elf	First Stage Boot Loader
pmufw.elf	Platform Management Unit firmware
bl31.elf	ARM Trusted Firmware
u-boot.elf	U-Boot bootloader

Generating the Boot Image

After building, package the boot image:

petalinux-package –boot –fsbl images/linux/zynqmp_fsbl.elf \

  –pmufw images/linux/pmufw.elf \

  –atf images/linux/bl31.elf \

  –fpga images/linux/system.bit \

  –u-boot images/linux/u-boot.elf

This creates BOOT.BIN containing all boot components.

Booting Zynq UltraScale+ Linux on Hardware

SD Card Boot

Prepare an SD card with two partitions:

Partition	Format	Size	Contents
BOOT	FAT32	500 MB	BOOT.BIN, image.ub, boot.scr
rootfs	ext4	Remaining	Extract rootfs.tar.gz

# Copy boot files to FAT partition

cp images/linux/BOOT.BIN /media/user/BOOT/

cp images/linux/image.ub /media/user/BOOT/

cp images/linux/boot.scr /media/user/BOOT/

# Extract rootfs to ext4 partition

sudo tar xzf images/linux/rootfs.tar.gz -C /media/user/rootfs/

Set the board’s boot mode switches to SD card boot and power on.

JTAG Boot for Development

For faster development iteration:

petalinux-boot –jtag –kernel –fpga

This downloads the FPGA bitstream, kernel, and filesystem via JTAG without requiring SD card preparation.

Xilinx Yocto: The Pure Yocto Approach

For production systems or when PetaLinux’s abstractions become limiting, the pure Xilinx Yocto workflow provides maximum control.

Setting Up the Yocto Environment

# Install repo tool

curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo

chmod a+x ~/bin/repo

# Initialize Yocto workspace

mkdir yocto-zynq && cd yocto-zynq

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

repo sync

repo start rel-v2024.1 –all

# Configure build environment

source setupsdk

Building with BitBake

Edit conf/local.conf to specify your target machine:

MACHINE = “zcu102-zynqmp”

Build the image:

MACHINE=zcu102-zynqmp bitbake petalinux-image-minimal

The Yocto Zynq build produces the same output files as PetaLinux but with full control over every aspect of the build.

Creating Custom Yocto Layers

For production systems, create a custom layer:

bitbake-layers create-layer ../sources/meta-custom

bitbake-layers add-layer ../sources/meta-custom

Custom layers can contain:

• Machine configurations for custom boards
• Custom kernel configurations
• Application recipes
• Distro configurations

Adding Custom Applications

Creating a PetaLinux Application

# Create application from template

petalinux-create -t apps –template c –name myapp –enable

# Edit source code

vi project-spec/meta-user/recipes-apps/myapp/files/myapp.c

# Rebuild

petalinux-build

Application Recipe Structure

PetaLinux creates a Yocto recipe at project-spec/meta-user/recipes-apps/myapp/myapp.bb:

SUMMARY = “Simple myapp application”

LICENSE = “MIT”

LIC_FILES_CHKSUM = “file://${COMMON_LICENSE_DIR}/MIT;md5=…”

SRC_URI = “file://myapp.c”

S = “${WORKDIR}”

do_compile() {

    ${CC} ${CFLAGS} ${LDFLAGS} myapp.c -o myapp

}

do_install() {

    install -d ${D}${bindir}

    install -m 0755 myapp ${D}${bindir}

}

Understanding this recipe structure helps when transitioning to pure Yocto development.

Essential Resources for Zynq UltraScale+ Linux Development

Official Documentation

Document	Number	Description
PetaLinux Reference Guide	UG1144	Complete command reference
Embedded Design Tutorial	UG1209	Step-by-step development guide
Zynq UltraScale+ TRM	UG1085	Hardware reference
Yocto Project Manual	–	Build system documentation

Download Links

Resource	URL
PetaLinux Installer	https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools.html
Board Support Packages	https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools/2024-1.html
meta-xilinx Repository	https://github.com/Xilinx/meta-xilinx
AMD Wiki	https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18841862/Install+and+Build+with+Xilinx+Yocto

Community Resources

Resource	Description
AMD Forums	Official support forums
Yocto Mailing List	meta-xilinx discussions
GitHub Issues	Bug reports and feature requests
Stack Overflow	Community troubleshooting

Troubleshooting Common Issues

Build Failures

Error	Cause	Solution
“do_fetch failed”	Network/download issue	Check internet, use mirrors
“do_compile failed”	Missing dependencies	Install required packages
“/bin/sh is dash”	Wrong shell	Run dpkg-reconfigure dash
“Out of space”	Insufficient disk	Ensure 100+ GB free

Boot Failures

Symptom	Likely Cause	Solution
No console output	Wrong UART, baud rate	Verify serial settings
Kernel panic	Wrong device tree	Regenerate from correct XSA
Filesystem not found	Missing rootfs	Check SD card partitioning
U-Boot hangs	Boot mode mismatch	Verify boot mode switches

Debugging the Boot Process

When Zynq UltraScale+ Linux fails to boot, systematic debugging identifies the failure point:

Stage 1 – FSBL: If the board shows no signs of life, verify FSBL is loading. Check boot mode switches and ensure BOOT.BIN is on the correct media. FSBL failures often indicate XSA/hardware mismatches.

Stage 2 – U-Boot: If you see U-Boot messages but Linux doesn’t start, the kernel or device tree may be corrupted. Try loading via TFTP to isolate SD card issues:

# In U-Boot console

setenv serverip 192.168.1.100

setenv ipaddr 192.168.1.50

tftpboot 0x10000000 image.ub

bootm 0x10000000

Stage 3 – Kernel: Kernel panics typically indicate device tree problems, missing drivers, or filesystem issues. Add earlycon=cdns,0xFF000000,115200n8 to kernel command line for early debug output.

Device Tree Customization

The device tree describes hardware to the Linux kernel. For custom boards, device tree modifications are often necessary.

Understanding Device Tree Structure

The Yocto Zynq build generates device trees from multiple sources:

Source	Location	Purpose
Base DTS	Auto-generated from XSA	Hardware peripherals
Include files	meta-xilinx	Common definitions
Custom fragments	project-spec/meta-user	User modifications

Adding Custom Device Tree Entries

Create device tree fragments in project-spec/meta-user/recipes-bsp/device-tree/files/:

/* system-user.dtsi */

/include/ “system-conf.dtsi”

/ {

    /* Custom aliases */

    aliases {

        serial0 = &uart0;

        ethernet0 = &gem3;

    };

};

/* Enable I2C device */

&i2c0 {

    status = “okay”;

    clock-frequency = <100000>;

    temperature_sensor@48 {

        compatible = “ti,tmp102”;

        reg = <0x48>;

    };

};

/* Configure GPIO */

&gpio {

    status = “okay”;

};

Reference this file in the device tree recipe:

# device-tree.bbappend

FILESEXTRAPATHS:prepend := “${THISDIR}/files:”

SRC_URI += “file://system-user.dtsi”

Read more Xilinx Products:

Debugging Device Tree Issues

Examine the compiled device tree:

# Decompile device tree blob

dtc -I dtb -O dts -o system.dts images/linux/system.dtb

# Search for specific nodes

grep -A 10 “uart0” system.dts

Common device tree problems:

• Missing status = “okay” for enabled peripherals
• Incorrect interrupt specifications
• Wrong clock references
• Address/size cell mismatches

Working with the Xilinx Yocto Layers

Understanding the meta-xilinx layer structure helps when customizing beyond PetaLinux’s abstractions.

Layer Organization

The Xilinx Yocto layers provide:

Layer	Purpose
meta-xilinx-core	Core SoC support, tune files
meta-xilinx-bsp	Evaluation board BSPs
meta-xilinx-standalone	Bare-metal toolchains
meta-xilinx-tools	XSCT integration
meta-petalinux	PetaLinux-specific recipes

Overriding Recipes

To modify an upstream recipe, create a .bbappend file in your custom layer:

# linux-xlnx_%.bbappend

FILESEXTRAPATHS:prepend := “${THISDIR}/files:”

SRC_URI += “file://custom-driver.patch”

SRC_URI += “file://custom.cfg”

KERNEL_CONFIG_FRAGMENTS += “file://custom.cfg”

This approach maintains upstream compatibility while adding customizations.

Building Specific Components

During development, rebuild individual components rather than the entire system:

# Rebuild kernel only

petalinux-build -c kernel

# Rebuild U-Boot only

petalinux-build -c u-boot

# Rebuild device tree only

petalinux-build -c device-tree

# Rebuild specific application

petalinux-build -c myapp

Advanced Configuration Topics

Network Boot with NFS Root

For rapid development iteration, boot with network filesystem:

# In petalinux-config

# Image Packaging Configuration -> Root filesystem type -> NFS

# Set NFS server details

# Subsystem AUTO Hardware Settings -> Ethernet Settings -> IP address

Configure your NFS server to export the root filesystem:

# On host machine

sudo mkdir -p /export/rootfs

sudo tar xzf rootfs.tar.gz -C /export/rootfs

# Add to /etc/exports

echo “/export/rootfs *(rw,no_root_squash,no_subtree_check)” | sudo tee -a /etc/exports

sudo exportfs -a

NFS boot eliminates SD card preparation for every change, dramatically speeding development.

Partial Reconfiguration Support

For FPGA designs using partial reconfiguration:

# Enable in kernel config

petalinux-config -c kernel

# Device Drivers -> FPGA Configuration Support -> FPGA Region

Load partial bitstreams at runtime:

# On target

fpgautil -b partial.bit.bin -o overlay.dtbo

OpenAMP for Cortex-R5 Communication

The Zynq UltraScale+ Linux kernel includes support for communicating with the Cortex-R5 real-time processor:

# Enable OpenAMP packages

petalinux-config -c rootfs

# Petalinux Package Groups -> packagegroup-petalinux-openamp

This enables remoteproc for loading R5 firmware and rpmsg for inter-processor communication.

Frequently Asked Questions

What is the difference between PetaLinux and Yocto for Zynq UltraScale+ Linux?

PetaLinux is a wrapper around Yocto that provides simplified commands (petalinux-build, petalinux-config) and default configurations for AMD devices. The Xilinx Yocto layers (meta-xilinx) that PetaLinux uses can also be used directly with standard Yocto tools (BitBake). PetaLinux is faster to start with, while pure Yocto offers more flexibility for production systems.

Can I use Ubuntu or other distributions instead of PetaLinux’s root filesystem?

Yes. Canonical provides official Ubuntu images for some AMD platforms, and you can build custom distributions using the Yocto Zynq workflow. Replace the root filesystem while keeping the same boot components (BOOT.BIN, kernel, device tree). The processing system boots the same regardless of which Linux distribution runs on top.

How long does a full PetaLinux build take?

Initial builds typically take 1-4 hours depending on system specifications. Subsequent builds are much faster (minutes) when only changing applications or configurations, as Yocto’s sstate cache preserves unchanged components. Adding more CPU cores and using SSD storage significantly reduces build times.

Why does my PetaLinux build fail with “unsupported OS” warning?

PetaLinux validates the host operating system and may refuse to build on unsupported versions. While warnings can sometimes be ignored, actual build failures usually require using a supported OS. Virtual machines or containers running supported Ubuntu or RHEL versions provide the most reliable build environment.

How do I add a custom kernel driver to my Zynq UltraScale+ Linux image?

Create a kernel module recipe in project-spec/meta-user/recipes-modules/ or enable built-in kernel drivers using petalinux-config -c kernel. For out-of-tree modules, create a recipe that compiles against the kernel headers. Include the module in rootfs configuration to ensure it’s packaged in the final image.

Building Production-Ready Systems

Transitioning from development to production requires attention to several factors beyond basic functionality.

Security considerations:

• Disable debug features and console access
• Enable secure boot with encrypted images
• Remove development packages from rootfs
• Configure firewall rules and user authentication

Reliability measures:

• Implement watchdog monitoring
• Configure redundant boot partitions
• Test across temperature ranges
• Validate power sequencing under load

Build reproducibility:

• Pin specific layer commits in manifest files
• Archive download sources (use Yocto’s archiver class)
• Document all configuration changes in version control
• Create BSPs for repeatable project creation

The combination of PetaLinux for rapid prototyping and pure Xilinx Yocto for production builds provides flexibility throughout the development lifecycle. Understanding both approaches enables efficient Zynq UltraScale+ Linux development regardless of project requirements. As your project matures, transitioning from PetaLinux wrappers to direct Yocto control provides the fine-grained customization that production systems demand.