Integrating Vitis Acceleration Designs with Certified Ubuntu

This page documents how to integrate the standard Vitis software development process into the Certified Ubuntu for Xilinx Devices workflow. The Certified Ubuntu on Xilinx Devices release is based on the Xilinx 2020.2 release so all references are based on this software stack. The documentation below uses a command line flow for building the Vitis design. Use of the Vitis GUI is not documented, though the same concepts should apply.

This process is currently limited to the ZCU10x evaluation boards. Kria documentation is coming soon.

Table of Contents

Building the Vitis Platform Components

The first step is to build the Vitis platform components.  For this tutorial, the hello_world application from the Xilinx Vitis_Accel_Examples GitHub repository is used, but any application build will follow the same basic steps.

To start, clone the Vitis_Accel_Examples repository and switch to the latest 2020.2 tag:

git clone https://github.com/Xilinx/Vitis_Accel_Examples.git cd Vitis_Accel_Examples git checkout 2020.2_update1

Next, change to the hello_world application directory

cd hello_world

Note that there is a bug in the utils.mk file for the 2020.2 release which must be fixed prior to compiling the platform.  The bug is that there are spaces in the variable declarations found around line 50.  The references to DEV_FAM can be removed because they are not used in this example but the easier fix (for future maintainability) is to fix the declarations by removing the spaces. This bug is fixed in the 2021.1_rel1 release (commit).

#Checks for Device Family ifeq ($(HOST_ARCH), aarch32)        DEV_FAM=7Series else ifeq ($(HOST_ARCH), aarch64)        DEV_FAM=Ultrascale endif

Next, compile the platform with the following syntax:

The options used are as such:

  • For Zynq UltraScale+ devices, the HOST_ARCH must be set to aarch64

  • To compile the platform, TARGET must be set to hw

  • The DEVICE value is the full path to the .xpfm target platform file, including the filename

  • The EDGE_COMMON_SW argument is unused in this example but must be set to something non-null for the compilation to complete

These steps are largely unchanged from a standard Vitis build.

Build the Vitis Software Components

After the platform is compiled, the software components must be compiled.  Unlike the platform, the software compilation makes direct use of the Certified Ubuntu for Xilinx devices release.  Specifically, it uses the official sysroot component which can be downloaded from https://ubuntu.com/download/xilinx

Download and extract the file iot-zcu10x-classic-desktop-2004-x07-20210728-85-sysroot.tar.xz.  Next, extract the sysroot file with tar xvf  iot-zcu10x-classic-desktop-2004-x07-20210728-85-sysroot.tar.xz.

After extracting the sysroot, compile the software components with the following syntax:

The syntax is deconstructed as follows:

  • The host flag to make instructs it to build the host-side software application

  • The CXX argument should point to the local non-Xilinx version of the g++ tool (not gcc). It must be the version from the host OS package manager rather than the Xilinx -provided version.  This may require the installation of the g++-aarch64-linux-gnu package

  • HOST_ARCH is once again set to aarch64 since the software will run on the ZynqMP processor

  • EDGE_COMMON_SW must point to the path containing the Certified Ubuntu on Xilinx Devices “sysroots” directory

Example:

Note that the directory specified in EDGE_COMMON_SW is expected to contain a sub-directory called “sysroots” and inside it is expected a directory called “aarch64-xilinx-linux”.

Once the build is complete, the binary will be created in the source code directory (in this case “hello_world”)

Constructing the Platform Assets Container

The Certified Ubuntu on Xilinx Devices software environment is heavily centered around a set of boot assets including the firmware code (eg, FSBL, bl31.elf, pmufw.elf, etc) and bitstream configuration.  The xlnx-config utility manages these assets for the user and can switch between different configurations on the running system.

A given set of boot assets is called a Platform Assets Container (PAC) and is structured as noted on the Xilinx wiki here: https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/2057043969/Snaps+-+xlnx-config+Snap+for+Certified+Ubuntu+on+Xilinx+Devices#Directory-Structure-and-Configuration-Assets

Scripting the PAC Creation for Vitis Builds

The PAC scheme can also be used to collect and deploy collateral related to a Vitis Accelerated Platform. Since the required contents can be dispersed in various places in the filesystem, the script below can automate collecting all of the contents into a properly formed PAC directory structure. The experimental create_vitis_pac.sh script has been developed and tested against the 2020.2 tag of the Vitis Accel Examples repository.

The script It is run at the command line and accepts several arguments needed to properly generate the directory structure.  In addition, the create_ubuntu_pac.sh script also regenerates the manifest.yaml file after each run to reflect the current state of the PAC.

When run, the create_ubuntu_pac.sh script initially accepts names for the directories contained with the PAC.  In addition, it requires the user to specify which board is being used.  The board is validated against a current whitelist since not all board configurations are supported by xlnx-config.  The create_ubuntu_pac.sh script also accepts the full path to the reference Vitis hardware platform file (eg, .xpfm file).  From this path it constructs the paths to other components – specifically the boot assets for the Vitis hardware platform and copies them into the PAC.  Finally, the script can (optionally) accept a path to software components and these components are placed in the swdata directory inside the PAC.

Note that the create_ubuntu_pac.sh script populates the manifest.yaml with some default metadata.  If you require more complete metadata, manually edit the manifest.yaml file before copying it to the target Ubuntu system.

The create_vitis_pac.sh script below is provided as-is as a reference at this time.

Vitis PAC Creation Script Usage

Usage

Examples

The following examples shows how to create PAC that includes both the hello_world and mult_compute_units examples for the zcu102 board.

To create a new PAC and add the mult_compute_unit boot assets to it, use the following command from the root directory of the Vitis_Accel_Examples repo:

 

To add the hello_world boot assets into the PAC, use the following command:

Finally, copy the resulting PAC directory structure to the /boot/firmware/xlnx-config/ directory on the Ubuntu SD card, and follow the directions for using a custom PAC here:

https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/2057043969/Snaps+-+xlnx-config+Snap+for+Certified+Ubuntu+on+Xilinx+Devices#ZCU10x-Usage-Example

 

© Copyright 2019 - 2022 Xilinx Inc. Privacy Policy