Petalinux is the Xilinx’s toolchain used for creating whole embedded Linux system for Xilinx devices. It is a convenient way of building all blocks necessary to create the bootable image for the targeted platform. But lets go to the very beginning. What you need for using the Petalinux toolchain except the Development board? Well basically one has to create “a preferably virtual OS – VirtualBox or Vmware player” with the OS recommended via the UG1144. I have been using the Kubuntu 18.04 LTS and it works very good with the latest Petalinux Version (2019.1). You may think at first, that choosing a newer version would be fine, but! Never use the most up to date version of the guest Linux system! This will save you plenty of time debugging the Petalinux errors. Especially fixing python errors is awesome (Or errors with deprecated functions and libraries). Go for the latest only if you are masochist :) 

The recommended flow is to open up Vivado and create a default project with the targeted board (Note that if you are using non-Xilinx dev. board, you need to download the Vivado Board files from the manufacturer and put them inside /Vivado/2019.1/data/boards/board_files so that they should be visible from Vivado GUI). Once it is created, you can either customize the project yourself (For beginners, starters and people trying to bring up a board for the first time: Make the project as simple as possible without any unnecessary components! – This is going to save you a lot of time – Create basically only a singe block design with only the ZYNQ / ZYNQMP processing IP. Nothing more!). Once in the Block Designer : Run block Automation. This  will basically configure the ZYNQ/ZYNQMP IP based on the board specification file. After this, you have to synthesize the Out-Of Context runs for the Block Designer and Export Hardware Definition File (HDF) via the Vivado’s menu toolbar. You can optionally generate a bitstream for the targeted device and include it in the .HDF file.

Tip: The HDF file contains the hardware specification and optionally a bitstream. Although its extension is .hdf, you can change it to .zip, extract it and see whats really inside :)

Tip: The HDF file cannot be generated if there is no Zynq / ZynqMP Processing system IP inside a Block Designer. This .bd file needs to be somewhere in the hierarchy under your Vivado TOP module.

Some vendors and Xilinx Itself provide the BSP (Board Support Package) files. My recommendation is not to use them, as they provide some pre-configured system and you are not usually aware of how it has been configured. Instead create a new Petalinux project and configure it according to the HDF file generated by Vivado. Very important thing is to never mix the Vivado/XSDK/Petalinux versions. Always maintain a single version toolset such as 2019.1. This will as well ease your pain during building. The best way to create the HDF file is to target the Vivado project for a development board (Such as ZCU102/ZCU104 … ) and configure the Zynq UltraScale+ MPSoC Processing System IP according to the target board via “run block automation” option inside the Vivado’s block designer. I do personally recommend to double-check the PS-DDR memory controller configuration as vendors do occasionally change shipped SODIMM modules and or DDR ram Chips, which may lead to blank console UART output of the board, as nothing will likely work. 

Petalinux Installation and Configuration

Recommended package setup for installing Petalinux 2019.1 on Kubuntu 18.04LTS (you don’t need tftp):

Installing Petalinux:

After installing source the Petalinux Environment:

Change shell to Bash:

Xilinx default git repositories in case you need them: (Likely only the dtc and device-tree sources are optionally required):

Useful Linux commands of various kinds:

Example .its file specification (edit with text editor and save as .its):

Petalinux Commands:

Bootimage specification (Edit with text editor and save as .bif):

Creating SD card from scratch (recommended) – and don’t do it under windows:

Petalinux DeviceTreeCustomization:

Recommended via “system-user.dtsi” inside: PROJECT/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi. An example of the file is listed below with reserved memory for DMAs ( LINK ). Reserved memory is useful for manually controlling the DMAs inside the PL. In case the memory is not reserved, then system may write to the location and not knowing,that there are some transfers running in the background. The DT overlay should be enabled in petalinux-config in order to make nodes such as &spi0 / &spi1 / &sdhci0 visible. A common error of compiling the devicetree is to address the common nodes inside the /{ }; section, but they need to be modified outside the scope such as shown below:

Install nano

Note: In order to install nano editor, open: … /project-spec/meta-user/recipes-core/images/petalinux-image-full.bbappend and add: IMAGE_INSTALL_append = ” nano”. Once this is done,the package should be visible under petalinux-config -c rootfs -> user packages.

Initialization scripts

Browse to /etc/init.d and customize scripts already launched after startup. In order to create a custom initialization script (Such that network mount, package update, interface configuration and so on …) create an .sh file and place it in /etc/rcS.d/ By default, all initialization scripts (Starting with “S” prefix) are executed from this directory alphabetically. That is why additional prefix such as 99 is required and or at least recommended. 

Final Notes:

The Petalinux is a great tool for building a bootable Linux image in a relatively simple way. Despite this, one cannot expect to be successful during first compilation and boot. From my own experience, there will very likely be difficulties of different kinds, starting with compilation problems, dependencies, package compatibilities and OS support for Petalinux. Problems with device tree files and kernel drives are quite common I would say. What is also embarrassing is that petalinux needs plenty of resources. I do recommend to dedicate at least of 6GB of RAM for the virtual machine and use 256GB virtual hard drive due to the fact, that each petalinux project needs plenty of space on the hard drive. I have personally seen project sizes of up to 60GB, though the required size is usually based on the components selected for the Linux environment. Plenty of .bsp files comes with http server, python, GUI and so on. These components then “virtually eat the hard drive”. That is why I suggest not to use the BSP files,but rather start from scratch with your own design. A base project with drivers and common utilities should not exceed the size of approx 15GB. By the way Baobab is a great tool for disk usage analysis. In the end, I can say that  petalinux is a great tool for starters, but for advanced users, I would recommend to create, build, configure and compile most of the sources by hand and downloading only the necessary Xilinx source files from the repositories mentioned. I hope my next post will provide more details on compilation of the sources by hand.  

I would also recommend to use the VS Code editor for ease of use and furthermore: Keep your directory structure well organized!


If you are looking for cost-optimized Zynq Ultrascale+ development boards, you may check the following: