Coding Guidelines for Free-Running Kernels - 2021.2 English

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

Document ID
English (United States)
Release Date
2021.2 English

As mentioned previously, the free-running kernel only contains hls::stream inputs and outputs. The recommended coding guidelines include:

  • Use hls::stream<ap_axiu<D,0,0,0> > if the port is interacting with another stream port from the kernel.
  • Use hls::stream<qdma_axis<D,0,0,0> > if the port is interacting with the host.
  • Use the hls::stream data type for the function parameter causes Vitis HLS to infer an AXI4-Stream port (axis) for the interface.
  • The free-running kernel must also specify the following special INTERFACE pragma.
    #pragma HLS interface ap_ctrl_none port=return
Tip: ap_ctrl_none means there is no control interface for the kernel so typically there is no s_axilite interface generated. However, the presence of either scalar arguments or m_axi interfaces requires the use of an s_axilite interface.

The following code example shows a free-running kernel with one input and one output communicating with another kernel. The while(1) loop structure contains the substance of the kernel code, which repeats as long as the kernel runs.

void kernel_top(hls::stream<ap_axiu<32, 0, 0, 0> >& input, 
   hls::stream<ap_axiu<32, 0, 0, 0> >& output) {
#pragma HLS interface ap_ctrl_none port=return  // Special pragma for free-running kernel
#pragma HLS DATAFLOW // The kernel is using DATAFLOW optimization
	while(1) {
Tip: The example shows the definition of the streaming input/output ports in a free-running kernel. However, the streaming connection from the free-running kernel to or from another kernel must be defined during the kernel linking process as described in Specifying Streaming Connections between Compute Units.