Port-Level I/O Protocols - 2021.1 English

Vitis High-Level Synthesis User Guide (UG1399)

Document ID
Release Date
2021.1 English
Important: The port-level I/O protocols of interfaces defined in the Vitis kernel flow are set by design and should not be modified as a general rule.

By default input pointers and pass-by-value arguments are implemented as simple wire ports with no associated handshaking signal. For example, in the vadd function discussed in Interfaces for Vivado IP Flow, the input ports are implemented without an I/O protocol, only a data port. If the port has no I/O protocol, (by default or by design) the input data must be held stable until it is read.

By default output pointers are implemented with an associated output valid signal to indicate when the output data is valid. In the vadd function example, the output port is implemented with an associated output valid port (out_r_o_ap_vld) which indicates when the data on the port is valid and can be read. If there is no I/O protocol associated with the output port, it is difficult to know when to read the data.
Tip: It is always a good idea to use an I/O protocol on an output.

Function arguments which are both read from and written to are split into separate input and output ports. In the vadd function example, the out_r argument is implemented as both an input port out_r_i, and an output port out_r_o with associated I/O protocol port out_r_o_ap_vld.

If the function has a return value, an output port ap_return is implemented to provide the return value. When the RTL design completes one transaction, this is equivalent to one execution of the C/C++ function, the block-level protocols indicate the function is complete with the ap_done signal. This also indicates the data on port ap_return is valid and can be read.

Note: The return value of the top-level function cannot be a pointer.

For the example code shown the timing behavior is shown in the following figure (assuming that the target technology and clock frequency allow a single addition per clock cycle).

Figure 1. RTL Port Timing with Default Synthesis
  • The design starts when ap_start is asserted High.
  • The ap_idle signal is asserted Low to indicate the design is operating.
  • The input data is read at any clock after the first cycle. Vitis HLS schedules when the reads occur. The ap_ready signal is asserted High when all inputs have been read.
  • When output sum is calculated, the associated output handshake (sum_o_ap_vld) indicates that the data is valid.
  • When the function completes, ap_done is asserted. This also indicates that the data on ap_return is valid.
  • Port ap_idle is asserted High to indicate that the design is waiting start again.