Setting Up XRT-Managed Kernels and Kernel Arguments - 2024.1 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID
UG1393
Release Date
2024-05-30
Version
2024.1 English

After identifying devices and loading the program, the software application should identify the kernels that execute on the device, and set up the kernel arguments. All kernels the software application interacts with are defined within the loaded .xclbin file, and so should be identified from there.

For XRT-managed kernels, the XRT API provides a Kernel class (xrt::kernel), that is used to access the kernels contained within the .xclbin file. The kernel object identifies an XRT-managed kernel in the .xclbin loaded into the AMD device that can be run by the host application.

Tip: As discussed in Working with User-Managed Kernels, you should use the IP class (xrt::ip) to identify the user-managed kernels in the .xclbin file.

The use of the kernel and buffer objects require the addition of the following include statements in your source code:

#include <xrt/xrt_kernel.h>
#include <xrt/xrt_bo.h>

The following code example identifies a kernel ("vadd") defined in the program (uuid) loaded onto the device:

auto krnl = xrt::kernel(device, uuid, "vadd");
Tip: You can use the xclbinutil command to examine the contents of an existing .xclbin file and determine the kernels contained within.
After identifying the kernel, or kernels to be run, you need to define buffer objects to associate with the kernel arguments and enable data transfer from the host application to the kernel instance or compute unit (CU):
std::cout << "Allocate Buffer in Global Memory\n";
auto bo0 = xrt::bo(device, vector_size_bytes, krnl.group_id(0));
auto bo1 = xrt::bo(device, vector_size_bytes, krnl.group_id(1));
auto bo_out = xrt::bo(device, vector_size_bytes, krnl.group_id(2));

The kernel object (xrt::kernel) includes a method to return the memory associated with each kernel argument, kernel.group_id().

Note: A buffer is not required for scalar arguments.