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:

• A newer platform

  • Go to Installing a new platform

• An updated XRT

  • Go to Installing an XRT update

• An older platform

  • Go to Installing an older platform

• An older XRT

  • Go to Installing an older XRT

• A development platform to match a deployment platform

  • Go to Installing a development platform

• Installing XRT on a machine that is offline

  • Go to Installing offline

You Will Need

Before modifying XRT, you need to:

• Have root/sudo permissions

• Ensure the card(s), XRT, and the deployment packages are installed and working as expected as part of the card install

Next determine your starting state:

• Determine XRT and platform packages installed on the system

• Determine platform running on each card

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:

1. Download the new platform from the Alveo landing page

2. Confirm XRT/Platform compatibility

   • Download a new XRT if needed

3. Return each card to golden

4. Remove the old deployment package using

   • Ubuntu: sudo apt remove installed_platform_name

   • RHEL/CentOS: sudo yum remove installed_platform_name

5. 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

6. 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

7. Run sudo xbmgmt examine to get a list of management BDFs

8. For each management BDF, program the FPGA image onto the card(s) using sudo xbmgmt program --base --device <management BDF>

   • If needed, you can determine the platform name with sudo xbmgmt examine --device <management BDF>

9. Cold boot the machine

10. Use sudo xbmgmt examine --device <management BDF> for each card 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

11. Run xbutil examine to get a list of user BDFs

12. For each user BDF, run xbutil validate --device <user BDF> to confirm the card install is working

13. 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:

1. Download the new XRT package from the Alveo landing page

2. Confirm the host system is compatible

3. Check which platforms are on card with sudo xbmgmt examine

   • For each card that has a platform installed Confirm XRT/Platform compatibility

   • If XRT does not support the new platform Return the card to golden

4. 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

5. Warm boot the machine

6. Run xbutil --version to confirm the XRT version

7. Run xbutil examine to see the user BDF for each installed card

8. For each card, confirm functionality by running xbutil validate -d <user BDF>

---

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:

1. Download the platform package from the archive section of the Alveo landing page

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

   • Download XRT package if needed

3. Return each card to golden

4. 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

5. 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

6. Install the replacement 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

7. Run xbmgmt examine to get the list of management BDFs

8. For each compatible card run sudo xbmgmt program --base --device <management BDF>

9. Cold boot the machine to update the FPGA

10. Confirm each card validates using xbutil validate -d <user BDF>

11. 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:

1. Download the XRT package from the archives section of the Alveo landing page

2. Determine which platform will be used

   • Make sure to have the package(s) to re-install the platform

3. Determine platform running on each card

4. If the platform is different, Return each card to golden

5. Remove XRT

6. 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

7. Install the replacement 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

8. Run xbmgmt examine to get the list of management BDFs

9. For each compatible card run sudo xbmgmt program --base --device <management BDF>

10. Cold boot the machine to update the FPGA

11. Confirm each card validates using xbutil validate -d <user BDF>

12. 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:

1. Determine platform running on the card

2. Go to the Alveo landing page to download the matching development platform

3. Install the 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

---

Platform Re-Install

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

1. Uninstall the deployment package on the system using one of the commands below

   • Redhat/CentOS: sudo yum remove ./<platform_package_name>

   • Ubuntu: sudo apt remove ./<platform_package_name>

2. Install the replacement 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

---

Uninstalling XRT

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

1. Go to Remove XRT

---

No XRT installed

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

1. Go to the software install and card validation of the appropriate install guide

---

Installing offline

If you have a system that does not have direct access to the internet and wish to install XRT and platforms pacakges off line.

1. For Ubuntu, see AR

2. For CentOS or RedHat, see AR

---

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.}