.. _xbutil2.rst: Xbutil Next Generation ====================== The next generation of the ``xbutil`` command-line tool is in preview mode for the 2020.2 release of XRT. This version will replace the current ``xbutil`` in a future release of XRT. This document describes the usage of this new version of the tool. To invoke the new version please set the following environment variable .. code:: export XRT_TOOLS_NEXTGEN=true The xbutil command options are - ``xbutil program`` - ``xbutil validate`` - ``xbutil examine`` - ``xbutil reset`` - ``xbutil advanced`` **A note about multidevice system**: All the ``xbutil`` command supports a ``--device`` (or ``-d``) switch to specify the target device of interest. The ``xbutil`` command accept the PCIe user function bdf as an argument of ``--device`` switch. The user can check the user function bdf from ``xbutil examine`` command. .. code:: xbutil examine .... .... Devices present [0000:b3:00.1] : xilinx_u200_xdma_201830_2 [0000:65:00.1] : xilinx_u50_gen3x16_xdma_201920_3 The above output shows two devices and their user function bdf (``0000:b3:00.1`` and ``0000:65:00.1``) can be used with the ``--device`` switch xbutil program ~~~~~~~~~~~~~~ The ``xbutil program`` command downloads a specified xclbin binary to the programmable region on the card. **The supported options** .. code-block:: xbutil program [--device|-d] [--program|-p] **The details of the supported options** - The ``--device`` (or ``-d``) specifies the target device to be programmed - : Optional for a single device system. - + : Mandetory for multiple device system, has to be specified with one or more device user bdf information - ``all``: To specify all devices ``–-device all`` or ``-d all`` can be used - The ``--program`` (or ``-p``) is required to specify the .xclbin file - : The xclbin file to be used to program the device **Example commands** .. code-block:: #Programming a only available device with a xclbin xbutil program --program my_kernel.xclbin #Multiple Devices, program all the devices xbutil program --device all --program my_kernel.xclbin #Multiple Device, programing a single device xbutil program --device 0000:03:00.1 --program my_kernel.xclbin #Multiple Device, programing two devices xbutil program --device 0000:03:00.1 0000:d8:00.1 --program my_kernel.xclbin xbutil validate ~~~~~~~~~~~~~~~ The command ``xbutil validate`` validates the card installation by running precompiled basic tests. **The supported options** .. code-block:: xbutil validate [--device| -d] [--run| -r] [--format| -f] **The details of the supported options** - The ``--device`` (or ``-d``) specifies the target device to be validate - : Optional for a single device system. - + : Mandetory for multiple device system, has to be specified with one or more device user bdf information - ``all``: To specify all devices ``–-device all`` or ``-d all`` can be used - The ``--run`` (or ``-r``) specifies the perticular test to execute - ``all`` (**default**): runs all the tests listed below - ``Kernel version``: Check if the kernel version is supported by XRT - ``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 kernel``: Run 'Hello World' kernel test - ``DMA``: Run dma test - ``Bandwidth kernel``: Run 'bandwidth kernel' and check the throughput - ``Peer to peer bar``: Run P2P test - ``Memory to memory DMA``: Run M2M test - ``Host memory bandwidth test``: Run 'bandwidth kernel' when slave bridge is enabled - ``quick``: Run first five tests (Kernel version, Aux connection, PCIE link, SC version and Verify kernel) - The ``--format`` (or ``-f``) specifies the report format - ``text`` (**default**): The report is shown in the text format, default behavior - ``json``: The report is shown in json-2020.2 **Example commands** .. code-block:: # For a single device run all the tests xbutil validate # For a multiple device system run all the tests on all the devices xbutil validate --device all # For a multiple device system run "DMA" program on a specific device xbutil valiadate --device 0000:d8:00.1 --run DMA # For a multiple device system run "DMA" and "Validate Kernel" program on two devices and generates Json format xbutil validate --device 0000:d8:00.1 0000:03:00.1 --run DMA "Verify Kernel" --format json-2021.2 xbutil examine ~~~~~~~~~~~~~~ The command ``xbutil examine`` can be used to find the details of the specific device(s), **The supported options** .. code-block:: xbutil examine [--device|-d] [--report| -r] [--format| -f] [--output| -o] **The details of the supported options** - The ``--device`` (or ``-d``) specifies the target device to be validate - : Optional for a single device system. - + : Mandetory for multiple device system, has to be specified with one or more device user bdf information - ``all``:To specify all devices ``–-device all`` or ``-d all`` can be used - The ``--report`` (or ``-r``) switch can be used to view specific report(s) of interest from the following options - ``scan`` (**default**): Shows System Configuration, XRT and Device user bdf information. - ``aie``: Reports AIE kernels metadata from the .xclbin - ``electrical``: Reports Electrical and power sensors present on the device - ``debug-ip-status``: Reports information related to Debug-IPs inserted during the kernel compilation - ``firewall``: Reports the current firewall status - ``host``: Reports the host configuration and drivers - ``fan``: Reports fans present on the device - ``memory``: Reports memory topology of the XCLBIN (if XCLBIN is already loaded) - ``thermal``: Reports thermal sensors present on the device - ``verbose``: Reports everything - The ``--format`` (or ``-f``) can be used to specify the output format - ``text`` (**default**): The output is shown in the text format, default behavior - ``json``: The output is shown in json-2020.2 - The ``--output`` (or ``-o``) can be used to dump output in a file instead of stdout - : The output file to be dumped **Example commands** .. code-block:: # Examine all the devices and produces all the reports xbutil examine # Examine a specific device and report electrical information in the stdout xbutil examine --device 0000:d8:00.0 --run electrical # Example a list of devices and reports a list of information and dump in a file json format xbutil examine --device 0000:d8:00.0 0000:d8:00.1 --run electrical firewall --format json --output my_reports.json xbutil reset ~~~~~~~~~~~~ This ``xbutil reset`` command can be used to reset one or more devices. **The supported options** .. code-block:: xbutil reset [--device| -d] [--type| -t] **The details of the supported options** - The ``--device`` (or ``-d``) used to specify the device to be reset - + : Mandetory, has to be specified with one or more device user bdf - ``all``: To specify all devices ``–-device all`` or ``-d all`` can be used - The ``--type`` (or ``-t``) can be used to specify the reset type. Currently supported reset type - ``hot`` (**default**): Complete reset of the device **Example commands** .. code-block:: xbutil reset --device 0000:65:00.1 xbutil reset --device 0000:65:00.1 --type hot xbutil advanced ~~~~~~~~~~~~~~~ The ``xbutil advanced`` commands are the group of commands only recommended for the advanced users. As a disclaimer, the formats of these commands can change significantly as we know more about the advnced use-cases. **The supported options** Read from Memory .. code-block:: xbutil advanced [--device| -d] --read-mem
[--output] Fill Memory with binary value .. code-block:: xbutil advanced [--device| -d] --write-mem
[--fill] Fill Memory from a file content .. code-block:: xbutil advanced [--device| -d] --write-mem
[--input] P2P Enable, disable or valiadte .. code-block:: xbutil advanced [--device| -d] --p2p [enable|disable|validate] **The details of the supported options** - The ``--device`` (or ``-d``) used to specify the device to be reset - + : Mandetory, has to be specified with one or more device user bdf - ``all``: To specify all devices ``–-device all`` or ``-d all`` can be used - The ``--read-mem`` is used to read from perticular memory location. It has to use with following arguments -
: The read location and the size of the read. - The ``--output`` can be used with ``--read-mem`` to dump the read data to a file instead of console - : When specified the output of ``--read-mem`` commands are dumped into the user provided file - The ``--write-mem`` is used to write to the perticular memory location. It has to use with following arguments -
: The write location and the size of the write. - The ``--fill`` can be used with ``--write-mem`` to fill the memory location with a perticular binary value - : The filled value in byte - The ``--input`` can be used with ``--write-mem`` to write the memory location from a file content - : The binary file - The ``--p2p`` can be used to enable, disable or validate p2p operation - enable: Enable the p2p - disable: Disable the p2p - validate: Validate the p2p **Example commands** .. code-block:: xbutil advanced --device 0000:65:00.1 --read-mem 0x100 0x30 xbutil advanced --device 0000:65:00.1 --read-mem 0x100 0x30 --output foo.bin xbutil advanced --device 0000:65:00.1 --write-mem 0x100 0x10 --fill 0xAA xbutil advanced --device 0000:65:00.1 --write-mem 0x100 0x20 --input foo.bin xbutil advanced --device 0000:65:00.1 --p2p enable xbutil advanced --device 0000:65:00.1 --p2p disble xbutil advanced --device 0000:65:00.1 --p2p validate