Petalinux Build Tutorial for ZU+ RFSoC ZCU111 2021.1 and 2021.2

This page describes the steps for creating and building a 2021.1 PetaLinux project for use with the ZCU111 RFSoC Evaluation tool.

Table of Contents


The ZCU111 RFSoC Evaluation Tool has three designs based on the functionality. A detailed information about the three designs can be found from the following pages.

This tutorial includes the following:-

  • Steps to source and setup the PetaLinux tool for building the images.  

  • Step-by-step tutorial to build all the images using the PetaLinux tool.  

  • Information about the relevant kernel and device tree patches as well as the applications within the designs.

For more details on ZU+ RFSoC RF Data Converter Evaluation Tool refer to ZCU111 RFSoC RF Data Converter Evaluation Tool Getting Started Guide.

Building the Linux Image


PetaLinux consists of three key elements: pre-configured binary bootable images, fully customizable Linux for the Xilinx device, and PetaLinux SDK which includes tools and utilities to automate complex tasks across configuration, build, and deployment. Visit the PetaLinux wiki page for more details. Refer to the PetaLinux Tool Documentation (UG1144) for installation.

Procedure to build the Linux Image

The following section provides the steps to build all the images using the petalinux tool.  

 Set $DCET_HOME environment variable as given below.

1 % export DCET_HOME=</path/to/download/zipfile>/rdf0476-zcu111-RFdc-eval-tool-2021.1
  1. Sourcing the petalinux tool:

1 % source <path/to/petalinux-installer>/petalinux-v2021.1/petalinux-v2021.1-final/

2. Post petalinux installation, $PETALINUX variable should be set, command to cross-check the variable:

1 % echo $PETALINUX

The following steps should be executed for each design (mts, non-mts and ssr).

3. Create a petalinux project from .bsp file:

1 2 3 % cd $DCET_HOME/apu/ % petalinux-create -t project -s rfsoc_petalinux_bsp.bsp % cd rfsoc_petalinux_bsp
  • After creating project, please refer to Modifications on top of 2020.1 release BSP

  • As per the TRD flow, by-default NON-MTS bitstream and device-tree are loaded first and thereafter the requested bitstream and respective device-tree. Hence, when building any other design, NON-MTS binaries should always be generated first and kept in SD-Card. Otherwise, it will throw an error.

4. Configure the PetaLinux project using step “a” or “b”.

a) With the pre-built XSA file located in folder <pl/<design_path>pre-built/rfsoc_trd>, depending on the design, user can select the "path".

Make sure the design_path indicates the folder in which the XSA resides.

1 % petalinux-config --get-hw-description=$DCET_HOME/pl/<design_path>/pre-built/rfsoc_trd/

For Example : If the user wants to build for Non-MTS Design, the design_path would be given as below:

1 % petalinux-config --get-hw-description=$DCET_HOME/pl/NON-MTSDesign_8x8/project/zcu111_rfsoc_trd.sdk/

b) If Vivado project is modified/design is changed, user is expected to configure the bsp with the modified XSA file as follows:

1 % petalinux-config --get-hw-description=$DCET_HOME/pl/<design_path>/project/zcu111_rfsoc_trd.sdk/

After executing step "a" or "b", petalinux menuconfig will be displayed, change the following:

In FPGA Manager :

i. Enable "FPGA Manager".

ii. In "Specify hw directory path", add path to XSA as


iii. Save and Exit.

5. Build all Linux image components along with Evaluation Tool application:

1 % petalinux-build

The following steps are required as we load the design-type bitstream and design-type device-tree dynamically by enabling the FPGA-manager. Therefore, pl.dtsi is not part of packaged kernel image (image.ub) and has to be loaded separately.

The pl.dtbo gets auto generated inside $DCET_HOME/apu/rfsoc_petalinux_bsp/images/linux folder after Step 5.

6. Create <design_type> sub-directories in the sd-card directory (design_type can be mts, nonmts and ssr).

% mkdir -p $DCET_HOME/sd-card/<design_type>

7. Navigate to <petalinux-project>/images/linux/ folder. Copy pl.dtbo from this directory (rfsoc_petalinux_bsp/images/linux) to sdcard directory

% cd $DCET_HOME/apu/rfsoc_petalinux_bsp/images/linux 2% cp pl.dtbo $DCET_HOME/sd-card/<design_type>

8. To generate the design-type bitstream for each design, create a new file called bitstream.bif in the same location with the following content:

9. Create a new file called bitstream.bif in the same location with the following content:

1 2 3 4 all: { [destination_device = pl] system.bit /* Bitstream file name */ }

10. Generate bitstream in bin format using the following command:

1 % bootgen -image bitstream.bif -arch zynqmp -o zcu111_rfsoc_trd_wrapper.bit.bin -w

 11. Copy bitstream to sdcard directory.

1 % cp zcu111_rfsoc_trd_wrapper.bit.bin $DCET_HOME/sd-card/<design_type>

 12. Create a boot image (BOOT.BIN) including FSBL, ATF, PMUFW and u-boot:

1 % petalinux-package --force --boot --fsbl zynqmp_fsbl.elf --pmufw pmufw.elf --u-boot u-boot.elf

 13. Copy BOOT.BIN, boot.scr, Image, system.dtb, rootfs.cpio.gz.u-boot to sdcard:

1 % cp BOOT.BIN boot.scr Image system.dtb rootfs.cpio.gz.u-boot $DCET_HOME/sd-card

Modifications on top of 2021.1 released BSP

Below are the modification in this TRD for linux-kernel, rfdc drivers, rftool, rfdc example, trd-autostart applications and device tree on top of 2021.1 petalinux released BSP. For more details on patch information please refer to AR# 75664: ZCU111 2021.1 BSP patch files .

  • Kernel patch information as follows:

1 2 3 4 5 6 7 8 9 10 11 12 13 vim project-spec/meta-user/recipes-kernel/linux/linux-xlnx_%.bbappend SRC_URI_append = " \ file://0001-power-supply-irps-Add-support-for-irps-supply.patch \ file://0002-drivers-misc-add-support-for-DDR-memory-management.patch \ file://0003-dmaengine-xilinx_dma-In-SG-cyclic-mode-allow-multipl.patch \ file://0004-drivers-misc-add-support-for-selecting-mem-type.patch \ file://0005-i2c-cadence-Implement-timeout.patch \ file://0006-drivers-misc-change-ADC-packet-size-as-per-FIFO-size.patch \ file://0007-drivers-misc-change-parameters-for-of_dma_configure.patch \ file://0008-plmem-clean-up-sysfs-node-and-character-device-nodes.patch \ file://0009-dma-clean-the-BD-s-only-when-done-bit-is-set.patch \ file://0010-misc-plmem-replace-dma_declare_memory-with-reserved-.patch \ file://0011-DMA-changes-as-per-kernel-v5_10.patch \"
  • RFTOOL application patch as follows:

1 % vim project-spec/meta-user/recipes-apps/rftool/
  • RFDC example application patch as follows:

1 % vim project-spec/meta-user/recipes-apps/rfdc-data-write-example/
  • TRD Autostart patch information as follows:

1 % vim project-spec/meta-user/recipes-apps/trd-autostart/
  • RFDC Self-test application changes as follows:

1 2 3 % vim project-spec/meta-user/recipes-bsp/rfdc-examples/rfdc-selftest_%.bbappend SRC_URI_append = " \ file://0001-selftest_example-change-default-frequency.patch \"
  • RFDC Read-Write application changes as follows:

1 % vim project-spec/meta-user/recipes-bsp/rfdc-examples/rfdc-read-write_%.bbappend
  • Device Tree Changes are as follows:

The changes required with respect to pl memory nodes in kernel version 5.10 have been updated in the following path.

1 % vim project-spec/meta-user/recipes-bsp/device-tree/files/pl-custom.dtsi

The changes required with respect to contiguous memory allocation (CMA size) are updated in the following path.

1 % vim project-spec/meta-user/recipes-bsp/device-tree/files/system_user.dtsi

To get "project-spec/meta-user/" folder, please extract files from. bsp using step #3 from above.

For known issues and limitations for version 1.8 of the ZCU111 Evaluation Tool please refer to the answer record-AR71424.

  1. GPIO chip base address has been changed from 416 to 412 in /sys/class/gpio/.

  2. SMBUS bus number for configuring clocks of dac/adc has been changed from 12 to 11.

Once the images are built successfully the user can refer to for further information on test set-up.