.. _xbmgmt.rst: .. comment:: SPDX-License-Identifier: Apache-2.0 comment:: Copyright (C) 2019-2022 Xilinx, Inc. All rights reserved. xbmgmt ====== This document describes the latest ``xbmgmt`` commands. These latest commands are default from 21.1 release. For an instructive video on xbmgmt 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 ``xbmgmt`` commands are - ``xbmgmt configure`` - ``xbmgmt dump`` - ``xbmgmt examine`` - ``xbmgmt program`` - ``xbmgmt reset`` xbmgmt configure ~~~~~~~~~~~ The ``xbmgmt configure`` command provides advanced options for configuring a device's memory, clock, and DDR memory retention settings. A .ini file input is required for configuration except for DDR memory retention. The .ini file can be located in a directory of your choosing with the path specified in the command. - TIP: Instead of creating a .ini file from scratch, use ``xbmgmt dump --config`` (see the ``xbmgmt dump`` section) to generate the file contents which can be edited accordingly. **Command Options** The supported options are ``--input`` and ``--retention``. Command usage is below. .. code-block:: shell xbmgmt configure [--device| -d] [--input] Enabling/Disabling clock throttling on a device - When enabled, clock throttling reduces the kernel clock frequency dynamically when either thermal or electrical sensors exceed defined threshold values. By lowering the clock frequency, clock throttling reduces the required power and subsequently generated heat. Only when all sensor values fall below their respective clock throttling threshold values will the kernel clock be restored to full performance. - Default clock throttling threshold values are available in ` `_ for supported platforms. - The contents of the .ini file for clock throttling configuration should be similar to the example provided below. Underneath the first line, ``[Device]``, specify one or more key-value pairings as needed. .. code-block:: ini [Device] throttling_enabled=true throttling_power_override=200 throttling_temp_override=90 - The definition of the three key-value pairings are given below. - ``throttling_enabled`` : When set to ``true``, clock throttling will be enabled. When set to ``false``, clock throttling will be disabled, and no clock throttling will occur. The default value is ``false``. - ``throttling_power_override`` : Provide a power threshold override in watts for clock throttling to activate. The default threshold value is given in ` `_. - ``throttling_temp_override`` : Provide a temperature threshold override in Celsius for clock throttling to activate. The default threshold value is given in ` `_. - If a pairing is not listed in the .ini file, the default value (or the updated value from previous usage of ``xbmgmt configure --input``) is used. - Thresholds can be set higher or lower as necessary (e.g. debugging purposes). Note that cards still have built-in card and clock shutdown logic with independent thresholds to protect the cards. - To check clock throttling settings, use ``xbmgmt examine`` with the ``cmc`` report. Enabling/Disabling DDR memory retention on a device .. code-block:: shell xbmgmt configure [--device| -d] --retention [ENABLE|DISABLE] **The details of the supported options** - The ``--device`` (or ``-d``) specifies the target device - : The Bus:Device.Function of the device of interest - The ``--input`` specifies an INI file with configuration details (e.g. memory, clock throttling). - The ``--retention`` option enables / disables DDR memory retention. **Example commands** .. code-block:: shell #Configure a device's memory settings using an image xbmgmt configure --device 0000:b3:00.0 --input /tmp/memory_config.ini #Configure a device using edited output .ini from xbmgmt dump --config xbmgmt configure --device 0000:b3:00.0 --input /tmp/config.ini #Enable a device's DDR memory retention xbmgmt configure --device 0000:b3:00.0 --retention ENABLE xbmgmt dump ~~~~~~~~~~~ The ``xbmgmt dump`` command dumps out content of the specified option **The supported options** Dumping the output of system configuration. .. code-block:: shell xbmgmt dump [--device| -d] [--config| -c] [--output| -o] Dumping the output of programmed system image .. code-block:: shell xbmgmt dump [--device| -d] [--flash| -f] [--output| -o] **The details of the supported options** - The ``--device`` (or ``-d``) specifies the target device - : The Bus:Device.Function of the device of interest - The ``--flash`` (or ``-f``) option dumps the output of programmed system image. Requires a .bin output file by ``-o`` option. - The ``--config`` (or ``-c``) option dumps the output of system configuration. Requires a .ini output file by ``-o`` option. - The ``--output`` (or ``-o``) specifies the output file to direct the dumped output. **Example commands** .. code-block:: shell #Dump programmed system image data xbmgmt dump --device 0000:b3:00.0 --flash -o /tmp/flash_dump.bin #Dump system configuration. This .ini file can be edited and used as input for xbmgmt configure. xbmgmt dump --device 0000:b3:00.0 --config -o /tmp/config_dump.ini #Example .ini file contents from xbmgmt dump --config. #Only edit the throttling_enabled, throttling_power_override, and throttling_temp_override values when editing clock throttling settings. [Device] mailbox_channel_disable=0x0 mailbox_channel_switch=0x0 xclbin_change=0 cache_xclbin=0 throttling_enabled=true throttling_power_override=200 throttling_temp_override=90 xbmgmt examine ~~~~~~~~~~~~~~ The ``xbmgmt examine`` command reports detail status information of the specified device `