Free-Running Kernels - 2023.2 English

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

Document ID
UG1393
Release Date
2023-12-13
Version
2023.2 English

While the Vitis core development kit provides support for streaming interfaces on PL kernels, it also supports a special kind of data-driven kernel called a free-running kernel. Free-running kernels have no control signal ports, no mechanism for interaction with a software application, and cannot be started or stopped. Free-running kernels have the following characteristics:

  • When the device is programmed by the binary container (xclbin), free-running kernels start running automatically and do not need to be started from a software application.
  • Has no memory input or output port, and therefore interacts with other kernels only through input or output streams
  • The kernel operates on the stream data as soon as the data is received and the kernel stalls when data is not available.

The main advantage of a free-running kernel is that it does not follow the C-semantics where all the functions should be executed an equal number of times. This modeling style is more like RTL designs as shown in the example below. The compiler models the kernel to restart automatically after the previous function call finishes. This functionality is similar to a while(1) loop in software code, without having to specify the loop in the kernel code.

A free-running kernel only contains hls::stream inputs and outputs. The recommended coding guidelines include:

  • Use hls::stream<ap_axiu<D,0,0,0> > for the kernel interfaces.
  • The hls::stream data type for the function parameter causes Vitis HLS to infer an AXI4-Stream port (axis) for the interface.
  • The kernel only supports streaming interfaces (axis). It should not use m_axi or s_axilite interfaces, as shown in the example below.
  • The free-running kernel must also specify the following block control protocol using the INTERFACE pragma.
    #pragma HLS interface ap_ctrl_none port=return
    Tip: This will create a kernel without control signals or an AXI4-Lite interface. This modeling technique is called a free-running kernel, as it is free of any control handshake and will start automatically and run continuously. For kernels requiring some interaction with software applications, consider using auto-restarting kernels as described in ( Vitis High-Level Synthesis User Guide (UG1399)).

The following code example shows a free-running kernel with one input and one output communicating with another kernel.

void increment(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
   ap_axiu<32, 0, 0, 0> v = input.read();
   v.data = v.data + 1;
   output.write(v);
   if (v.last){
      break;
   }
}
Important: Software emulation is not supported for free-running kernels.