5. Generate boot files for Xilinx SoC boards

To generate the required files to boot the SoC boards (Zynq and Zynq Ultrascale+ families), Xilinx offers the PetaLinux set of tools. Additionally, OmpSs@FPGA toolchain supports the automatic generation of boot files using these tools.

The following sections describe how to generate the boot files both manually and automatically.

5.1. Prerequisites

  • PetaLinux installer (2021.2 or newer)
  • Xilinx support archive (XSA) file from a synthesized Vivado project
  • Board Support Package (BSP) file for the target board

5.1.1. PetaLinux installation

PetaLinux is installed running its auto-installer package:

./petalinux-v2023.2-10121855-installer.run --dir <installation directory>

After installation, you should source the PetaLinux environment file. Usually, this needs to be done every time you want to run from a new terminal.

Caution

Sourcing PetaLinux settings file may change the ARM cross-compilers.

source <petalinux install dir>/settings.sh

5.2. PetaLinux project setup

The following steps should be executed once. After that, you will be able to generate boot files for the target board just using the ait feature or executing the steps in any of the following sections.

5.2.1. Unpack the bsp

Unpack the bsp to create the PetaLinux project:

petalinux-create -t project -s <path to board bsp> -n <project name>

5.2.2. Configure PetaLinux

Run PetaLinux configuration and change the root filesystem type to ext4:

petalinux-config

Image Packaging Configuration →
    Root filesystem type →
        EXT4 (SD/eMMC/SATA/USB)

You might also want to disable automatic copy to tftpboot to avoid a warning message at every build:

Image Packaging Configuration →
    Copy final images to tftpboot

Note

Some boards may fail to build the First Stage Boot Loader (FSBL) due to its size.

In order to shrink the FSBL provide the following flags to the compiler (this will disable support for NAND and QSPI boot modes):

FSBL Configuration →
    FSBL compiler flags →
        -DFSBL_NAND_EXCLUDE, -DFSBL_QSPI_EXCLUDE

5.2.3. Configure linux kernel

To enter the kernel configuration utility, run:

petalinux-config -c kernel

Note

You may want to increase the CMA size. It is used by Nanos6 as memory for the FPGA device copies. Its size can be set in:

Device drivers →
    Generic Driver Options →
        DMA Contiguous Memory Allocator

5.3. Generate boot files manually

Once PetaLinux project is setup, you can update it to contain a custom bitstream with your hardware. These steps can be repeated several times without executing again the steps in the PetaLinux project setup section.

First, you need to import the Xilinx support archive file (xsa) in the PetaLinux project. This is done by executing the following command in the root directory of the PetaLinux project build.

petalinux-config --silent-config --get-hw-description <path to project xsa file>

5.3.1. Add OmpSs@FPGA node to the device tree

The OmpSs@FPGA node must be added to the device-tree before compiling it.

Copy the file pl_ompss_at_fpga.dtsi generated by AIT to project-spec/meta-user/recipes-bsp/device-tree/files/.

Edit files project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi and project-spec/meta-user/recipes-bsp/device-tree/device-tree.bbappend and add the following lines:

echo '/include/ "pl_ompss_at_fpga.dtsi"' > project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi
echo 'SRC_URI:append = " file://pl_ompss_at_fpga.dtsi"' > project-spec/meta-user/recipes-bsp/device-tree/device-tree.bbappend

5.3.2. Build the Linux system

When the project is correctly updated, you can build it with the following command:

petalinux-build

5.3.3. Create BOOT.BIN file

Finally, generate the boot files by running the following command:

petalinux-package --force --boot --fsbl images/linux/zynq*_fsbl.elf --fpga <path to bitstream file> --u-boot images/linux/u-boot.elf

5.4. Use AIT to generate boot files

The Accelerator Integration Tool (AIT) can automatically and transparently perform the steps described in Generate boot files manually. To do so, you must:

  • Add the option --to_step=boot on the AIT call to enable the boot step
  • Set the environment variable PETALINUX_BUILD with the path to the pre-configured PetaLinux build project of the target board

Once the boot files have been correctly generated, AIT will copy them into the project directory at <AIT project path>/boot.

5.5. Copy the files to the SD boot partition

Finally, mount the boot partition of the board SD into your system and copy the required files (device name and paths might not be the same):

udisksctl mount --block-device /dev/mmcblk0p1
cp <path to petalinux project>/images/linux/BOOT.BIN /media/<user>/boot/
cp <path to petalinux project>/images/linux/image.ub /media/<user>/boot/
cp <path to petalinux project>/images/linux/boot.scr /media/<user>/boot/
udisksctl unmount --block-device /dev/mmcblk0p1