Block-Level Control Protocols - 2022.1 English

Vitis High-Level Synthesis User Guide (UG1399)

Document ID
UG1399
Release Date
2022-06-07
Version
2022.1 English
The execution mode of a Vitis kernel or Vivado IP is specified by the block-level control protocol. Execution modes of kernels include:
  • Pipelined execution (ap_ctrl_chain) permitting overlapping kernel runs to begin processing additional data as soon as the kernel is ready.
  • Sequential execution (ap_ctrl_hs) requiring the kernel to complete one cycle before beginning another.
  • Data driven execution (ap_ctrl_none) which enables the kernel to run when data is available, and stall when data is not.
You can specify the block-level control protocol on the function or the function return. If the C/C++ code does not return a value, you can still specify the control protocol on the function return. If the C/C++ code uses a function return, Vitis HLS creates an output port ap_return for the return value.
Tip: When the function return is specified as an AXI4-Lite interface (s_axilite) all the ports in the control protocol are bundled into the s_axilite interface. This is a common practice for software-controllable kernels or IP when an application or software driver is used to configure and control when the block starts and stops operation. This is a requirement of XRT and the Vitis kernel flow.

The ap_ctrl_hs block-level control protocol is the default for the Vivado IP flow. Interfaces for Vivado IP Flow shows the resulting RTL ports and behavior when Vitis HLS implements ap_ctrl_hs on a function.

The ap_ctrl_chain control protocol is the default for the Vitis kernel flow as explained in Interfaces for Vitis Kernel Flow. It is similar to ap_ctrl_hs but provides an additional input signal ap_continue to apply back pressure. Xilinx recommends using the ap_ctrl_chain block-level I/O protocol when chaining Vitis HLS blocks together.

Tip: Refer to Supported Kernel Execution Models for more information on how XRT uses these control protocols.

ap_ctrl_hs

The following figure shows the behavior of the block-level handshake signals created by the ap_ctrl_hs control protocol for a non-pipelined design.

Figure 1. Behavior of ap_ctrl_hs Interface

After reset, the following occurs:

  1. The block waits for ap_start to go High before it begins operation.
  2. Output ap_idle goes Low immediately to indicate the design is no longer idle.
  3. The ap_start signal must remain High until ap_ready goes High. Once ap_ready goes High:
    • If ap_start remains High the design will start the next transaction.
    • If ap_start is taken Low, the design will complete the current transaction and halt operation.
  4. Data can be read on the input ports.
  5. Data can be written to the output ports.
    Note: The input and output ports can also specify a port-level I/O protocol that is independent of the control protocol. For details, see Port-Level I/O Protocols.
  6. Output ap_done goes High when the block completes operation.
    Note: If there is an ap_return port, the data on this port is valid when ap_done is High. Therefore, the ap_done signal also indicates when the data on output ap_return is valid.
  7. When the design is ready to accept new inputs, the ap_ready signal goes High. Following is additional information about the ap_ready signal:
    • The ap_ready signal is inactive until the design starts operation.
    • In non-pipelined designs, the ap_ready signal is asserted at the same time as ap_done.
    • In pipelined designs, the ap_ready signal might go High at any cycle after ap_start is sampled High. This depends on how the design is pipelined.
    • If the ap_start signal is Low when ap_ready is High, the design executes until ap_done is High and then stops operation.
    • If the ap_start signal is High when ap_ready is High, the next transaction starts immediately, and the design continues to operate.
  8. The ap_idle signal indicates when the design is idle and not operating. Following is additional information about the ap_idle signal:
    • If the ap_start signal is Low when ap_ready is High, the design stops operation, and the ap_idle signal goes High one cycle after ap_done.
    • If the ap_start signal is High when ap_ready is High, the design continues to operate, and the ap_idle signal remains Low.

ap_ctrl_chain

The ap_ctrl_chain control protocol is similar to the ap_ctrl_hs protocol but provides an additional input port named ap_continue. An active-High ap_continue signal indicates that the downstream block that consumes the output data is ready for new data inputs. If the downstream block is not able to consume new data inputs, the ap_continue signal is Low, which prevents upstream blocks from generating additional data.

The ap_ready port of the downstream block can directly drive the ap_continue port. Following is additional information about the ap_continue port:

  • If the ap_continue signal is High when ap_done is High, the design continues operating. The behavior of the other block-level control signals is identical to those described in the ap_ctrl_hs block-level I/O protocol.
  • If the ap_continue signal is Low when ap_done is High, the design stops operating, the ap_done signal remains High, and data remains valid on the ap_return port if the ap_return port is present.

In the following figure, the first transaction completes, and the second transaction starts immediately because ap_continue is High when ap_done is High. However, the design halts at the end of the second transaction until ap_continue is asserted High.

Figure 2. Behavior of ap_ctrl_chain Interface

ap_ctrl_none

If you specify the ap_ctrl_none control protocol, the handshake signal ports (ap_start, ap_idle, ap_ready, and ap_done) are not created. It is highly recommended to use the autorestart mode (see section on autorestart drivers) even for data-driven kernels, because it allows the host code to start and stop when needed, in an orderly fashion.

Important: If you use the ap_ctrl_none control protocol in your design, you must meet at least one of the conditions for C/RTL co-simulation as described in Interface Synthesis Requirements to verify the RTL design. If at least one of these conditions is not met, C/RTL co-simulation halts with the following message:
@E [SIM-345] Cosim only supports the following 'ap_ctrl_none' designs: (1) 
combinational designs; (2) pipelined design with task interval of 1; (3) designs with 
array streaming or hls_stream ports.
@E [SIM-4] *** C/RTL co-simulation finished: FAIL ***