.. _xbutil.rst: .. comment:: SPDX-License-Identifier: Apache-2.0 comment:: Copyright (C) 2019-2022 Xilinx, Inc. All rights reserved. comment:: Copyright (C) 2022 Advanced Micro Devices, Inc. All rights reserved. xrt-smi (Alveo) =============== .. note:: For **latest** xrt-smi documentation, please visit :doc:`xrt-smi (NPU) `. The details below describe the **legacy** ``xrt-smi`` commands which may not work with the latest xrt-smi. For an instructive video on xrt-smi commands listed below click `here `_. **Global options**: These are the global options can be used with any command. - ``--verbose``: Turn on verbosity and shows more outputs whenever applicable - ``--batch``: Enable batch mode - ``--force``: When possible, force an operation - ``--help`` : Get help message - ``--version`` : Report the version of XRT and its drivers Currently supported ``xrt-smi`` commands are - ``xrt-smi program`` - ``xrt-smi validate`` - ``xrt-smi examine`` - ``xrt-smi configure`` - ``xrt-smi reset`` **Note**: For applicable commands, if only one device is present on the system ``--device`` (or ``-d``) is not required. If more than one device is present in the system, ``--device`` (or ``-d``) is required. xrt-smi program ~~~~~~~~~~~~~~~ The ``xrt-smi program`` command downloads a specified xclbin binary to the programmable region on the card `program (video) `__. **The supported options** .. code-block:: shell xrt-smi program [--device|-d] [--user|-u] **The details of the supported options** - The ``--device`` (or ``-d``) specifies the target device to program - : The Bus:Device.Function of the device of interest - The ``--user`` (or ``-u``) is required to specify the .xclbin file - : The xclbin file with full-path to program the device **Example commands** .. code-block:: shell xrt-smi program --device 0000:b3:00.1 --user ./my_kernel.xclbin xrt-smi validate ~~~~~~~~~~~~~~~~ The command ``xrt-smi validate`` validates the installed card by running precompiled basic tests `validate (video) `__. **The supported options** .. code-block:: shell xrt-smi validate [--device| -d] [--run| -r] [--format| -f] [--output| -o] [--param] :: **The details of the supported options** - The ``--device`` (or ``-d``) specifies the target device to validate - : The Bus:Device.Function of the device of interest - The ``--run`` (or ``-r``) specifies the particular test(s) to execute - ``all`` (**default**): runs all the tests listed below - ``aux-connection``: Check if auxiliary power is connected - ``pcie-link``: Check if PCIE link is active - ``sc-version``: Check if SC firmware is up-to-date - ``verify``: Run 'Hello World' kernel test - ``dma``: Run dma test - ``iops``: Run test to measure performance of scheduler (number of `hello world` kernel execution per second) - ``mem-bw``: Run 'bandwidth kernel' and check the throughput - ``p2p``: Run peer-to-peer test - ``m2m``: Run zero copy memory to memory data transfer test - ``hostmem-bw``: Run 'bandwidth kernel' when host memory is enabled - ``bist``: Run BIST test - ``vcu``: Run decoder test (only applicable for specific platform). - ``quick``: Run first four tests (Aux connection, PCIE link, SC version and Verify kernel) - ``aie-pl``: Run AIE PL test - The ``--format`` (or ``-f``) specifies the report format. Note that ``--format`` also needs an ``--output`` to dump the report in json format. If ``--output`` is missing text format will be shown in stdout - ``JSON``: The report is shown in latest JSON schema - ``JSON-2020.2``: The report is shown in JSON 2020.2 schema (legacy option that is identical to ``JSON``) - The ``--output`` (or ``-o``) specifies the output file to direct the output - The ``--param`` specifies the extended parameters that can be passed to a test. Valid values: - ``test``: dma - ``key``: block-size - ``value``: value in bytes **Example commands** .. code-block:: shell # Run all the tests xrt-smi validate --device 0000:b3:00.1 # Run "DMA" test, produce text output in stdout xrt-smi validate --device 0000:b3:00.1 --run DMA # Run "DMA" and "Validate Kernel" test and generates Json format xrt-smi validate --device 0000:b3:00.1 --run DMA "Verify Kernel" --format JSON --output xyz.json # Pass in a custom block size to dma test xrt-smi validate --device 0000:b3:00.1 --run DMA --param dma:block-size:1024 xrt-smi examine ~~~~~~~~~~~~~~~ The command ``xrt-smi examine`` can be used to find the details of the specific device `examine (video) `__. **The supported options** .. code-block:: shell xrt-smi examine [--device|-d] [--report| -r] [--format| -f] [--output| -o] **The details of the supported options** - The ``--device`` (or ``-d``) specifies the target device to examine - : The Bus:Device.Function of the device of interest .. _xbutil_report_label: - The ``--report`` (or ``-r``) switch can be used to view specific report(s) of interest from the following options - ``aie``: Reports AIE kernels metadata from the .xclbin - ``aieshim``: Reports AIE shim tile status - ``all``: All known reports are generated - ``debug-ip-status``: Reports information related to Debug-IPs inserted during the kernel compilation - ``dynamic-regions``: Information about the xclbin and the compute units (default when ``--device`` is provided) - ``electrical``: Reports Electrical and power sensors present on the device - ``error``: Asyncronus Error present on the device - ``firewall``: Reports the current firewall status - ``host``: Reports the host configuration and drivers (default when ``--device`` is not provided) - ``mailbox``: Mailbox metrics of the device - ``mechanical``: Mechanical sensors on and surrounding the device - ``memory``: Reports memory topology of the XCLBIN (if XCLBIN is already loaded) - ``pcie-info`` : Pcie information of the device - ``platform``: Platforms flashed on the device (default when ``--device`` is provided) - ``qspi-status``: QSPI write protection status - ``telemetry``: Telemetry data for the device - ``thermal``: Reports thermal sensors present on the device - The ``--format`` (or ``-f``) specifies the report format. Note that ``--format`` also needs an ``--output`` to dump the report in json format. If ``--output`` is missing text format will be shown in stdout - ``JSON``: The report is shown in latest JSON schema - ``JSON-2020.2``: The report is shown in JSON 2020.2 schema - The ``--output`` (or ``-o``) specifies the output file to direct the output **Example commands** .. code-block:: shell # Shows ``xrt-smi examine --host`` xrt-smi examine # Reports electrical information in the stdout xrt-smi examine --device 0000:b3:00.1 --report electrical # Reports "electrical" and "firewall" and dump in json format xrt-smi examine --device 0000:b3:00.1 --report electrical firewall --format JSON --output n.json xrt-smi configure ~~~~~~~~~~~~~~~~~ Command ``xrt-smi configure`` is used to configure specific settings based on the need of user application (requires sudo) `configure (video) `__. **The supported options** .. code-block:: shell xrt-smi configure [ --host-mem | --p2p | --performance ] [--help] **The details of the supported options** - The ``--device`` (or ``-d``) specifies the target device to examine - : The Bus:Device.Function of the device of interest - The ``--host-mem`` or ``--p2p`` select specific configuration - ``enable``: Enable the host-memory or p2p - ``disable``: Disable the host-memory or p2p - The ``--size`` is used in conjuction with ``xrt-smi configure --host-mem enable`` to specify the host-memory size to be enabled - ````: Size and unit specified as a combined string - The ``--performance`` select specific configuration for benchmarking tests - ``low``: Set performance mode to low - ``medium``: Set performance mode to medium - ``high``: Set performance mode to high - ``default``: Set performance mode to default **Example commands** .. code-block:: shell # Enable Host-Memory of Size 1 GB sudo xrt-smi configure --device 0000:b3:00.1 --host-mem enable --size 1G # Enable Host-Memory of size 256 MB sudo xrt-smi configure --device 0000:b3:00.1 --host-mem enable --size 256M # Disable previously enabled Host-Memory sudo xrt-smi configure --device 0000:b3:00.1 --host-mem disable # Enable P2P sudo xrt-smi configure --device 0000:b3:00.1 --p2p enable # Disable P2P sudo xrt-smi configure --device 0000:b3:00.1 --p2p disable xrt-smi reset ~~~~~~~~~~~~~ This ``xrt-smi reset`` command can be used to reset device `reset (video) `__. **The supported options** .. code-block:: shell xrt-smi reset [--device| -d] [--type| -t] **The details of the supported options** - The ``--device`` (or ``-d``) specifies the target device to reset - : The Bus:Device.Function of the device of interest - The ``--type`` (or ``-t``) can be used to specify the reset type. Currently only supported reset type is - ``hot`` (**default**): Complete reset of the device **Example commands** .. code-block:: shell xrt-smi reset --device 0000:65:00.1