Running Linux on Zynq-7000: Complete Setup Tutorial

Getting Linux running on a Zynq-7000 device was one of those projects that looked straightforward on paper but had me scratching my head more than once. After bringing up Zynq 7000 Linux on several custom boards over the years, I’ve learned that the devil really is in the details. This guide covers everything from understanding the boot sequence to getting a full Zynq Ubuntu distribution running on your hardware.

Understanding the Zynq-7000 Boot Architecture

Before diving into commands and configurations, it helps to understand what happens when you power on a Zynq-7000 device. The boot process follows a specific sequence that determines how your Linux system starts.

The Zynq Boot Sequence Explained

When power is applied to a Zynq-7000 SoC, the ARM Cortex-A9 processor (CPU0) begins executing code from an internal Boot ROM. This factory-programmed 128KB ROM is your starting point, and you cannot modify it. The Boot ROM reads the boot mode pins on your board and initializes the appropriate non-volatile memory controller based on those settings.

Boot Stage	Component	Location	Function
Stage 0	Boot ROM	On-chip (128KB)	Initialize memory controller, load FSBL
Stage 1	FSBL	QSPI/SD/NAND	Configure PS, load bitstream, start U-Boot
Stage 2	Zynq U-Boot	DDR	Initialize peripherals, load Linux
Stage 3	Linux Kernel	DDR	Operating system execution

The First Stage Boot Loader (FSBL) gets loaded into the 256KB on-chip memory (OCM) and takes over from the Boot ROM. The FSBL handles critical tasks including DDR memory initialization, FPGA bitstream configuration (if present), and loading the secondary bootloader.

Boot Mode Pin Configuration

The boot mode pins determine where the Boot ROM looks for the FSBL. Getting these wrong is one of the most common reasons for a board that refuses to boot. Most development boards use DIP switches to configure these pins.

Boot Mode	Mode Pins [4:0]	Boot Source
JTAG	00000	Debug/development
QSPI	00001	Quad-SPI flash
NOR	00010	Parallel NOR flash
NAND	00100	NAND flash
SD Card	00110	SD/MMC card

For development work, I typically use SD card boot because it allows quick iteration. QSPI boot makes sense for production where you need faster startup times and don’t want removable media.

Setting Up Your Zynq 7000 Linux Development Environment

The tools you need depend on which approach you take. AMD provides PetaLinux as the recommended path, but you can also build everything from source using Yocto or Buildroot. Let me walk through the PetaLinux approach first since it’s what most engineers start with.

PetaLinux Installation Prerequisites

PetaLinux runs on Linux host machines only. I’ve had the best results with Ubuntu 18.04 or 20.04 LTS. Before installing PetaLinux, make sure your system has the required packages.

sudo apt-get install -y 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 build-essential libsdl1.2-dev libglib2.0-dev zlib1g:i386 \

screen pax gzip python3

Download the PetaLinux installer from AMD’s website. The installer is a single executable that extracts and sets up the entire toolchain.

chmod +x petalinux-v2023.1-final-installer.run

./petalinux-v2023.1-final-installer.run /opt/petalinux/2023.1

After installation, source the settings script before using any PetaLinux commands:

source /opt/petalinux/2023.1/settings.sh

Creating a PetaLinux Project

AMD provides Board Support Packages (BSPs) for their evaluation boards like the ZC702 and ZC706. These BSPs include pre-configured settings that save significant time.

# Create project from BSP

petalinux-create -t project -s xilinx-zc702-v2023.1-final.bsp

# Or create a blank project for custom hardware

petalinux-create -t project –template zynq –name my_zynq_project

For custom hardware, you need to import your hardware description file (XSA) generated by Vivado:

cd my_zynq_project

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

This command opens a configuration menu where you set up boot options, root filesystem location, and various system parameters.

Read more Xilinx FPGA Series:

Configuring Zynq U-Boot for Your Hardware

U-Boot serves as the secondary bootloader and handles the heavy lifting of getting Linux running. It initializes remaining peripherals, provides a command-line interface for debugging, and loads the kernel, device tree, and root filesystem.

Essential Zynq U-Boot Environment Variables

Understanding U-Boot environment variables saves hours of debugging. These variables control how U-Boot finds and loads your Linux components.

Variable	Purpose	Typical Value
bootcmd	Commands executed on boot	run sdboot or run qspiboot
bootargs	Kernel command line	console=ttyPS0,115200 root=/dev/mmcblk0p2
kernel_addr	Kernel load address	0x3000000
devicetree_addr	Device tree load address	0x2A00000
ramdisk_addr	Ramdisk load address	0x4000000
ethaddr	MAC address	00:0a:35:00:01:22

When Zynq U-Boot fails to boot Linux, I start by interrupting the boot process (press any key during the countdown) and checking these variables:

Zynq> printenv bootcmd

Zynq> printenv bootargs

Configuring U-Boot in PetaLinux

To modify Zynq U-Boot configuration within a PetaLinux project:

petalinux-config -c u-boot

This opens a menuconfig interface where you can enable or disable features, set default environment variables, and configure device drivers. Common changes include:

Boot Configuration Options: Navigate to “Boot options” to set the default boot command and boot delay.

Device Drivers: Enable drivers for Ethernet, USB, or other peripherals you need during boot.

Environment Storage: Configure where U-Boot stores its environment (QSPI, SD card, or in-memory only).

After making changes, rebuild the project:

petalinux-build

Building the Linux Kernel and Device Tree

The Linux kernel is the heart of your embedded system. PetaLinux handles kernel configuration, but understanding the process helps when you need to enable specific drivers or tune performance.

Kernel Configuration

To configure the kernel:

petalinux-config -c kernel

Key configuration areas for Zynq-7000 include:

Device Drivers → Network device support: Enable Cadence GEM Ethernet driver for the built-in Gigabit Ethernet.

Device Drivers → USB support: Enable USB OTG support and USB storage if you’re using USB peripherals.

Device Drivers → SPI support: Enable Cadence QSPI controller for QSPI flash access.

Device Drivers → GPIO support: Enable Zynq GPIO controller for PS GPIO and AXI GPIO for PL GPIO.

Device Tree Configuration for Zynq

The device tree describes your hardware to the Linux kernel. PetaLinux generates a device tree from your Vivado hardware description, but you often need to customize it.

Device tree source files are located in:

<petalinux-project>/project-spec/meta-user/recipes-bsp/device-tree/files/

The main customization file is system-user.dtsi. Here’s an example that configures the boot arguments for a root filesystem on the second SD card partition:

/include/ “system-conf.dtsi”

/ {

    chosen {

        bootargs = “console=ttyPS0,115200 root=/dev/mmcblk0p2 rw earlyprintk rootfstype=ext4 rootwait devtmpfs.mount=1”;

    };

};

Common device tree modifications include:

• Setting kernel boot arguments
• Configuring Ethernet PHY addresses
• Adding nodes for custom PL peripherals
• Configuring GPIO and interrupt mappings

Building Everything

Once configured, build the entire system:

petalinux-build

This generates all boot components in images/linux/:

File	Description
BOOT.BIN	Combined boot image (FSBL + bitstream + U-Boot)
image.ub	FIT image containing kernel, device tree, rootfs
boot.scr	U-Boot boot script
u-boot.elf	U-Boot executable
zynq_fsbl.elf	First Stage Boot Loader

To create the boot image:

petalinux-package –boot –fsbl zynq_fsbl.elf –fpga system.bit –u-boot

Installing Zynq Ubuntu on Your Board

While PetaLinux provides a minimal root filesystem, many projects benefit from a full distribution like Zynq Ubuntu. The apt package manager makes installing additional software straightforward, and you get a familiar development environment.

Preparing the SD Card for Zynq Ubuntu

The SD card needs two partitions: a FAT32 boot partition and an ext4 root filesystem partition.

# Identify your SD card device (be careful here!)

lsblk

# Create partitions using fdisk

sudo fdisk /dev/sdX

# Create partition 1: 500MB FAT32 for boot files

# Create partition 2: Remaining space ext4 for rootfs

# Format partitions

sudo mkfs.vfat -n BOOT /dev/sdX1

sudo mkfs.ext4 -L ROOTFS /dev/sdX2

Downloading and Preparing Ubuntu Root Filesystem

Ubuntu provides ARM hard-float root filesystems that work with Zynq’s Cortex-A9:

# Download Ubuntu base (example for 20.04)

wget http://cdimage.ubuntu.com/ubuntu-base/releases/20.04/release/ubuntu-base-20.04.5-base-armhf.tar.gz

# Mount the rootfs partition

sudo mount /dev/sdX2 /mnt

# Extract Ubuntu base

sudo tar xf ubuntu-base-20.04.5-base-armhf.tar.gz -C /mnt

# Copy DNS configuration

sudo cp /etc/resolv.conf /mnt/etc/resolv.conf

Configuring the Zynq Ubuntu Root Filesystem

Before the first boot, configure essential system files using QEMU and chroot:

# Install QEMU for ARM emulation

sudo apt-get install qemu-user-static

# Copy QEMU to the rootfs

sudo cp /usr/bin/qemu-arm-static /mnt/usr/bin/

# Mount required filesystems

sudo mount -o bind /proc /mnt/proc

sudo mount -o bind /sys /mnt/sys

sudo mount -o bind /dev /mnt/dev

# Enter the chroot

sudo chroot /mnt

# Inside chroot: Update packages

apt-get update

apt-get upgrade

# Set root password

passwd

# Create a user account

adduser zynquser

usermod -aG sudo zynquser

# Configure serial console

systemctl enable serial-getty@ttyPS0.service

# Install essential packages

apt-get install -y openssh-server net-tools sudo nano

# Exit chroot

exit

# Unmount everything

sudo umount /mnt/dev /mnt/sys /mnt/proc

sudo umount /mnt

Copying Boot Files

Copy the PetaLinux-generated boot files to the boot partition:

sudo mount /dev/sdX1 /mnt

sudo cp BOOT.BIN image.ub boot.scr /mnt/

sudo umount /mnt

Booting Linux from QSPI Flash

SD card boot works great for development, but production systems often boot from QSPI flash for faster startup and better reliability.

Configuring PetaLinux for QSPI Boot

Reconfigure your PetaLinux project for QSPI boot:

petalinux-config

Navigate to:

• Subsystem AUTO Hardware Settings → Advanced bootable images storage Settings → boot image settings
• Set “image storage media” to “primary flash”

Also configure:

• kernel image settings → image storage media → primary flash
• dtb image settings → image storage media → primary flash

Rebuild and package:

petalinux-build

petalinux-package –boot –fsbl zynq_fsbl.elf –fpga system.bit –u-boot –format MCS

Programming QSPI Flash

You can program QSPI flash through Vivado, XSCT, or U-Boot itself. Using U-Boot is particularly useful for field updates:

# From U-Boot command line

Zynq> sf probe 0

Zynq> sf erase 0 0x1000000

Zynq> mmc dev 0

Zynq> fatload mmc 0 0x3000000 BOOT.bin

Zynq> sf write 0x3000000 0 ${filesize}

Zynq> fatload mmc 0 0x3000000 image.ub

Zynq> sf write 0x3000000 0x600000 ${filesize}

QSPI Boot Memory Map

When using QSPI boot, organize your flash memory carefully:

Address Range	Size	Content
0x000000 – 0x5FFFFF	6MB	BOOT.BIN (FSBL + bitstream + U-Boot)
0x600000 – 0xDFFFFF	8MB	image.ub (kernel + device tree + rootfs)
0xE00000 – 0xFFFFFF	2MB	U-Boot environment

Adjust these values based on your actual image sizes and QSPI flash capacity.

Read more Xilinx Products:

Debugging Common Zynq 7000 Linux Boot Problems

After bringing up dozens of Zynq boards, I’ve compiled a list of issues that trip up even experienced engineers.

Boot Hangs at FSBL

Symptoms: No U-Boot prompt, possibly some FSBL messages on UART.

Common causes:

• DDR initialization failure (check DDR3 memory timing parameters in Vivado)
• Incorrect boot mode pins
• Corrupted or missing BOOT.BIN

Debug approach: Connect JTAG and use XSCT to check where execution stops:

xsct> connect

xsct> targets

xsct> ta 2

xsct> rrd

U-Boot Starts but Kernel Doesn’t Boot

Symptoms: U-Boot runs, but hangs loading or starting the kernel.

Common causes:

• Incorrect device tree (especially memory nodes)
• Kernel compiled for wrong architecture
• Missing drivers for boot device

Debug approach: Check U-Boot environment and manually try loading components:

Zynq> fatload mmc 0 0x3000000 image.ub

Zynq> iminfo 0x3000000

Kernel Panic on Root Filesystem Mount

Symptoms: Kernel boots but panics trying to mount root.

Common causes:

• Wrong root device in bootargs
• Missing filesystem driver in kernel
• Corrupted root filesystem

Debug approach: Verify bootargs and filesystem:

# Check bootargs

cat /proc/cmdline

# Ensure ext4 support is compiled into kernel

zcat /proc/config.gz | grep EXT4

Essential Resources for Zynq Linux Development

Having the right documentation makes all the difference. Here are the resources I keep bookmarked:

Official AMD Documentation

Document	ID	Description
Zynq-7000 TRM	UG585	Complete technical reference
PetaLinux Reference Guide	UG1144	PetaLinux tools documentation
Embedded Design Tutorial	UG1165	Step-by-step tutorials
PCB Design Guide	UG933	Hardware design guidance

Download Links

PetaLinux Tools: 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/archive.html

Pre-built Linux Images: https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18841738/Pre-Built+Linux+Images

Xilinx Linux Kernel Source: https://github.com/Xilinx/linux-xlnx

Xilinx U-Boot Source: https://github.com/Xilinx/u-boot-xlnx

Community Resources

AMD Adaptive Computing Wiki: https://xilinx-wiki.atlassian.net/wiki/spaces/A/overview

AMD Forums: https://support.xilinx.com/s/topic/0TO2E000000YKXdWAO/embedded-linux

Frequently Asked Questions About Zynq 7000 Linux

Can I run mainline Linux kernel on Zynq-7000?

Yes, mainline Linux supports Zynq-7000 with the zynq_defconfig configuration. However, you’ll miss some AMD-specific features and drivers that exist only in the linux-xlnx fork. For production, I recommend the Xilinx kernel because AMD actively maintains it and includes optimizations specific to their silicon. For learning or contributing upstream, mainline works fine with basic functionality.

What’s the difference between PetaLinux and Yocto for Zynq?

PetaLinux is actually built on top of Yocto with AMD-specific layers and tools added. PetaLinux simplifies the workflow by providing petalinux-* commands that abstract the underlying Yocto complexity. Use PetaLinux when you want quick results and good AMD support. Use raw Yocto when you need maximum customization, want to integrate with an existing Yocto build system, or need to support multiple hardware platforms in one build infrastructure.

How do I add a custom driver to my Zynq 7000 Linux image?

There are several approaches depending on your situation. For kernel modules, create a recipe in your PetaLinux project under project-spec/meta-user/recipes-modules/. For out-of-tree modules, add them to the rootfs configuration using petalinux-config -c rootfs. For drivers that need kernel source modifications, patch the kernel through the meta-user layer. The PetaLinux UG1144 document provides detailed examples for each scenario.

Why won’t my Zynq board boot from SD card?

Start with the basics: verify boot mode pins are set correctly (typically 00110 for SD boot). Check that the SD card is FAT32 formatted for the boot partition and that BOOT.BIN is in the root directory. Ensure you’re using a compatible SD card, as some high-speed cards have compatibility issues. Connect a serial terminal at 115200 baud to ttyPS0 to see boot messages. If FSBL loads but U-Boot fails, the issue is likely in your boot image. If nothing appears on serial, check boot mode pins and power sequencing.

Can I use Zynq Ubuntu with FPGA fabric acceleration?

Absolutely, and this is where Zynq really shines. You can access PL peripherals from Linux through memory-mapped I/O using /dev/mem or through proper kernel drivers. For DMA transfers between PS and PL, the Xilinx DMA driver (xilinx-dma) works well. Device tree overlays allow you to load different FPGA configurations at runtime without rebooting. The combination of Zynq Ubuntu’s package management with FPGA acceleration makes for a powerful development platform for applications like video processing, software-defined radio, and machine learning inference.

Alternative Build Methods: Buildroot and Manual Compilation

While PetaLinux offers convenience, some projects require more control over the build process. Buildroot provides a lighter-weight alternative, and manual compilation gives you maximum flexibility.

Using Buildroot for Zynq-7000

Buildroot can generate a complete Linux system including toolchain, bootloader, kernel, and root filesystem. It’s particularly useful when you need a minimal system or want to understand exactly what goes into your image.

Download Buildroot and create a Zynq configuration:

wget https://buildroot.org/downloads/buildroot-2023.02.tar.gz

tar xf buildroot-2023.02.tar.gz

cd buildroot-2023.02

# Create ZC702 configuration

make zynq_zc702_defconfig

make menuconfig

Key configuration options for Zynq:

• Target Architecture: ARM (little endian)
• Target Architecture Variant: Cortex-A9
• Enable NEON and VFPv3
• Target ABI: EABIhf

Build the entire system:

make -j$(nproc)

Output files appear in output/images/ and can be used with your existing BOOT.BIN and device tree.

Manual Kernel Compilation

For maximum control or when debugging kernel issues, compile the kernel directly:

# Clone Xilinx kernel

git clone https://github.com/Xilinx/linux-xlnx.git

cd linux-xlnx

git checkout xilinx-v2023.1

# Set up cross-compiler

export ARCH=arm

export CROSS_COMPILE=arm-linux-gnueabihf-

# Configure for Zynq

make xilinx_zynq_defconfig

# Customize if needed

make menuconfig

# Build kernel and device trees

make -j$(nproc) UIMAGE_LOADADDR=0x8000 uImage modules dtbs

The compiled kernel lives at arch/arm/boot/uImage and device trees at arch/arm/boot/dts/*.dtb.

Performance Optimization Tips

Getting Linux running is just the beginning. Optimizing for your application often requires additional tuning.

Reducing Boot Time

For applications where fast startup matters, consider these optimizations:

Kernel configuration:

• Disable unused drivers and filesystems
• Use built-in drivers instead of modules for boot-critical components
• Enable kernel compression (GZIP vs LZO tradeoffs)

U-Boot optimization:

• Reduce boot delay to 0 or 1 second
• Remove unnecessary device initialization
• Use pre-computed environment variables

Root filesystem:

• Use initramfs instead of SD card root for fastest boot
• Minimize startup services
• Consider read-only root with tmpfs overlays

Memory Optimization for Constrained Systems

Zynq-7000 devices share memory between PS and PL. Optimizing Linux memory usage leaves more available for FPGA DMA buffers:

• Use kernel command line mem= to limit Linux’s view of memory
• Configure CMA (Contiguous Memory Allocator) for DMA buffers
• Use lightweight alternatives (busybox instead of coreutils)

Wrapping Up Your Zynq Linux Journey

Running Linux on Zynq-7000 opens up possibilities that bare-metal simply can’t match. You get networking stacks, filesystems, process management, and access to thousands of Linux packages. The initial setup takes effort, but once you have a working system, iteration becomes fast.

My recommendation for anyone starting out: begin with PetaLinux and a supported evaluation board. Get comfortable with the tool flow, understand what each component does, then gradually customize. When you move to custom hardware, you’ll know exactly which pieces need modification and which can remain default.

The combination of FPGA flexibility with Linux’s rich ecosystem makes Zynq-7000 one of the most capable embedded platforms available. Whether you’re building industrial controllers, video processing systems, or software-defined radios, mastering Zynq 7000 Linux puts powerful capabilities at your fingertips.