Linux Boot Files

PetaLinux can generate the Linux boot files for an SDSoC platform using the process documented in PetaLinux Tools Documentation: Workflow Tutorial (UG1156). The overall workflow for SDSoC platforms is the same, and the basic steps are outlined below. If you are familiar with the PetaLinux tools, you should be able to complete these steps for Zynq® UltraScale+™ MPSoC or Zynq®-7000 SoC designs.

Before starting, you should complete the following:

  1. Set up your shell environment with PetaLinux tools in your PATH environment variable.
    IMPORTANT!: Because of the different configuration requirements for the different tools, such as the Vivado Design Suite and PetaLinux, running the tools in separate terminal shells is the recommended practice.
  2. Create and cd into a working directory.
  3. Create a new PetaLinux project targeting a BSP that corresponds to the type of board you are targeting:
    petalinux-create –t project -n <project_name> \
    -s <path_to_base_BSP>
  4. Obtain a copy of the hardware handoff file (.hdf) from the Vivado project for your hardware platform.
IMPORTANT!: This guide assumes the existence of a valid hardware description file (HDF) for the platform, which is generated from the Vivado Design Suite project. Refer to SDSoC Hardware Platform Creation for more information..

The steps below include basic setup, loading the hardware handoff file, kernel configuration, root file system configuration, and building the Linux image, fsbl, pmufw, and atf. The steps include the actions to perform, or the PetaLinux command to run, with arguments. Once the build completes, your working directory contains a FIT image file (image.ub) that includes the devicetree, kernel and ramdisk. The basic setup is the procedure used to configure the Linux images packaged in all base platforms shipped with SDSoC platforms.

When using the petalinux-config command, a text-based user interface appears with a hierarchical menu system. The steps present a hierarchy of commands and the settings to use. Selections with the same indentation are at the same level of hierarchy. For example, the petalinx-config –c kernel step asks you to select Device Drivers from the top-level menu, select Generic Driver Options, go down one level to apply settings, go back up to Staging drivers, and apply settings to its sub-menu items.

Building the PetaLinux Image

To build the PetaLinux image, use the following steps:

  1. Configure PetaLinux with the HDF derived earlier for the associated platform (the production of which is described in the introduction):
    petalinux-config -p <petalinux_project> \
    --get-hw-description=<HDF path>
    Optionally, change boot args to include "quiet" at the end of whatever is the default:
    • Kernel Bootargs→generate boot args automatically (OFF)
    • for Zynq MPSoC: Kernel Bootargs→ user set kernel bootargs (earlycon clk_ignore_unused quiet)
    • for Zynq-7000: Kernel Bootargs→ user set kernel bootargs (console=ttyPS0,115200 earlyprintk quiet)
  2. Configure PetaLinux kernel:
    petalinux-config -p <petalinux_project> \
    -c kernel
    Set CMA size to be larger, for SDS-alloc buffers:
    • for Zynq MPSoC: Device Drivers→ Generic Driver Options → Size in Mega Bytes(1024)
    • for Zynq-7000: Device Drivers→ Generic Driver Options → Size in Mega Bytes(256)
    Enable staging drivers:
    • Device Drivers → Staging drivers (ON)
    Enable APF management driver:
    • Device Drivers → Staging drivers → Xilinx APF Accelerator driver (ON)
    Enable APF DMA driver:
    • Device Drivers → Staging drivers → Xilinx APF Accelerator driver → Xilinx APF DMA engines support (ON)

    For Zynq MPSoC, you must turn off CPU idle and frequency scaling. To do so, mark the following options:

    • CPU Power Management->CPU idle->CPU idle PM support (OFF)
    • CPU Power Management->CPU Frequency scaling->CPU Frequency scaling (OFF)
  3. Configure petalinux rootfs:
    petalinux-config -p <petalinux_project> \
    -c rootfs
    Add stdc++ libs:
    • Filesystem Packages → misc → gcc-runtime → libstdc++ (ON)
  4. Add device tree fragment for APF driver. At the bottom of <>/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi, add the following entry:
     xlnk {
     compatible = "xlnx,xlnk-1.0";
  5. Build the PetaLinux image:
    • petalinux-build

Preparing the Image for the SDSoC Platform Utility

In the directory <petalinux_project>/images/linux/ there are a number of important files that are partitioned into two categories:
  1. Files that end up compiled into BOOT.BIN, referred to collectively as ‘boot files’, that should be copied into a boot folder. Boot files include the following: u-boot.elf, zynq-fsbl.elf or zynqmp-fsbl.elf, along with bl31.elf and pmufw.elf for Zynq UltraScale+ devices.
  2. Files that must reside on the SD card but are not compiled into BOOT.BIN, referred to as ‘image files’, that should be copied into an image folder. The only image file from a PetaLinux build is image.ub, but you can add other files to the image folder that you want to make available to users of the platform.
From within the <petalinux_project>/images/linux/ folder run the following commands:
$ mkdir ./boot
$ mkdir ./image
$ cp u-boot.elf ./boot/u-boot.elf
$ cp *fsbl.elf ./boot/fsbl.elf
$ cp bl31.elf ./boot/bl31.elf
$ cp linux/pmufw.elf ./boot/pmufw.elf
$ cp image.ub ./image/image.ub
TIP: The bl31.elf and pmufw.elf files are only required for for Zynq UltraScale+ devices.

Finally, create a boot image format, or BIF file, that is used to compile the contents of the boot folder into a BOOT.BIN file. For more information on creating the BIF file for a target processor, refer to Zynq-7000 SoC Software Developers Guide (UG821) or Zynq UltraScale+ MPSoC Software Developer Guide (UG1137).

An SDSoC boot image format file looks similar to a standard BIF file, with tokens specified in angle brackets (< >) rather than direct paths to boot files. The BIF file tokens are replaced at SDSoC compile time with actual files and generated content. This is because the bitstream file for the programmable logic (PL) region will be procedurally generated, and some of the elements do not have known file names at the time the BIF file is created.

The following is an example boot.bif file for the Zynq-7000 SoC:
/* linux */
The following is an example BIF for a Zynq UltraScale+ MPSoC device:
  [fsbl_config] a53_x64
  [destination_device=pl] <bitstream>
  [destination_cpu=a53-0, exception_level=el-3, trustzone] <bl31.elf>
  [destination_cpu=a53-0, exception_level=el-2] <u-boot.elf>

Taken together, the boot directory, the image directory, and the BIF file, constitute the software elements that the SDSoC platform project needs as input for the Linux OS. See Defining the Software Platform for more information.