Xilinx Runtime

https://github.com/xilinx/xrt
Admin
Xilinx Runtime (XRT) is a unified software platform providing APIs, drivers, and tools for...
Tokens:545,553
Snippets:3,712
Trust Score:9.3
Update:6 days ago
Show doc for...
Tokens:
Raw
### xbmgmt reset example with --device

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xbmgmt.rst

Example command that resets the device with management BDF 0000:65:00.0.

```shell
xbmgmt reset --device 0000:65:00.0
```

--------------------------------

### Example commands for xbmgmt program

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xbmgmt.rst

Example commands for programming base, shell, and reverting to golden. The first two examples program the base partition (with and without --image), the third programs the shell partition, and the last reverts to golden.

```shell
#Program the base partition
xbmgmt program --device 0000:d8:00.0 --base


#Program the base partition
xbmgmt program --device 0000:d8:00.0 --base --image xilinx-u250-gen3x16-base

#Program the shell partition
xbmgmt program --device 0000:d8:00.0 --shell <partition file with path>

xbmgmt program --device 0000:d8:00.0 --revert-to-golden
```

--------------------------------

### xbmgmt examine example commands

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xbmgmt.rst

Two example commands: one reports all information for a specific device, and the other reports platform information in JSON format to an output file.

```shell
#Report all the information for a specific device
xbmgmt examine --device 0000:d8:00.0 --report all

#Reports platform information in JSON format
xbmgmt examine --device 0000:b3:00.0 --report platform --format JSON --output output.json
```

--------------------------------

### xrt-smi configure example commands

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xrt-smi-alveo.rst

Example commands for enabling/disabling host-memory and P2P using xrt-smi configure. Requires sudo.

```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 configure example commands

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xrt-smi-npu.rst

Example commands for the configure subcommand: setting the power mode to performance and restoring the default power mode.

```shell
# Set the power mode to performance
xrt-smi configure --pmode performance

# Restore the default power mode
xrt-smi configure --pmode default
```

--------------------------------

### Install EPEL on RHEL 10.x

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/install.rst

Enable the CodeReady Builder repository and install EPEL release for RHEL 10.x.

```none
sudo subscription-manager repos --enable "codeready-builder-for-rhel-10-x86_64-rpms"
sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-10.noarch.rpm
```

--------------------------------

### Install EPEL on RHEL 9.x

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/install.rst

Enable the CodeReady Builder repository and install EPEL release for RHEL 9.x.

```none
sudo subscription-manager repos --enable "codeready-builder-for-rhel-9-x86_64-rpms"
sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
```

--------------------------------

### Install xrt-npu package

Source: https://github.com/xilinx/xrt/blob/master/build/arch/README.md

Install the built xrt-npu package using pacman.

```bash
sudo pacman -U ./xrt-npu-[0-9]*-x86_64.pkg.tar.zst
```

--------------------------------

### Example commands for xbflash2 program --qspips

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xbflash2.rst

Example commands showing how to program the boot.bin image and erase flash on the device. The first two commands program the image, with the second specifying offset and bar options. The third command erases flash using the --spi option.

```shell
#Program the boot.bin image.
xbflash2 program --qspips --device 0000:3b:00.0 --image <boot.bin path>

#Program the boot.bin image.
xbflash2 program --qspips --device 0000:3b:00.0 --image <boot.bin path> --offset 0x0 --bar-offset 0x10000 --bar 0

#Erase flash on the device
xbflash2 program --spi --device 0000:d8:00.0 --erase --length 0x06000000 --offset 0x0 --bar 0 --bar-offset 0x40000
```

--------------------------------

### Build and install xrt-base and xrt-npu packages

Source: https://github.com/xilinx/xrt/blob/master/build/arch/README.md

Build the xrt-base package, install it as a required dependency, then build the xrt-npu package.

```bash
# Build xrt-base package
makepkg -p PKGBUILD-xrt-base

# Install xrt-base first (required dependency)
sudo pacman -U ./xrt-base-[0-9]*-x86_64.pkg.tar.zst

# Build xrt-npu package
makepkg -p PKGBUILD-xrt-npu
```

--------------------------------

### Install XRT on Ubuntu

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/install.rst

Install the XRT DEB package using apt.

```none
sudo apt install xrt_<version>.deb
```

--------------------------------

### Install build dependencies

Source: https://github.com/xilinx/xrt/blob/master/build/arch/README.md

Run from the build/arch directory to install required dependencies for building XRT.

```bash
cd ../..
sudo ./src/runtime_src/tools/scripts/xrtdeps.sh
```

--------------------------------

### xrt-smi program example command

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xrt-smi-alveo.rst

Example command that programs the device at BDF 0000:b3:00.1 with the xclbin file ./my_kernel.xclbin.

```shell
xrt-smi program --device 0000:b3:00.1 --user ./my_kernel.xclbin
```

--------------------------------

### xrt::run::start()

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xrt_native_apis.rst

Starts the next kernel execution with new argument(s).

```APIDOC
## xrt::run::start()

### Description
Starts the next kernel execution with new argument(s).

### Method
C++ member function

### Signature
`void start()`

### Example
```c++
runt.start();
```
```

--------------------------------

### Example xrt-smi validate commands

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xrt-smi-alveo.rst

Provides four example commands: running all tests, running the DMA test, running DMA and Verify Kernel tests with JSON output, and passing a custom block size to the DMA test.

```shell
# Run all the tests
xrt-smi validate --device 0000:b3:00.1
```

```shell
# Run "DMA" test, produce text output in stdout
xrt-smi validate --device 0000:b3:00.1 --run DMA
```

```shell
# 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
```

```shell
# Pass in a custom block size to dma test
xrt-smi validate --device 0000:b3:00.1 --run DMA --param dma:block-size:1024
```

--------------------------------

### Example: xbflash2 dump --qspips command

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xbflash2.rst

Example command that dumps content from a QSPIPS flash to a file, specifying device, offset, length, BAR offset, BAR index, and output file.

```shell
#Dump out content to the given ouput file
xbflash2 dump --qspips --device 0000:3b:00.0 --offset 0x0 --length 0x08000000 --bar-offset 0x10000 --bar 0 --output /tmp/flash_dump.txt
```

--------------------------------

### Recipe execution section with runs, sub-buffers, and constants

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/core/common/runner/recipe.md

These JSON examples show how to define the 'execution' section of a recipe. The first example demonstrates multiple runs with CPU functions, buffer sub-slicing via 'size' and 'offset', and string constants; the second shows a kernel run with integer constants, including setting argidx 0 to '3' for a transaction buffer opcode.

```json
  "execution": {
    "runs": [
      {
        "kernel": "convert_ifm",
        "where": "cpu",
        "arguments" : [
            { "name": "ifm", "argidx": 0 },
            { "name": "ifm_int", "argidx": 1 }
         ],
         "constants" : [
            { "value": "nchw2nchw4c", "type": "string", "argidx": 2 }
         ]
        ]
      },
      {
        "kernel": "k1",
        "arguments" : [
            { "name": "ifm_int", "size": 512, "offset": 0, "argidx": 3 },
            { "name": "wts", "argidx": 4 },
            { "name": "ofm_int", "size": 512, "offset": 512, "argidx": 5 }
        ]
      },
      {
        "kernel": "k1",
        "arguments" : [
            { "name": "ifm_int", "size": 512, "offset": 512, "argidx": 3 },
            { "name": "wts", "argidx": 4 },
            { "name": "ofm_int", "size": 512, "offset": 0, "argidx": 5 }
        ]
      },
      {
        "kernel": "convert_ofm",
        "where": "cpu",
        "arguments" : [
            { "name": "ofm_int", "argidx": 0 },
            { "name": "ofm", "argidx": 1 }
         ],
         "constants" : [
            { "value": "nchw4c2nchw", "argidx": 2 }
         ]
        ]
      },
      ...
    ]
  }
```

```json
  "execution": {
    "runs": [
      {
        "kernel": "k1",
        "arguments" : [
            { "name": "wts", "argidx": 4 },
            { "name": "ifm", "argidx": 3 },
            { "name": "ofm", "argidx": 5 }
        ],
        "constants" : [
            { "value": "3", "type": "int", "argidx": 0 },
            { "value": "0", "type": "int", "argidx": 1 },
            { "value": "0", "type": "int", "argidx": 2 },
            { "value": "0", "type": "int", "argidx": 6 },
            { "value": "0", "type": "int", "argidx": 7 }
        ]
      }
    ]
  }
```

--------------------------------

### Example commands for xbflash2 program --spi

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xbflash2.rst

Example commands demonstrating programming an MCS image, specifying BAR index and offset, dual-flash programming, and reverting to golden image.

```shell
#Program the mcs image.
xbflash2 program --spi --device 0000:3b:00.0 --image <mcs path>
```

```shell
#Program the mcs image.
xbflash2 program --spi --device 0000:3b:00.0 --image <mcs path> --bar 0 --bar-offset 0x10000
```

```shell
#Program the image for dual-flash type.
xbflash2 program --spi --device 0000:5e:00.1 --image <primary.mcs path> --image <secondary.mcs path> --bar 0 --bar-offset 0x40000 --dual-flash
```

```shell
#Revert to golden image
xbflash2 program --spi --device 0000:d8:00.0 --revert-to-golden --bar 0 --bar-offset 0x40000 --dual-flash
```

--------------------------------

### xrt-smi examine example commands

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xrt-smi-npu.rst

Example commands for the examine subcommand: showing the host report, reporting the platform summary, and dumping multiple reports in JSON format.

```shell
# Shows the host report
xrt-smi examine

# Reports the platform summary in the stdout
xrt-smi examine --report platform

# Reports "platform" and "aie-partitions" and dump in json format
xrt-smi examine --report platform aie-partitions --format JSON --output n.json
```

--------------------------------

### Install EPEL on AlmaLinux 9.x/Rocky 9.x

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/install.rst

Enable the CRB repository and install EPEL release for AlmaLinux 9.x or Rocky 9.x.

```none
sudo dnf config-manager --set-enabled crb
sudo dnf install epel-release
```

--------------------------------

### Build XRT documentation with Sphinx

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/build.rst

Run these commands to compile and install the documentation into the 'doc' directory at the top of the repository. The second command opens the generated local documentation in a web browser.

```none
cd build
./build.sh docs
# To browse the generated local documentation with a web browser:
xdg-open Release/runtime_src/doc/html/index.html
```

--------------------------------

### Basic xrt.ini example enabling timeline trace and console logging

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xrt_ini.rst

A simple xrt.ini file that turns on profile timeline trace in the Debug group and sends runtime log messages to the console in the Runtime group. Comments start with #.

```ini
#Start of Runtime group
[Runtime]
runtime_log = console

#Start of Debug group
[Debug]
timeline_trace = true
```

--------------------------------

### xrt-smi examine example commands

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xrt-smi-alveo.rst

Example commands for using xrt-smi examine: showing host report, reporting electrical information, and dumping multiple reports in JSON format.

```shell
# Shows ``xrt-smi examine --host``
xrt-smi examine
```

```shell
# Reports electrical information in the stdout
xrt-smi examine --device 0000:b3:00.1 --report electrical
```

```shell
# 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
```

--------------------------------

### xbmgmt dump example commands and .ini file contents

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xbmgmt.rst

Example commands for dumping programmed system image data and system configuration. The .ini file can be edited and used as input for xbmgmt configure. Only edit the throttling_enabled, throttling_power_override, and throttling_temp_override values when editing clock throttling settings.

```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
```

--------------------------------

### Start AI Engine profiling with xrt::aie::profiling::start()

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xrt_native_apis.rst

Configures and starts performance counters in the AI Engine based on the profiling option and port names. The value parameter's meaning depends on the profiling_option. After starting, run the graph and wait for completion before reading results.

```c
     auto graph = xrt::graph(device, xclbin_uuid, "graph_name");
     std::string port1_name = "...";  // PLIO/GMIO port per UG1079
     std::string port2_name = "...";  // PLIO/GMIO port per UG1079
     uint32_t value = 0;               // meaning depends on profiling_option
     event.start(
         xrt::aie::profiling::profiling_option::io_total_stream_running_to_idle_cycles,
         port1_name, port2_name, value);

     // run graph
     ...
     s2mm_run.wait();
```

--------------------------------

### Compile the IOPS test with make

Source: https://github.com/xilinx/xrt/blob/master/tests/xrt/perf_IOPS/README.md

Source setup.sh after installing the XRT package, then run make to build the test.

```bash
$ make
```

--------------------------------

### xrt-smi reset example command

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xrt-smi-alveo.rst

Example command that resets the device with BDF 0000:65:00.1 using the default reset type 'hot'.

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

--------------------------------

### clCreateBuffer with CL_MEM_EXT_PTR_XILINX - P2P Buffer

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/opencl_extension.rst

Example of creating a P2P buffer using the cl_mem_ext_ptr_t structure with the XCL_MEM_EXT_P2P_BUFFER flag.

```APIDOC
## clCreateBuffer with CL_MEM_EXT_PTR_XILINX - P2P Buffer

### Description
Creates a P2P buffer using the Xilinx OpenCL extension. The buffer is specified as a special P2P buffer using the `cl_mem_ext_ptr_t` structure with the `XCL_MEM_EXT_P2P_BUFFER` flag.

### Method
clCreateBuffer

### Parameters
- **context** (cl_context) - Required - The OpenCL context.
- **flags** (cl_mem_flags) - Required - Must include `CL_MEM_READ_ONLY` and `CL_MEM_EXT_PTR_XILINX`.
- **size** (size_t) - Required - Size of the buffer in bytes.
- **host_ptr** (void*) - Required - Pointer to a `cl_mem_ext_ptr_t` structure with `flags` set to `XCL_MEM_EXT_P2P_BUFFER`.
- **errcode_ret** (cl_int*) - Optional - Returns error code.

### Request Example
```c++
cl_mem_ext_ptr_t p2p_buf_ext = {0};
p2p_buf_ext.flags = XCL_MEM_EXT_P2P_BUFFER;

cl_mem p2p_buf = clCreateBuffer(context, CL_MEM_READ_ONLY | CL_MEM_EXT_PTR_XILINX, buffersize, &p2p_buf_ext, &err);
```

### Response
#### Success Response
- **cl_mem** - The created buffer object.

#### Error Codes
- **CL_INVALID_CONTEXT** - If context is not a valid context.
- **CL_INVALID_VALUE** - If flags are invalid or host_ptr is NULL.
- **CL_INVALID_BUFFER_SIZE** - If size is 0 or exceeds device limits.
- **CL_MEM_OBJECT_ALLOCATION_FAILURE** - If memory allocation fails.
```

--------------------------------

### Build host executable with make host.exe

Source: https://github.com/xilinx/xrt/blob/master/tests/unit_test/subdevice/readme.txt

Builds the host executable using the XILINX_XRT environment variable pointing to the XRT installation. The command is run from the test directory.

```bash
% env XILINX_XRT=/opt/xilin/xrt make host.exe
```

--------------------------------

### Install XRT build dependencies with xrtdeps.sh

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/build.rst

Run this command to install the standard distribution packages for tools and libraries XRT depends on. If system libraries like Boost are updated to non-standard versions, XRT must be rebuilt.

```none
sudo <XRT>/src/runtime_src/tools/scripts/xrtdeps.sh
```

--------------------------------

### xrt::aie::profiling::start()

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xrt_native_apis.rst

Starts performance counters in the AI Engine according to the specified profiling option. Configures the counters and begins profiling.

```APIDOC
## xrt::aie::profiling::start()

### Description
Starts performance counters in the AI Engine based on the profiling option passed as an argument. This configures the counters and begins profiling.

### Method
Member function

### Parameters
- **profiling_option** (xrt::aie::profiling::profiling_option) - Required - The profiling option to configure, e.g., `io_total_stream_running_to_idle_cycles`.
- **port1_name** (std::string) - Required - PLIO/GMIO port name per UG1079.
- **port2_name** (std::string) - Required - PLIO/GMIO port name per UG1079.
- **value** (uint32_t) - Required - Meaning depends on the profiling option.

### Request Example
```c
auto graph = xrt::graph(device, xclbin_uuid, "graph_name");
std::string port1_name = "...";  // PLIO/GMIO port per UG1079
std::string port2_name = "...";  // PLIO/GMIO port per UG1079
uint32_t value = 0;               // meaning depends on profiling_option
event.start(
    xrt::aie::profiling::profiling_option::io_total_stream_running_to_idle_cycles,
    port1_name, port2_name, value);
```

### Response
No return value.
```

--------------------------------

### cl::Buffer with CL_MEM_EXT_PTR_XILINX - Host Only Buffer

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/opencl_extension.rst

Example of creating a host-only buffer using the cl_mem_ext_ptr_t structure with the XCL_MEM_EXT_HOST_ONLY flag.

```APIDOC
## cl::Buffer with CL_MEM_EXT_PTR_XILINX - Host Only Buffer

### Description
Creates a host-only buffer using the Xilinx OpenCL extension. The buffer is specified as a special host-only buffer using the `cl_mem_ext_ptr_t` structure with the `XCL_MEM_EXT_HOST_ONLY` flag.

### Method
cl::Buffer constructor

### Parameters
- **context** (cl::Context) - Required - The OpenCL context.
- **flags** (cl_mem_flags) - Required - Must include `CL_MEM_READ_ONLY` and `CL_MEM_EXT_PTR_XILINX`.
- **size** (size_t) - Required - Size of the buffer in bytes.
- **host_ptr** (void*) - Required - Pointer to a `cl_mem_ext_ptr_t` structure with `flags` set to `XCL_MEM_EXT_HOST_ONLY`.

### Request Example
```c++
cl_mem_ext_ptr_t host_buffer_ext = {0};
host_buffer_ext.flags = XCL_MEM_EXT_HOST_ONLY;

cl::Buffer host_buffer (context, CL_MEM_READ_ONLY | CL_MEM_EXT_PTR_XILINX, size, &host_buffer_ext);
```

### Response
#### Success Response
- **cl::Buffer** - The created buffer object.
```

--------------------------------

### Program the Base partition with --image for multiple base partitions

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xbmgmt.rst

Syntax for programming the base partition when multiple base partitions are installed. The --image option specifies the desired partition name.

```shell
xbmgmt program [--device|-d] <management bdf> [--base|-b] [--image|-i] <partition name>
```

--------------------------------

### clCreateBuffer with CL_MEM_EXT_PTR_XILINX - Kernel Argument Index

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/opencl_extension.rst

Example of specifying a buffer location by kernel name and argument index using the cl_mem_ext_ptr_t structure.

```APIDOC
## clCreateBuffer with CL_MEM_EXT_PTR_XILINX - Kernel Argument Index

### Description
Creates a buffer with a memory bank location determined by the kernel argument index. The kernel handle and argument index are used to detect the memory bank.

### Method
clCreateBuffer

### Parameters
- **context** (cl_context) - Required - The OpenCL context.
- **flags** (cl_mem_flags) - Required - Must include `CL_MEM_EXT_PTR_XILINX`.
- **size** (size_t) - Required - Size of the buffer in bytes.
- **host_ptr** (void*) - Required - Pointer to a `cl_mem_ext_ptr_t` structure with `argidx` set to the argument index and `kernel` set to the kernel handle.
- **errcode_ret** (cl_int*) - Optional - Returns error code.

### Request Example
```c++
ext.argidx = idx;
ext.kernel = kernel;
cl_int error;
clCreateBuffer(context, CL_MEM_EXT_PTR_XILINX, size, &ext, &error);
```

### Response
#### Success Response
- **cl_mem** - The created buffer object.

#### Error Codes
- **CL_INVALID_CONTEXT** - If context is not a valid context.
- **CL_INVALID_VALUE** - If flags are invalid or host_ptr is NULL.
- **CL_INVALID_BUFFER_SIZE** - If size is 0 or exceeds device limits.
- **CL_MEM_OBJECT_ALLOCATION_FAILURE** - If memory allocation fails.
```

--------------------------------

### Build GTest from Source on Older Ubuntu

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/test.rst

Install GTest from source on Ubuntu up to 18.04, where the package provides source only. Creates symlinks in /usr/lib for the compiled static libraries.

```none
cd /usr/src/gtest
sudo cmake CMakeLists.txt
sudo make
cd /usr/lib
sudo ln -s /usr/src/gtest/libgtest.a
sudo ln -s /usr/src/gtest/libgtest_main.a
# Validate:
ls *gtest*
```

--------------------------------

### Get information from xclbin file

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xclbintools.rst

Use the -i option to obtain information from an xclbin file. Optionally specify an output file with --info; if omitted, output goes to the console.

```none
xclbinutil -i binary_container_1.xclbin [--info=<FILE_NAME>]
```

--------------------------------

### Create a sub-buffer from a parent buffer using xrt::bo constructor

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xrt_native_apis.rst

Allocates a sub-buffer from a parent buffer by specifying a start offset and size. The example creates a sub-buffer of size 4 bytes starting at offset 0.

```c++
     size_t sub_buffer_size = 4;
     size_t sub_buffer_offset = 0;

     auto sub_buffer = xrt::bo(parent_buffer, sub_buffer_size, sub_buffer_offset);
```

--------------------------------

### Program the Base partition (1RP and 2RP)

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xbmgmt.rst

Syntax for programming the base partition, applicable for both 1RP and 2RP platforms. The --base option only works if exactly one base partition package is installed; otherwise --image is required.

```shell
xbmgmt program [--device|-d] <management bdf> [--base|-b]
```

--------------------------------

### Thread 2 C++ code for two-threaded replay example

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/core/common/runner/replay.md

Shows Thread 2's sequence of start and wait calls for frame 1.

```cpp
run2.start();     // Frame 1, Thread 2
run2.wait();
```

--------------------------------

### List CPU functions in recipe resources

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/core/common/runner/recipe.md

Defines CPU functions to be executed on the host. Each entry specifies a name and a library_path relative to the XRT install location (or inferred on Windows as the driver store). The library is loaded via dlopen.

```json
  "resources": {
    "cpus": [
      {
        "name": "convert_ifm",
        "library_path": "umd/convert.dll"
      },
      {
        "name": "convert_ofm",
        "library_path": "umd/convert.dll"
      },
      {
        "name": "average_pool",
        "library_path": "umd/operators.dll"
      }
    ]
  },
```

--------------------------------

### Thread 1 C++ code for two-threaded replay example

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/core/common/runner/replay.md

Shows Thread 1's sequence of start and wait calls for frames 0 and 2.

```cpp
run1.start();     // Frame 0, Thread 1
run1.wait();
run3.start();     // Frame 2, Thread 1
run3.wait();
```

--------------------------------

### pkgdsa.sh usage example

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/tools/scripts/README.md

Generates a deb/rpm package for a XSA. Requires a development platform directory containing .xpfm, hw/, and sw/. The -dsa flag specifies the name, -dsadir the platform path, and -pkgdir the output directory.

```bash
$ pkgdsa.sh -dsa <name> -dsadir <path/to/platform> -pkgdir ./pkgdsa
```

--------------------------------

### Create Buffer from User Pointer with xrt::bo

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xrt_native_apis.rst

Allocates a buffer from a user-provided host pointer aligned to 4K boundary. The example allocates memory with posix_memalign, fills it, and creates the buffer with xrt::bo.

```c++
     // Host Memory pointer aligned to 4K boundary
     int *host_ptr;
     posix_memalign(&host_ptr,4096,MAX_LENGTH*sizeof(int));

     // Simple example: fill the allocated host memory
     for(int i=0; i<MAX_LENGTH; i++) {
       host_ptr[i] = i;  // whatever
     }

     auto mybuf = xrt::bo (device, host_ptr, MAX_LENGTH*sizeof(int), kernel.group_id(3));
```

--------------------------------

### Asynchronous GMIO/External Buffer Transfer with xrt::aie::buffer::async and wait

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xrt_native_apis.rst

Same scenario as the synchronous example but uses xrt::aie::buffer::async() to start transfers and xrt::aie::buffer::wait() to block until completion. Useful when overlapping transfers with graph execution.

```c++
   auto device = xrt::aie::device(0);
   auto uuid = device.load_xclbin("kernel.xclbin");

   // Create buffer in DDR / global memory and prepare input
   auto in_bo  = xrt::aie::bo (device, SIZE * sizeof (float), 0, 0);
   auto inp_bo_map = in_bo.map<float *>();
   std::copy(my_float_array,my_float_array+SIZE,inp_bo_map);

   // Create buffer in DDR / global memory for output
   auto out_bo  = xrt::aie::bo (device, SIZE * sizeof (float), 0, 0);
   auto out_bo_map = out_bo.map<float *>();

   // GMIO / external buffer for input
   auto in_buffer = xrt::aie::buffer(device, uuid, "gr.in1");
   in_buffer.async(in_bo, XCL_BO_SYNC_BO_GMIO_TO_AIE, SIZE * sizeof(float),0);

   // Run graphs that use the output GMIO / external buffer

   // GMIO / external buffer for output
   auto out_buffer  = xrt::aie::buffer(device, uuid, "gr.out1");
   out_buffer.async(out_bo, XCL_BO_SYNC_BO_AIE_TO_GMIO, SIZE * sizeof(float),0);
   out_buffer.wait();
```

--------------------------------

### Install XRT on RHEL/CentOS

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/install.rst

Install the XRT RPM package using yum.

```none
sudo yum install xrt_<version>.rpm
```

--------------------------------

### Build and run 100_ert_ncu test

Source: https://github.com/xilinx/xrt/blob/master/tests/xrt/100_ert_ncu/readme.txt

Commands to build the executables, build the xclbin, and run the test. The build script is invoked via [run.sh] and the executables are placed under <path>/XRT/tests/xrt/build/<OS>/Debug/100_ert_ncu. The xclbin is built with make -f xclbin.mk and the test is run with xrt.exe using -jobs 32 -seconds 1 cus 8.

```bash
# build executables
# [run.sh] <path>/XRT/tests/xrt/build.sh
# The execs are located under
# <path>/XRT/tests/xrt/build/<OS>/Debug/100_ert_ncu
```

```bash
# build xclbin
% pwd
<here>
% [run.sh] make -f xclbin.mk DSA=... MODE=... xclbin
```

```bash
# run
% [run.sh] xrt.exe -k kernel.hw.xclbin -jobs 32 -seconds 1 cus 8
```

--------------------------------

### Run 00_hello commands

Source: https://github.com/xilinx/xrt/blob/master/tests/python/README.md

Commands to build and run the 00_hello test, including copying the kernel.xclbin and executing main.py.

```bash
./build.sh <br/>
cd XRT/tests/python/00_hello <br/>
cp kernel.xclbin . <br/>
python main.py -k kernel.xclbin
```

--------------------------------

### Install XRT and zocl on target embedded system using dnf

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/yocto.rst

Run these commands on the target embedded system to install XRT 2020.1 PU1 for ZCU104. It sets up the dnf repository, cleans the local cache, and installs the xrt and zocl packages.

```bash
# Execute the following scripts on target embedded system
# Install dnf repository description
cd /etc/yum.repos.d
wget http://petalinux.xilinx.com/sswreleases/rel-v2020/generic/rpm/repos/zynqmp-generic_ev.repo
wget http://petalinux.xilinx.com/sswreleases/rel-v2020/generic-updates/rpm/repos/zynqmp-generic_ev-update.repo
# Clean dnf local cache
dnf clean all
# Install XRT and zocl
dnf install xrt
dnf install zocl
```

--------------------------------

### Create PetaLinux Project with XRT

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/yocto.rst

Commands to create a PetaLinux project, configure hardware, kernel, rootfs, and build the image. Includes enabling XRT, zocl, and OpenCL headers in rootfs.

```bash
# Replace <name> in below commands
$ petalinux-create -t project -n <name> --template zynqMP

# Get XSA file, which is exported by Vivado
# A menu will show up for configuration, use below config to avoid password for login.
#       menu -> "Yocto Setting" -> "Enable Debug Tweaks"
$ petalinux-config -p <name> --get-hw-description=<XSA>

#Now we can configure Linux kernel and rootfs.

#Configure Linux kernel (default kernel config is good for zocl driver)
$ petalinux-config -c kernel

# Configure rootfs, enable below components:

#   menu -> "user packages" -> xrt
#   menu -> "user packages" -> xrt-dev
#   menu -> "user packages" -> zocl
#   menu -> "user packages" -> opencl-headers-dev
#   menu -> "user packages" -> opencl-clhpp-dev
$ petalinux-config -c rootfs

# Enable "xrt" and "xrt-dev" options will install XRT libraries and header files to /opt/xilinx/xrt directory in rootfs. Enable "zocl" option will install zocl.ko in rootfs. The zocl.ko driver is a XRT driver module only for MPSoC platform.


# Build package
$ petalinux-build
```

--------------------------------

### Enable P2P with xrt-smi configure

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/p2p.rst

Command to enable P2P on a device. Requires root privileges. May require a warm reboot if the PCIe BAR cannot be resized without one.

```none
# sudo xrt-smi configure --device 0000:b3:00.1 --p2p enable
```

--------------------------------

### Load ELF and Create Hardware Context

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xrt_native_apis.rst

Opens device 0, loads 'config.elf' into host memory, and creates a hardware context on the device. This is the simplest way to load a compiled kernel binary.

```c++
     unsigned int dev_index = 0;
     auto device = xrt::device(dev_index);
     xrt::elf elf{"config.elf"};
     auto hwctx = xrt::hw_context(device, elf);
```

--------------------------------

### xrt-smi validate example commands

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xrt-smi-npu.rst

Example commands for the validate subcommand: running all tests, running the latency test, and running latency and throughput tests with JSON output.

```shell
# Run all the tests
xrt-smi validate

# Run "latency" test, produce text output in stdout
xrt-smi validate --run latency

# Run "latency" and "throughput" test and generate Json format
xrt-smi validate --run latency throughput --format JSON --output xyz.json
```

--------------------------------

### Replay options help

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/core/common/runner/replay.md

Shows the command-line options for xrt-runner replay, including required and optional parameters.

```text
xrt-runner --replay <replay.json> [options]

Options:
  --replay <replay.json> Replay script to execute (required)
  [--dir <path>]         Directory containing artifacts (default: current directory)
  [--iterations <num>]   Number of iterations to execute (default: from replay.json)
  [--report <file>]      Output metrics to file (use "-" for stdout)

  [--help, -h]           Show help message
```

--------------------------------

### Run host.exe with addone.xclbin

Source: https://github.com/xilinx/xrt/blob/master/tests/unit_test/subdevice/readme.txt

Executes the host program with the generated xclbin file. The command is shown as a run script.

```bash
% [run.sh] ./host.exe addone.xclbin
```

--------------------------------

### Configure MSD/MPD services for SW mailbox

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/cloud_vendor_support.rst

Commands to configure and start MSD/MPD services for SW mailbox. Includes checking and setting the host IP, starting services, and enabling them for reboot persistence.

```bash
# In host, make sure the IP address configured is the one VM talks to
Host>$ sudo xbmgmt config --show

# If the IP address is not correct, change it by running
Host>$ sudo xbmgmt config --daemon --host <host-or-ip>

# Start MSD in host
Host>$ sudo systemctl start msd

# Start MPD in VM
VM>$ sudo systemctl start mpd

#Enable these services If you want them to be in active even after reboot
Host>$ sudo systemctl enable msd

VM>$ sudo systemctl enable mpd
```

--------------------------------

### Build xclbin with make MODE=hw DSA=xilinx_vcu1525_dynamic_5_1

Source: https://github.com/xilinx/xrt/blob/master/tests/unit_test/subdevice/readme.txt

Builds the hardware xclbin using the specified DSA (xilinx_vcu1525_dynamic_5_1). Requires XILINX_XRT and XILINX_SDX environment variables.

```bash
% env XILINX_XRT=/opt/xilinx/xrt XILINX_SDX=<TA path> make MODE=hw DSA=xilinx_vcu1525_dynamic_5_1 xclbin
```

--------------------------------

### Clone and Build XRT with build.sh

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/test.rst

Clone the XRT repository, navigate to the build directory, and run the build script to compile XRT for both Debug and Release profiles.

```none
git clone https://github.com/Xilinx/XRT.git
cd XRT/build
./build.sh
```

--------------------------------

### Complete run recipe.json for NPU with no internal buffers

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/core/common/runner/recipe.md

Validated on NPU with no internal buffers; external inputs and output are consumed in one kernel execution. Reference `runner/test/recipe.json` for an example using CPU functions. The example defines buffers wts, ifm, ofm and a kernel k1 with an instance named DPU.

```json
{
  "version": "1.0",
  "header": {
    "xclbin": "design.xclbin",
  },
  "resources": {
    "hwctxs": [
      {
        "name": "hwctx1",
        "xclbin": "xclbin"
      }
    ],
    "buffers": [
      {
        "name": "wts",
        "type": "input"
      },
      {
        "name": "ifm",
        "type": "input"
      },
      {
        "name": "ofm",
        "type": "output"
      }
    ],
    "kernels": [
      {
        "name": "k1",
        "instance": "DPU",
        "hwctx": "hwctx1",
        "ctrlcode": "no-ctrl-packet.elf"
      }
    ]
  },
  "execution": {
    "runs": [
      {
        "kernel": "k1",
        "arguments" : [
            { "name": "wts", "argidx": 4 },
            { "name": "ifm", "argidx": 3 },
            { "name": "ofm", "argidx": 5 }
         ],
         "constants": [
            { "value": "3", "type": "int", "argidx": 0 },
            { "value": "0", "type": "int", "argidx": 1 },
            { "value": "0", "type": "int", "argidx": 2 },
            { "value": "0", "type": "int", "argidx": 6 },
            { "value": "0", "type": "int", "argidx": 7 }
        ]
      }
    ]
  }
}

```

--------------------------------

### clGetKernelInfo with CL_KERNEL_INSTANCE_BASE_ADDRESS

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/opencl_extension.rst

XRT-specific parameter extension for clGetKernelInfo to get the base address of a kernel object.

```APIDOC
## clGetKernelInfo with CL_KERNEL_INSTANCE_BASE_ADDRESS

### Description
XRT-specific parameter extension for clGetKernelInfo to get the base address of a kernel object.

### Method
Function call

### Endpoint
clGetKernelInfo

### Parameters
- **kernel** (cl_kernel) - Required - Kernel object
- **param_name** (cl_kernel_info) - Required - Parameter to query. Use CL_KERNEL_INSTANCE_BASE_ADDRESS to get the base address.
- **param_value_size** (size_t) - Required - Size of the output buffer
- **param_value** (void*) - Required - Pointer to store the retrieved value
- **param_value_size_ret** (size_t*) - Optional - Pointer to store the actual size of the retrieved value

### Response
#### Success Response
- **param_value** (size_t) - Base address of the kernel object

### Response Example
```c++
size_t base_addr;
clGetKernelInfo(kernel, CL_KERNEL_INSTANCE_BASE_ADDRESS, sizeof(base_addr), &base_addr, nullptr);
```
```

--------------------------------

### Reinstall XRT on Ubuntu

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/install.rst

Reinstall the XRT DEB package using apt install --reinstall.

```none
sudo apt install --reinstall ./xrt_<version>.deb
```

--------------------------------

### Build host executable

Source: https://github.com/xilinx/xrt/blob/master/tests/unit_test/cuselect/readme.txt

Builds the host executable using the XILINX_XRT environment variable.

```bash
env XILINX_XRT=/opt/xilin/xrt make host.exe
```

--------------------------------

### xrt::run::set_arg()

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/xrt_native_apis.rst

Sets a kernel argument for the next execution. Arguments are specified starting from 0.

```APIDOC
## xrt::run::set_arg()

### Description
Sets a kernel argument for the next execution. Arguments are specified starting from 0.

### Method
C++ member function

### Signature
`void set_arg(int index, const Arg& arg)`

### Parameters
- **index** (int) - Required - The argument index (0-based).
- **arg** (Arg) - Required - The argument value.

### Example
```c++
runt.set_arg(2, scalar_2); // Arguments are specified starting from 0
```
```

--------------------------------

### clGetKernelArgInfo with CL_KERNEL_ARG_OFFSET

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/opencl_extension.rst

XRT-specific parameter extension for clGetKernelArgInfo to get the argument offset for a specific kernel argument.

```APIDOC
## clGetKernelArgInfo with CL_KERNEL_ARG_OFFSET

### Description
XRT-specific parameter extension for clGetKernelArgInfo to get the argument offset for a specific kernel argument.

### Method
Function call

### Endpoint
clGetKernelArgInfo

### Parameters
- **kernel** (cl_kernel) - Required - Kernel object
- **arg_indx** (cl_uint) - Required - Index of the kernel argument
- **param_name** (cl_kernel_arg_info) - Required - Parameter to query. Use CL_KERNEL_ARG_OFFSET to get the argument offset.
- **param_value_size** (size_t) - Required - Size of the output buffer
- **param_value** (void*) - Required - Pointer to store the retrieved value
- **param_value_size_ret** (size_t*) - Optional - Pointer to store the actual size of the retrieved value

### Response
#### Success Response
- **param_value** (size_t) - Argument offset

### Response Example
```c++
size_t foo_offset = 0;
clGetKernelArgInfo(kernel, 2, CL_KERNEL_ARG_OFFSET, sizeof(foo_offset), &foo_offset, nullptr);
```
```

--------------------------------

### clGetKernelInfo with CL_KERNEL_COMPUTE_UNIT_COUNT

Source: https://github.com/xilinx/xrt/blob/master/src/runtime_src/doc/toc/opencl_extension.rst

XRT-specific parameter extension for clGetKernelInfo to get the number of Compute Units from a kernel object.

```APIDOC
## clGetKernelInfo with CL_KERNEL_COMPUTE_UNIT_COUNT

### Description
XRT-specific parameter extension for clGetKernelInfo to get the number of Compute Units from a kernel object.

### Method
Function call

### Endpoint
clGetKernelInfo

### Parameters
- **kernel** (cl_kernel) - Required - Kernel object
- **param_name** (cl_kernel_info) - Required - Parameter to query. Use CL_KERNEL_COMPUTE_UNIT_COUNT to get the number of CUs.
- **param_value_size** (size_t) - Required - Size of the output buffer
- **param_value** (void*) - Required - Pointer to store the retrieved value
- **param_value_size_ret** (size_t*) - Optional - Pointer to store the actual size of the retrieved value

### Response
#### Success Response
- **param_value** (cl_uint) - Number of Compute Units

### Response Example
```c++
cl_uint numcus = 0;
clGetKernelInfo(kernel,CL_KERNEL_COMPUTE_UNIT_COUNT,sizeof(cl_uint),&numcus,nullptr);
```
```
Tokens:
Raw