Installation Guide for Platform Deployment Packages¶

The Platform Deployment Package is needed when using an Alveo® Versal® Data Center accelerator card. This could be to:

run a newly created application (XCLBIN) generated with Vitis and the Platform Development Package

run a 3rd party application created for the desired platform

run some built-in applications to validate the hardware, see xbtest or xbutil validate

Attention

When using 3rd party applications they will be platform dependent. Check that they support your desired Alveo card and platform.

Platform Naming and Life Cycle¶

Package Naming¶

Starting with the 2022.1 release, Alveo Versal platforms are delivered through a single Linux installation deployment package outlined in the following table. Platforms consisted of multiple dependent deployment packages in previous releases.

**Table: Versal Deployment Package Types**¶
Tools	Package	Description
2021.2 or earlier	Partition	Contains a device PDI that implements the static region of the deployment platform.
	Validate	Contains binaries to validate a platform installation and Alveo card setup.
	Firmware	Contains compiled SC and CMC firmware binary files.
2022.1 onwards	Partition	Contains all device configuration and validation device binaries.

The partition installation package names are generated by concatenating the following elements:

<name>_<version>-<release>-<architecture>[-<OS version>].<extension>

Each element consists of one or more sub-elements and are further described in the following table.

**Table: Deployment Package Name Element Fields**¶
Element	Sub-Element	Description	Examples
Name	Company	Vendor name.	xilinx
	Card	Card name.	vck5000
	Chassis	PCIe Link and DMA Type.	gen4x8-xdma
	Partition	Partition type. For Alveo Versal only base is supported.	base
Version		Version of chassis. Dot separated list of integers. Increments when chassis interface changes.	1.1, 2
Release		Integer release number.	2200000
Architecture		Indicates processor architecture for RPM packages. Will always be noarch for Versal platform packages.	noarch
OS Version		Only applies to Ubuntu packages. Will always be all for Versal platform packages.	all
Extension		Package extension. rpm for RedHat and CentOS. deb for ubuntu.	rpm deb

The following is an example of a deployment installation package for Ubuntu:

xilinx-vck5000-gen4x8-xdma-base_2-20220303_all.deb

Life-cycle of a Platform and User Applications¶

For the initial Versal platforms only the released version of XRT is supported for the platform. This differs from previous Ultrascale platforms where at least 1 year of backwards compatibility was provided.

At present there is no guarantee of backwards compatibility for applications (XCLBINs) used to program the DFX region. Vitis-generated XCLBINs must always be generated with the same version of tools as was used to generate the platform even if newer tools versions are available. For example, if you are using a platform created with version 2022.1 of the tools then version 2022.1 must be used to create the application XCLBIN.

Info

This restrictive compatibility limitation will be relaxed in future platform releases.

Deployment Package Installation¶

This section details the procedures for installing deployment software on RedHat/CentOS and Ubuntu operating systems. All software installations use standard Linux RPM and Linux DEB packages and require root access.

The deployment software consists of the following software packages:

Xilinx runtime (XRT): XRT provides the libraries and drivers for an application to run on an Alveo Versal acceleration cards and also includes xbutil and xbmgmt utilities. Utility command line help can always be obtained using the –help option.

Deployment platform: The deployment platform provides the base firmware needed to run pre-compiled applications. It cannot be used to compile or create new applications. To create new applications, install the development software. Whilst you can also install the development software on a machine with an installed card, doing so is not necessary to run applications.

All installation packages can be downloaded from the relevant lounges as listed in the table below.

Attention

Please install the version of XRT in the lounge for the desired platform. If a different version of XRT is already installed in your system please ensure it’s version is at least the same that specified in the lounge but not more than the life-cycle guarantee above. For changing XRT version please see Changing XRT and Target Platform Versions.

Attention

The version of development package used to create applications must explicitly match the version of deployment package used to run the applications.

Info

Root access is required for all software and firmware installations.

**Table: Alveo Versal Deployment Packages**¶
Platform Name	Tool Version	SC Version	Platform UUID
Manufacturing Image	N/A	4.4.9	A1D8D240-49C0-ED21-27A9-C3EC8520ECB1
vck5000-gen3x16-xdma-base-1	2021.2	4.4.12	96E93BAB-A74E-D333-EE00-F559D71933A2
vck5000-gen4x8-xdma-base-2	2022.1	4.4.33	04624343-B44B-B0A1-3CD4-8A411789FF20
vck5000-gen4x8-qdma-base-2	2022.2	4.4.35	05DCA096-76CB-730B-8D19-EC1192FBAE3F

Note

VCK5000 Data Center Acceleration Development Kit Hardware Installation Guide (UG1531) is only applicable to new VCK5000 cards running the vck5000-gen3x16-xdma-base-1 platform.

The Platform Name, SC Version and Platform UUID will be used later to perform and verify installation. Click the links in the table above to download the required installation packages.

The deployment package installation procedure has been split into three major steps:

Installation of XRT and the deployment package on the host operating system

Installation of the deployment platform configuration data on the target card

Validation of the installation procedure

XRT environment setup:¶

Note

After installing XRT, it may be necessary to setup the XRT environment to use the utilities below (xbmgmt, xbutil) by running the following command. Note that the command is dependent on the shell-type in use.
Use the following command in a csh shell:
$ source /opt/xilinx/xrt/setup.csh
Use the following command in a bash shell:
$ source /opt/xilinx/xrt/setup.sh
This only needs performed if the system has been rebooted or a new terminal is opened. Running which xbmgmt should indicate if the location of the XRT utilities (/opt/xilinx/xrt/bin) is already known to the system.

Step 1 (RedHat and CentOS) Package Installation¶

Use the following steps to download and install the XRT and deployment platform using a .rpm installation package.

The following steps apply for the first time installation for a card. For details on installing a newer or older version of XRT and deployment platform, see Changing XRT and Target Platform Versions.

XRT installation requires Extra Packages for Enterprise Linux (EPEL) and a related repository. If not already installed, install EPEL on your system by following the steps provided in XRT Installation.
Run the following commands to install kernel headers and kernel development packages. Ensure that uname is surrounded by backticks (`) and not single quotes (‘).
$ sudo yum install kernel-headers-`uname -r`
$ sudo yum install kernel-devel-`uname -r`
After the previous command completes, warm reboot your machine.

Download the Xilinx® runtime (XRT) and deployment target platform installation packages from the appropriate lounge, see links in table above.
Install the XRT package by running the following command from within the directory where the installation packages reside. <version> is the latter part of the installation package file name.
$ sudo yum install ./xrt_<version>.rpm
This will install XRT to /opt/xilinx/xrt/. Follow the instructions when prompted throughout the installation.
Unpack the deployment target platform tar.gz file into a single directory. The location of the directory is not important, however the directory should not contain any other files.
Install the deployment packages. From within the directory where the installation packages were unpacked, run the following command. This will install all deployment packages.
$ sudo yum install ./*.rpm

Proceed to step 2 to install the deployment platform configuration files onto the Alveo Versal card.

Step 1 (Ubuntu) Package Installation¶

Use the following steps to download and install the XRT and deployment platform using a .deb installation package.

For details on installing a newer or older version of XRT and deployment platform, see Changing XRT and Target Platform Versions.

From the appropriate lounge, see links in table above, download the Xilinx® runtime (XRT) and deployment target platform installation packages.
Install the XRT installation package by running the following command from within the directory where the installation packages reside. <version> is the latter part of the installation package file name.
$ sudo apt install ./xrt_<version>.deb
This will install XRT to /opt/xilinx/xrt/ and its necessary dependencies. Follow the instructions when prompted throughout the installation.
Unpack the deployment target platform tar.gz file into a single directory. The location of the directory is not important, however the directory should not contain any other files.
Install the deployment packages. From within the directory where the installation packages were unpacked, run the following command. This will install all deployment packages.
$ sudo apt install ./*.deb

Proceed to step 2 to install the deployment platform configuration files onto the Alveo Versal card.

Step 2 Installation On The Card¶

Attention

FOR VCK5000 PLATFORMS ONLY. From Tools version 2022.1 onwards, new cards or cards with pre-2022.1 platforms installed must be explicitly migrated. Please see the VCK5000 Migration Guide to complete the steps for migration. After which continue to step 3 to complete installation.

It may be necessary to setup the XRT environment to use the xbmgmt utility below. See XRT environment setup.

Flash the platform firmware on the card.
$ sudo xbmgmt program --base shell --device <Management BDF> --image <platform name>
To find the correct <platform name> see Alveo Versal Deployment Packages Table above. To find <Management BDF> see Obtaining Card BDF Values

A message similar to the following will be displayed after successfully flashing the card:
1 device(s) flashed successfully.

****************************************************
Cold reboot machine to load the new image on device(s).
****************************************************
If the card has already been flashed with the current platform firmware, you will see a message similar to the following:
Device(s) up-to-date and do not need to be flashed.
Info

Flashing can take several minutes. If you have multiple cards installed in the system, you must run the above xbmgmt program command separately for each card.

Warning

Do not enter Ctrl + c in the terminal while the firmware is flashing as this can cause the card to become inoperable.
Cold boot the machine to load the new firmware image on the FPGA.

Attention

Ensure a cold boot has been performed. The image will not load from flash if the machine is only warm rebooted e.g. ‘sudo reboot’. If unsure, power off the machine and power it on again.
Run the following command to update the SC firmware on the card. It is the identical command used to flash the platform firmware on the card.
$ sudo xbmgmt program --base sc --device <Management BDF> --image <base name>
Info

Updating the SC firmware can take several minutes. If you have multiple cards installed in the system, you must run the above xbmgmt program command separately for each card.

A message similar to the following will be displayed after a successful SC firmware update, where the device Management BDF is given in square brackets.
Report
[0000:af:00.0] : Successfully flashed
1 device(s) flashed successfully.
******************************************************************
Warm reboot is required to recognize new SC image on the device.
******************************************************************
If the card already has the current firmware, a message similar to the following is displayed and no additional installation steps are necessary.
Device(s) up-to-date and do not need to be flashed.
Warm reboot the system for XRT to recognize the new SC image.

The installation for deployment is now complete. The following steps can optionally be used to confirm the platform installation is fully operational.

Step3 Validating Platform Installation¶

After fully installing XRT and the deployment platform, installation can be verified using the following commands, which are explained in more detail below:

lspci

xbmgmt examine

xbutil validate

xbutil examine

The lspci Linux command is used to confirm the card is seen by the OS.

The additional commands are XRT utilities used to validate and identify the installed card(s) and report additional card details including thermal and electrical status, memory, PCIe®, platform name, and system information.

Checking for PCIe card enumeration on lspci - Enter the following command:

$ sudo lspci -vd 10ee:

If the card is successfully installed and found by the operating system, you will see a message similar to the following. Note that for each card, there will be two physical functions found: one for management and one for user. See Obtaining Card BDF Values for additional details.

02:00.0 Memory controller: Xilinx® Corporation Device 5048
   Subsystem: Xilinx® Corporation Device 000e
   Physical Slot: 1
   Flags: bus master, fast devsel, latency 0, IRQ 26, NUMA node 0
   Memory at f0000000 (64-bit, prefetchable) [size=128M]
   Memory at f8000000 (64-bit, prefetchable) [size=128K]
   Capabilities: [40] Power Management version 3
   Capabilities: [48] MSI: Enable- Count=1/1 Maskable- 64bit+
   Capabilities: [60] MSI-X: Enable- Count=32 Masked-
   Capabilities: [70] Express Endpoint, MSI 00
   Capabilities: [100] Advanced Error Reporting
   Capabilities: [180] Alternative Routing-ID Interpretation (ARI)
   Capabilities: [1c0] #19
   Capabilities: [3a0] #25
   Capabilities: [600] Vendor Specific Information: ID=0020 Rev=0 Len=010 <?>
   Kernel driver in use: xclmgmt
   Kernel modules: xclmgmt
02:00.1 Memory controller: Xilinx® Corporation Device 5049
   Subsystem: Xilinx® Corporation Device 000e
   Physical Slot: 1
   Flags: bus master, fast devsel, latency 0, IRQ 68, NUMA node 0
   Memory at f8020000 (64-bit, prefetchable) [size=64K]
   Memory at e0000000 (64-bit, prefetchable) [size=256M]
   Capabilities: [40] Power Management version 3
   Capabilities: [48] MSI: Enable- Count=1/1 Maskable- 64bit+
   Capabilities: [60] MSI-X: Enable- Count=32 Masked-
   Capabilities: [70] Express Endpoint, MSI 00
   Capabilities: [100] Advanced Error Reporting
   Capabilities: [180] Alternative Routing-ID Interpretation (ARI)
   Capabilities: [600] Vendor Specific Information: ID=0020 Rev=0 Len=010 <?>
   Kernel driver in use: xocl
   Kernel modules: xocl

Confirm Firmware Installation

When a card has successfully been installed and the firmware has been updated, both entries for Platform and the satellite controller (SC) version installed on the card and the system must match. If they do not match, the system will be unable to correctly run applications on your card.

To confirm they match, run the following command and visually compare the Platform, Platform UUID and SC Version entries under ‘Flashable partitions running on FPGA’ and ‘Flashable partitions installed in system’ match.

$ sudo xbmgmt examine -device <Management BDF> -r platform

The response to this command is shown below. Please check the following information for valid operation.

Platform name of running and installed matches expected, see Alveo Versal Deployment Packages Table
SC Version of running and installed matches, see Alveo Versal Deployment Packages Table for expected SC Version

Platform UUID of running and installed matches, see Alveo Versal Deployment Packages Table for expected Platform UUID

-------------------------------------------------------
1/1 [0000:d8:00.0] : xilinx_vck5000_gen4x8_xdma_base_2
-------------------------------------------------------
Flash properties
Type                 : ospi_xgq
Serial Number        : N/A

Device properties
Type                 : vck5000
Name                 : N/A
Config Mode          : 0
Max Power            : N/A

Flashable partitions running on FPGA
Platform             : xilinx_vck5000_gen4x8_xdma_base_2
SC Version           : 4.4.32
Platform UUID        : 539C76AC-F219-2CDC-B9DB-69A6450407C0
Interface UUID       : 1782B562-019C-AB41-EE85-7964621BB773

Flashable partitions installed in system
Platform             : xilinx_vck5000_gen4x8_xdma_base_2
SC Version           : 4.4.32
Platform UUID        : 539C76AC-F219-2CDC-B9DB-69A6450407C0

Bootable Partitions:
Default              : ACTIVE
Backup               : INACTIVE

Note

The response above may change slightly with different XRT versions however the important content should remain the same.

Card Validation

Card installation can be validated using the ‘xbutil validate’ command. This command performs various tests and checks on the card including PCIe link status, SC version status, memory and bandwidth tests and auxiliary power connection where applicable. Full command details can be found in xbutil documentation. Depending on the card tested, not all tests are valid or may require the function to be enabled first (e.g. Peer-2-Peer).

Use the following command to run the card validation test:

$ xbutil validate -d <User BDF>

Where User BDF is the PCIe address of the card to be validated. See Obtaining Card BDF Values to obtain the user BDF value.

If the card was installed and validated successfully, a message similar to the following will be displayed. Additional validation details are displayed by appending the --verbose option to the command.

Starting validation for 1 devices
Platform         : xilinx_vck5000_gen3x16_xdma_base_1
SC Version        : 4.4.12
Platform ID        : 1E56042E-C345-CF41-5D66-4E9EE73451FC
-------------------------------------------------------------------------------
Test 1 [0000:01:00.1]   : PCIE link
   Test Status      : [PASSED]
-------------------------------------------------------------------------------
Test 2 [0000:01:00.1]   : SC version
   Test Status      : [PASSED]
-------------------------------------------------------------------------------
Test 3 [0000:01:00.1]   : Verify kernel
Test Status        : [PASSED]
-------------------------------------------------------------------------------
Test 4 [0000:01:00.1]   : DMA
Details          : Host -> PCIe -> FPGA write bandwidth = 10820.6 MB/s
               Host <- PCIe <- FPGA read bandwidth = 10513.8 MB/s
Test Status        : [PASSED]
-------------------------------------------------------------------------------
Test 5 [0000:01:00.1]   : iops
Details          : IOPS: 132544 (hello)
   Test Status      : [PASSED]
-------------------------------------------------------------------------------
Test 6 [0000:01:00.1]   : Bandwidth kernel
Details          : Maximum throughput: 50540 MB/s
   Test Status      : [PASSED]
-------------------------------------------------------------------------------
Validation completed. Please run the command '--verbose' option for more
details

Tip

For a quicker validation check please run xbutil validate -r quick. This option does not check kernel memory performance.

Temperature and Electrical Status

To monitor the current electrical and temperature status, use the following commands:

$ xbutil examine --device <user BDF> --report thermal electrical

It will generate an output similar to the following. For command details see the xbutil documentation.

--------------------------------------------------------
1/1 [0000:03:00.1] : xilinx_vck5000_gen3x16_xdma_base_1
--------------------------------------------------------
Thermals
PCB Top Front : 24 C
PCB Top Rear : 28 C
FPGA     : 36 C

Electrical
Max Power   : 225 Watts
Power     : 25.839361 Watts
Power Warning : false

Power Rails : Voltage Current
12 Volts Auxillary  : 24.376 V, 0.603 A
12 Volts PCI Express : 12.149 V, 0.917 A
3.3 Volts PCI Express : 3.279 V
3.3 Volts Auxillary  : 3.327 V
Internal FPGA Vcc   : 0.803 V, 48.000 A
DDR Vpp Top      : 2.492 V
5.5 Volts System   : 5.011 V
Vcc 1.2 Volts Top   : 1.203 V
1.8 Volts Top     : 1.803 V
0.9 Volts Vcc     : 0.878 V
Mgt Vtt        : 1.197 V
3.3 Volts Vcc     : 3.270 V
Vcc 1.2 Volts i    : 2.200 A
Vcc Auxillary     : 1.508 V
Vcc Auxillary Pmc   : 1.512 V
Vcc Ram        : 0.800 V

Next Steps¶

What you have done so far allows you to deploy and run accelerated applications on your system. If you are an application developer who wants to develop and deliver accelerated applications, install the Vitis® Unified Software Platform. It allows you to develop, debug, and optimize accelerated applications. Installation instructions can be found in Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393).

For complete details on the development flow and getting started in Vitis, see Vitis® Unified Software Platform. For designing an application using the Versal AI Engines see AI Engine Kernel Coding Best Practices Guide.

Obtaining Card BDF Values¶

The following example is given for the xilinx_vck5000_gen4x8_xdma_base_2 platform but the same approach can be taken with any Alveo Versal Data Center accelerator platform.

Each Alveo Versal card is assigned at minimum a Management and a User BDF (Bus:Device:Function). For a given card, the management and user BDF values differ only by the function digit.

To obtain the Management and User BDF values for installed cards, use the following commands.

Note

The procedure requires XRT to be installed and the environment to be setup. See XRT environment setup.

Management BDF¶

The Management BDF is used by the xbmgmt utility to perform operations such as platform update and XCLBIN download. To display the Management BDF values of installed cards, use the following command:

$ sudo xbmgmt examine

The Management BDF values of installed cards are given in the square brackets under ‘Devices present’. In the below example, only one device is present and has a management BDF of 0000:d8:00.0.

Devices present
BDF             :  Shell           Platform UUID  Device ID
[0000:d8:00.0]  :  xilinx_vck5000  0x0            mgmt(inst=55296)

User BDF¶

The User BDF is used by the xbutil utility to run applications such as validate and to query the status of the platform and application. To display the User BDF values of installed cards, use the following command:

$ xbutil examine

The User BDF values of installed cards are given in the square brackets under ‘Devices present’. In the below example, only one device is present and has a user BDF of 0000:d8:00.1.

Devices present
BDF             :  Shell           Platform UUID  Device ID
[0000:d8:00.1]  :  xilinx_vck5000  0x0            user(inst=128)

Changing XRT and Target Platform Versions¶

Alveo Versal Data Center accelerator platforms and XRT revisions can change significantly between releases. To ensure a successful migration to a newer or older version of platform, carefully follow the instructions for your specific release pairing. Failure to adhere to these procedures can result in an unstable installation or other issues. In general, it is recommended to use the latest available versions which contain bug fixes and the newest features.

Info

For links to the available platform and XRT revisions, see Alveo Versal Deployment Packages Table.

RedHat and CentOS¶

During upgrading, downgrading, or uninstalling, it can be useful to list the currently installed packages. To list the currently installed deployment platform package, run the following command in a Linux terminal:

$ yum list installed | grep -i xilinx

To list the currently installed XRT package, run the following command:

$ yum list installed | grep -i xrt

Installing Newer Packages

Install the newest XRT and deployment platform on your card by following these steps. Currently, both packages must be upgraded concurrently.

Download the desired XRT and deployment platform packages and follow the installation procedure at Step 1 (RedHat and CentOS) Package Installation.

Installing Older Packages

To install older platforms, perform the following steps.

Remove the current XRT and shell versions.
```
$ sudo yum remove xrt
```
Note

Removing XRT should automatically remove all Alveo packages. Make sure that all of the platform packages are displayed in the output terminal after running the command. If not, manually list the packages using the list command at the beginning of this section, then delete the remaining packages using the yum remove command.
Cold reboot the system.
Follow the installation procedures outlined in Step 1 (RedHat and CentOS) Package Installation.

Ubuntu¶

During upgrading, downgrading, or uninstalling, it can be useful to list the currently installed packages. To list the currently installed deployment platform package, run the following command in a Linux terminal:

$ apt list --installed | grep -i xilinx

To list the currently installed XRT package, run the following command:

$ apt list --installed | grep -i xrt

Installing Newer Packages

Install the newest XRT and deployment platform on your card by following these steps. Currently, both packages must be upgraded concurrently.

Download the desired XRT and deployment platform packages. Follow the installation procedure at Step 1 (Ubuntu) Package Installation.

Installing Older Packages

To install older platforms, perform the following steps.

Remove the current XRT and shell versions.
```
$ sudo apt remove xrt
```
Note

Removing XRT should automatically remove all Alveo packages. Make sure that all of the platform packages are displayed in the output terminal after running the command. If not, manually list the packages using the list command at the beginning of this section, then delete the remaining packages using the apt remove command.
Cold reboot the system.
Follow the installation procedures outlined in Step 1 (Ubuntu) Package Installation.

Xilinx Support

For additional support resources such as Answers, Documentation, Downloads, and Alerts, see the Xilinx Support pages. For additional assistance, post your question on the Xilinx Community Forums – Alveo Accelerator Card.

License

All software including scripts in this distribution are licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.

You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

All images and documentation, including all debug and support documentation, are licensed under the Creative Commons (CC) Attribution 4.0 International License (the “CC-BY-4.0 License”); you may not use this file except in compliance with the CC-BY-4.0 License.

You may obtain a copy of the CC-BY-4.0 License at https://creativecommons.org/licenses/by/4.0/

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.