Alveo Debug Guide

Modifying XRT or Platform

The Xilinx Runtime library (XRT) is an open-source easy to use software stack that facilitates management and usage of Alveo™ accelerator cards. Not all versions of XRT will work with all Alveo card deployment platforms, in some cases it may be necessary to modify the XRT or platform to meet overall requirements. It is not intended to be used standalone. If you are just starting to debug please consult the main page

This Page Covers

Steps to modify XRT, deployment, and development package installations.

If you want to install:

You Will Need

Before modifying XRT, you need to:

Next determine your starting state:

Common Cases


Installing a new platform

If XRT is already installed and there is a new platform to be installed on the Alveo card, follow the below steps:

  • Download the new platform from the Alveo landing page

  • Confirm XRT/Platform compatibility

    • Download a new XRT if needed

  • Return each card to golden

  • Remove the old deployment package using

    • Ubuntu: sudo apt remove installed_platform_name

    • RHEL/CentOS: sudo yum remove installed_platform_name

  • If a new XRT is needed, upgrade XRT using one of the commands below

    • Ubuntu: sudo apt install ./xrt_package_name.deb

    • RHEL/CentOS: sudo yum install xrt_package_name.rpm

  • Install the new deployment package on the system using one of the commands below

    • Ubuntu: sudo apt install ./platform_package_name.deb

    • RHEL/CentOS: sudo yum install platform_package_name.rpm

  • Flash the FPGA image onto the card(s) using sudo xbmgmt flash --update --shell <name>

    • If needed, you can determine the shell name with sudo xbmgmt flash --scan --verbose

  • Cold boot the machine

  • Use sudo xbmgmt flash --scan --verbose to make sure the platform and the SC image on card match those installed on the system

    • Some platforms require a second flash to update the SC image

    • If the SC image mismatches run the flash command a second time

  • Run xbutil validate to determine install is working

  • Optionally download and install the development platform


Installing an XRT update

If XRT is already installed and you want to install a newer XRT version, follow the below steps:

  • Download the new XRT package from the Alveo landing page

  • Confirm the host system is compatible

  • Check which platforms are on card with sudo xbmgmt flash --scan --verbose

  • Upgrade XRT using one of the commands below

    • Ubuntu: sudo apt install ./xrt_package_name.deb

    • RHEL/CentOS: sudo yum install xrt_package_name.rpm

  • Warm boot the machine

  • Run xbutil version to confirm the XRT version

  • Run xbutil validate to determine install is working


Installing an older platform

If XRT is already installed and there is a older platform to be installed on the Alveo card, follow the below steps:

  • Download the platform package from the archive section of the Alveo landing page

  • Confirm XRT/Platform compatibility to make sure XRT that will support the platform

    • Download XRT package if needed

  • Return each card to golden

  • If a different XRT is needed, Remove XRT and install the replacement XRT package on the system using one of the commands below

    • Ubuntu: sudo apt install ./xrt_package_name.deb

    • RHEL/CentOS: sudo yum install xrt_package_name.rpm

  • Else remove the current deployment package with sudo apt remove or sudo yum remove

    • If needed use the package manager to find the installed package names

  • Install the replacement deployment package on the system using one of the below

    • Ubuntu: sudo apt install ./platform_package_name.deb

    • RHEL/CentOS: sudo yum install platform_package_name.rpm

  • Flash the card with the command given during package install

  • Cold boot the machine to update the FPGA

  • Confirm card validates using xbutil validate

  • Optionally download and install the development platform


Installing an older XRT

If XRT is already installed and an older version of XRT is to be installed, follow the below steps:

  • Download the XRT package from the archives section of the Alveo landing page

  • Determine which platform will be used

    • Make sure to have the package to re-install the platform

  • Determine which platform is on the card

  • If the platform is different

  • Remove XRT

  • Install the replacement xrt package on the system using one of commands the below

    • Ubuntu: sudo apt install ./xrt_package_name.deb

    • RHEL/CentOS: sudo yum install xrt_package_name.rpm

  • Install the replacement deployment package on the system using one of commands the below

    • Ubuntu: sudo apt install ./platform_package_name.deb

    • RHEL/CentOS: sudo yum install platform_package_name.rpm

  • Flash the card with the command given during package install

  • Cold boot the machine to update the FPGA

  • Confirm card validates using xbutil validate

  • Optionally download and install the development platform


Installing a development platform

After XRT is installed and once it has been decided on the platform that will be used on the Alveo card, follow the below steps to install the development platform:


Platform Re-Install

The steps to re-install a platform are given below.

  • Uninstall the packages first

    • sudo yum remove ./<xrt_package_name> (or)

    • sudo apt remove ./<xrt_package_name>

  • Go to Installing an older XRT


Uninstalling XRT

Removing XRT will also remove any packages that depend on XRT, for example the platforms. Please follow the below link to remove XRT:


No XRT installed

If you have Alveo cards in a system and no XRT drivers, treat this as a new install.


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.

Have a suggestion, or found an issue please send an email to alveo_cards_debugging@xilinx.com .

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.

XD027 | © Copyright 2021 Xilinx, Inc.