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 aarch64To compile the platform,
TARGET
must be set to hwThe
DEVICE
value is the full path to the .xpfm target platform file, including the filenameThe
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 applicationThe
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 theg++-aarch64-linux-gnu
packageHOST_ARCH
is once again set to aarch64 since the software will run on the ZynqMP processorEDGE_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: 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:
Snaps - xlnx-config Snap for Certified Ubuntu on Xilinx Devices | ZCU10x Usage Example
© Copyright 2019 - 2022 Xilinx Inc. Privacy Policy