Using Avnet Build Scripts to Build a PetaLinux BSP (2020.1 and later)

This is an update to the popular Using Avnet Build Scripts to Build a PetaLinux BSP (2019.2 and earlier) blog post.

Like the Avnet HDL github repository of build scripts, IP, etc. for building the Vivado projects that are the hardware foundation for customers to use and customize, Avnet's PetaLinux github repository is also full of build scripts, bitbake recipes, etc. for creating BSPs that customers are able to use as the basis for their own Linux development on Avnet Zynq and Zynq UltraScale+ SOMs and development boards.  This blog will focus on building a PetaLinux BSP for the Avnet Ultra96-V2 board using a Linux bash build script from the Avnet "petalinux" github repository.

Before We Begin

Bold assumptions:

User is familiar with:

• git commands
• Linux command line
• Xilinx PetaLinux tools

Software requirements:

• Ubuntu v16.04 LTS or v18.04 LTS 64-bit host OS
• PetaLinux tools installed

• At least 100GB of free disk space

Repository Setup

Make the Repositories Folder

The git repositories must be installed into the same parent folder because the build scripts use relative paths to reference their required input files.  Choose a folder where you wish to clone the git repositories and run the scripts.  You will need at least 100GB of free disk space in this folder.  For example, you may wish to clone the repositories into a /home/<user>/git/avnet folder.

$ cd ~

$ mkdir -p git/avnet

$ cd git/avnet

Clone the Repositories

Clone the Avnet "petalinux", "hdl", and "bdf" git repositories.  Though we are building a PetaLinux BSP the underlying Vivado hardware platform is required and the PetaLinux build script will take care of launching the Vivado tools in the background to build this, hence the requirement now for the "hdl" and "bdf" repositories.The "bdf" repository stores the Vivado Board Definition Files (BDFs) that are required to build or open any designs that target a known SOM or development board.  Xilinx provides BDFs for their boards (ZC702, ZCU102, etc.) and includes them in the Vivado installation.  Avnet provides this repository for the BDFs that target their SOMs and dev boards.

$ git clone https://github.com/avnet/bdf.git

The "hdl" git repository stores all of the TCL build scripts and design input files (constraints files, IP sources, etc.).

$ git clone https://github.com/avnet/hdl.git

The "petalinux" git repository stores all of the Linux bash build scripts and input files (config files, etc.).

$ git clone https://github.com/avnet/petalinux.git

Checkout the Correct git Branch

As you may know, git uses the concept of branches to separate revision controlled versions of source files.  For a stable repository with not many changes, like the bdf store, all changes can be tracked on the master branch.  For a more dynamic repository, like the hdl and petalinux stores, it makes sense to create branches tied to the version of Vivado and PetaLinux tools the build scripts, etc. are meant to work with

$ cd bdf

$ git checkout master

$ cd ../hdl

$ git checkout <2020.1 | 2020.2>

$ cd ../petalinux

$ git checkout <2020.1 | 2020.2>

Repository File Structure

The Avnet git repository for PetaLinux projects contains the following subdirectories:

This structure has been setup for maximum flexibility in design creation as well as maximum reuse of designs . Avnet has made a commitment to using this structure to implement our designs in order to give our customers a consistent look and feel to our reference designs. This will allow anyone to be able to edit a project to fit their needs. Typically we will release a TAG (snapshot) of a project guaranteeing it’s validity for a specific configuration. This provides great flexibility for users to start with a known-good project and edit the scripts as needed to create a project that has been purpose built for the configuration they want.

Anatomy of a Project Script

It is important to note that the PetaLinux projects scripts will also first run the associated Vivado build script to build the underlying hardware platform that PetaLinux will run on. This is why it is a requirement that the git HDL repository also be cloned AND that it is cloned into the same parent folder as the PetaLinux git repository. For each PetaLinux scripted build there is a per-project build script and a common.sh helper shell script that does all the heavy lifting and is where all of the custom build commands are defined.  There are five key portions of the PetaLinux Build Script:

• Script Variables
• Environment Setup
• Build Hardware Platform
• Create and Configure PetaLinux Project
• Build OS Images for Each Boot Method

To get an understanding of what happens when we launch a scripted PetaLinux build, let's take a look at a sample build script and follow the chain of events that occur.  For this example we will examine the make_ultra96v2_sbc_base.sh build script.

Script Variables

This section is where build options like the project-specific and architecture-specific settings for the BSP are set.

Environment Setup

The build script will first check to see if the required git repositories have been cloned and that Xilinx environment variables have been properly set.  This part of the script will also check to see if the BSP is being built using a specific git tag. This is helpful when it is necessary to rebuild the complete BSP using the same git-controlled sources as the original BSP.

Build Hardware Platform

The build script will first check to see if the Vivado hardware project has already been built. If it has then the script will move on to the next step to build the PetaLinux BSP. This is helpful to reduce run times when this PetaLinux script is run many times during development and debug.

Create and Configure PetaLinux Project

The next step is to create the PetaLinux project, import the Vivado hardware platform, and configure the PetaLinux project with board-specific settings.

Build OS Images for Each Boot Method

This is the part of the script where the build target(s) are specified. The boot method can either be "INITRD" or "EXT4".  The "INITRD" boot is an OS image that will use a RAMdisk root filesystem that does not store any changes when rebooted.  The "EXT4" boot OS image provides a persistent file system that uses an EXT4 formatted partition on either an SD card or eMMC to store the root filesystem.  The "INITRD" OS image will also build the "avnet-image-minimal" root filesystem which has fewer features and software packages installed, and thus is much smaller than the full-featured "avnet-image-full" root filesystem configuration used by the "EXT4" boot method.  Boot options include SD card, QSPI Flash, and eMMC.  Not all SOMs and SBCs support all boot methods.  The Ultra96-V2 board, for example, does not support QSPI or eMMC boot.  The default for the Ultra96-V2 is SD card boot with a ext4 partition for the root file system (rootfs).

The script will build a PetaLinux image for each boot method that has been specified. The script will loop here until the PetaLinux image is built successfully and the boot method-specific product files will be saved and copied to new filenames so they won't be overwritten later.  Once the builds are complete for each of the boot methods, the binary product files are copied to a project folder and the BSP file is created.

Launch the PetaLinux Build Script

Open a command terminal and navigate to the build scripts folder.

$ cd ~/git/avnet/petalinux/scripts

$ ./make_ultra96v2_sbc_base.sh

The build will begin and the terminal window will display the progress as the hardware platform is built in Vivado and the the Linux OS image is created.

Prepare the SD Card and Boot the New Linux OS Image

Once the BSP build is complete you can boot the new OS image on the Ultra96-V2 board.  If you haven't already followed the Getting Started Guide you will need to first partition the SD card with - for example - a 1GB FAT32 boot partition and (assuming you are using the provided 16GB Delkin micro SD card) and a 15GB ext4 partition.  Navigate to the 'images/linux' folder of the PetaLinux project and extract the rootfs.tar.gz file to the ext4 partition and copy the BOOT.BIN and Linux kernel image.ub files to the FAT32 partition.  Remember that you will need to have 'root' or 'su' permissions to extract the rootfs to the ext4 partition.  It is a good idea to delete anything that is already in that partition, so be careful that you don't delete anything you need to keep.  For example, on an Ubuntu host:

$ cd ~/git/avnet/petalinux/projects/ultra96v2_oob_2019_2

$ cp ./images/linux/BOOT.BIN /media/training/<UUID of FAT32 partition>/.

$ cp ./images/linux/image.ub /media/training/<UUID of FAT32 partition>/.

$ cp ./images/linux/boot.scr /media/training/<UUID of FAT32 partition>/.

$ sudo rm -rf /media/training/<UUID of ext4 partition>/*

$ sudo tar xvf ./images/linux/rootfs.tar.gz -C /media/training/<UUID of ext4 partition>/

$ sync; sync (VERY IMPORTANT to sync the filesystem BEFORE ejecting the SD card!  If you don't the filesystem may be corrupted.)

Instructions for Other Boot Methods

The example above is for the Ultra96-V2 SBC, and admittedly it is quite simple.  The other Avnet SOMs and SBCs support many more boot media besides INITRD or EXT4 boot from an SD card.  For example, the PicoZed SOMs can boot from JTAG, JTAG+TFTP, QSPI, QSPI+eMMC (INITRD and EXT4), and of course SD card (INITRD and EXT4).  That is a lot of different ways to boot the Linux OS image!  Avnet provides a "how_to_boot.txt" file of instructions for each supported boot method for every BSP build.  This instruction file will be found in the PetaLinux project folder when building the BSP via the build script and also in the <project>/pre-built/linux/images/ folder if the BSP was downloaded from the internet.

Rebuild the OS Image Binaries

New in the 2020.2 git branch of the PetaLinux repository are scripts to allow the user to easily rebuild the OS image binaries. This is especially convenient when making changes to the project, u-boot, kernel, or rootfs configurations and you need a way to easily rebuild the OS for testing but may not remember all of the exact steps.  These scripts are provided in board-specific subfolders of the "petalinux/scripts/rebuild/" repository folder, and are copied into the respective PetaLinux project and also in the <project>/pre-built/linux/images/ folder at BSP build time.  If using this script to rebuild a BSP that has been downloaded this script must first be copied to the project root folder.

The Value of a Known-Good Design and Starting Point

The key idea behind these PetaLinux build scripts and the "bdf", "hdl", and "petalinux" github repositories is to easily create a known-good BSP targeting an Avnet SOM or dev board quickly, easily, and repeatably.  Being able to start a Xilinx design from a known-good starting point is critical when designing with complex devices like Zynq and Zynq MPSoC.  There are many Linux kernel, u-boot, and root filesystem configuration details, from devicetree settings and software packages, etc., that can cause hours and days of anguish to debug if they aren't done correctly.  For the engineers at Avnet these build scripts have the added benefit of providing a starting point when it is time to update a published reference design.  Public users are also welcome to use these repositories and contribute.

Buy Ultra96-V2Buy Ultra96-V2

Buy Ultra96-V2 I-gradeBuy Ultra96-V2 I-grade

Buy 96Boards 4A Power SupplyBuy 96Boards 4A Power Supply

Buy Ultra96-V2 JTAG/UART AdapterBuy Ultra96-V2 JTAG/UART Adapter