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](../README.md) ## 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](#installing-a-new-platform) - An updated XRT - Go to [Installing an XRT update](#installing-an-xrt-update) - An older platform - Go to [Installing an older platform](#installing-an-older-platform) - An older XRT - Go to [Installing an older XRT](#installing-an-older-xrt) - A development platform to match a deployment platform - Go to [Installing a development platform](#installing-a-development-platform) - Installing XRT on a machine that is offline - Go to [Installing offline](#installing-offline) ## You Will Need Before modifying XRT, you need to: - Have [root/sudo permissions](common-steps.html#root-sudo-access) - Ensure the card(s), XRT, and the deployment packages are installed and working as expected as part of the [card install](card-install.md) Next determine your starting state: - [Determine XRT and platform packages installed on the system](common-steps.html#determine-xrt-packages-using-the-package-manager) - [Determine platform running on each card](common-steps.html#display-card-and-host-platform-and-sc-versions) ## 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](https://www.xilinx.com/products/boards-and-kits/alveo.html) 1. [Confirm XRT/Platform compatibility](common-steps.html#confirm-xrt-platform-compatibility) - Download a new XRT if needed 1. [Return each card to golden](common-steps.html#reverting-the-card-to-factory-image) 1. Remove the old deployment package using - Ubuntu: `sudo apt remove installed_platform_name` - RHEL/CentOS: `sudo yum remove installed_platform_name` 1. If a new XRT is needed, upgrade XRT using one of the commands below - Ubuntu: `sudo apt install ./.deb` - RHEL/CentOS: `sudo yum install ./.rpm` 1. Install the new deployment package on the system using one of the commands below - Ubuntu: `sudo apt install ./.deb` - RHEL/CentOS: `sudo yum install ./.rpm` 1. Run `sudo xbmgmt examine` to get a list of management BDFs 1. For each management BDF, program the FPGA image onto the card(s) using `sudo xbmgmt program --base --device ` - If needed, you can determine the platform name with `sudo xbmgmt examine --device ` 1. [Cold boot](terminology.html#cold-boot-power-cycle) the machine 1. Use `sudo xbmgmt examine --device ` 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 1. Run [xbutil examine](https://xilinx.github.io/XRT/master/html/xbutil.html#xbutil-examine) to get a list of user BDFs 1. For each user BDF, run `xbutil validate --device ` to confirm the card install is working 1. Optionally, download and [install the development platform](#installing-a-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](https://www.xilinx.com/products/boards-and-kits/alveo.html) 1. Confirm the [host system is compatible](check-system-compatibility.md) 1. Check which platforms are on card with `sudo xbmgmt examine` - For each card that has a platform installed [Confirm XRT/Platform compatibility](common-steps.html#confirm-xrt-platform-compatibility) - If XRT does not support the new platform [Return the card to golden](common-steps.html#reverting-the-card-to-factory-image) 1. Upgrade XRT using one of the commands below - Ubuntu: `sudo apt install ./.deb` - RHEL/CentOS: `sudo yum install ./.rpm` 1. [Warm boot](terminology.html#reboot-warm-boot-reset-system) the machine 1. Run `xbutil --version` to confirm the XRT version 1. Run [xbutil examine](https://xilinx.github.io/XRT/master/html/xbutil.html#xbutil-examine) to see the user BDF for each installed card 1. For each card, confirm functionality by running `xbutil validate -d ` - - - ### 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](https://www.xilinx.com/products/boards-and-kits/alveo.html) 1. [Confirm XRT/Platform compatibility](common-steps.html#confirm-xrt-platform-compatibility) to make sure XRT that will support the platform - Download XRT package if needed 1. [Return each card to golden](common-steps.html#reverting-the-card-to-factory-image) 1. If a different XRT is needed, [Remove XRT](common-steps.html#remove-xrt) and install the replacement XRT package on the system using one of the commands below - Ubuntu: `sudo apt install ./.deb` - RHEL/CentOS: `sudo yum install ./.rpm` 1. 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](common-steps.html#determine-xrt-packages-using-the-package-manager) 1. Install the replacement deployment package on the system using one of the commands below - Ubuntu: `sudo apt install ./.deb` - RHEL/CentOS: `sudo yum install ./.rpm` 1. Run [xbmgmt examine](https://xilinx.github.io/XRT/master/html/xbmgmt.html#xbmgmt-examine) to get the list of management BDFs 1. For each compatible card run `sudo xbmgmt program --base --device ` 1. [Cold boot](terminology.html#cold-boot-power-cycle) the machine to update the FPGA 1. Confirm each card validates using `xbutil validate -d ` 1. Optionally download and [install the development platform](#installing-a-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](https://www.xilinx.com/products/boards-and-kits/alveo.html) 1. Determine which platform will be used - Make sure to have the package(s) to re-install the platform 1. [Determine platform running on each card](common-steps.html#display-card-and-host-platform-and-sc-versions) 1. If the platform is different, [Return each card to golden](common-steps.html#reverting-the-card-to-factory-image) 1. [Remove XRT](common-steps.html#remove-xrt) 1. Install the replacement XRT package on the system using one of the commands below - Ubuntu: `sudo apt install ./.deb` - RHEL/CentOS: `sudo yum install ./.rpm` 1. Install the replacement deployment package on the system using one of the commands below - Ubuntu: `sudo apt install ./.deb` - RHEL/CentOS: `sudo yum install ./.rpm` 1. Run [xbmgmt examine](https://xilinx.github.io/XRT/master/html/xbmgmt.html#xbmgmt-examine) to get the list of management BDFs 1. For each compatible card run `sudo xbmgmt program --base --device ` 1. [Cold boot](terminology.html#cold-boot-power-cycle) the machine to update the FPGA 1. Confirm each card validates using `xbutil validate -d ` 1. Optionally download and [install the development platform](#installing-a-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](common-steps.html#display-card-and-host-platform-and-sc-versions) 1. Go to the [Alveo landing page](https://www.xilinx.com/products/boards-and-kits/alveo.html) to download the matching development platform 1. Install the deployment package on the system using one of the commands below - Ubuntu: `sudo apt install ./.deb` - RHEL/CentOS: `sudo yum install ./.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 ./` - Ubuntu: `sudo apt remove ./` 1. Install the replacement deployment package on the system using one of the commands below - Ubuntu: `sudo apt install ./.deb` - RHEL/CentOS: `sudo yum install ./.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](common-steps.html#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](card-install.md) 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](https://support.xilinx.com/s/article/XRT-Offline-install-steps-for-XRT-and-Alveo-platform-packages-on-Ubuntu) 2. For CentOS or RedHat, see [AR](https://support.xilinx.com/s/article/XRT-Offline-install-steps-for-XRT-and-Alveo-platform-packages-on-Redhat-CentOS) - - - ### Xilinx Support For additional support resources such as Answers, Documentation, Downloads, and Alerts, see the [Xilinx Support pages](http://www.xilinx.com/support). For additional assistance, post your question on the Xilinx Community Forums – [Alveo Accelerator Card](https://support.xilinx.com/s/topic/0TO2E000000YKXlWAO/alveo-accelerator-cards). 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](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/]( 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.