ZYNQ Easy Startup Guide, Part II

In previous part I of ZYNQ Easy Startup Guide, I introduced how we start a bare metal PS program on ZYNQ7 board. In the second part of this serious, we will try to build and start Linux on ZYNQ, using Xilinx’s PetaLinux tool.

Required Things

In general, Linux kernel is a “bare metal” program that runs on ZYNQ’s Cortex-A7 processer. We are using the Vitis IDE to build normal bare metal program, but Linux and some components use it self’s make file. So actuary we does not need Vitis IDE. In a hard way, we only need cross compile toolchain and source file. It’s really really hard, so Xilinx provide a all in one tool called PetaLinux.

Software Tools

Install PetaLinux

Install PetaLinux is not quite straight forward. So it’s covered in this post.

  1. Download the PetaLinux installer (.run file) from Xilinx Website. Choose latest installer (2019.2 when I’m writing this post, 7+ GB).

  2. Prepare the install environment:

  3. Install PetaLinux using installer:

  4. After install configuration:

  5. (Optional) Download the sstate-cache (8+ GB for arm/zynq) and downloads (22+ GB) file if you want a completely off-line workspace. See README on download page to see how to use it.

  6. (Optional) Download the BSP files if you have OEM board.

  7. (Optional) Download the “Open Components Source Code” to review the 1000+ software used by PetaLinux. It’s not necessary for using PetaLinux.

Install Xilinx Cable Driver

  1. Install Vivado, or Vivado Lab Edition (much smaller).
  2. Run driver install script located at: <vivado-install-dir>/data/xicom/cable_drivers/lin64/install_script/install_drivers/. The script’s name is install_drivers.

Development Board

Still we will use PYNQ-Z2 board.

Step 1. Create PetaLinux Project

Ensure you are using bash shell. Source PetaLinux’s setup script by:

source <path-to-petalinux-installed-folder>/settings.sh

The script will setup environment variable and path, then you can run petalinx-* executable tools from terminal. On workspace folder, create a PetaLinux project using:

petalinux-create -t project -n <name-of-project> --template zynq

cd into the project folder, and look around. There are few files.

Step 2. Import Hardware Description

Like bare metal program, PetaLinux need the hardware definition file .xsa to get the information about PL design and process initial configuration.

petalinux-config --get-hw-description=<path-to-hdf-folder>

Note that the path is not to .xsa file, but to the folder contains it (very strange). The tool will try to import the .xsa file found on that folder and generate some configuration files. After you type the command, an menu will appear in terminal (same configurate menu as you type petalinux-config). This is configuration wizard for PetaLinux project, or Xilinx call it system configuration. You can look around but close it with all default value.

Note: Xilinx’s UG1144 says you should set DTG Settings —> MACHINE_NAME (CONFIG_SUBSYSTEM_MACHINE_NAME) to some OEM board’s name like zc702. But for custom board, leave the default value template. Or the tool will load some different device tree for your board and lead to some strange error.

After you close the menu, tool will start to build some library and tools for ZYNQ. Mainly the toolchain, I think. This takes a long time. After the tools finished processing, the folder will become very large :)

Step 3. Build Project

Components we need to boot and to build including:

Other things included in the boot image is bitstream file for FPGA. All these things can be build together by using:


It takes time when PetaLinux download source from internet and build them. After finish, all build result will be placed in <petalinux-project-dir>/images/linux.

Step 4. Package the Boot Image

Next step is package the boot components into “boot image”. In fact there are many ways to package the components. For SD boot, I recommend package FSBL, FPGA Bitstream and U-Boot into boot image.

petalinux-package --boot --fsbl --fpga --u-boot

The packaged boot image is called BOOT.BIN and placed in <petalinux-project-dir>/images/linux folder.

Copy BOOT.BIN and image.ub to SD card. Plug the card into board. Change the boot mode to SD, then power up board. Plug the UART cable and see the print information using a serial terminal tool (e.g. tera term).

What Happened

We just finished a simple PetaLinux workflow to build an bootable Linux image for ZYNQ. Even almost all the build steps are done by tools and we know less about the detail, the build result is a good start point for us to play.

What’s Next

Next step we will try to build each components all by our hand, and learn how to modify them.


UG1144 - PetaLinux Tools Documentation: Reference Guide

UG1157 - PetaLinux Tools Documentation: Command Line Reference Guide

© 2021 Kele, CC BY-NC-SA 4.0