xrt-smi

Note

xbutil has been renamed to xrt-smi.

xbutil is still available in the 2024.2 release, but this alias has been removed in this release. You can still use xbutil in the 2024.2 version of Xilinx Runtime.

This document describes the latest xrt-smi commands. These latest commands are default from 21.1 release.

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 <video reference>.

The supported options

xrt-smi program [--device|-d] <user bdf> [--user|-u] <xclbin>

The details of the supported options

  • The --device (or -d) specifies the target device to program

    • <user bdf> : The Bus:Device.Function of the device of interest

  • The --user (or -u) is required to specify the .xclbin file

    • <xclbin file> : The xclbin file with full-path to program the device

Example commands

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 <video reference>.

The supported options

xrt-smi validate [--device| -d] <user bdf> [--run| -r] <test> [--format| -f] <report format> [--output| -o] <filename> [--param] <test>:<key>:<value>

The details of the supported options

  • The --device (or -d) specifies the target device to validate

    • <user bdf> : The Bus:Device.Function of the device of interest

  • The --run (or -r) specifies the perticular 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

  • 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

# 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 <video reference>.

The supported options

xrt-smi examine [--device|-d] <user bdf> [--report| -r] <report of interest> [--format| -f] <report format> [--output| -o] <filename>

The details of the supported options

  • The --device (or -d) specifies the target device to examine

    • <user bdf> : The Bus:Device.Function of the device of interest

  • 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

# 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) <video reference>.

The supported options

xrt-smi configure [ --host-mem | --p2p | --performance ] [--help]

The details of the supported options

  • The --device (or -d) specifies the target device to examine

    • <user bdf> : 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>: 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

# 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 <video reference>.

The supported options

xrt-smi reset [--device| -d] <user bdf> [--type| -t] <reset type>

The details of the supported options

  • The --device (or -d) specifies the target device to reset

    • <user bdf> : 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

xrt-smi reset --device 0000:65:00.1