diff --git a/.github/workflows/pipeline.yml b/.github/workflows/pipeline.yml index 431d54d8bdb..db1a51dfc04 100644 --- a/.github/workflows/pipeline.yml +++ b/.github/workflows/pipeline.yml @@ -106,23 +106,23 @@ jobs: timeout-minutes: 5 run: | source /opt/xilinx/xrt/setup.sh - echo "Y" | xbutil reset -d + echo "Y" | xrt-smi reset -d - name: Examine card timeout-minutes: 5 run: | source /opt/xilinx/xrt/setup.sh - xbutil examine -d + xrt-smi examine -d - name: Validate card timeout-minutes: 5 run: | source /opt/xilinx/xrt/setup.sh - xbutil validate -d --verbose --batch - xbutil examine -d + xrt-smi validate -d --verbose --batch + xrt-smi examine -d - name: Verify kernel run: | source /opt/xilinx/xrt/setup.sh echo "Running 'Verify Kernel' testcase" - xbutil validate --batch -r 'Verify kernel' -d --verbose + xrt-smi validate --batch -r 'Verify kernel' -d --verbose - name: Drivers reloading timeout-minutes: 10 run: | diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 087f58819ea..c692f4214a0 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -75,17 +75,17 @@ Removed Added ..... -**xbutil/xbmgmt** +**xrt-smi/xbmgmt** -* Added ``xball`` helper script to execute a common set of utility commands (e.g., ``xbutil`` & ``xbmgmt``) across a filtered set of devices. More information can be found using ``--help`` or in the XRT documents. +* Added ``xball`` helper script to execute a common set of utility commands (e.g., ``xrt-smi`` & ``xbmgmt``) across a filtered set of devices. More information can be found using ``--help`` or in the XRT documents. * Auto-selecting a device if only one device exits. If the option ``--device`` or ``-d`` is specified and there is only one device installed, it will be automatically selected and used. * All failing operations will now return an error code. Note: An error will also be returned if there are validation failures. * Improved error reporting. * Legacy commands have been deprecated. * Various report output improvements. -* ``xbutil configure`` *root* level command introduced. Added ``host_mem`` and ``p2p`` as commands to configure. +* ``xrt-smi configure`` *root* level command introduced. Added ``host_mem`` and ``p2p`` as commands to configure. * ``--force`` option support for all operations. -* ``xbutil validate`` now supports alternative platform validation directories. +* ``xrt-smi validate`` now supports alternative platform validation directories. **xclbin** @@ -134,7 +134,7 @@ Added * API errors are now propagated up the stack as ``std::system_error`` exceptions with POSIX error code. * Added C++ APIs for AIE graph control and execution. * XRT driver debug trace support through debugfs ``/sys/kernel/debug/xclmgmt/...`` and ``/sys/kernel/debug/xocl/...`` -* Greatly improved and feature full next generation xbutil and xbmgmt utilities are now the default. The legacy version of the tools can be invoked by passing *--legacy* as the first switch to xbutil or xbmgmt invocation. +* Greatly improved and feature full next generation xrt-smi and xbmgmt utilities are now the default. The legacy version of the tools can be invoked by passing *--legacy* as the first switch to xrt-smi or xbmgmt invocation. * KDS scheduler in xocl has been refactored to significantly improve the throughput across hundreds of processes exercising multiple compute units across multiple devices concurrently. * Initial support for PS Kernel -- where a helper application running on APU on platforms like U30 and VCK5000 can be controlled from PCIe host -- has been added. * Initial pybind11 bindings for XRT C++ APIs. See ``tests/python/22_verify/22_verify.py`` for an example. @@ -186,12 +186,12 @@ Added * Support for data driven *two stage* platforms have been added. * Slimmed down XRT RPM/DEB package dependencies. XRT package does not depend on other **dev/devel** packages anymore. * Enabled LPDDR for edge platforms -* xbutil for edge platforms (use xbutil --new) +* xrt-smi for edge platforms (use xrt-smi --new) Removed ....... -* xbsak, please use xbutil +* xbsak, please use xrt-smi 2.7.0 (202010.2.7.x) @@ -221,8 +221,8 @@ Added * Support for data-driven platforms have been added. XRT uses PCIe VSEC to identify data-driven platforms. For these class of platforms XRT uses device tree to discover IPs in the shell and then initialize them. * Experimental APIs have been added for AIE control for edge platforms. The APIs are defined in header file ``xrt_aie.h``. * Support for U30 video acceleration offload device has been added. -* Early access versions of next generation utilities, *xbutil* and *xbmgmt* are available. They can be invoked via *--new* switch as ``xbutil --new``. -* Utilties xbutil and xbmgmt now give a warning when they detect an unsupported Linux distribution version and kernel version. +* Early access versions of next generation utilities, *xrt-smi* and *xbmgmt* are available. They can be invoked via *--new* switch as ``xrt-smi --new``. +* Utilties xrt-smi and xbmgmt now give a warning when they detect an unsupported Linux distribution version and kernel version. * Error code paths for clPollStreams() API has been improved. @@ -230,7 +230,7 @@ Removed ....... * Deprecated utilties xclbincat and xclbinsplit have been removed. Please use xclbinutil to work with xclbin files. -* ``xclResetDevice()`` has been marked as deprecated in this release and will be removed in a future release. Please use xbutil reset to reset device. +* ``xclResetDevice()`` has been marked as deprecated in this release and will be removed in a future release. Please use xrt-smi reset to reset device. * ``xclUpgradeFirmware()``, ``xclUpgradeFirmware2()`` and ``xclUpgradeFirmwareXSpi()`` have been marked as deprecated in this release and will be removed in a future release. Please use xbmgmt utility to flash device. * ``xclBootFPGA()``, ``xclRemoveAndScanFPGA()`` and ``xclRegisterInterruptNotify()`` have been marked as deprecated in this release and will be removed in a future release. These functionalities are no longer supported. * ``xclLockDevice()`` and ``xclUnlockDevice()`` have been marked as deprecated in this release and will be removed in a future release. These functionalities are no longer supported. @@ -263,13 +263,13 @@ Added * Edge platforms based on MPSoC now support M2M feature via **Zynqmp built-in DMA engine**. M2M for both PCIe and edge platforms can be performed using ``xclCopyBO()`` XRT API or ``clEnqueueCopyBuffers()`` OCL API. Note that the same APIs can also be used to copy buffers between two devices using PCIe peer-to-peer transfer. * For edge platforms XRT now supports ACC (adapter execution model). * XRT documentation has been reorganized and significantly updated. -* XRT now natively supports fully virtualized environments where management physical function (PF0) is completely hidden in host and only user physical function (PF1) is exported to the guest. End-user applications based on libxrt_core and xbutil command line utility do not need directly interact with xclmgmt driver. Communication between xocl driver and xclmgmt driver is done over hardware mailbox and MPD/MSD framework. For more information refer to MPD/MSD and Mailbox sections in XRT documentation. -* Management Physical Function (PF0) should now be managed using ``xbmgmt`` utility which is geared towards system adminstrators. ``xbutil`` continues to be end-user facing utility. +* XRT now natively supports fully virtualized environments where management physical function (PF0) is completely hidden in host and only user physical function (PF1) is exported to the guest. End-user applications based on libxrt_core and xrt-smi command line utility do not need directly interact with xclmgmt driver. Communication between xocl driver and xclmgmt driver is done over hardware mailbox and MPD/MSD framework. For more information refer to MPD/MSD and Mailbox sections in XRT documentation. +* Management Physical Function (PF0) should now be managed using ``xbmgmt`` utility which is geared towards system adminstrators. ``xrt-smi`` continues to be end-user facing utility. * Support has been added for device memory only buffer with no backing shadow buffer in host on PCIe platforms. To allocate such buffers use ``XCL_BO_FLAGS_DEV_ONLY`` in flags field of xclAllocBO() or ``CL_MEM_HOST_NO_ACCESS`` in flags field of OCL API. * XRT now has integrated support for Linux hwmon. Run Linux sensors utility to see all the sensor values exported by Alveo/XRT. * XRT now has production support for edge platforms. The following non DFX platforms edge platforms are supported: zcu102_base, zcu104_base, zc702, zc706. In addition zcu102_base_dfx platform has DFX support. * Emulation and HW profiling support has been enabled for all the above mentioned edge platforms. Zynq MPSoC platforms: zcu102_base, zcu104_base and zcu102_base_dfx also has emulation profiling enabled. -* Improved handling of PCIe reset via ``xbutil reset`` which resolves system crash observed on some servers. +* Improved handling of PCIe reset via ``xrt-smi reset`` which resolves system crash observed on some servers. * Resource management has been moved out of XMA library. * Only signed xclbins can be loaded on systems running in UEFI secure boot mode. You can use DKMS key used to sign XRT drivers to sign xclbins as well. As root please use the following command to sign xclbin with DKMS UEFI key-- ``xclbinutil --private-key /var/lib/shim-signed/mok/MOK.priv --certificate /var/lib/shim-signed/mok/MOK.der --input a.xclbin --output signed.xclbin`` @@ -281,7 +281,7 @@ Known Issue * On U280 Platform, downloading XCLBIN is going to reset P2P BAR size back to 256M internally. XRT workaround this issue by reading BAR size register and writing back the same value. This sets the P2P BAR size back to the value before downloading XCLBIN. * On edge platforms intermittent hang is observed when downloading different xclbins multiple times while CU interrupt is enabled. * Dynamic clock scaling is not enabled for edge platforms. -* On PPC64LE ``xbutil reset`` uses PCIe fundamental reset effectively reloading the platform from PROM. Note on x86_64 ``xbutil reset`` continues to use PCIe warm reset which just resets the shell and the dynamic region without reloading the platform from PROM. +* On PPC64LE ``xrt-smi reset`` uses PCIe fundamental reset effectively reloading the platform from PROM. Note on x86_64 ``xrt-smi reset`` continues to use PCIe warm reset which just resets the shell and the dynamic region without reloading the platform from PROM. 2.2.0 (201910.2.2) ~~~~~~~~~~~~~~~~~~ @@ -303,7 +303,7 @@ Added * OCL can perform automatic binding of cl_mem to DDR bank by using several heuristics like kernel argument index and kernel instance information. The API ``clCreateKernel`` is enhanced to accept annotated CU name(s) to fetch asymmetrical compute units (If all the CUs of a kernel have exact same port maps or port connections they are symmetrical compute units, otherwise CUs are asymmetrical) and streaming compute units. * XRT will give error if it cannot identify the buffer location (in earlier releases it used to assume a default location). Remedies: a) Check kernel XCLBIN to make sure kernel argument corresponding to the buffer is mapped to device memory properly b) Use ``clSetKernelArg`` before any enqueue operation on buffer * Host applications directly linking with libxilinxopencl.so must use ``-Wl,-rpath-link,$(XILINX_XRT)/lib`` in the linker line. Host applications linking with ICD loader, libOpenCL.so do not need to change. -* ``xbutil top`` now reports live CU usage metric. +* ``xrt-smi top`` now reports live CU usage metric. * ``xclbincat`` and ``xclbinsplit`` are deprecated by ``xclbinutil``. These deprecated tools are currently scheduled to be obsoleted in the next release. * Profiling subsystem has been enhanced to show dataflow, PCIe peer to peer transfers, M2M transfers and kernel to kernel streaming information. * XRT has switched to new header file ``xrt.h`` in place of ``xclhal2.h``. The latter is still around for backwards compatibility but hash includes xrt.h for all definitions. A new file ``xrt-next.h`` has been added for experimental features. @@ -315,7 +315,7 @@ Added Added ..... -* xbutil can now generate output in JSON format for easy parsing by other tools. Use ``xbutil dump`` to generate JSON output on stdout. +* xrt-smi can now generate output in JSON format for easy parsing by other tools. Use ``xrt-smi dump`` to generate JSON output on stdout. * Initial support for PCIe peer-to-peer transactions has been added. Please consult https://xilinx.github.io/XRT/2018.3/html/p2p.html for details. * 64-bit BARs in Alveo shells are natively supported. * Initial implementation of XRT logging API, xclLogMsg() for use by XRT clients. @@ -326,7 +326,7 @@ Added Fixed ..... -* ``xbutil flash -a`` PROM corruption issue with multiple Alveo boards. +* ``xrt-smi flash -a`` PROM corruption issue with multiple Alveo boards. * XRT scheduling bug with multiple boards on AWS F1 when scheduler was serializing board access. * xocl kernel driver bugs in handling multiple processes accessing the same device. * PPC64LE build failure. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 15cc8c61eb2..d93b10d0516 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -13,7 +13,7 @@ When reporting issues on GitHub please include the following: 1. XRT version including git hash 2. Alveo platform name and version -3. Output of ``xbutil query`` +3. Output of ``xrt-smi query`` 4. Output of ``xbmgmt scan`` 5. ``dmesg`` 6. gdb stack trace of host application diff --git a/build/board.sh b/build/board.sh index a9b41a7500f..69a8a63dd27 100755 --- a/build/board.sh +++ b/build/board.sh @@ -141,7 +141,7 @@ if [[ "X$xrt" != "X" && -d "$xrt" ]] ; then export OCL_ICD_VENDORS=$XILINX_XRT/lib/libxilinxopencl.so fi -export DSA=`${XILINX_XRT}/bin/xbutil scan | grep '\[0\]' | cut -d':' -f5 | cut -d'(' -f1` +export DSA=`${XILINX_XRT}/bin/xrt-smi scan | grep '\[0\]' | cut -d':' -f5 | cut -d'(' -f1` echo "XILINX_XRT = $XILINX_XRT" echo "LD_LIBRARY_PATH = $LD_LIBRARY_PATH" diff --git a/build/debian/copyright b/build/debian/copyright index a814429b811..443cf450d7f 100644 --- a/build/debian/copyright +++ b/build/debian/copyright @@ -106,7 +106,7 @@ License: Apache-2.0 and/or GPL-2 FIXME Files: src/runtime_src/core/pcie/linux/LICENSE - src/runtime_src/core/pcie/tools/xbutil/LICENSE + src/runtime_src/core/pcie/tools/xrt-smi/LICENSE Copyright: [yyyy] [name of copyright owner] License: Apache-2.0 FIXME diff --git a/src/runtime_src/core/common/debug_ip.cpp b/src/runtime_src/core/common/debug_ip.cpp index 850c793fc0f..999e1546aa2 100644 --- a/src/runtime_src/core/common/debug_ip.cpp +++ b/src/runtime_src/core/common/debug_ip.cpp @@ -97,7 +97,7 @@ std::vector get_am_counter_result(const xrt_core::device* device, debug_ip_data* dbg_ip_data) { // read counter values - // These are in "xbutil" order + // These are in "xrt-smi" order static const uint64_t am_offsets[] = { xdp::IP::AM::AXI_LITE::EXECUTION_COUNT, xdp::IP::AM::AXI_LITE::EXECUTION_CYCLES, @@ -109,7 +109,7 @@ get_am_counter_result(const xrt_core::device* device, debug_ip_data* dbg_ip_data xdp::IP::AM::AXI_LITE::TOTAL_CU_START }; - // These are in "xbutil" order + // These are in "xrt-smi" order static const uint64_t am_upper_offsets[] = { xdp::IP::AM::AXI_LITE::EXECUTION_COUNT_UPPER, xdp::IP::AM::AXI_LITE::EXECUTION_CYCLES_UPPER, diff --git a/src/runtime_src/core/common/drv/kds_core.c b/src/runtime_src/core/common/drv/kds_core.c index 51f8ffe076f..cfdbf1a0c09 100644 --- a/src/runtime_src/core/common/drv/kds_core.c +++ b/src/runtime_src/core/common/drv/kds_core.c @@ -32,7 +32,7 @@ int store_kds_echo(struct kds_sched *kds, const char *buf, size_t count, /* Ideally, KDS should be locked to reject new client. * But, this node is hidden for internal test purpose. * Let's refine it after new KDS is the default and - * user is allow to configure it through xbutil. + * user is allow to configure it through xrt-smi. */ if (live_clients > 0) return -EBUSY; diff --git a/src/runtime_src/core/common/sensor.cpp b/src/runtime_src/core/common/sensor.cpp index 6ea111ad0fb..2dbdd4f02d1 100644 --- a/src/runtime_src/core/common/sensor.cpp +++ b/src/runtime_src/core/common/sensor.cpp @@ -542,7 +542,7 @@ read_mechanical(const xrt_core::device * device) }} // sensor,xrt -// The following namespace is only used by legacy xbutil dump +// The following namespace is only used by legacy xrt-smi dump namespace sensor_tree { // Singleton diff --git a/src/runtime_src/core/common/sensor.h b/src/runtime_src/core/common/sensor.h index a4d6eb10a02..12e8afdead4 100644 --- a/src/runtime_src/core/common/sensor.h +++ b/src/runtime_src/core/common/sensor.h @@ -42,7 +42,7 @@ read_mechanical(const xrt_core::device * device); }} // sensor, xrt_core -// The following namespace is only used by legacy xbutil dump +// The following namespace is only used by legacy xrt-smi dump namespace sensor_tree { boost::property_tree::ptree& diff --git a/src/runtime_src/core/edge/user/shim.h b/src/runtime_src/core/edge/user/shim.h index 4e4313c09c2..0607ba9f933 100644 --- a/src/runtime_src/core/edge/user/shim.h +++ b/src/runtime_src/core/edge/user/shim.h @@ -323,7 +323,7 @@ class shim { int xclIPName2Index(const char *name); int xclIPSetReadRange(uint32_t ipIndex, uint32_t start, uint32_t size); - // Application debug path functionality for xbutil + // Application debug path functionality for xrt-smi size_t xclDebugReadCheckers(xdp::LAPCCounterResults* aCheckerResults); size_t xclDebugReadCounters(xdp::AIMCounterResults* aCounterResults); size_t xclDebugReadAccelMonitorCounters(xdp::AMCounterResults* samResult); diff --git a/src/runtime_src/core/include/deprecated/xrt.h b/src/runtime_src/core/include/deprecated/xrt.h index 4647a4d7a20..6aa891d2c5f 100644 --- a/src/runtime_src/core/include/deprecated/xrt.h +++ b/src/runtime_src/core/include/deprecated/xrt.h @@ -710,7 +710,7 @@ XCL_DRIVER_DLLHIDDEN const struct axlf_section_header* wrap_get_axlf_section(const struct axlf* top, enum axlf_section_kind kind); -/* Use xbutil to reset device */ +/* Use xrt-smi to reset device */ XRT_DEPRECATED XCL_DRIVER_DLLHIDDEN int diff --git a/src/runtime_src/core/include/xclerr_int.h b/src/runtime_src/core/include/xclerr_int.h index a504a5a0d25..707ef7b9059 100644 --- a/src/runtime_src/core/include/xclerr_int.h +++ b/src/runtime_src/core/include/xclerr_int.h @@ -34,7 +34,7 @@ /** * DOC: Device last / latest error status related structs and defines * This file is used by both userspace and kernel driver. - * This file is used by xbutil, xocl, zocl and xbmgmt. + * This file is used by xrt-smi, xocl, zocl and xbmgmt. */ #ifndef XCLERR_INT_H_ diff --git a/src/runtime_src/core/include/xdp/aim.h b/src/runtime_src/core/include/xdp/aim.h index 65fa4226773..dfdd12c1a03 100644 --- a/src/runtime_src/core/include/xdp/aim.h +++ b/src/runtime_src/core/include/xdp/aim.h @@ -16,7 +16,7 @@ // This file captures all the constants used to access the // AXI Interface Monitor cores that may exist in the design. -// These values are shared between xbutil and the XDP library. +// These values are shared between xrt-smi and the XDP library. #ifndef AIM_DOT_H #define AIM_DOT_H @@ -25,7 +25,7 @@ namespace xdp::IP::AIM { // The total number of 64-bit counters accessible on the IP constexpr int NUM_COUNTERS = 13; -// The number of 64-bit counters displayed (as when accessed via xbutil) +// The number of 64-bit counters displayed (as when accessed via xrt-smi) constexpr int NUM_COUNTERS_REPORT = 9; namespace AXI_LITE { @@ -94,7 +94,7 @@ namespace report { // When we are reporting the status of this IP, we // strip away the write latency, write busy, read latency, and // read busy cycle information. The numbers here represent the -// index into the array used by xbutil and XDP to access the register value +// index into the array used by xrt-smi and XDP to access the register value constexpr int WRITE_BYTES = 0; constexpr int WRITE_TRANX = 1; constexpr int READ_BYTES = 2; diff --git a/src/runtime_src/core/include/xdp/am.h b/src/runtime_src/core/include/xdp/am.h index 22f59ada3e1..3dd01dc48b0 100644 --- a/src/runtime_src/core/include/xdp/am.h +++ b/src/runtime_src/core/include/xdp/am.h @@ -16,7 +16,7 @@ // This file captures all the constants used to access the // Accelerator Monitor cores that may exist in the design. These -// values are shared between xbutil and the XDP library. +// values are shared between xrt-smi and the XDP library. #ifndef AM_DOT_H #define AM_DOT_H @@ -25,7 +25,7 @@ namespace xdp::IP::AM { // The total number of 64-bit counters accessible on the IP constexpr int NUM_COUNTERS = 10; -// The number of 64-bit counters displayed (as when accessed via xbutil) +// The number of 64-bit counters displayed (as when accessed via xrt-smi) constexpr int NUM_COUNTERS_REPORT = 8; namespace AXI_LITE { diff --git a/src/runtime_src/core/include/xdp/app_debug.h b/src/runtime_src/core/include/xdp/app_debug.h index 6b8fd1f390a..eee3ef8adac 100644 --- a/src/runtime_src/core/include/xdp/app_debug.h +++ b/src/runtime_src/core/include/xdp/app_debug.h @@ -30,7 +30,7 @@ namespace xdp { -// The structs declared in this file are used in xbutil and application +// The structs declared in this file are used in xrt-smi and application // debug in order to read all the debug counter values from the // debug/profile IP. diff --git a/src/runtime_src/core/include/xdp/asm.h b/src/runtime_src/core/include/xdp/asm.h index c1c1229d1ac..c169f6fa903 100644 --- a/src/runtime_src/core/include/xdp/asm.h +++ b/src/runtime_src/core/include/xdp/asm.h @@ -16,7 +16,7 @@ // This file captures all the constants used to access the AXI Stream Monitor // cores that may exist in the design. These values are shared between -// the xbutil code base and the XDP library +// the xrt-smi code base and the XDP library #ifndef ASM_DOT_H #define ASM_DOT_H diff --git a/src/runtime_src/core/include/xdp/axi_checker_codes.h b/src/runtime_src/core/include/xdp/axi_checker_codes.h index ab5fd4c6fc8..2bb98aea4ba 100644 --- a/src/runtime_src/core/include/xdp/axi_checker_codes.h +++ b/src/runtime_src/core/include/xdp/axi_checker_codes.h @@ -14,7 +14,7 @@ * under the License. */ -// These AXI error codes are used in both xbutil and the gdb application +// These AXI error codes are used in both xrt-smi and the gdb application // debug extensions #ifndef AXI_CHECKER_CODES_H diff --git a/src/runtime_src/core/include/xdp/lapc.h b/src/runtime_src/core/include/xdp/lapc.h index b2e309c6667..63c8618af98 100644 --- a/src/runtime_src/core/include/xdp/lapc.h +++ b/src/runtime_src/core/include/xdp/lapc.h @@ -16,7 +16,7 @@ // This file captures all the constants used to access the // Lightweight AXI Protocol Checker cores that may exist in the design. -// These values are shared between xbutil and the XDP library. +// These values are shared between xrt-smi and the XDP library. #ifndef LAPC_DOT_H #define LAPC_DOT_H diff --git a/src/runtime_src/core/include/xdp/spc.h b/src/runtime_src/core/include/xdp/spc.h index 562d63b53d0..57fe8f651d0 100644 --- a/src/runtime_src/core/include/xdp/spc.h +++ b/src/runtime_src/core/include/xdp/spc.h @@ -16,7 +16,7 @@ // This file captures all the constants used to access the // AXI Stream Protocol Checker cores that may exist in the design. -// These values are shared between xbutil and the XDP library. +// These values are shared between xrt-smi and the XDP library. #ifndef SPC_DOT_H #define SPC_DOT_H diff --git a/src/runtime_src/core/pcie/driver/linux/xocl/subdev/icap.c b/src/runtime_src/core/pcie/driver/linux/xocl/subdev/icap.c index 6a0d4bbe878..042c2133e03 100644 --- a/src/runtime_src/core/pcie/driver/linux/xocl/subdev/icap.c +++ b/src/runtime_src/core/pcie/driver/linux/xocl/subdev/icap.c @@ -2284,7 +2284,7 @@ static int icap_calib_and_check(struct platform_device *pdev, uint32_t slot_id) BUG_ON(!mutex_is_locked(&icap->icap_lock)); if (icap->data_retention) - ICAP_WARN(icap, "xbutil reclock may not retain data"); + ICAP_WARN(icap, "xrt-smi reclock may not retain data"); icap_calib(icap, slot_id, false); diff --git a/src/runtime_src/core/pcie/driver/linux/xocl/userpf/xocl_bo.h b/src/runtime_src/core/pcie/driver/linux/xocl/userpf/xocl_bo.h index 686f1188f2b..dbedf3e54b8 100644 --- a/src/runtime_src/core/pcie/driver/linux/xocl/userpf/xocl_bo.h +++ b/src/runtime_src/core/pcie/driver/linux/xocl/userpf/xocl_bo.h @@ -47,7 +47,7 @@ /* * BO Usage stats stored in an array in drm_device. * BO types are tracked: P2P, EXECBUF, etc - * BO usage stats to be shown in sysfs & with xbutil + * BO usage stats to be shown in sysfs & with xrt-smi */ #define XOCL_BO_USAGE_TOTAL 7 #define XOCL_BO_USAGE_NORMAL 0 //Array indexes diff --git a/src/runtime_src/core/pcie/driver/linux/xocl/userpf/xocl_drv.c b/src/runtime_src/core/pcie/driver/linux/xocl/userpf/xocl_drv.c index dc82f8e738f..1e8d8873aff 100644 --- a/src/runtime_src/core/pcie/driver/linux/xocl/userpf/xocl_drv.c +++ b/src/runtime_src/core/pcie/driver/linux/xocl/userpf/xocl_drv.c @@ -344,7 +344,7 @@ int xocl_program_shell(struct xocl_dev *xdev, bool force) /* * Reset command should support following cases * case 1) When device is not in ready state - * - xbutil should not send any request to the xocl. + * - xrt-smi should not send any request to the xocl. * - It should just return fail status from userspace itself * case 2) When device is ready & device offline status is true * - Need to check when we hit this case @@ -359,12 +359,12 @@ int xocl_program_shell(struct xocl_dev *xdev, bool force) * d) Reset is issued to mgmt/mpd, but mgmt/mpd unable to reset properly * - xocl gets a ESHUTDOWN response from mgmt/mpd, * - xocl assumes that reset is successful, - * - xbutil waits on the device ready state in a loop. - * - xbutil reset would be in waiting state forever. - * - Need to handle this case to exit xbutil reset gracefully. + * - xrt-smi waits on the device ready state in a loop. + * - xrt-smi reset would be in waiting state forever. + * - Need to handle this case to exit xrt-smi reset gracefully. * e) Reset is issued to mgmt/mpd, but mgmt/mpd reset properly * - xocl gets a ESHUTDOWN response from mgmt/mpd, - * - Device becomes ready and xbutil reset successful. + * - Device becomes ready and xrt-smi reset successful. */ int xocl_hot_reset(struct xocl_dev *xdev, u32 flag) { @@ -724,7 +724,7 @@ static void xocl_mailbox_srv(void *arg, void *data, size_t len, userpf_info(xdev, "AXI Firewall %llu tripped", fw_status.err_detected_level); userpf_info(xdev, - "Card is in a BAD state, please issue xbutil reset"); + "Card is in a BAD state, please issue xrt-smi reset"); err_last.pid = 0; err_last.ts = fw_status.err_detected_time; err_last.err_code = XRT_ERROR_CODE_BUILD(XRT_ERROR_NUM_FIRWWALL_TRIP, @@ -1661,7 +1661,7 @@ int xocl_cma_bank_alloc(struct xocl_dev *xdev, struct drm_xocl_alloc_cma_info *c goto unlock; } else { DRM_ERROR("HOST MEM already allocated, size 0x%llx", allocated_size); - DRM_ERROR("Please run xbutil host disable first"); + DRM_ERROR("Please run xrt-smi host disable first"); err = -EBUSY; goto unlock; } @@ -1803,7 +1803,7 @@ int xocl_userpf_probe(struct pci_dev *pdev, store_pcie_link_info(xdev); /* - * sysfs has to be the last thing to init because xbutil + * sysfs has to be the last thing to init because xrt-smi * relies it to report if the card is ready. Driver should * only announce ready after syncing metadata and creating * all subdevices diff --git a/src/runtime_src/core/pcie/driver/linux/xocl/userpf/xocl_ioctl.c b/src/runtime_src/core/pcie/driver/linux/xocl/userpf/xocl_ioctl.c index b624c5f3fc1..df3fcbafe40 100644 --- a/src/runtime_src/core/pcie/driver/linux/xocl/userpf/xocl_ioctl.c +++ b/src/runtime_src/core/pcie/driver/linux/xocl/userpf/xocl_ioctl.c @@ -826,7 +826,7 @@ int xocl_hot_reset_ioctl(struct drm_device *dev, void *data, /* * if the reset mailbox opcode is disabled, we don't allow - * user run 'xbutil reset' + * user run 'xrt-smi reset' */ xocl_mailbox_get(xdev, CHAN_DISABLE, &chan_disable); if (chan_disable & (1 << XCL_MAILBOX_REQ_HOT_RESET)) diff --git a/src/runtime_src/core/pcie/driver/linux/xocl/userpf/xocl_kds.c b/src/runtime_src/core/pcie/driver/linux/xocl/userpf/xocl_kds.c index 7de044db049..e87e07d9c32 100644 --- a/src/runtime_src/core/pcie/driver/linux/xocl/userpf/xocl_kds.c +++ b/src/runtime_src/core/pcie/driver/linux/xocl/userpf/xocl_kds.c @@ -424,7 +424,7 @@ static inline void read_ert_stat(struct kds_command *xcmd) /* TODO: For CU stat command, there are few things to refine. * 1. Define size of the command * 2. Define CU status enum/macro in a header file - * a. xocl/zocl/MB/RPU/xbutil can shared + * a. xocl/zocl/MB/RPU/xrt-smi can shared * b. parser helper function if need */ diff --git a/src/runtime_src/core/pcie/tools/cloud-daemon/azure/azure.cpp b/src/runtime_src/core/pcie/tools/cloud-daemon/azure/azure.cpp index 73df8db77d8..1858b57db8a 100644 --- a/src/runtime_src/core/pcie/tools/cloud-daemon/azure/azure.cpp +++ b/src/runtime_src/core/pcie/tools/cloud-daemon/azure/azure.cpp @@ -173,7 +173,7 @@ int azureHotReset(size_t index, int *resp) * to wireserver since this makes no sense and even hangs the instance. * Empty S/N may happen in this scenario, * 1. vm boots and is ready before the mgmt side is ready - * 2. 'xbutil reset' tries to reset the card immediately after mgmt is ready + * 2. 'xrt-smi reset' tries to reset the card immediately after mgmt is ready * in this case, there is no chance for mpd to get S/N info. so we just fails * the reset */ diff --git a/src/runtime_src/core/pcie/tools/cloud-daemon/container/container.cpp b/src/runtime_src/core/pcie/tools/cloud-daemon/container/container.cpp index 32f43f9157e..bd84fa61930 100644 --- a/src/runtime_src/core/pcie/tools/cloud-daemon/container/container.cpp +++ b/src/runtime_src/core/pcie/tools/cloud-daemon/container/container.cpp @@ -117,7 +117,7 @@ int Container::xclLoadXclBin(const xclBin *buffer) * That means, the input xclbin file is downloaded as-is. This is also * useful in xrt container deployment case, with which, only the user PF * is granted to the container, and mgmt is left at host, but within - * container users can use xbutil and/or openCL without seeing any + * container users can use xrt-smi and/or openCL without seeing any * difference compared to within host. * * If container platform vendors, say Nimbix, want to have xclbin proction, diff --git a/src/runtime_src/core/tools/xbmgmt2/xbmgmt-csh-completion b/src/runtime_src/core/tools/xbmgmt2/xbmgmt-csh-completion index ecd7e0ede32..f8fb6897200 100755 --- a/src/runtime_src/core/tools/xbmgmt2/xbmgmt-csh-completion +++ b/src/runtime_src/core/tools/xbmgmt2/xbmgmt-csh-completion @@ -5,7 +5,7 @@ # parse out required variables set list = "$COMMAND_LINE" -# The command word associated with this xbutil invocation +# The command word associated with this xrt-smi invocation set commandWord = `echo $list | awk 'BEGIN{FS=" "}{print $2}'` # Get the number of arguments. This script turns spaces into ampersands to count # the number of commands. This script is NOT space in path name friendly. @@ -24,7 +24,7 @@ set currentWord = `echo $argsplit | awk 'BEGIN{FS="@"}{print $NF}'` # The options for the current command line statement set programOptions = "--verbose --batch --force --help -h --version" -# Handle the default xbutil options first +# Handle the default xrt-smi options first if($commandCount == "1") then set programOptions="dump examine program reset ${programOptions}" # All other commands enter into this case diff --git a/src/runtime_src/core/tools/xbmgmt2/xbmgmt-csh-completion-wrapper b/src/runtime_src/core/tools/xbmgmt2/xbmgmt-csh-completion-wrapper index c4ff09e73b9..bdecc307d08 100755 --- a/src/runtime_src/core/tools/xbmgmt2/xbmgmt-csh-completion-wrapper +++ b/src/runtime_src/core/tools/xbmgmt2/xbmgmt-csh-completion-wrapper @@ -3,7 +3,7 @@ # Copyright (C) 2021-2022 Xilinx, Inc. All rights reserved. # -# Enable autocompletion for the xbutil and xbmgmt commands +# Enable autocompletion for the xrt-smi and xbmgmt commands alias __xbmgmt_completion_csh tcsh $XILINX_XRT/share/completions/xbmgmt-csh-completion # TCSH is very unfriendly when performing file completions inside the aliased script # to get around this we add certain options that default to file/directory searches here diff --git a/src/runtime_src/core/tools/xbutil2/CMakeLists.txt b/src/runtime_src/core/tools/xbutil2/CMakeLists.txt index 96ba609af4c..b48de255a9d 100644 --- a/src/runtime_src/core/tools/xbutil2/CMakeLists.txt +++ b/src/runtime_src/core/tools/xbutil2/CMakeLists.txt @@ -60,7 +60,7 @@ set(XBUTIL2_NAME "xrt-smi") if(WIN32) set(XRT_HELPER_SCRIPTS "xrt-smi" "xrt-smi.bat") else() - set(XRT_HELPER_SCRIPTS "xbutil" "xrt-smi") + set(XRT_HELPER_SCRIPTS "xrt-smi") endif() add_executable(${XBUTIL2_NAME} ${XBUTIL_V2_SRCS}) diff --git a/src/runtime_src/core/tools/xbutil2/xbutil b/src/runtime_src/core/tools/xbutil2/xbutil deleted file mode 100755 index d4ac1bd42a7..00000000000 --- a/src/runtime_src/core/tools/xbutil2/xbutil +++ /dev/null @@ -1,59 +0,0 @@ -#!/bin/bash - -# -# SPDX-License-Identifier: Apache-2.0 -# -# Copyright (C) 2020-2022 Xilinx, Inc. -# - -# -- Detect a Windows environment and automatically switch to the .bat file -if [[ "`uname`" == windows32* ]] || [[ "`uname`" == CYGWIN* ]] ; then - trap "" INT - "$0.bat" "$@" - exit $? -fi - -# Working variables -XRT_PROG=xrt-smi -echo "----------------------------------------------------------------------" -echo " WARNING: - xbutil has been renamed to xrt-smi - Please migrate to using xrt-smi instead of xbutil. - - Commands, options, arguments and their descriptions can also be - reported via the --help option." -echo "----------------------------------------------------------------------" - -# -- Examine the options -XRTWARP_PROG_ARGS_size=0 -XRTWRAP_PROG_ARGS=() -while [ $# -gt 0 ]; do - case "$1" in - # Copy the options the remaining options - *) - XRTWRAP_PROG_ARGS[$XRTWARP_PROG_ARGS_size]="$1" - XRTWARP_PROG_ARGS_size=$(($XRTWARP_PROG_ARGS_size + 1)) - shift - ;; - esac -done - -# -- Find loader directory -XRT_LOADER_DIR="`dirname \"$0\"`" - -# For edge platforms loader is not required as tools are in standard location(/usr). -# So calling unwrapped tool from this script itself. -if [[ $XRT_LOADER_DIR =~ "/usr" || $XRT_LOADER_DIR =~ "/bin" ]]; then - "${XRT_LOADER_DIR}/unwrapped/${XRT_PROG}" "${XRTWRAP_PROG_ARGS[@]}" - exit 0 -fi - -# Call loader for dc platforms -XRT_LOADER="${XRT_LOADER_DIR}/unwrapped/loader" -if [ ! -f "$XRT_LOADER" ]; then - echo "ERROR: Could not find 64-bit loader executable." - echo "ERROR: ${XRT_LOADER} does not exist." - exit 1 -fi - -"${XRT_LOADER}" -exec ${XRT_PROG} "${XRTWRAP_PROG_ARGS[@]}" diff --git a/src/runtime_src/core/tools/xbutil2/xbutil-bash-completion b/src/runtime_src/core/tools/xbutil2/xbutil-bash-completion index a71635006db..e3fe997facb 100755 --- a/src/runtime_src/core/tools/xbutil2/xbutil-bash-completion +++ b/src/runtime_src/core/tools/xbutil2/xbutil-bash-completion @@ -1,4 +1,4 @@ -# bash completion for xbutil -*- shell-script -*- +# bash completion for xrt-smi -*- shell-script -*- # SPDX-License-Identifier: Apache-2.0 # Copyright (C) 2021-2022 Xilinx, Inc. All rights reserved. # @@ -77,10 +77,10 @@ _xbutil_completion() { commonSubCommands="--verbose --batch --force --help -h --version" # COMP_CWORD is the current index of the cursor in the command line - # 0 is the first argument (xbutil), 1 is the desired command for xbutil, + # 0 is the first argument (xrt-smi), 1 is the desired command for xrt-smi, # 2 is an option for the command, etc. case ${COMP_CWORD} in - # Case for command after xbutil + # Case for command after xrt-smi 1) options="program validate examine configure reset ${commonSubCommands}" ;; diff --git a/src/runtime_src/core/tools/xbutil2/xbutil-csh-completion b/src/runtime_src/core/tools/xbutil2/xbutil-csh-completion index beb319d4f61..39f6de6c377 100755 --- a/src/runtime_src/core/tools/xbutil2/xbutil-csh-completion +++ b/src/runtime_src/core/tools/xbutil2/xbutil-csh-completion @@ -5,7 +5,7 @@ # parse out required variables set list = "$COMMAND_LINE" -# The command word associated with this xbutil invocation +# The command word associated with this xrt-smi invocation set commandWord = `echo $list | awk 'BEGIN{FS=" "}{print $2}'` # Get the number of arguments. This script turns spaces into ampersands to count # the number of commands. This script is NOT space in path name friendly. @@ -24,7 +24,7 @@ set currentWord = `echo $argsplit | awk 'BEGIN{FS="@"}{print $NF}'` # The options for the current command line statement set programOptions = "--verbose --batch --force --help -h --version" -# Handle the default xbutil options first +# Handle the default xrt-smi options first if($commandCount == "1") then set programOptions="${programOptions} program validate examine configure reset" else @@ -74,7 +74,7 @@ else case "hostmem": set programOptions="" breaksw - # -r shorthand applies to multiple commands under xbutil and requires additional processing + # -r shorthand applies to multiple commands under xrt-smi and requires additional processing # Assuming we want to add something here one day case "report": case "run": diff --git a/src/runtime_src/core/tools/xbutil2/xbutil-csh-completion-wrapper b/src/runtime_src/core/tools/xbutil2/xbutil-csh-completion-wrapper index d30a292aed1..5bd6c952539 100644 --- a/src/runtime_src/core/tools/xbutil2/xbutil-csh-completion-wrapper +++ b/src/runtime_src/core/tools/xbutil2/xbutil-csh-completion-wrapper @@ -3,8 +3,8 @@ # Copyright (C) 2021-2022 Xilinx, Inc. All rights reserved. # -# Enable autocompletion for the xbutil and xbmgmt commands -alias __xbutil_completion_csh tcsh $XILINX_XRT/share/completions/xbutil-csh-completion +# Enable autocompletion for the xrt-smi and xbmgmt commands +alias __xbutil_completion_csh tcsh $XILINX_XRT/share/completions/xrt-smi-csh-completion # TCSH is very unfriendly when performing file completions inside the aliased script # to get around this we add certain options that default to file/directory searches here # The options that bypass the completion script are identified (using the n as the first parameter) by their name diff --git a/src/runtime_src/doc/toc/cloud_vendor_support.rst b/src/runtime_src/doc/toc/cloud_vendor_support.rst index 9966ca13b25..ae5b4b2c4cc 100644 --- a/src/runtime_src/doc/toc/cloud_vendor_support.rst +++ b/src/runtime_src/doc/toc/cloud_vendor_support.rst @@ -44,7 +44,7 @@ The following picture illustrates how a xclbin file is downloaded on baremetal m As shown by the red arrows in the picture, the flow of the download in this case is as following: -1. User requests xclbin download from ‘xbutil program’ cmdline or OpenCL API +1. User requests xclbin download from ‘xrt-smi program’ cmdline or OpenCL API 2. Shim layer issues ioctl to xocl driver 3. Xocl driver subdev icap sends the req to subdev mailbox (the xclbin file is in host memory, the req size is very small) 4. Mailbox transfers the req to the peer in xclmgmt through hw mailbox @@ -97,7 +97,7 @@ The flow of downloading xclbin through SW mailbox and MSD/MPD is illustrated as As shown by the green arrows in the picture, the flow of the download in this case is as following: -1. User requests xclbin download from ‘xbutil program’ cmdline or OpenCL API +1. User requests xclbin download from ‘xrt-smi program’ cmdline or OpenCL API 2. Shim layer issues ioctl to xocl driver 3. Xocl driver subdev icap sends the req to subdev mailbox 4. Mailbox transfers the req and xclbin file to MPD as mailbox message diff --git a/src/runtime_src/doc/toc/debug-faq.rst b/src/runtime_src/doc/toc/debug-faq.rst index aabe4e7bf6b..75e1e1dc45f 100644 --- a/src/runtime_src/doc/toc/debug-faq.rst +++ b/src/runtime_src/doc/toc/debug-faq.rst @@ -18,7 +18,7 @@ Tools of the Trade Capture stack trace of an XRT application ``lspci`` Enumerate Xilinx® PCIe devices -``xbutil`` +``xrt-smi`` Query status of Xilinx® PCIe device ``xclbinutil`` Retrieve info from an xclbin @@ -40,16 +40,16 @@ Board Enumeration Check if XRT can see the board and reports sane values :: - xbutil examine + xrt-smi examine XSA Sanity Test Card validation on kernel, bandwidth, dmatest and etc. (--device for pointing a specific board) :: - xbutil validate --device + xrt-smi validate --device Check DDR and PCIe bandwidth :: - xbutil validate --device --run dma + xrt-smi validate --device --run dma Common Reasons For Failures ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -66,8 +66,8 @@ Memory Read Before Write Read-Before-Write in 5.0+ XSAs will cause MIG *ECC* error. This is typically a user error. For example if user expects a kernel to write 4KB of data in DDR but it produced only 1KB of data and now the user tries to transfer full 4KB of data to host. It can also happen if user supplied 1KB sized buffer to a kernel but the kernel tries to read 4KB of data. Note ECC read-before-write error occurs if -- since the last bitstream download which results in MIG initialization -- no data has been written to a memory location but a read request is made for that same memory location. ECC errors stall the affected MIG since usually kernels are not able to handle this error. This can manifest in two different ways: -1. CU may hang or stall because it does not know how to handle this error while reading/writing to/from the affected MIG. ``xbutil examine --device --report dynamic-regions`` will show that the CU is stuck in *BUSY* state and not making progress. -2. AXI Firewall may trip if PCIe DMA request is made to the affected MIG as the DMA engine will be unable to complete request. AXI Firewall trips result in the Linux kernel driver killing all processes which have opened the device node with *SIGBUS* signal. ``xbutil examine --device --report firewall`` will show if an AXI Firewall has indeed tripped including its timestamp. +1. CU may hang or stall because it does not know how to handle this error while reading/writing to/from the affected MIG. ``xrt-smi examine --device --report dynamic-regions`` will show that the CU is stuck in *BUSY* state and not making progress. +2. AXI Firewall may trip if PCIe DMA request is made to the affected MIG as the DMA engine will be unable to complete request. AXI Firewall trips result in the Linux kernel driver killing all processes which have opened the device node with *SIGBUS* signal. ``xrt-smi examine --device --report firewall`` will show if an AXI Firewall has indeed tripped including its timestamp. Users should review the host code carefully. One common example is compression where the size of the compressed data is not known upfront and an application may try to migrate more data to host than was produced by the kernel. @@ -86,18 +86,18 @@ kernels will demonstrate weird behavior. 3. When run several times, a CU may produce correct results a few times and incorrect results rest of the time 4. A single CU run may produce a pattern of correct and incorrect result segments. Hence for a CU which produces a very long vector output (e.g. vector add), a pattern of correct — typically 64 bytes or one AXI burst — segment followed by incorrect segments are generated. -Users should check the frequency of the board with ``xbutil examine --device --report platform`` and compare it against the metadata in xclbin. ``xclbinutil`` may be used to extract metadata from xclbin. +Users should check the frequency of the board with ``xrt-smi examine --device --report platform`` and compare it against the metadata in xclbin. ``xclbinutil`` may be used to extract metadata from xclbin. CU Deadlock ........... -HLS scheduler bugs can also result in CU hangs. CU deadlocks AXI data bus at which point neither read nor write operation can make progress. The deadlocks can be observed with ``xbutil examine --device --report dynamic-regions`` where the CU will appear stuck in *START* or *---* state (can also be observed through debug-ip using the command ``xbutil examine --device --report debug-ip-status``). Note this deadlock can cause other CUs which read/write from/to the same MIG to also hang. +HLS scheduler bugs can also result in CU hangs. CU deadlocks AXI data bus at which point neither read nor write operation can make progress. The deadlocks can be observed with ``xrt-smi examine --device --report dynamic-regions`` where the CU will appear stuck in *START* or *---* state (can also be observed through debug-ip using the command ``xrt-smi examine --device --report debug-ip-status``). Note this deadlock can cause other CUs which read/write from/to the same MIG to also hang. AXI Bus Deadlock ................ -AXI Bus deadlocks can be caused by `Memory Read Before Write`_ or `CU Deadlock`_ described above. These usually show up as CU hang and sometimes may cause AXI FireWall to trip. Run ``xbutil examine --device --report dynamic-regions`` and ``xbutil examine --device --report firewall`` to check if CU is stuck in *START* or *--* state or if one of the AXI Firewall has tripped. +AXI Bus deadlocks can be caused by `Memory Read Before Write`_ or `CU Deadlock`_ described above. These usually show up as CU hang and sometimes may cause AXI FireWall to trip. Run ``xrt-smi examine --device --report dynamic-regions`` and ``xrt-smi examine --device --report firewall`` to check if CU is stuck in *START* or *--* state or if one of the AXI Firewall has tripped. Platform Bugs @@ -120,15 +120,15 @@ Board in Crashed State ~~~~~~~~~~~~~~~~~~~~~~ When board is in crashed state PCIe read operations start returning -``0XFF``. In this state ``xbutil examine`` would show bizarre +``0XFF``. In this state ``xrt-smi examine`` would show bizarre metrics. For example ``Temp`` would be very high. Boards in crashed state may be recovered with PCIe hot reset :: - xbutil reset + xrt-smi reset If this does not recover the board perform a warm reboot. After reset/reboot please follow steps in `Validating a Working Setup`_ -If for some reason communication between xocl driver and management driver gets disrupted, ``xbutil reset`` may not be successful to reset the board. In those cases the following steps are recommended with the help of the sysadmin who has the root previledge +If for some reason communication between xocl driver and management driver gets disrupted, ``xrt-smi reset`` may not be successful to reset the board. In those cases the following steps are recommended with the help of the sysadmin who has the root previledge 1) unload xocl driver (also shut down VM if xocl is running on a VM) 2) Run ``xbmgmt reset`` @@ -148,7 +148,7 @@ Writing Good Bug Reports When creating bug reports please include the following: 1. Output of ``dmesg`` -2. Output of ``xbutil examine --device --report all`` +2. Output of ``xrt-smi examine --device --report all`` 3. Application binaries: xclbin, host executable and code, any data files used by the application 4. XRT version 5. XSA name and version diff --git a/src/runtime_src/doc/toc/hm.rst b/src/runtime_src/doc/toc/hm.rst index 32dda91409a..b1af26ae633 100644 --- a/src/runtime_src/doc/toc/hm.rst +++ b/src/runtime_src/doc/toc/hm.rst @@ -73,31 +73,31 @@ The following table can be used to determine the number of Hugepages required ba Enabling the Host Memory by XRT ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Irrespective of the Hugepages settings, ``xbutil configure --host-mem`` command must be used to reserve the host memory for the kernel. This has to be done upfront before the XCLBIN download. In the example below, ``sudo xbutil configure --host-mem -d `` command is used to reserve 1G, 4G, and 16G host memory respectively for 3 cards. +Irrespective of the Hugepages settings, ``xrt-smi configure --host-mem`` command must be used to reserve the host memory for the kernel. This has to be done upfront before the XCLBIN download. In the example below, ``sudo xrt-smi configure --host-mem -d `` command is used to reserve 1G, 4G, and 16G host memory respectively for 3 cards. .. code-block:: bash - sudo xbutil configure --host-mem -d 0000:a6:00.1 --size 1G enable - sudo xbutil configure --host-mem -d 0000:73:00.1 --size 4G enable - sudo xbutil configure --host-mem -d 0000:17:00.1 --size 16G enable + sudo xrt-smi configure --host-mem -d 0000:a6:00.1 --size 1G enable + sudo xrt-smi configure --host-mem -d 0000:73:00.1 --size 4G enable + sudo xrt-smi configure --host-mem -d 0000:17:00.1 --size 16G enable Maximum Host memory supported by the platform ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For the platform supporting the host memory access feature, we can observe the following two data from the ``xbutil examine -r pcie-info -d `` output +For the platform supporting the host memory access feature, we can observe the following two data from the ``xrt-smi examine -r pcie-info -d `` output - **Max Shared Host Memory**: The maximum host memory supported by the platform. - - **Shared Host Memory**: The host memory specified for this card (by ``xbutil configure --host-mem``) + - **Shared Host Memory**: The host memory specified for this card (by ``xrt-smi configure --host-mem``) Assuming the platform supported maximum host memory is 16GB, the following output will be observed when the card is configured for 1GB host memory, no xclbin loaded. .. code-block:: bash - shell>>sudo xbutil configure --host-mem -d 0000:17:00.1 --size 1G enable + shell>>sudo xrt-smi configure --host-mem -d 0000:17:00.1 --size 1G enable Host-mem enabled successfully - shell>>xbutil examine -r pcie-info -d 0000:17:00.1 + shell>>xrt-smi examine -r pcie-info -d 0000:17:00.1 ----------------------------------------------- 1/1 [0000:a6:00.1] : xilinx_u250_gen3x16_xdma_shell_3_1 @@ -118,7 +118,7 @@ When you load an xclbin with the host mem support, the ``Max Shared Host Mem`` g .. code-block:: bash - shell>>xbutil examine -r pcie-info -d 0000:17:00.1 + shell>>xrt-smi examine -r pcie-info -d 0000:17:00.1 ----------------------------------------------- 1/1 [0000:a6:00.1] : xilinx_u250_gen3x16_xdma_shell_3_1 @@ -139,7 +139,7 @@ Finally, when you run an application which exercises HOST[0], ``Enabled Host Mem .. code-block:: bash - shell>>xbutil examine -r pcie-info -d 0000:17:00.1 + shell>>xrt-smi examine -r pcie-info -d 0000:17:00.1 ----------------------------------------------- 1/1 [0000:a6:00.1] : xilinx_u250_gen3x16_xdma_shell_3_1 diff --git a/src/runtime_src/doc/toc/index.rst b/src/runtime_src/doc/toc/index.rst index 6c4efdef709..fcec3bc75a3 100644 --- a/src/runtime_src/doc/toc/index.rst +++ b/src/runtime_src/doc/toc/index.rst @@ -68,7 +68,7 @@ FPGA. The key user APIs are defined in ``xrt.h`` header file. :maxdepth: 1 xclbintools.rst - xbutil.rst + xrt-smi.rst xbmgmt.rst xbflash2.rst xball.rst diff --git a/src/runtime_src/doc/toc/nagios_plugin.rst b/src/runtime_src/doc/toc/nagios_plugin.rst index 4d4fa43fc3d..355672335b5 100644 --- a/src/runtime_src/doc/toc/nagios_plugin.rst +++ b/src/runtime_src/doc/toc/nagios_plugin.rst @@ -23,7 +23,7 @@ The plugin places the requested device report text in a JSON format into the sta - The ``--report`` (or ``-r``) switch can be used to view specific report(s) of interest from the following options - - See :ref:`xbutil examine report options ` for a list of valid reports + - See :ref:`xrt-smi examine report options ` for a list of valid reports **Example commands** diff --git a/src/runtime_src/doc/toc/opencl_extension.rst b/src/runtime_src/doc/toc/opencl_extension.rst index fe48256da13..787746da1e7 100644 --- a/src/runtime_src/doc/toc/opencl_extension.rst +++ b/src/runtime_src/doc/toc/opencl_extension.rst @@ -68,7 +68,7 @@ Here is an example of specifying explicit name of the bank, this works for only 2. Specify a Buffer location by memory bank index ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This approach works for all types of memory banks as it accept index of the memory. The memory index can be obtained by inspecting .xclbin.info file or by xbutil query. +This approach works for all types of memory banks as it accept index of the memory. The memory index can be obtained by inspecting .xclbin.info file or by xrt-smi query. .. code:: c++ diff --git a/src/runtime_src/doc/toc/p2p.rst b/src/runtime_src/doc/toc/p2p.rst index ee5ac6f2d55..f9d62370a0d 100644 --- a/src/runtime_src/doc/toc/p2p.rst +++ b/src/runtime_src/doc/toc/p2p.rst @@ -45,7 +45,7 @@ Some Mother board BIOS setup allows administrator to set IO Memory base address Enable/Disable P2P ~~~~~~~~~~~~~~~~~~ -XRT ``xbutil`` is used to enable/disable P2P feature and check current configuration. P2P configuration is persistent across warm reboot. Enabling or disabling P2P requires root privilege. +XRT ``xrt-smi`` is used to enable/disable P2P feature and check current configuration. P2P configuration is persistent across warm reboot. Enabling or disabling P2P requires root privilege. Enabling P2P after cold boot is likly to fail because it resizes an exisitng P2P PCIe BAR to a large size and usually Linux will not reserve large IO memory for the PCIe bridges. XRT driver checks the maximum IO memory allowed by host BIOS setup and returns error if there is not enough IO memory for P2P. A warm reboot is required in this scenario after which BIOS and Linux will reassign the required expanded IO memory resource for P2P BAR. If a system stops responding after enabling P2P and warm reboot does not recover the host then power cycle is required to recover the host. @@ -57,11 +57,11 @@ The IO memory region will not be completely released after disabling P2P. Thus, Current P2P Configuration ......................... -``P2P Enabled`` is shown within ``xbutil examine`` output as below. +``P2P Enabled`` is shown within ``xrt-smi examine`` output as below. :: - # xbutil examine --device 0000:03:00.1 + # xrt-smi examine --device 0000:03:00.1 . . . P2P Status : disabled @@ -84,10 +84,10 @@ The command for enabling p2p is as below :: - # sudo xbutil configure --device 0000:b3:00.1 --p2p enable + # sudo xrt-smi configure --device 0000:b3:00.1 --p2p enable -When trying to enable p2p, it is possible that the Pcie Bar increase cannot happen without an warm reboot. In those situation when trying to enable the P2P, you will see a message for warm reboot request. You can also verify this through ``xbutil examine`` that would show P2P status is ``no iomem`` +When trying to enable p2p, it is possible that the Pcie Bar increase cannot happen without an warm reboot. In those situation when trying to enable the P2P, you will see a message for warm reboot request. You can also verify this through ``xrt-smi examine`` that would show P2P status is ``no iomem`` Disable P2P @@ -97,7 +97,7 @@ The commands for disabling p2p is as below :: - # sudo xbutil configure --device 0000:b3:00.1 --p2p disable + # sudo xrt-smi configure --device 0000:b3:00.1 --p2p disable Disabling and re-enabling P2P work without a warm reboot in-between. diff --git a/src/runtime_src/doc/toc/platforms_partitions.rst b/src/runtime_src/doc/toc/platforms_partitions.rst index 953dff8d71e..7538fa52970 100644 --- a/src/runtime_src/doc/toc/platforms_partitions.rst +++ b/src/runtime_src/doc/toc/platforms_partitions.rst @@ -67,7 +67,7 @@ In two stage platforms, Shell partition contains additional shell components suc User ==== -User partition contains user compiled components like acceleration engines/compute kernels etc. It is loaded by xclmgmt driver on request by user. XRT provides API ``xclLoadXclBin()`` and command line utility ``xbutil program`` to help load xclbins. This allows users to dynamically swap the image running on User parition to meet their workload requirements. +User partition contains user compiled components like acceleration engines/compute kernels etc. It is loaded by xclmgmt driver on request by user. XRT provides API ``xclLoadXclBin()`` and command line utility ``xrt-smi program`` to help load xclbins. This allows users to dynamically swap the image running on User parition to meet their workload requirements. .. note:: Refer to :doc:`mailbox.main` for detailed protocol used by xocl and xclmgmt drivers for loading Shell xsabin and User xclbin. diff --git a/src/runtime_src/doc/toc/security.rst b/src/runtime_src/doc/toc/security.rst index df97c055b01..ea5391bd797 100644 --- a/src/runtime_src/doc/toc/security.rst +++ b/src/runtime_src/doc/toc/security.rst @@ -96,7 +96,7 @@ PF BAR Driver Purpose 1 4 xocl CPU direct and P2P access to device attached DDR/HBM/PL-RAM memory. By default its size is limited to 256MB but can be expanded - using XRT xbutil tool as described in :doc:`p2p` + using XRT xrt-smi tool as described in :doc:`p2p` == === ======= =============================================================== Sample output of Linux ``lspci`` command for U50 device below:: @@ -331,7 +331,7 @@ Device Reset and Recovery Device reset and recovery is a privileged operation and can only be performed by xclmgmt driver. xocl driver can request device reset by sending a message to xclmgmt driver over the Mailbox. An end user -can reset a device by using XRT **xbutil** utility. This utility talks to xocl driver which uses the reset +can reset a device by using XRT **xrt-smi** utility. This utility talks to xocl driver which uses the reset message as defined in :doc:`mailbox.main` Currently Alveo boards are reset by using PCIe bus *hot reset* mechanism. This resets the board peripherals diff --git a/src/runtime_src/doc/toc/sysfs.rst b/src/runtime_src/doc/toc/sysfs.rst index de94675de79..ecab24be0b8 100644 --- a/src/runtime_src/doc/toc/sysfs.rst +++ b/src/runtime_src/doc/toc/sysfs.rst @@ -17,7 +17,7 @@ xocl The ``xocl`` driver exposes various sections of the ``xclbin`` image including the ``xclbinuuid`` on ``sysfs``. This makes it very -convenient for tools (such as ``xbutil``) to discover characteristics +convenient for tools (such as ``xrt-smi``) to discover characteristics of the image currently loaded on the FPGA. The data layout of ``xclbin`` sections are defined in file ``xclbin.h`` which can be found under ``runtime/core/include`` directory. Platform drivers XDMA, ICAP, @@ -401,7 +401,7 @@ xclmgmt The ``xclmgmt`` driver exposes various sections of the ``xclbin`` image including the ``xclbinuuid`` on ``sysfs``. This makes it very -convenient for tools (such as ``xbutil``) to discover characteristics +convenient for tools (such as ``xrt-smi``) to discover characteristics of the image currently loaded on the FPGA. The data layout of ``xclbin`` sections are defined in file ``xclbin.h`` which can be found under ``runtime/core/include`` directory. Platform drivers ICAP, FPGA Manager, @@ -856,7 +856,7 @@ zocl Similar to PCIe drivers ``zocl`` driver used in embedded platforms exposes various sections of the ``xclbin`` image including the ``xclbinuuid`` on ``sysfs``. This makes it very -convenient for tools (such as ``xbutil``) to discover characteristics +convenient for tools (such as ``xrt-smi``) to discover characteristics of the image currently loaded on the FPGA. The data layout of ``xclbin`` sections are defined in file ``xclbin.h`` which can be found under ``runtime/core/include`` directory. diff --git a/src/runtime_src/doc/toc/xball.rst b/src/runtime_src/doc/toc/xball.rst index c5e511bd810..ae20d022112 100644 --- a/src/runtime_src/doc/toc/xball.rst +++ b/src/runtime_src/doc/toc/xball.rst @@ -7,21 +7,21 @@ xball ===== -To facilitate running the same ``xbutil`` or ``xbmgmt`` command on a multi-card environment XRT provides a utility script named ``xball``. The script ``xball`` can be used as below: +To facilitate running the same ``xrt-smi`` or ``xbmgmt`` command on a multi-card environment XRT provides a utility script named ``xball``. The script ``xball`` can be used as below: .. code-block:: shell - #xball - xball xbutil examine + #xball + xball xrt-smi examine -The ``xball`` script will detect all the cards attached to the server, and execute the ``xbutil`` or ``xbmgmt`` command on all of them. +The ``xball`` script will detect all the cards attached to the server, and execute the ``xrt-smi`` or ``xbmgmt`` command on all of them. Additionally, the ``xball`` script provides a filtering option to execute the command on some specific cards, such as .. code-block:: shell - #Run `xbutil examine` command only on U30 cards - xball --device-filter 'u30' xbutil examine + #Run `xrt-smi examine` command only on U30 cards + xball --device-filter 'u30' xrt-smi examine - #Run `xbutil examine` command only on U250 cards - xball --device-filter '^xilinx_u250' xbutil examine + #Run `xrt-smi examine` command only on U250 cards + xball --device-filter '^xilinx_u250' xrt-smi examine diff --git a/src/runtime_src/doc/toc/xbtools_map.rst b/src/runtime_src/doc/toc/xbtools_map.rst index bb8b19f40d4..50b9d3b4282 100644 --- a/src/runtime_src/doc/toc/xbtools_map.rst +++ b/src/runtime_src/doc/toc/xbtools_map.rst @@ -7,15 +7,15 @@ Utility Migration Guide *********************** -This document maps the legacy ``xbutil``/``xbmgmt`` commands to the new ``xbutil``/``xbmgmt`` commands. It lists out the new ``xbutil``/``xbmgmt`` calls that replace the existing calls. A few points: +This document maps the legacy ``xbutil``/``xbmgmt`` commands to the new ``xrt-smi``/``xbmgmt`` commands. It lists out the new ``xrt-smi``/``xbmgmt`` calls that replace the existing calls. A few points: 1) The new utilities are complete redesign and architecture, hence there may not be exact 1-to-1 mapping. 2) The help menus (``--help``) of these new utilities have also been improved and are highly descriptive with regards to both the commands and options. Please refer to them as needed. 3) The new command opions have both short and long format, for example ``-d`` or ``--device``. In the table below, only the longer option format is used. -You may refer the documentation of the new tools in the following links :doc:`xbutil` and :doc:`xbmgmt` . +You may refer the documentation of the new tools in the following links :doc:`xrt-smi` and :doc:`xbmgmt` . -xbutil +xrt-smi ~~~~~~ +------------+-------------+-------------------+----------------------+ @@ -223,20 +223,20 @@ There were two variants of legacy commands .. code-block:: shell - xbutil query + xrt-smi query or .. code-block:: shell - xbutil dump + xrt-smi dump **New command** .. code-block:: shell - xbutil examine --device 0000:b3:00.1 --report all + xrt-smi examine --device 0000:b3:00.1 --report all **2. Validate the card** @@ -244,13 +244,13 @@ or .. code-block:: shell - xbutil validate + xrt-smi validate **New command** .. code-block:: shell - xbutil validate --device 0000:b3:00.1 + xrt-smi validate --device 0000:b3:00.1 **3. Obtaining platform information such as SC version, flashed partition(s) running on the card, etc.** @@ -295,12 +295,12 @@ or when a specific partition to choose .. code-block:: shell - xbutil --reset + xrt-smi --reset **New command** .. code-block:: shell - xbutil --reset --device 0000:d8:00.1 + xrt-smi --reset --device 0000:d8:00.1 diff --git a/src/runtime_src/doc/toc/xbutil.rst b/src/runtime_src/doc/toc/xrt-smi.rst similarity index 69% rename from src/runtime_src/doc/toc/xbutil.rst rename to src/runtime_src/doc/toc/xrt-smi.rst index f6bc9bf899d..19e62d102a1 100644 --- a/src/runtime_src/doc/toc/xbutil.rst +++ b/src/runtime_src/doc/toc/xrt-smi.rst @@ -6,13 +6,16 @@ comment:: Copyright (C) 2022 Advanced Micro Devices, Inc. All rights reserved. -xbutil +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 ``xbutil`` commands. These latest commands are default from 21.1 release. +This document describes the latest ``xrt-smi`` commands. These latest commands are default from 21.1 release. -For an instructive video on xbutil commands listed below click `here `_. +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. @@ -23,28 +26,28 @@ For an instructive video on xbutil commands listed below click `here `_. +The ``xrt-smi program`` command downloads a specified xclbin binary to the programmable region on the card `