HLS Kernel Interface Requirements - 2025.2 English - UG1701

Embedded Design Development Using Vitis User Guide (UG1701)
Document ID
UG1701
Release Date
2025-11-20
Version
2025.2 English

The kernel interfaces are used to exchange the data with the host application, other kernels, or device I/Os. HLS kernel interface requirements are listed below:

Control interface
  • XRT-managed or user-managed kernels: Kernels can only have a single AXI4-Lite interface.
  • Data driven kernels: The AXI4-Lite interface is optional and used to pass scalar values to the kernel.
Data interfaces
  • XRT-managed or user-managed kernels: Any number and combination of AXI4 and AXI4-Stream interfaces.
  • Data driven kernels: The kernel requires at least one AXI4-Stream interface.
Clocks and resets
As described in Clock and Reset Requirements.
Tip: XRT-managed kernels have specific requirements for control registers in the AXI4-Lite interface (including start and stop bits) as described in Control Requirements for XRT-Managed Kernels. User-managed kernels can implement the control scheme the user specifies.

Refer to the following table for the type of interface required based on the characteristics of the data movement in your application.

Table 1. Kernel Interface Types
Register (AXI4-Lite) Memory Mapped (M_AXI) Streaming (AXI4-Stream)
  • Register interfaces must be implemented using a single AXI4-Lite interface.
  • Designed for transferring scalars between the host application and the kernel.
  • Register reads and writes are initiated by the host application.
  • The kernel acts as a slave.
  • Memory mapped interfaces must be implemented using one or more AXI4 Masters interfaces.
  • Designed for bi-directional data transfers with global memory (DDR, PLRAM, HBM).
  • Introduces additional latency for memory transfers.
  • The kernel acts as a master accessing data stored into global memory.
  • The host application allocates the buffer for the size of the dataset.
  • The base address of the buffer is provided by the host application to the kernel via the AXI4-Lite interface.
  • Streaming interfaces must be implemented using one or more AXI4-Stream interfaces.
  • Designed for uni-directional data transfers between kernels.
  • The access pattern is sequential.
  • Does not use global memory.
  • Data set is unbounded.
  • A sideband signal can be used to indicate the last value in the stream.

User-managed PL kernels have no predefined execution mode. It is up to the kernel designer to implement the control protocol and the execution mechanism. It is the application developer's responsibility to manage the operation of the kernel by executing appropriate sequences of register reads and writes from the software application, in accordance with the user-defined control protocol of the kernel.

XRT-managed PL kernels, as described in Supported Kernel Execution Models in the XRT documentation, provide defined kernel execution modes supporting overlapping execution of the kernel, or sequential execution.

  • A kernel is started by the software application using an XRT API call. When the kernel is ready for new data, it notifies the host application through bits in the control register.
  • The default control protocol, ap_ctrl_chain, supports pipelined execution enabling multiple executions of the same PL kernel to be overlapped to improve the overall application throughput.
  • If required, pipelined execution can be disabled by using the ap_ctrl_hs control protocol which forces kernels to run sequentially, waiting until the prior run has completed before starting the next run.
  • Finally, a kernel can be auto-restarting, allowing it to run for a specified number of iterations, or until reset by the host application as described in Auto-Restarting Kernels in Vitis High-Level Synthesis User Guide (UG1399).