.. include:: /include/links.txt .. include:: /include/format.txt .. # S1 * S2 = S3 - S4 .. _Installation Guide for Platform Deployment Packages: ########################################################################## 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 :ref:`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 `_ .. # TODO add link for xbtest when published on github .. 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:: **Table: Versal Deployment Package Types** +-------------------+-----------+------------------------------------------------------------------------------------------------------------+ | Tools | Package | Description | +===================+===========+============================================================================================================+ | 2021.2 or earlier | Partition | Contains a device PDI that implements the :ref:`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: ``_--[-].`` Each element consists of one or more sub-elements and are further described in the following table. .. _Deployment Package Name Element Fields: .. 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. | 1.1, | | | Increments when chassis interface changes. | 2 | +----------------------------+---------------------------------------------------------+-------------+ | Release | Integer release number. | 2200000 | +----------------------------+---------------------------------------------------------+-------------+ | Architecture | Indicates processor architecture for RPM packages. | noarch | | | Will always be noarch for Versal platform packages. | | +----------------------------+---------------------------------------------------------+-------------+ | OS Version | Only applies to Ubuntu packages. Will always be all for | all | | | Versal platform packages. | | +----------------------------+---------------------------------------------------------+-------------+ | Extension | Package extension. rpm for RedHat and CentOS. | rpm | | | deb for ubuntu. | 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 :ref:`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. .. admonition:: 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 :ref:`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. .. admonition:: Info Root access is required for all software and firmware installations. .. _Alveo Versal Deployment Packages Table: .. csv-table:: **Table: Alveo Versal Deployment Packages** :header: "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: 1. Installation of XRT and the deployment package on the host operating system 2. Installation of the deployment platform configuration data on the target card 3. Validation of the installation procedure .. _XRT environment setup: 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: .. code:: bash $ source /opt/xilinx/xrt/setup.csh Use the following command in a **bash** shell: .. code:: bash $ 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. ------------------------------------------ .. _Alveo Versal Deployment Package Installation Step 1: 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`_. a. 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`_. b. Run the following commands to install kernel headers and kernel development packages. Ensure that uname is surrounded by backticks (\`) and not single quotes ('). .. code:: bash $ sudo yum install kernel-headers-`uname -r` $ sudo yum install kernel-devel-`uname -r` c. After the previous command completes, ``warm reboot`` your machine. d. Download the Xilinx® runtime (XRT) and deployment target platform installation packages from the appropriate lounge, see links in table above. e. Install the XRT package by running the following command from within the directory where the installation packages reside. is the latter part of the installation package file name. .. code:: bash $ sudo yum install ./xrt_.rpm This will install XRT to ``/opt/xilinx/xrt/``. Follow the instructions when prompted throughout the installation. f. 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. g. Install the deployment packages. From within the directory where the installation packages were unpacked, run the following command. This will install all deployment packages. .. code:: bash $ 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`_. a. From the appropriate lounge, see links in table above, download the Xilinx® runtime (XRT) and deployment target platform installation packages. b. Install the XRT installation package by running the following command from within the directory where the installation packages reside. is the latter part of the installation package file name. .. code:: bash $ sudo apt install ./xrt_.deb This will install XRT to ``/opt/xilinx/xrt/`` and its necessary dependencies. Follow the instructions when prompted throughout the installation. f. 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. g. Install the deployment packages. From within the directory where the installation packages were unpacked, run the following command. This will install all deployment packages. .. code:: bash $ 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 :ref:`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`_. a. Flash the platform firmware on the card. .. code:: bash $ sudo xbmgmt program --base shell --device --image To find the correct see `Alveo Versal Deployment Packages Table`_ above. To find see `Obtaining Card BDF Values`_ A message similar to the following will be displayed after successfully flashing the card: .. code:: bash 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: .. code:: bash Device(s) up-to-date and do not need to be flashed. .. admonition:: 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. b. ``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. c. 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. .. code:: bash $ sudo xbmgmt program --base sc --device --image .. admonition:: 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. .. code:: bash 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. .. code:: bash Device(s) up-to-date and do not need to be flashed. d. 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. ----------------------------------------- .. _Alveo Versal Deployment Package Installation Step 3: 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. a. Checking for PCIe card enumeration on lspci - Enter the following command: .. code:: bash $ 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. .. code:: bash 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 b. 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. .. code:: bash $ sudo xbmgmt examine -device -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 .. code:: bash ------------------------------------------------------- 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. c. 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: .. code:: bash $ xbutil validate -d 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. .. code:: bash 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. d. Temperature and Electrical Status To monitor the current electrical and temperature status, use the following commands: .. code:: bash $ xbutil examine --device --report thermal electrical It will generate an output similar to the following. For command details see the xbutil documentation. .. code:: bash -------------------------------------------------------- 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: 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: .. code:: bash $ 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. .. code:: bash 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: .. code:: bash $ 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. .. code:: bash 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. .. admonition:: 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: .. code:: bash $ yum list installed | grep -i xilinx To list the currently installed XRT package, run the following command: .. code:: bash $ yum list installed | grep -i xrt .. rubric:: Installing Newer Packages Install the newest XRT and deployment platform on your card by following these steps. Currently, both packages must be upgraded concurrently. 1. Download the desired XRT and deployment platform packages and follow the installation procedure at `Step 1 (RedHat and CentOS) Package Installation`_. .. rubric:: Installing Older Packages To install older platforms, perform the following steps. 1. Remove the current XRT and shell versions. .. code:: bash $ 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. 2. ``Cold reboot`` the system. 3. 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: .. code:: bash $ apt list --installed | grep -i xilinx To list the currently installed XRT package, run the following command: .. code:: bash $ apt list --installed | grep -i xrt .. rubric:: Installing Newer Packages Install the newest XRT and deployment platform on your card by following these steps. Currently, both packages must be upgraded concurrently. 1. Download the desired XRT and deployment platform packages. Follow the installation procedure at `Step 1 (Ubuntu) Package Installation`_. .. rubric:: Installing Older Packages To install older platforms, perform the following steps. 1. Remove the current XRT and shell versions. .. code:: bash $ 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. 2. ``Cold reboot`` the system. 3. Follow the installation procedures outlined in `Step 1 (Ubuntu) Package Installation`_. ---------------------------------- .. include:: /include/license.txt