Coding Guidelines for Free-Running Kernels - 2020.2 English

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

Document ID
Release Date
2020.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
Important: The kernel interface should not have any #pragma HLS interface s_axilite or #pragma HLS interface m_axi (as there should not be any memory or control port).

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.