Port-Level I/O: Wire Handshakes - 2025.2 English - UG1399

Vitis High-Level Synthesis User Guide (UG1399)
Document ID
UG1399
Release Date
2025-11-20
Version
2025.2 English

Interface mode ap_hs includes a two-way handshake signal with the data port. The handshake is an industry standard valid and acknowledge handshake. Mode ap_vld is the same but only has a valid port and ap_ack only has a acknowledge port.

Mode ap_ovld is for use with in-out arguments. When the in-out is split into separate input and output ports, mode ap_none is applied to the input port and ap_vld applied to the output port. This is the default for pointer arguments that are both read and written.

The ap_hs mode can be applied to arrays that are read or written in sequential order. If Vitis HLS can determine the read or write accesses are not sequential, it will halt synthesis with an error. If the access order cannot be determined, Vitis HLS will issue a warning.

ap_hs (ap_ack, ap_vld, and ap_ovld)

The ap_hs port-level I/O protocol provides the greatest flexibility in the development process, allowing both bottom-up and top-down design flows. Two-way handshakes safely perform all intra-block communication, and manual intervention or assumptions are not required for correct operation. The ap_hs port-level I/O protocol provides the following signals:

  • Data port
  • Valid signal to indicate when the data signal is valid and can be read
  • Acknowledge signal to indicate when the data has been read

The following figure shows how an ap_hs interface behaves for both an input and output port. In this example, the input port is named in, and the output port is named out.

Note: The control signals names are based on the original port name. For example, the valid port for data input in is named in_vld.
Figure 1. Behavior of ap_hs Interface

For inputs, the following occurs:

  • After start is applied, the block begins normal operation.
  • If the design is ready for input data but the input valid is Low, the design stalls and waits for the input valid to be asserted to indicate a new input value is present.
    Note: The preceding figure shows this behavior. In this example, the design is ready to read data input in on clock cycle 4 and stalls waiting for the input valid before reading the data.
  • When the input valid is asserted High, an output acknowledge is asserted High to indicate the data was read.

For outputs, the following occurs:

  • After start is applied, the block begins normal operation.
  • When an output port is written to, its associated output valid signal is simultaneously asserted to indicate valid data is present on the port.
  • If the associated input acknowledge is Low, the design stalls and waits for the input acknowledge to be asserted.
  • When the input acknowledge is asserted, indicating the data has been read, the output valid is deasserted on the next clock edge.

ap_ack

The ap_ack port-level I/O protocol is a subset of the ap_hs interface type. The ap_ack port-level I/O protocol provides the following signals:

  • Data port
  • Acknowledge signal to indicate when data is consumed
    • For input arguments, the design generates an output acknowledge that is active-High in the cycle the input is read.
    • For output arguments, Vitis HLS implements an input acknowledge port to confirm the output was read.
    Note: After a write operation, the design stalls and waits until the input acknowledge is asserted High, which indicates the output was read by a consumer block. However, there is no associated output port to indicate when the data can be consumed.
CAUTION:
You cannot use C/RTL co-simulation to verify designs that use ap_ack on an output port.

ap_vld

The ap_vld is a subset of the ap_hs interface type. The ap_vld port-level I/O protocol provides the following signals:

  • Data port
  • Valid signal to indicate when the data signal is valid and can be read
    • For input arguments, the design reads the data port as soon as the valid is active. Even if the design is not ready to read new data, the design samples the data port and holds the data internally until needed.
    • For output arguments, Vitis HLS implements an output valid port to indicate when the data on the output port is valid.

ap_ovld

The ap_ovld is a subset of the ap_hs interface type. The ap_ovld port-level I/O protocol provides the following signals:

  • Data port
  • Valid signal to indicate when the data signal is valid and can be read
    • For input arguments and the input half of inout arguments, the design defaults to type ap_none.
    • For output arguments and the output half of inout arguments, the design implements type ap_vld.