Xilinx Yocto & PetaLinux: Embedded Linux Development Guide

Building embedded Linux for Xilinx devices has always been one of those tasks that looks straightforward until you actually attempt it. I’ve spent more hours than I’d like to admit wrestling with device trees, kernel configurations, and boot sequence issues on Zynq projects. Whether you’re using Xilinx Yocto layers directly or working through PetaLinux, understanding how these tools fit together will save you significant debugging time.

This guide covers the practical aspects of Yocto Xilinx development, from choosing the right approach for your project to building custom Linux images for Yocto Zynq systems.

Understanding the Xilinx Embedded Linux Landscape

The Xilinx embedded Linux ecosystem has evolved significantly, especially since AMD’s acquisition. Before diving into specifics, let’s clarify how the major components relate to each other.

PetaLinux vs Pure Yocto: What’s the Difference?

PetaLinux is essentially a wrapper around Yocto that simplifies embedded Linux development for Xilinx devices. It uses Yocto as its build engine but adds Xilinx-specific tools, pre-configured BSPs, and simplified commands for common tasks.

The key distinction: PetaLinux provides a managed experience where Xilinx handles the layer integration and testing. Pure Xilinx Yocto development gives you more flexibility but requires deeper understanding of how Yocto works.

Aspect	PetaLinux	Pure Yocto
Learning Curve	Moderate	Steep
Flexibility	Limited to Xilinx	Any hardware
BSP Availability	Pre-built for eval boards	Requires layer configuration
Build Time	Faster with caching	Similar, depends on setup
Disk Space	100+ GB	50-100+ GB
Vendor Lock-in	High	Low
Community Support	Xilinx forums	Broader Yocto community

For quick prototyping on Xilinx evaluation boards, PetaLinux gets you running faster. For production systems or custom boards, understanding Xilinx Yocto layers directly pays dividends.

The Transition to AMD EDF

AMD announced that PetaLinux is being superseded by the AMD Embedded Development Framework (EDF), a pure Yocto Project-based solution. Starting with Vivado 2025.1, EDF provides the official path forward for embedded Linux development on AMD/Xilinx devices.

This transition matters for new projects. While existing PetaLinux releases remain available, AMD recommends EDF for all new development. The good news: if you learn Xilinx Yocto workflows now, you’re already prepared for EDF.

Setting Up Your Xilinx Yocto Development Environment

A proper development environment prevents most frustrating build failures. The requirements for Yocto Zynq development are substantial.

Host System Requirements

Yocto builds are resource-intensive. Plan for these minimums:

Resource	Minimum	Recommended
CPU Cores	4	8+
RAM	8 GB	16-32 GB
Disk Space	100 GB	250+ GB (SSD)
OS	Ubuntu 20.04/22.04	Ubuntu 22.04 LTS
Python	3.8+	3.10+

The disk space requirement catches many developers off guard. Yocto downloads sources, builds intermediate objects, and maintains caches that consume significant storage. An SSD dramatically improves build times.

Installing Dependencies for Ubuntu

Before any Yocto Xilinx build, install the required packages:

sudo apt update

sudo apt install gawk wget git diffstat unzip texinfo gcc build-essential \

    chrpath socat cpio python3 python3-pip python3-pexpect xz-utils \

    debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa \

    libsdl1.2-dev pylint3 xterm python3-subunit mesa-common-dev zstd liblz4-tool

For PetaLinux specifically, additional packages are required depending on your Ubuntu version. Check the PetaLinux release notes for the exact list, as it changes between versions.

Working with Meta-Xilinx Yocto Layers

The meta-xilinx layer collection provides Yocto support for all AMD/Xilinx devices. Understanding its structure helps you customize builds effectively.

Meta-Xilinx Layer Architecture

The meta-xilinx repository contains several sub-layers, each serving a specific purpose:

Layer	Purpose
meta-xilinx-core	Core support for Zynq, ZynqMP, Versal devices
meta-xilinx-bsp	Evaluation board configurations
meta-xilinx-standalone	Baremetal and standalone toolchains
meta-xilinx-vendor	Third-party board configurations
meta-xilinx-contrib	Community-contributed board support
meta-xilinx-multimedia	GStreamer and multimedia packages

For a Yocto Zynq build targeting custom hardware, you’ll primarily work with meta-xilinx-core and possibly create your own machine configuration based on meta-xilinx-bsp examples.

Essential Supporting Layers

Beyond meta-xilinx, several layers are typically required:

poky (meta, meta-poky)

meta-openembedded (meta-oe, meta-python, meta-networking)

meta-arm (meta-arm, meta-arm-toolchain)

meta-xilinx-tools (for hardware description processing)

The meta-xilinx-tools layer deserves special attention. It processes Vivado hardware exports (.xsa files) and generates device trees matching your programmable logic design.

Read more Xilinx FPGA Series:

Building Linux for Zynq with PetaLinux

PetaLinux remains the most accessible entry point for Yocto Zynq development. Here’s the practical workflow.

Creating a PetaLinux Project

The typical flow starts with your Vivado hardware design:

# Source PetaLinux environment

source /opt/petalinux/2024.2/settings.sh

# Create project from template

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

# Import hardware description

cd my_project

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

The –template option accepts zynq for Zynq-7000, zynqMP for Zynq UltraScale+, versal for Versal devices, and microblaze for MicroBlaze soft processors.

Configuring the Build

PetaLinux provides menu-based configuration for major components:

# System configuration (boot, rootfs type, networking)

petalinux-config

# Kernel configuration

petalinux-config -c kernel

# Root filesystem package selection

petalinux-config -c rootfs

Key settings in the main configuration include the root filesystem type (initramfs vs ext4), boot device (SD card, QSPI, NAND), and network configuration. For development, SD card boot with ext4 rootfs provides the most flexibility.

Building and Packaging

Once configured, building is straightforward:

# Build everything

petalinux-build

# Package boot images

petalinux-package –boot –fsbl –fpga –u-boot –force

Build times vary dramatically based on your hardware and what’s being built. Initial builds can take 2-4 hours; incremental builds are much faster.

Device Tree Customization for Yocto Zynq Builds

Device trees describe hardware to the Linux kernel. For Xilinx devices with programmable logic, device tree management becomes critical.

How Device Trees Are Generated

PetaLinux and meta-xilinx-tools use the Device Tree Generator (DTG) to create device trees from your Vivado hardware description. The DTG parses the .xsa file and generates nodes for:

Processing system configuration (clocks, peripherals, memory), programmable logic IP blocks connected to the PS, and interrupt routing between PL and PS.

Adding Custom Device Tree Entries

Custom device tree modifications go in system-user.dtsi. For PetaLinux projects:

project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi

For pure Yocto builds, create a bbappend file extending the device-tree recipe:

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

SRC_URI:append = ” file://system-user.dtsi”

Common customizations include fixing clock frequencies for custom IP, adding peripheral configurations not captured by the hardware export, and enabling or disabling specific kernel features.

Boot Sequence and Boot Image Generation

Understanding the Zynq boot sequence helps troubleshoot startup issues, which are frustratingly common during board bring-up.

Zynq UltraScale+ Boot Components

The boot sequence for Zynq UltraScale+ involves multiple stages:

Stage	Component	Purpose
0	BootROM	Initial hardware setup, loads FSBL
1	FSBL	Platform setup, loads PMU FW, ATF, bitstream
2	PMU Firmware	Power management, system monitoring
3	TF-A (ATF)	Secure monitor, EL3 services
4	U-Boot	Bootloader, loads kernel/DTB
5	Linux Kernel	Operating system

Each component must match the hardware design. A mismatch between the device tree and actual hardware configuration typically causes hangs during boot.

Creating BOOT.BIN

The BOOT.BIN file packages multiple boot components for SD card or flash boot:

# PetaLinux command

petalinux-package –boot –fsbl –fpga system.bit –pmufw –u-boot –force

# Yocto generates this through the wic image or separate recipes

For QSPI boot, additional packaging steps create an MCS file with appropriate offsets for each component.

Pure Yocto Xilinx Development Workflow

For projects requiring more control than PetaLinux provides, pure Xilinx Yocto development offers maximum flexibility.

Setting Up a Yocto Build

Clone the required layers and configure your build:

# Clone poky

git clone -b scarthgap git://git.yoctoproject.org/poky

# Clone meta layers

cd poky

git clone -b scarthgap git://git.openembedded.org/meta-openembedded

git clone -b scarthgap https://github.com/Xilinx/meta-xilinx

git clone -b scarthgap git://git.yoctoproject.org/meta-arm

# Initialize build

source oe-init-build-env build

# Add layers to bblayers.conf

bitbake-layers add-layer ../meta-openembedded/meta-oe

bitbake-layers add-layer ../meta-arm/meta-arm

bitbake-layers add-layer ../meta-arm/meta-arm-toolchain

bitbake-layers add-layer ../meta-xilinx/meta-xilinx-core

bitbake-layers add-layer ../meta-xilinx/meta-xilinx-bsp

Configuring Machine and Build Options

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

MACHINE = “zcu102-zynqmp”

DISTRO = “poky”

# Performance tuning

BB_NUMBER_THREADS = “8”

PARALLEL_MAKE = “-j 8”

Available machines are defined in the meta-xilinx-bsp layer. For custom boards, you’ll create your own machine configuration.

Building an Image

# Build minimal image

bitbake core-image-minimal

# Build image with development tools

bitbake core-image-full-cmdline

Build artifacts appear in tmp/deploy/images/<machine>/.

Read more Xilinx Products:

Migrating from PetaLinux to EDF/Yocto

With PetaLinux reaching end-of-life, migration planning becomes important for long-term projects.

Key Differences in Workflow

The AMD EDF approach aligns more closely with standard Yocto practices:

PetaLinux	EDF/Yocto Equivalent
petalinux-create	git clone + bitbake-layers
petalinux-config	bitbake -c menuconfig
petalinux-build	bitbake <image-target>
petalinux-package –boot	Automated through wic images
BSP files (.bsp)	Machine configs + layers

EDF provides gen-machine-conf tools that generate Yocto machine configurations from Vivado hardware exports, bridging the gap for users accustomed to PetaLinux workflows.

Migration Considerations

Before migrating, audit your PetaLinux customizations. Common items to port include kernel configuration fragments, device tree modifications, custom recipes in meta-user, and rootfs package selections. The meta-user layer from PetaLinux can often be adapted for pure Yocto use with minimal changes.

Kernel Configuration for Yocto Zynq Systems

Kernel configuration significantly impacts system behavior and boot time. Understanding Xilinx-specific kernel options helps optimize your embedded Linux system.

Key Xilinx Kernel Options

The Xilinx kernel fork includes drivers not yet mainlined. Critical options include:

FPGA Manager support for runtime bitstream loading, Xilinx DMA engines (AXI DMA, MCDMA, VDMA) for PL data movement, Display and video pipeline drivers for multimedia applications, and Xilinx-specific ethernet drivers for ARM GEM controllers.

For minimal boot times, disable unnecessary drivers and filesystems. A stripped-down Yocto Zynq kernel can boot in under 2 seconds; a full-featured configuration might take 10-15 seconds.

Applying Kernel Patches

Custom kernel patches use the kernel-yocto bbappend mechanism:

# In your layer’s recipes-kernel/linux/

SRC_URI:append = ” file://custom-driver.patch”

SRC_URI:append = ” file://performance.cfg”

Configuration fragments (.cfg files) are cleaner than patching defconfig directly. They clearly document your customizations and survive kernel version upgrades better.

Troubleshooting Common Issues

After debugging countless Yocto Zynq builds, certain issues appear repeatedly.

Build Failures

Missing host dependencies cause cryptic errors that waste debugging time. Always verify your environment matches the documented requirements before investigating build logs in detail.

Fetcher failures often indicate network issues or removed upstream sources. Yocto’s shared state cache (sstate-cache) helps significantly by reusing previous build artifacts, and maintaining a persistent downloads directory across projects prevents redundant fetching.

Boot Problems

The board hangs at FSBL: Usually indicates DDR configuration mismatch or clock settings. Verify your .xsa file matches the actual board hardware.

U-Boot starts but kernel doesn’t: Check device tree loading and kernel image format. The bootm or booti command in U-Boot must match the kernel image type.

Kernel panics with rootfs errors: Verify rootfs type matches kernel configuration and boot parameters. Common for SD card boots when the partition isn’t correctly formatted or labeled.

Useful Resources for Xilinx Yocto Development

These resources provide authoritative information for Xilinx Yocto development:

Resource	Description	URL
Xilinx Wiki – Yocto	Official Yocto documentation	xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18841883/Yocto
meta-xilinx GitHub	Layer source and documentation	github.com/Xilinx/meta-xilinx
PetaLinux User Guide (UG1144)	Official PetaLinux documentation	docs.amd.com
AMD EDF Documentation	New embedded framework docs	amd.com/en/products/software/adaptive-socs-and-fpgas/embedded-software
Yocto Project Manual	Build system reference	docs.yoctoproject.org
Xilinx Downloads	BSPs and tool downloads	xilinx.com/support/download
meta-xilinx Mailing List	Community support	lists.yoctoproject.org/g/meta-xilinx

Frequently Asked Questions About Xilinx Yocto Development

Should I use PetaLinux or pure Yocto for a new project?

For new projects in 2025 and beyond, lean toward pure Yocto or AMD EDF. PetaLinux is heading toward retirement, and investing time in Yocto skills provides broader applicability. However, if you need to ship quickly and Xilinx provides a BSP for your evaluation board, PetaLinux still offers faster initial bring-up. Just plan for eventual migration.

How much disk space do I really need for Yocto Zynq builds?

Plan for 200-300 GB if you’re doing active development. A single build might use 50-100 GB, but the download directory and shared state cache grow over time. You can reclaim space by cleaning old builds, but having headroom prevents frustrating mid-build failures. SSDs are strongly recommended; build times on spinning disks are painful.

Can I use the same Yocto layers for Zynq-7000 and Zynq UltraScale+?

Yes, meta-xilinx supports both architectures. The key differences are in machine selection (zynq vs zynqmp) and the resulting boot sequence. Zynq UltraScale+ requires additional components like PMU firmware and ARM Trusted Firmware that Zynq-7000 doesn’t need. Your recipes and most customizations transfer between platforms, but boot image packaging differs.

Why does my first Yocto build take so long?

Initial builds download all sources and compile everything from scratch. Subsequent builds leverage the shared state cache (sstate-cache) to skip unchanged components. Build times drop dramatically after the first run. You can further improve rebuild times by using a separate download directory that persists across projects and configuring adequate parallel build threads.

How do I add custom kernel modules to my Yocto Zynq image?

Create a recipe that inherits from the module class, pointing to your kernel module source code. Add the recipe to your layer and include it in IMAGE_INSTALL. For out-of-tree modules, ensure KERNEL_SRC points to the built kernel headers. Test module loading manually with modprobe before integrating into the rootfs to catch dependency issues and missing symbols early in the development cycle.

Conclusion

Xilinx Yocto and PetaLinux development requires understanding both the Yocto build system and Xilinx-specific hardware considerations. The transition from PetaLinux to AMD EDF makes learning core Yocto concepts increasingly valuable for engineers working on embedded projects.

Whether you’re building for a Zynq-7000 development board or a custom Zynq UltraScale+ design, the workflows covered here provide a solid foundation for embedded Linux development on AMD/Xilinx platforms. Start with PetaLinux if you need quick results on evaluation hardware, but invest time in understanding the underlying Xilinx Yocto layers for long-term maintainability and production deployment.

The embedded Linux landscape continues evolving rapidly, but the fundamental concepts of layer management, device tree customization, boot sequence understanding, and kernel configuration remain constant across tool generations. Mastering these skills now positions you well for future Xilinx projects regardless of which specific tools AMD provides.