UdaraDe Silva

Getting Started With Xilinx Petalinux

Xilinx Petalinux is a toolset that allows you to customize, build and deploy an embedded Linux application in a supported Xilinx FPGA like Zynp Ultrascale+ MPSoC. The toolset is available only for Linux, therefore if you are a Windows user consider installing Hyper-V or Virtual Box and creating a Ubuntu virtual machine.

Petalinux toolset contains the following tools to build custom embedded Linux images:

  • Application, device driver and library generators and templates
  • Bootable system image builder
  • Debug agents
  • GCC tools
  • QEMU system simulator

Step 1: Build hardware description file

Linux communicates with the hardware using the technique called memory-mapped I\O. This requires a description of the addresses of each hardware IP (i.e. start address, address range). These details are passed on to Petalinux tools by means of a .xsa file (earlier known as .hdf file). The following tutorial describes in detail how to generate a .xsa file for a hardware design that contains only the processor system (PS).


The above tutorial contains only the PS. I added an additional processor reset block and keep the AXI HPM0 FPD and AXI HPM1 FPD (The abbreviation stands for advanced extensible interface high-performance master<number> full power) busses activated as shown below. These AXI masters are used to communicate with your custom hardware IPs.

Fig 1: Hardware design with PS and reset block

In addition to the XSA file, you also need a board support package (BSP) to build a Linux image. The BSP is a collection of drivers customized to the hardware you are using. You can download the BSP from the below link if you are using a Xilinx board. Alternatively, you can generate your own as mentioned here.


Make sure the BSP you are downloading is the same version as your Petalinux tools version.

Step 2: Create Petalinux project

The Petalinux tools are accessible from the command line. Source the <Xilinx_Installation_Directory>/petalinux/settings.sh

The steps to build the Petalinux project and compile a simple hello world C application is provided below tutorial:


I also listed the commands that are required to create the Petalinux image below:

petalinux-create -t project -s <path to .bsp file> -n <project_name>

cd <project_name>

petalinux-config --get-hw-description=<path to .xsa file>


cd images/linux

petalinux-package --boot --fsbl zynqmp_fsbl.elf --fpga <path to bitfile> --u-boot u-boot.elf

These steps will create the following files which need to be copied to the boot partition of the SD card. Once it is copied you can use that SD card to run Linux on your FPGA board

  • u-boot.bin
  • boot.scr

Connect to the serial port of the FPGA board using the following settings to verify that Linux is running properly:

Fig 2: Serial port settings to connect to FPGA [1]

Step 3: Create a Linux application

Open Vitis IDE and create a new platform project. This would require you to provide the previously generated .xsa file. Select the OS as Linux and the application processor you intend to use (i.e. psu_coretexa53 in ZCU104)

Fig 3: Create new platform project in Vitis
  1. Build the platform project using the hammer icon
  2. Create an application project : File->New->Application Project
  3. Select the platform we just created
  4. Follow the instructions for the application project:
    1. Select the platform we just created
    2. Give an application name : hello_linux
    3. Use the default domain : linux
    4. Keep SYSROOT, rootfs, and kernel image empty
    5. Select Linux Hello World template. Click Finish
    6. Click hammer icon to build the application project

Step 4: Running the program on FPGA

Fig 4: Steps to run the C application on FPGA

Debugging programs can be done using the debug mode. Use the Run As -> Run configurations to enable Single Application Debug. This allows stepping through the program lines to debug the application.

( To upload the application program to the FPGA you need to have a TFTP server installed in your machine. Instructions to install a TFTP server can be found here )


This short tutorial describes how to build an embedded Linux image using Petalinux tools and run a simple C application on the FPGA

Leave a Comment