Using Vitis Embedded Platforms

Packaging Images

A new packaging stage is added to the Vitis™ compiler (v++) in 2020.1.

In 2019.2, v++ had two stages:

  • -c or --compile to compile acceleration kernels
  • -l or --link to link acceleration kernels with platform logic.

In the 2020.1 release, the new stage is -p or --package. The command V++ --package generates both boot.bin and the sd_card image files.

The --package command supports both initramfs and Ext4 rootfs images.

In the Vitis IDE, the package stage is automatically called during the build process. You can add additional package options in the system project detail page by double-clicking the .sprj file. Package log files, command configuration files, and output files are stored in the package directory under the Emulation-SW, Emulation-HW or Hardware directories.

In command line mode, you can pass in package options as v++ options or configuration files. For more detailed information about the v++ --package option, refer to the Vitis Compiler Command or the v++ -help command, and the Xilinx Vitis Acceleration Examples GitHub repository.

Packaging Images with Ext4 rootfs in the Vitis IDE

When ext4 rootfs is provided to the Vitis IDE, the generated sd_card.img file includes the following:
  • The xclbin file for PL kernel
  • The host application
  • The Linux kernel image
  • The device tree
  • The u-boot configuration file: boot.scr
  • The platform initialization script init.sh and platform name in platform_desc.txt.
    Note: init.sh sets up the environment variable XILINX_XRT and copies the platform_desc.txt file to /etc/xocl.txt. This must be executed manually.
  • The ext4 rootfs in the Ext4 partition

To package an image with Ext4 rootfs in the Vitis IDE:

  1. Select File > New > Application Project to create a new application project in the Vitis IDE.
  2. Select the platform (for example, xilinx_zcu102_base_202010_1), and click Next.
  3. Provide a name for the application project (for example, vadd)
  4. For the System Project selection, select Create New.
  5. For the Target processor, select the processor that can run the Linux domain (for example, psu_cortexa53 SMP), and click Next.
  6. In the Domain page, select xrt and provide the following application settings:
    • Sysroot path (for example, xilinx-zynqmp-common-v2020.1/sysroots/aarch64-xilinx-linux)
    • Root FS (for example, xilinx-zynqmp-common-v2020.1/rootfs.ext4)
    • Kernel Image (for example, xilinx-zynqmp-common-v2020.1/Image)
  7. Click Next.
  8. Select an application template (for example, Vector Addition) and click Finish.
  9. Select the system project and click the Build () button to build the project.
  10. Verify that the sd_card.img file was created in the package directory under the Emulation-SW, Emulation-HW or Hardware directory.
TIP: To change the path for sysroot, rootfs, or kernel after the application project has been created, double-click the .sprj file and change the path in the Options dialog box.

Packaging Images with initramfs rootfs in the Vitis IDE

When initramfs rootfs (rootfs.cpio) is provided to the Vitis IDE, the generated sd_card.img includes the following:
  • The xclbin file for PL kernel
  • The host application
  • The Linux kernel image
  • The device tree
  • The boot.scr
  • The init.sh, platform_desc.txt, and initramfs rootfs in FAT32 partition
Note: The sd_card.img file does not contain the ext4 partition.
  1. In the Vitis IDE, select File > New > Application Project to create a new application project.
  2. Select the platform (for example, xilinx_zcu102_base_202010_1), and click Next.
  3. Provide the application project name (for example, vadd).
  4. Select Create New.
  5. For the target processor, select the processor that can run the Linux domain (for example, psu_cortexa53 SMP), and click Next.
  6. In the Domain page, select the xrt domain and provide the application settings as follows:
    1. Sysroot path (for example, your_linux_component_dir/sysroots/aarch64-xilinx-linux)
    2. Root FS (for example, your_linux_component_dir/rootfs.cpio.gz.u-boot)
    3. Kernel Image (for example, your_linux_component_dir/Image)
  7. Click Next.
  8. Select the application template (for example, Vector Addition).
  9. Select the system project and click the Build () button to build the project.
  10. Verify that the sd_card.img file was created in the package directory under the Emulation-SW, Emulation-HW or Hardware directory.
Note: The common Linux components package does not provide initramfs rootfs. For more information about generating initramfs rootfs, refer to PetaLinux Tools Documentation: Reference Guide (UG1144).
TIP: To change the path for sysroot, rootfs, or kernel after the application project has been created, double-click the .sprj file and change the path in the Options dialog box.

Writing Images to the SD Card

You can use the Vitis unified software platform accelerated flow to target an embedded platform. This facilitates packaging and creating an SD image with RootFS as an EXT4 partition, because initramfs uses Double Data Rate SDRAM (DDR SDRAM) for file system storage. It limits the real usable DDR memory for Linux kernel and applications when the file system size increases. It cannot retain RootFS changes after reboot.

To write EXT4 RootFS to an SD Card:

  1. Prepare an SD card binary image file with FAT32 partition for boot and EXT4 partition for RootFS.
  2. Write SD card images to the SD card. You can use various tools to do this, such as Etcher on Windows or dd command on Linux.
    Note: Refer to Xilinx Answer Record 73711 for detailed information about these tools.

There are various ways to prepare an SD card image. You can use the v++ package tool to generate it, or use an open source tool. A pre-built SD card image is also provided in the base platform package, which you can download from the Vitis Embedded Platforms download page.

The pre-built SD card image (pre-built/sd_card.img) has two partitions:

FAT32 partition
1 GB size, initialized with the kernel image provided by common Linux components.
EXT4 partition
2 GB size, initialized with RootFS provided by common Linux components.

To make the pre-built SD card image boot, you must copy the following boot components to the FAT32 partition:

  • pre-built/BOOT.BIN
  • boot.scr, system.dtb, init.sh, and platform_desc.txt in the xrt/image directory

The pre-built SD card image can be used for evaluation usage and by Windows users. It does not require Vitis or PetaLinux to be installed.

Note: The v++ --package with Ext4 partition is not supported on Windows.
Note: init.sh sets up the environment variable XILINX_XRT and copies the platform_desc.txt file to /etc/xocl.txt. You must manually run this after Linux boots up before running any acceleration applications.

Configuring the PL Kernel in DFX Platforms and Non-DFX Platforms

The Xilinx Dynamic Function eXchange (DFX) feature can change some blocks of PL function while keeping other areas of PL working, allowing you to configure PL kernels on the fly. To use the DFX feature, when the xclbin file is generated, configure it with your host application. The new kernels in the xclbin take effect immediately without requiring a reboot.

For platforms without DFX features, PL kernel must be packed into boot.bin. Copy it to the FAT32 partition on your SD card and reboot the system. Then, configure the xclbin file with your host application.

The xclbin file contains both bit files for PL kernel and metadata to describe these kernel features and connections. Programming the xclbin file on DFX platforms loads the bit file and metadata; programming on non-DFX platforms only loads the metadata.

Running an Acceleration Application on the Board

If you are using the common Linux components that are provided by Xilinx perform the following to run an acceleration application on the platform:

  1. To the SD card, write the sd_card.img generated by the Vitis compiler command v++ --package.
  2. Boot the board.
  3. Run the command cd /mnt/sd-mmcblk0p1/.
  4. Run the command source init.sh.
  5. Run acceleration application. For example, for vector addition, run ./vadd ./binary_container_1.xclbin.

Acceleration application uses Xilinx Runtime (XRT) to communicate with acceleration kernels. To set up the environment for XRT, run init.sh. This command does the following:

  • It sets the environment variable XILINX_XRT to /usr to allow the application to find the XRT environment.
  • It copies platform_desc.txt to /etc/xocl.txt to inform XRT which platform it is running on.
Note: This was done automatically for embedded platforms in the 2019.2 release of Vitis. Because automatically running init.sh may introduce security breaches, common Linux rootfs did no run init.sh by default.
Note: If the sd_card.img file has already been written to the SD card and you are only updating the application, you can save time in the debugging phase by copying all files from <Vitis System Project>/Hardware/package/sd_card to FAT32 partition on SD card to replace existing files. The Ext4 partition does not change in sd_card.img.

Software Package Management in PetaLinux rootfs

The package management feature is new for the Vitis 2020.1 release. All PetaLinux rootfs software packages are hosted on http://petalinux.xilinx.com/sswreleases/rel-v2020/feeds. You can install these software packages to rootfs when running Linux on the target board as long as the board has Internet access.

To use this feature, you must enable package manager DNF in rootfs. The rootfs in Xilinx-provided pre-built Linux components provides the DNF package management features by default.

To set up a package feed URL:

  1. Visit the package feed repo directory http://petalinux.xilinx.com/sswreleases/rel-v2020/generic/rpm/repos/.
  2. Download the repo file that matches your SoC device to target board.
    # Example: ZCU102 uses ZU9EG devices
wget http://petalinux.xilinx.com/sswreleases/rel-v2020/generic/rpm/repos/zynqmp-generic_eg.repo
# Example: ZCU104 uses ZU7EV devices
wget http://petalinux.xilinx.com/sswreleases/rel-v2020/generic/rpm/repos/zynqmp-generic_ev.repo
  3. Copy the downloaded repo file to /etc/yum.repos.d/.
  4. Clean the cache.
    dnf clean all

To manage packages, use DNF:

  • Listing available packages: Use the command dnf repoquery.
  • Installing packages from a Xilinx repository: Use the command dnf install <pkg name>.

Here are some basic functions you can run with the DNF package manager.

Listing available packages
Use the command dnf repoquery.
Installing packages from a Xilinx repository
Use the command dnf install <pkg name>.
Installing packages from a local package file
Use the command dnf install <pkg file name>.
Installing packages to sysroot

When packages are installed on the rootfs of a running board, target has the latest binaries and libraries. When cross compiling on host is needed, these libraries must be added to host side sysroot.

A sysroot_overlay script is provided in XRT to extract RPM and update sysroot. This script will extract RPM libraries and include a file update in sysroot.

Besides XRT, this script supports all RPMs for various software packages.

Getting the sysroot_overlay.sh
Use the command wget https://github.com/Xilinx/XRT/blob/master/src/runtime_src/tools/scripts/sysroots_overlay.sh.
The sysroot command description is:
./sysroots_overlay.sh --sysroot --rpms-file

Where:

  • --sysroot is the sysroot to be overlaid.
  • --rpms-file is the RPMs file that contains the RPM file paths to be overlaid.

Examples

The following example is a command to install updated XRT to the common sysroot:

./sysroots_overlay.sh -s sysroots/aarch64-xilinx-linux/ -r $PWD/rpm.txt

This example shows the contents of an rpm.txt file:

./xrt-dev-202010.2.6.0-r0.aarch64.rpm
./xrt-202010.2.6.0-r0.aarch64.rpm
Note: This script works only for the local RPMs. You must download RPMs to your host machine to install them to the common sysroot.