Vitis Data Center Acceleration Examples

https://github.com/xilinx/vitis_accel_examples
Admin
This repository provides examples showcasing various features of the Vitis tools for Alveo Data...
Tokens:20,779
Snippets:318
Trust Score:9.3
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Example Execution Log

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/performance/kernel_global_bandwidth/README.rst

Sample output showing successful kernel execution and throughput calculation.

```text
./kernel_global ./build_dir.hw.xilinx_u200_xdma_201830_2/krnl_kernel_global.xclbin
Found Platform
Platform Name: Xilinx
Found Device=xilinx_u200_xdma_201830_2
INFO: Reading ./build_dir.hw.xilinx_u200_xdma_201830_2/krnl_kernel_global.xclbin
Loading: './build_dir.hw.xilinx_u200_xdma_201830_2/krnl_kernel_global.xclbin'
Starting kernel to read/write 1024 MB bytes from/to global memory... 
Kernel Duration...66662680 ns
Kernel completed read/write 1024 MB bytes from/to global memory.
Execution time = 0.066663 (sec) 
Concurrent Read and Write Throughput = 30.72 (GB/sec) 
TEST PASSED
```

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

### List Project Files

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/hbm_simple_xrt/README.rst

Displays the source files required for the HBM simple XRT example.

```text
src/host.cpp
src/krnl_vadd.cpp
```

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

### Runtime Throughput Log Output

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/performance/hbm_bandwidth_pseudo_random/details.rst

Example log output showing kernel initialization and measured HBM throughput.

```text
Loading: './build_dir.hw.xilinx_u50_xdma_201920_1/krnl_vaddmul.xclbin'
Creating a kernel [krnl_vaddmul:{krnl_vaddmul_1}] for CU(1)
Creating a kernel [krnl_vaddmul:{krnl_vaddmul_2}] for CU(2)
Creating a kernel [krnl_vaddmul:{krnl_vaddmul_3}] for CU(3)
OVERALL THROUGHPUT = 138.022 GB/s
CHANNEL THROUGHPUT = 11.501 GB/s
TEST PASSED
```

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

### Initialize Kernel and Mailbox

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/mailbox_auto_restart_xrt/README.rst

Start the kernel in auto-restart mode and create a mailbox object for communication.

```cpp
auto mbox_autorestart_run = mbox_autorestart(xrt::autostart{0}, adder1, adder2);
xrt::mailbox krnl_mbox(mbox_autorestart_run);
```

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

### Launch Vitis IDE

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/GUIREADME.md

Command to start the Vitis IDE from a terminal window.

```bash
    vitis
```

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

### Execution Log Output

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/hbm_simple_xrt/README.rst

Example output log showing performance comparison between single-bank and multi-bank HBM configurations.

```text
Open the device0
Load the xclbin krnl_vadd.xclbin
Running CASE 1  : Single HBM for all three Buffers 
input 1 -> bank 0 
input 2 -> bank 0 
output  -> bank 0 
Allocate Buffer in Global Memory
synchronize input buffer data to device global memory
Execution of the kernel
Get the output data from the device
[CASE 1] THROUGHPUT = 11.1863 GB/s
Running CASE 2: Three Separate Banks for Three Buffers
input 1 -> bank 1 
input 2 -> bank 2 
output  -> bank 3 
Allocate Buffer in Global Memory
synchronize input buffer data to device global memory
Execution of the kernel
Get the output data from the device
[CASE 2] THROUGHPUT = 30.915 GB/s 
TEST PASSED
```

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

### GUI Flow Configuration Entries

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/performance/kernel_global_bandwidth/details.rst

Configuration entries for 2DDR and 3DDR XSA setups in the .cfg file.

```ini
[Connecttivity] sp=bandwidth_1.m_axi_gmem0:DDR[0]
sp=bandwidth_1.m_axi_gmem1:DDR[1]
```

```ini
[Connecttivity] sp=bandwidth_1.m_axi_gmem0:DDR[0]
sp=bandwidth_1.m_axi_gmem1:DDR[1]
sp=bandwidth_1.m_axi_gmem2:DDR[2]
```

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

### High Throughput Runtime Log

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/performance/hbm_bandwidth/details.rst

Example output for 8 compute units showing throughput exceeding 400 GB/s.

```text
Loading: './build_dir.hw.xilinx_u280_xdma_201920_1/krnl_vaddmul.xclbin'
Creating a kernel [krnl_vaddmul:{krnl_vaddmul_1}] for CU(1)
Creating a kernel [krnl_vaddmul:{krnl_vaddmul_2}] for CU(2)
Creating a kernel [krnl_vaddmul:{krnl_vaddmul_3}] for CU(3)
Creating a kernel [krnl_vaddmul:{krnl_vaddmul_4}] for CU(4)
Creating a kernel [krnl_vaddmul:{krnl_vaddmul_5}] for CU(5)
Creating a kernel [krnl_vaddmul:{krnl_vaddmul_6}] for CU(6)
Creating a kernel [krnl_vaddmul:{krnl_vaddmul_7}] for CU(7)
Creating a kernel [krnl_vaddmul:{krnl_vaddmul_8}] for CU(8)
THROUGHPUT = 421.3 GB/s
TEST PASSED
```

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

### IOPS Test Execution Log

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/performance/iops_test_xrt/README.rst

Example output log showing IOPS measurements on a U250 platform.

```text
Open the device0
Load the xclbin ./build_dir.hw.xilinx_u250_gen3x16_xdma_4_1_202210_1/hello.xclbin
Allocated commands, expect 10000, created 10000
Commands:      10 iops: 84033.6
Commands:      50 iops: 127226
Commands:     100 iops: 270270
Commands:     200 iops: 282486
Commands:     500 iops: 295159
Commands:    1000 iops: 299940
Commands:    1500 iops: 297442
Commands:    2000 iops: 304599
Commands:    3000 iops: 310013
Commands:    5000 iops: 314505
Commands:   10000 iops: 316937
Commands:   50000 iops: 335004
Commands:  100000 iops: 340296
Commands:  500000 iops: 357458
Commands: 1000000 iops: 359184
TEST PASSED
```

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

### Initialize Device and Load XCLBIN

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_py/hello_world_py/details.rst

Opens a device handle and loads an xclbin file to retrieve its UUID.

```python
d = pyxrt.device(index)

xbin = pyxrt.xclbin(bitstreamFile)
uuid = d.load_xclbin(xbin)
```

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

### Execute Hello World XRT Application

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/hello_world/README.rst

Command line execution syntax for the compiled application.

```bash
./hello_world_xrt -x <vadd XCLBIN>
```

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

### Initialize Device and Load XCLBIN

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/hello_world/details.rst

Opens a device handle and loads an XCLBIN file to retrieve its UUID.

```cpp
xrt::device(unsigned int didx)
```

```cpp
load_xclbin(binaryFile)
```

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

### Load Binary and Create Kernel

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/sys_opt/multiple_devices/details.rst

Reads the binary file and creates a kernel for each FPGA device.

```cpp
fileBuf[d] = xcl::read_binary_file(binaryFile, fileBufSize);
bins[d].push_back({fileBuf[d], fileBufSize});
programs[d] = load_cl2_binary(bins[d], devices[d], contexts[d]);
kernels[d] = cl::Kernel(programs[d], "vadd", &err);
```

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

### Execute P2P Bandwidth Application

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/performance/p2p_fpga2fpga_bandwidth/README.rst

Run the compiled application by specifying the XCLBIN files for both FPGA devices.

```bash
./p2p_fpga2fpga_bandwidth -x1 <bandwidth XCLBIN> -x2 <bandwidth XCLBIN>
```

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

### Execute Application

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/p2p_simple_xrt/README.rst

Command line execution for the P2P simple application.

```bash
./p2p_simple_xrt -x <adder XCLBIN> -f ./data/sample.txt
```

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

### Execute Application via Command Line

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/mult_compute_units_xrt/README.rst

Run the compiled application by providing the path to the vadd XCLBIN file.

```bash
./mult_compute_units_xrt -x <vadd XCLBIN>
```

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

### Enable P2P Configuration

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/performance/p2p_fpga2fpga_bandwidth/README.rst

Commands to enable P2P functionality, check status, and perform a warm reboot if required for IO memory allocation.

```bash
# xbutil p2p --enable
ERROR: resoure busy, please try warm reboot
# xbutil query
...
PCIe            DMA chan(bidir) MIG Calibrated  P2P Enabled
GEN 3x16        2               true            no iomem
# reboot
...
# xbutil query
...
PCIe            DMA chan(bidir) MIG Calibrated  P2P Enabled
GEN 3x16        2               true            true
...
```

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

### Initialize OpenCL Context and Command Queue

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/sys_opt/multiple_devices/details.rst

Initializes a context and command queue for each individual FPGA device.

```cpp
contexts[d] =cl::Context(devices[d], props, nullptr, nullptr, &err);
queues[d] = cl::CommandQueue(contexts[d], devices[d], CL_QUEUE_PROFILING_ENABLE, &err);
```

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

### load_xclbin(binaryFile)

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/hello_world/details.rst

Loads an xclbin file from disk.

```APIDOC
## load_xclbin

### Description
Reads the specified file from disk and loads the xclbin, returning the UUID of the loaded xclbin.

### Parameters
- **binaryFile** (string) - Required - Path to the xclbin file.
```

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

### List Project Files

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/rtl_kernels/rtl_vadd_mixed_c_vadd/README.rst

Displays the directory structure of the source files for the RTL and C kernels.

```text
src/hdl/krnl_vadd_rtl.v
src/hdl/krnl_vadd_rtl_adder.sv
src/hdl/krnl_vadd_rtl_axi_read_master.sv
src/hdl/krnl_vadd_rtl_axi_write_master.sv
src/hdl/krnl_vadd_rtl_control_s_axi.v
src/hdl/krnl_vadd_rtl_counter.sv
src/hdl/krnl_vadd_rtl_int.sv
src/host.cpp
src/krnl_vadd.cpp
```

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

### Execute Application

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/hbm_simple_xrt/README.rst

Command to run the compiled application with the specified XCLBIN file.

```bash
./hbm_simple_xrt -x <krnl_vadd XCLBIN>
```

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

### List Project Source Files

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/rtl_kernels/rtl_vadd_2clks/README.rst

Displays the directory structure of the RTL kernel source and host application files.

```text
src/hdl/krnl_vadd_2clk_rtl.v
src/hdl/krnl_vadd_2clk_rtl_adder.sv
src/hdl/krnl_vadd_2clk_rtl_axi_read_master.sv
src/hdl/krnl_vadd_2clk_rtl_axi_write_master.sv
src/hdl/krnl_vadd_2clk_rtl_control_s_axi.v
src/hdl/krnl_vadd_2clk_rtl_counter.sv
src/hdl/krnl_vadd_2clk_rtl_int.sv
src/host.cpp
```

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

### Apply Connectivity Configuration

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/streaming_free_running_k2k_xrt/README.rst

Command line argument to pass the connectivity configuration file to the v++ linker.

```bash
--config krnl_incr.cfg
```

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

### Execute Kernel Global Bandwidth Application

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/performance/kernel_global_bandwidth/README.rst

Run the compiled application by providing the path to the XCLBIN file.

```bash
./kernel_global_bandwidth <krnl_kernel_global XCLBIN>
```

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

### Device and XCLBIN API Usage

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/hello_world/README.rst

Functions for opening a device and loading an XCLBIN file.

```cpp
xrt::device(unsigned int didx)
This call open the device and return device handle.

load_xclbin(binaryFile)
This function reads the file from disk and loads the xclbin. This 
will return the UUID of the xclbin.
```

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

### Execute P2P Application

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/p2p_fpga2fpga_xrt/README.rst

Command to run the compiled P2P application with the required XCLBIN file.

```bash
./p2p_fpga2fpga_xrt -x <increment XCLBIN>
```

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

### d.load_xclbin(xbin)

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_py/hello_world_py/details.rst

Loads the xclbin onto the device and returns the UUID.

```APIDOC
## d.load_xclbin(xbin)

### Description
Loads the provided xclbin object onto the device and returns the UUID of the loaded xclbin.

### Parameters
- **xbin** (object) - Required - The xclbin object created via pyxrt.xclbin.
```

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

### Include Configuration in V++ Command

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/multiple_cus_asymmetrical_xrt/details.rst

Pass the configuration file to the v++ compiler command line.

```bash
--config vadd.cfg
```

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

### kHandle(args...)

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_py/hello_world_py/details.rst

Executes a kernel.

```APIDOC
## kHandle(args...)

### Description
Executes the kernel with the provided arguments.

### Parameters
- **args** (list) - Required - Arguments for the kernel execution.
```

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

### Execute Python Host Application

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_py/hello_world_py/README.rst

Command to run the Python host script with the required XCLBIN file.

```bash
./src/host.py -k <vadd XCLBIN>
```

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

### Initialize Kernel Objects

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/hello_world/details.rst

Creates a kernel object to manage instances within a loaded XCLBIN.

```cpp
xrt::kernel(const xrt::device &device, const xrt::uuid &xclbin_id, const std::string &name)
```

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

### Host Memory Bandwidth Execution Log

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/performance/host_memory_bandwidth/details.rst

Sample output log showing throughput measurements for various buffer sizes on the U250 platform.

```text
Found Platform
Platform Name: Xilinx
INFO: Reading ./build_dir.hw.xilinx_u250_gen3x16_xdma_4_1_202210_1/bandwidth.xclbin
Loading: './build_dir.hw.xilinx_u250_gen3x16_xdma_4_1_202210_1/bandwidth.xclbin'
Trying to program device[0]: xilinx_u250_gen3x16_xdma_shell_3_1
Device[0]: program successful!
Concurrent Read and Write Throughput = 6.96748 (GB/sec) for buffer size 4.00 KB
Read Throughput = 4.87813 (GB/sec) for buffer size 4.00 KB
Write Throughput = 4.69212 (GB/sec) for buffer size 4.00 KB

Concurrent Read and Write Throughput = 7.25228 (GB/sec) for buffer size 8.00 KB
Read Throughput = 4.95737 (GB/sec) for buffer size 8.00 KB
Write Throughput = 5.155 (GB/sec) for buffer size 8.00 KB

Concurrent Read and Write Throughput = 8.31089 (GB/sec) for buffer size 16.00 KB
Read Throughput = 6.0383 (GB/sec) for buffer size 16.00 KB
Write Throughput = 6.16268 (GB/sec) for buffer size 16.00 KB

Concurrent Read and Write Throughput = 12.1802 (GB/sec) for buffer size 32.00 KB
Read Throughput = 8.17289 (GB/sec) for buffer size 32.00 KB
Write Throughput = 8.26587 (GB/sec) for buffer size 32.00 KB

Concurrent Read and Write Throughput = 15.9402 (GB/sec) for buffer size 64.00 KB
Read Throughput = 9.62244 (GB/sec) for buffer size 64.00 KB
Write Throughput = 9.59521 (GB/sec) for buffer size 64.00 KB

Concurrent Read and Write Throughput = 19.0601 (GB/sec) for buffer size 128.00 KB
Read Throughput = 10.6148 (GB/sec) for buffer size 128.00 KB
Write Throughput = 10.7014 (GB/sec) for buffer size 128.00 KB

Concurrent Read and Write Throughput = 20.8453 (GB/sec) for buffer size 256.00 KB
Read Throughput = 10.4822 (GB/sec) for buffer size 256.00 KB
Write Throughput = 11.2627 (GB/sec) for buffer size 256.00 KB

Concurrent Read and Write Throughput = 21.8754 (GB/sec) for buffer size 512.00 KB
Read Throughput = 10.3349 (GB/sec) for buffer size 512.00 KB
Write Throughput = 11.5728 (GB/sec) for buffer size 512.00 KB

Concurrent Read and Write Throughput = 22.9009 (GB/sec) for buffer size 1.00 MB
Read Throughput = 11.4337 (GB/sec) for buffer size 1.00 MB
Write Throughput = 11.7316 (GB/sec) for buffer size 1.00 MB

Concurrent Read and Write Throughput = 23.3553 (GB/sec) for buffer size 2.00 MB
Read Throughput = 11.6192 (GB/sec) for buffer size 2.00 MB
Write Throughput = 11.8272 (GB/sec) for buffer size 2.00 MB

Concurrent Read and Write Throughput = 21.2646 (GB/sec) for buffer size 4.00 MB
Read Throughput = 11.6355 (GB/sec) for buffer size 4.00 MB
Write Throughput = 11.8706 (GB/sec) for buffer size 4.00 MB

Concurrent Read and Write Throughput = 19.8527 (GB/sec) for buffer size 8.00 MB
Read Throughput = 11.0061 (GB/sec) for buffer size 8.00 MB
Write Throughput = 11.8895 (GB/sec) for buffer size 8.00 MB

Concurrent Read and Write Throughput = 14.4411 (GB/sec) for buffer size 16.00 MB
Read Throughput = 10.688 (GB/sec) for buffer size 16.00 MB
Write Throughput = 11.6946 (GB/sec) for buffer size 16.00 MB
```

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

### Create Buffer with Host Pointer

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/sys_opt/kernel_swap/details.rst

Initializes a device buffer using a host-side pointer for the first kernel operation.

```cpp
cl::Buffer d_mul(context, CL_MEM_USE_HOST_PTR | CL_MEM_READ_WRITE, sizeof(int) * LENGTH, h_temp.data(), &err);
```

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

### Scale to 8 Compute Units Configuration

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/performance/hbm_bandwidth/details.rst

Additional connectivity settings for scaling to 8 compute units.

```ini
sp=krnl_vaddmul_4.in1:HBM[12]
sp=krnl_vaddmul_4.in2:HBM[13]
sp=krnl_vaddmul_4.out_add:HBM[14]
sp=krnl_vaddmul_4.out_mul:HBM[15]
sp=krnl_vaddmul_5.in1:HBM[16]
sp=krnl_vaddmul_5.in2:HBM[17]
sp=krnl_vaddmul_5.out_add:HBM[18]
sp=krnl_vaddmul_5.out_mul:HBM[19]
sp=krnl_vaddmul_6.in1:HBM[20]
sp=krnl_vaddmul_6.in2:HBM[21]
sp=krnl_vaddmul_6.out_add:HBM[22]
sp=krnl_vaddmul_6.out_mul:HBM[23]
sp=krnl_vaddmul_7.in1:HBM[24]
sp=krnl_vaddmul_7.in2:HBM[25] 
sp=krnl_vaddmul_7.out_add:HBM[26]
sp=krnl_vaddmul_7.out_mul:HBM[27]
sp=krnl_vaddmul_8.in1:HBM[28]
sp=krnl_vaddmul_8.in2:HBM[29] 
sp=krnl_vaddmul_8.out_add:HBM[30]
sp=krnl_vaddmul_8.out_mul:HBM[31]
nk=krnl_vaddmul:8
```

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

### List of Design Files

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/rtl_kernels/rtl_vadd_hw_debug/README.rst

The source directory contains the RTL kernel implementation files and the host application code.

```text
src/hdl/krnl_vadd_rtl.v
src/hdl/krnl_vadd_rtl_adder.sv
src/hdl/krnl_vadd_rtl_axi_read_master.sv
src/hdl/krnl_vadd_rtl_axi_write_master.sv
src/hdl/krnl_vadd_rtl_control_s_axi.v
src/hdl/krnl_vadd_rtl_counter.sv
src/hdl/krnl_vadd_rtl_int.sv
src/host.cpp
```

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

### Execute Copy Buffer Application

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/copy_buffer_xrt/README.rst

Command to run the compiled application with the required XCLBIN file.

```bash
./copy_buffer_xrt -x <vector_addition XCLBIN>
```

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

### Create Buffer for Second Kernel

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/sys_opt/kernel_swap/details.rst

Initializes a new device buffer using the same host pointer after reprogramming.

```cpp
cl::Buffer d_temp(context, CL_MEM_USE_HOST_PTR | CL_MEM_READ_ONLY,   sizeof(int) * LENGTH, h_temp.data());
```

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

### Execute Memory Migration

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/performance/host_global_bandwidth/README.rst

Uses the clEnqueueMigrateMemObjects API to transfer data between host and global memory.

```cpp
err = commands.enqueueMigrateMemObjects(mems1, 0/* 0 means from host*/);
err = commands.enqueueMigrateMemObjects(mems2, CL_MIGRATE_MEM_OBJECT_HOST);
```

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

### Create P2P Buffer

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/p2p_simple_xrt/README.rst

Initialization of a P2P buffer using the XRT native API.

```cpp
xrt::bo::flags flags = xrt::bo::flags::p2p;
auto p2p_bo0 = xrt::bo(device, vector_size_bytes, flags, krnl.group_id(0));
```

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

### xrt::device(unsigned int didx)

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/hello_world/details.rst

Opens a device and returns a device handle.

```APIDOC
## xrt::device

### Description
Opens the device specified by the index and returns a device handle.

### Parameters
- **didx** (unsigned int) - Required - The device index to open.
```

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

### Configure AXI-Master Port Connectivity

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/performance/host_memory_bandwidth/details.rst

Define connectivity settings in the krnl_bandwidth.cfg file to map AXI-Master ports to the Slave-Bridge IP.

```ini
[connectivity]
sp=bandwidth_1.input0:HOST[0]
sp=bandwidth_1.output0:HOST[0]
sp=read_bandwidth_1.input0:HOST[0]
sp=write_bandwidth_1.output0:HOST[0]
```

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

### pyxrt.device(index)

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_py/hello_world_py/details.rst

Opens a device and returns a device handle.

```APIDOC
## pyxrt.device(index)

### Description
Opens the device at the specified index and returns a device handle.

### Parameters
- **index** (int) - Required - The index of the device to open.
```

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

### Configure HBM Connectivity

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/hbm_simple_xrt/README.rst

Configuration file snippet to map kernel interfaces to specific HBM banks.

```ini
[connectivity]
sp=krnl_vadd_1.in1:HBM[0:3]
sp=krnl_vadd_1.in2:HBM[0:3]
sp=krnl_vadd_1.out_r:HBM[0:3]
```

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

### Configure Kernel Arguments for Streaming

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/streaming_k2k_mm_xrt/details.rst

Set memory-mapped arguments for producer and consumer kernels while omitting streaming interface arguments.

```cpp
run.set_arg(0,bo0);
run.set_arg(1,bo1);
run.set_arg(3,DATA_SIZE);

run1.set_arg(0,bo2);
run1.set_arg(2,bo_out);
run1.set_arg(3,DATA_SIZE);
```

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

### boHandle.map()

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_py/hello_world_py/details.rst

Maps buffer memory to host.

```APIDOC
## boHandle.map()

### Description
Maps the contents of the buffer object into host memory.
```

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

### Allocate P2P Buffer

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/p2p_fpga2fpga_xrt/README.rst

Create a buffer with the p2p flag to enable direct device-to-device data transfer.

```cpp
xrt::bo::flags flags = xrt::bo::flags::p2p;
auto out1 = xrt::bo(device1, vector_size_bytes, flags, krnl.group_id(1));
```

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

### Transfer data from device to host

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/data_transfer_xrt/README.rst

Use sync with XCL_BO_SYNC_BO_FROM_DEVICE and read to retrieve data from the device to host memory.

```cpp
std::cout << "synchronize output buffer data from the device" << std::endl;
output_buffer.sync(XCL_BO_SYNC_BO_FROM_DEVICE);

std::cout << "Read the output data\n";
output_buffer.read(buff_out_data);
```

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

### Executing multiple tasks through xrt::queue

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/asynchronous_xrt/README.rst

Demonstrates enqueuing data synchronization and kernel execution tasks across multiple queues to achieve parallelism and synchronization.

```cpp
          xrt::queue main_queue;
          xrt::queue queue_bo1;
          auto bo0_event = main_queue.enqueue([&bo0] {bo0.sync(XCL_BO_SYNC_BO_TO_DEVICE); });
          auto bo1_event = queue_bo1.enqueue([&bo1] {bo1.sync(XCL_BO_SYNC_BO_TO_DEVICE); });
          main_queue.enqueue(bo1_event); 
          main_queue.enqueue([&run] {run.start(); run.wait(); });
          auto bo_out_event = main_queue.enqueue([&bo_out] {bo_out.sync(XCL_BO_SYNC_BO_FROM_DEVICE); });
          bo_out_event.wait();
```

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

### Executing multiple tasks through queue

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/asynchronous_xrt/details.rst

Demonstrates parallel data transfers using separate queues and synchronization by enqueuing events from one queue into another.

```c++
xrt::queue main_queue;
          xrt::queue queue_bo1;
          auto bo0_event = main_queue.enqueue([&bo0] {bo0.sync(XCL_BO_SYNC_BO_TO_DEVICE); });
          auto bo1_event = queue_bo1.enqueue([&bo1] {bo1.sync(XCL_BO_SYNC_BO_TO_DEVICE); });
          main_queue.enqueue(bo1_event); 
          main_queue.enqueue([&run] {run.start(); run.wait(); });
          auto bo_out_event = main_queue.enqueue([&bo_out] {bo_out.sync(XCL_BO_SYNC_BO_FROM_DEVICE); });
          bo_out_event.wait();
```

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

### pyxrt.device

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_py/hello_world_py/README.rst

Opens a device and returns a device handle.

```APIDOC
## pyxrt.device(index)

### Description
Opens the specified device and returns a device handle for further operations.

### Parameters
- **index** (int) - Required - The index of the device to open.
```

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

### Configure Multiple Compute Units

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/mult_compute_units_xrt/README.rst

Use the nk flag in a configuration file to specify the number of compute unit instances for a kernel.

```ini
[connectivity]
nk=vadd:4
```

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

### pyxrt.xclbin(bitstreamFile)

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_py/hello_world_py/details.rst

Loads an xclbin file from disk.

```APIDOC
## pyxrt.xclbin(bitstreamFile)

### Description
Reads the bitstream file from disk and prepares it for loading onto the device.

### Parameters
- **bitstreamFile** (string) - Required - Path to the xclbin file.
```

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

### Migrate Memory to Host

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/sys_opt/kernel_swap/details.rst

Transfers kernel results from device memory back to the host buffer.

```cpp
q.enqueueMigrateMemObjects({d_mul},CL_MIGRATE_MEM_OBJECT_HOST);
```

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

### xrt::bo(xclDeviceHandle dhdl, size_t size, memory_group grp)

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/hello_world/details.rst

Creates a buffer object.

```APIDOC
## xrt::bo

### Description
Creates a default buffer object with host and device buffers.

### Parameters
- **dhdl** (xclDeviceHandle) - Required - Device handle.
- **size** (size_t) - Required - Size of the buffer.
- **grp** (memory_group) - Required - Memory group for the buffer.
```

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

### Execute Kernel

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_py/hello_world_py/details.rst

Invokes a kernel with buffer arguments and waits for completion.

```python
run = kHandle(boHandle1, boHandle2, boHandle3, COUNT)
state = run.wait()
```

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

### pyxrt.xclbin

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_py/hello_world_py/README.rst

Loads an xclbin file onto the device.

```APIDOC
## pyxrt.xclbin(bitstreamFile)

### Description
Reads the xclbin file from disk and loads it onto the device, returning the UUID.

### Parameters
- **bitstreamFile** (string) - Required - Path to the xclbin file.
```

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

### Manage Buffer Objects

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_py/hello_world_py/details.rst

Allocates, synchronizes, and maps buffer objects for host-device data transfer.

```python
boHandle1 = pyxrt.bo(d, DATA_SIZE, pyxrt.bo.normal, kHandle.group_id(0))
boHandle1.sync(pyxrt.xclBOSyncDirection.XCL_BO_SYNC_BO_TO_DEVICE, DATA_SIZE, 0)
bo1 = boHandle1.map()
```

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

### Configure SoC Platform Clock Frequencies

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/rtl_kernels/rtl_vadd_2clks/README.rst

Configuration syntax for setting independent clock frequencies for SoC platforms in the V++ linking stage.

```ini
[clock]
freqHz=150000000:krnl_vadd_2clk_rtl_1.ap_clk
freqHz=250000000:krnl_vadd_2clk_rtl_1.ap_clk_2
```

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

### Transfer data from host to device

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/data_transfer_xrt/README.rst

Use write and sync with XCL_BO_SYNC_BO_TO_DEVICE to move data from host memory to the device.

```cpp
std::cout << "Write the input data\n";
input_buffer.write(buff_in_data);

std::cout << "synchronize input buffer data to device global memory\n";
input_buffer.sync(XCL_BO_SYNC_BO_TO_DEVICE);
```

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

### run.wait()

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_py/hello_world_py/details.rst

Waits for kernel execution to complete.

```APIDOC
## run.wait()

### Description
Blocks until the kernel execution is complete.
```

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

### Manage Buffer Objects

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/hello_world/details.rst

Allocates, synchronizes, and maps buffer objects for host-device data transfer.

```cpp
xrt::bo(xclDeviceHandle dhdl, size_t size, memory_group grp)
```

```cpp
void sync(xclBOSyncDirection dir, size_t sz, size_t offset)
```

```cpp
void *map()
```

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

### boHandle.sync

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_py/hello_world_py/README.rst

Synchronizes buffer data between host and device.

```APIDOC
## boHandle.sync(direction, size, offset)

### Description
Synchronizes a specified number of bytes of the buffer.

### Parameters
- **direction** (enum) - Required - Sync direction (e.g., pyxrt.xclBOSyncDirection.XCL_BO_SYNC_BO_TO_DEVICE).
- **size** (int) - Required - Number of bytes to sync.
- **offset** (int) - Required - Offset in the buffer.
```

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

### Allocate Host-Only Buffer

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/performance/host_memory_bandwidth/details.rst

Use cl_mem_ext_ptr_t with XCL_MEM_EXT_HOST_ONLY to explicitly assign memory to the host.

```cpp
cl_mem_ext_ptr_t input_buffer_ext;
input_buffer_ext.flags = XCL_MEM_EXT_HOST_ONLY;
input_buffer_ext.obj = nullptr;
input_buffer_ext.param = 0;

OCL_CHECK(err, buffer[0] = new cl::Buffer(context, CL_MEM_READ_WRITE | CL_MEM_EXT_PTR_XILINX, bufsize,
                                          &input_buffer_ext, &err));
```

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

### Configure ap_ctrl_chain Interface

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/kernel_chain/README.rst

Use these pragmas in the HLS kernel code to enable the ap_ctrl_chain interface for block-level control.

```cpp
#pragma HLS INTERFACE s_axilite port = return bundle = control
#pragma HLS INTERFACE ap_ctrl_chain port = return bundle = control
```

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

### Migrate Memory to Device

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/sys_opt/kernel_swap/details.rst

Transfers data from the host buffer to the device for the second kernel execution.

```cpp
q.enqueueMigrateMemObjects({d_temp}, 0/* 0 means from host*/);
```

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

### Create Device Buffers

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/sys_opt/multiple_devices/details.rst

Allocates memory buffers for each FPGA device independently.

```cpp
buffer_a[d] = cl::Buffer(contexts[d], CL_MEM_USE_HOST_PTR | CL_MEM_READ_ONLY, size_per_device, &A[offset], &err);
```

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

### Configure PCIe Platform Clock Frequencies

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/rtl_kernels/rtl_vadd_2clks/README.rst

Configuration syntax for setting kernel frequencies on PCIe platforms.

```text
kernel_frequency=0:150|1:250
```

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

### Configure Kernel Connectivity

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/rtl_kernels/rtl_streaming_free_running_k2k/README.rst

Configuration file settings to define stream connections between producer and consumer kernels during the system link phase.

```ini
[connectivity]
stream_connect=krnl_mm2s_1.out:myadder_1.in 
stream_connect=myadder_1.out:krnl_s2mm_1.in
```

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

### Configure Stream Connectivity

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/streaming_free_running_k2k_xrt/README.rst

Configuration settings for connecting streaming ports between kernels during the system link process.

```ini
[connectivity]
stream_connect=mem_read_1.stream:increment_1.input
stream_connect=increment_1.output:mem_write_1.stream
```

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

### Link Kernel Streams via Configuration File

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/streaming_k2k_mm_xrt/details.rst

Define the connectivity between kernel stream ports using a Vitis configuration file.

```ini
--config krnl_stream_vadd_vmult.cfg
```

```ini
[connectivity]
stream_connect=krnl_stream_vadd_1.out:krnl_stream_vmult_1.in2:64
```

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

### Create Host-Only Buffer with XRT

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_xrt/host_memory_simple_xrt/README.rst

Use the xrt::bo::flags::host_only flag during buffer creation to allocate memory that resides on the host and is accessible by the kernel.

```cpp
xrt::bo::flags flags = xrt::bo::flags::host_only;
auto bo0 = xrt::bo(device, size_in_bytes, flags, krnl.group_id(0));
```

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

### Configure Memory Connectivity

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/performance/kernel_global_bandwidth/README.rst

Specify DDR bank mapping for kernel ports in the configuration file.

```ini
[connectivity]
sp=bandwidth_1.m_axi_gmem0:DDR[0]
sp=bandwidth_1.m_axi_gmem1:DDR[1]
```

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

### Configure AXI-Master Port Connection

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/performance/host_memory_bandwidth_xrt/details.rst

Connects AXI-Master ports to the Slave-Bridge IP using the sp option in the configuration file.

```text
sp=bandwidth_1.input0:HOST[0]
sp=bandwidth_1.output0:HOST[0]
sp=read_bandwidth_1.input0:HOST[0]
sp=write_bandwidth_1.output0:HOST[0]
```

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

### Kernel Execution

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/host_py/hello_world_py/README.rst

Executes a kernel and waits for completion.

```APIDOC
## kHandle(*args)

### Description
Executes the kernel with the provided buffer arguments.

## run.wait()

### Description
Waits for the kernel execution to complete.
```

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

### Allocate HBM Buffer with CL_MEM_EXT_PTR_XILINX

Source: https://github.com/xilinx/vitis_accel_examples/blob/main/performance/hbm_bandwidth_pseudo_random/details.rst

Use cl_mem_ext_ptr_t to explicitly assign buffers to specific HBM banks during host memory allocation.

```cpp
cl_mem_ext_ptr_t bufExt;
bufExt.obj = host_pointer;
bufExt.param = 0;
bufExt.flags = n  | XCL_MEM_TOPOLOGY; 
buffer_input = cl::Buffer(context, CL_MEM_READ_ONLY | CL_MEM_EXT_PTR_XILINX | CL_MEM_USE_HOST_PTR, size, &bufExt, &err));
```
Tokens:
Raw