SW-Controllable Kernels - 2024.1 English

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

Document ID
Release Date
2024.1 English

Software controllable kernels expose a programmable register interface, allowing a host software application to interact with kernels through register reads and write. These are the most common and widely applicable types of PL kernels. There are two types of SW controllable kernels: user-managed and XRT-managed.

Note: XRT-managed kernels are a specialized form of user-managed kernels.

The primary difference between user-managed and XRT-managed kernels is related to the kernel execution mode. Because XRT relies on the ap_ctrl_chain and ap_ctrl_hs execution protocols generated by the HLS compiler, XRT-managed kernels are better for C++ developers as described in Developing PL Kernels using C++. Alternatively, user-managed kernels can support many different user-defined execution protocols as found in existing Vivado RTL IP, and so are a better fit for RTL designers described in Packaging RTL Kernels.

The Vitis development flow supports software applications written for use with PL kernels using the XRT native C/C++ API, which supports both user-managed kernels and XRT-managed kernels, in addition to some advanced designs as discussed in Execution Modes. The next sections briefly describe the programming API and the different hardware interfaces required for XRT-managed or user-managed kernels.

Tip: The general documentation for XRT can be found at Xilinx Runtime Architecture. The XRT API described below can be found at XRT Native C++ API.
Table 1. Software Control Using the XRT API
XRT-Managed Kernels User-Managed Kernels
  • The object class for an XRT-managed kernel is xrt::kernel
  • The software application communicates with the XRT-managed kernel using higher-level commands such as set_arg, run, and wait
  • The user does not need to know the low-level details of the programmable registers and kernel execution protocols
  • Control and status registers provide XRT with a known interface to interact with the kernel, which makes these high-level commands possible
  • If needed, it is also possible to control an XRT-managed kernel as a user-managed kernel (using atomic register reads and write)
  • OpenCL API can also be used with XRT-managed kernels (cl::kernel)
  • The object class for a user-managed kernel is xrt::ip
  • The software application communicates with the user-managed kernel using atomic register reads and writes through the AXI4-Lite interface
  • The application developer is responsible for knowing the address offset and purpose of each register in the kernel, and using them properly
  • There are no checks, high-level controls, or profiling capabilities. The user is responsible for running the simulations for performance analysis/debugging.