Description
The INTERFACE pragma or directive is only supported for use on the top-level function, and cannot be used for sub-functions of the HLS component. It specifies how RTL ports are created from the function arguments during interface synthesis, as described in Defining Interfaces. The Vitis HLS tool automatically determines the I/O protocol used by any sub-functions.
Ports in the RTL implementation are derived from the data type and
direction of the arguments of the top-level function and function return, the flow_target
for the HLS component, the default interface
configuration settings as specified by config_interface,
and by the INTERFACE pragma or directive. Each function argument can be specified to have
its own I/O protocol (such as valid handshake or acknowledge handshake).
The interface also defines the execution control protocol of the HLS component as described in Block-Level Control Protocols. The control protocol controls when the HLS component (or block) starts execution, and when the block completes operation, is idle and ready for new inputs.
Syntax
Place the pragma within the boundaries of the function.
#pragma HLS interface mode=<mode> port=<name> [OPTIONS]
Where:
-
mode=<mode>
-
The supported modes, and how the tool implements them in RTL, can be broken down into three categories as follows:
-
Port-Level
Protocols:
-
ap_none
: No port protocol. The interface is a simple data port. -
ap_vld
: Implements the data port with an associatedvalid
signal to indicate when the data is valid for reading or writing. -
ap_ack
: Implements the data port with an associatedacknowledge
signal to acknowledge that the data was read or written. -
ap_hs
: Implements the data port with bothvalid
andacknowledge
signals to provide a two-way handshake to indicate when the data is valid for reading and writing and to acknowledge that the data was read or written. -
ap_ovld
: Implements the output data port with an associatedvalid
signal to indicate when the data is valid for reading or writing.Tip: Forap_ovld
Vitis HLS implements the input argument or the input half of any read/write arguments with modeap_none
. -
ap_memory
: Implements array arguments as a standard RAM interface. If you use the RTL design in Vivado IP integrator the interface is composed of separate ports. -
bram
: Implements array arguments as a standard RAM interface. If you use the RTL design in Vivado IP integrator the memory interface is composed of a single port. -
ap_fifo
: Implements the port with a standard FIFO interface using data input and output ports with associated active-Low FIFOempty
andfull
ports.Note: You can only use theap_fifo
interface on read arguments or write arguments.ap_fifo
mode does not support bidirectional read/write arguments.
-
-
AXI Interface
Protocols:
-
s_axilite
: Implements the port as an AXI4-Lite interface. The tool produces an associated set of C driver files when exporting the generated RT for the HLS component. -
m_axi
: Implements the port as an AXI4 interface. You can use theconfig_interface -m_axi_addr64
command to specify either 32-bit (default) or 64-bit address ports and to control any address offset. -
axis
: Implements the port as an AXI4-Stream interface.
-
-
Block-Level Control Protocols:
-
ap_ctrl_chain
: Implements a set of block-level control ports tostart
the design operation,continue
operation, and indicate when the design isidle
,done
, andready
for new input data. -
ap_ctrl_hs
: Implements a set of block-level control ports tostart
the design operation and to indicate when the design isidle
,done
, andready
for new input data. -
ap_ctrl_none
: No block-level I/O protocol.Note: Using theap_ctrl_none
mode might prevent the design from being verified using C/RTL co-simulation.
-
-
Port-Level
Protocols:
-
port=<name>
- Specifies the name of the function argument or function return which
the INTERFACE pragma applies to.Tip: Block-level I/O protocols (
ap_ctrl_none
,ap_ctrl_hs
, orap_ctrl_chain
) can be assigned to a port for the functionreturn
value.
Options
-
bundle=<string>
- By default, the HLS tool groups or bundles function arguments with
compatible options into interface ports in the RTL code. All AXI4-Lite (
s_axilite
) interfaces are bundled into a single AXI4-Lite port whenever possible. Similarly, all function arguments specified as an AXI4 (m_axi
) interface are bundled into a single AXI4 port by default. -
channel=<string>
- To enable multiple channels on an
m_axi
interface specify the channel ID. Multiplem_axi
interfaces can be combined into a singlem_axi
adapter using separate channel IDs. -
clock=<name>
- By default, the AXI4-Lite
interface clock is the same clock as the system clock. This option is used to set
specify a separate clock for an AXI4-Lite interface.
If the
-bundle
option is used to group multiple top-level function arguments into a single AXI4-Lite interface, the clock option need only be specified on one of bundle members. -
depth=<int>
- Specifies the maximum number of samples for the test bench to
process. This setting indicates the maximum size of the FIFO needed in the verification
adapter that the HLS tool creates for RTL co-simulation.Tip: While
depth
is usually an option, it is required form_axi
interfaces and determines the amount of resources allocated for the adapter as explained in AXI4 Master Interface. -
interrupt=<int>
- Only used by
ap_vld
/ap_hs
. This option enables the I/O to be managed in interrupt, by creating the corresponding bits in theISR
andIER
in thes_axilite
register file. The integer value N=16..31 specifies the bit position in both registers (by default assigned contiguously from 16). -
latency=<value>
- This option can be used on
ap_memory
and M_AXI interfaces.- In an
ap_memory
interface, the interface option specifies the read latency of the RAM resource driving the interface. By default, a read operation of 1 clock cycle is used. This option allows an external RAM with more than 1 clock cycle of read latency to be modeled. - In an M_AXI interface, this option specifies the expected latency of the AXI4 interface, allowing the design to initiate a bus request <value> number of cycles (latency) before the read or write is expected. If this figure it too low, the design will be ready too soon and might stall waiting for the bus. If this figure is too high, bus access might be idle waiting on the design to start the access.
- In an
-
max_read_burst_length=<int>
- For use with the M_AXI interface, this option specifies the maximum number of data values read during a burst transfer. Refer to AXI Burst Transfers for more information.
-
max_write_burst_length=<int>
-
- For AXI4 (
m_axi
) interfaces, this option specifies the maximum number of data values written during a burst transfer.Tip: If the port is a read-only port, then set thenum_write_outstanding=1
andmax_write_burst_length=2
to conserve memory resources. For write-only ports, set thenum_read_outstanding=1
andmax_read_burst_length=2
.
- For AXI4 (
-
max_widen_bitwidth=<int>
- Specifies the maximum bit width available for the interface when
automatically widening the interface. This overrides the global value specified by the
config_interface -m_axi_max_bitwidth
command. -
name=<string>
- Specifies a name for the port which will be used in the generated RTL.
-
num_read_outstanding=<int>
- For AXI4 (
m_axi
) interfaces, this option specifies how many read requests can be made to the AXI4 bus, without a response, before the design stalls. This implies internal storage in the design, a FIFO of size:num_read_outstanding*max_read_burst_length*word_size
-
num_write_outstanding=<int>
- For AXI4 (
m_axi
) interfaces, this option specifies how many write requests can be made to the AXI4 bus, without a response, before the design stalls. This implies internal storage in the design, a FIFO of size:num_write_outstanding*max_write_burst_length*word_size
-
offset=<string>
- Controls the address offset in AXI4-Lite (
s_axilite
) and AXI4 memory mapped (m_axi
) interfaces for the specified port.- In an
s_axilite
interface,<string>
specifies the address in the register map. - In an
m_axi
interface this option overrides the global option specified by theconfig_interface -m_axi_offset
option, and<string>
is specified as:-
off
: Do not generate an offset port. -
direct
: Generate a scalar input offset port. -
slave
: Generate an offset port and automatically map it to an AXI4-Lite slave interface. This is the default offset.
-
- In an
-
register
- An optional keyword to register the signal and any relevant protocol
signals, and causes the signals to persist until at least the last cycle of the function
execution. The
-register_io
option of theconfig_interface
command globally controls registering all inputs/outputs on the top function. This option applies to the following interface modes:-
s_axilite
-
ap_fifo
-
ap_none
-
ap_hs
-
ap_ack
-
ap_vld
-
ap_ovld
-
-
register_mode=<forward|reverse|both|off>
- This option applies to AXI4-Stream interfaces, and specifies if registers are placed on the forward path (
TDATA
andTVALID
), the reverse path (TREADY
), on both paths (TDATA
,TVALID
, andTREADY
), or if none of the ports signals are to be registered (off
). The default isboth
. AXI4-Stream side-channel signals are considered to be data signals and are registered whenever theTDATA
is registered. -
storage_impl=<impl>
- For use with
s_axilite
only. This options defines a storage implementation to assign to the interface. -
storage_type=<value>
- For use with
ap_memory
andbram
interfaces only. This options specifies a storage type (that is, RAM_T2P) to assign to the variable.
Example 1
In this example, both function arguments are implemented using an AXI4-Stream interface:
void example(int A[50], int B[50]) {
//Set the HLS native interface types
#pragma HLS INTERFACE mode=axis port=A
#pragma HLS INTERFACE mode=axis port=B
int i;
for(i = 0; i < 50; i++){
B[i] = A[i] + 5;
}
}
Example 2
The following turns off block-level I/O protocols, and is assigned to the function return value:
#pragma HLS interface mode=ap_ctrl_none port=return
The function argument InData
is
specified to use the ap_vld
interface and also indicates
the input should be registered:
#pragma HLS interface mode=ap_vld register port=InData
Example 3
This example defines the INTERFACE standards for the ports of the
top-level transpose
function. Notice the use of the
bundle=
option to group signals.
// TOP LEVEL - TRANSPOSE
void transpose(int* input, int* output) {
#pragma HLS INTERFACE mode=m_axi port=input offset=slave bundle=gmem0
#pragma HLS INTERFACE mode=m_axi port=output offset=slave bundle=gmem1
#pragma HLS INTERFACE mode=s_axilite port=input bundle=control
#pragma HLS INTERFACE mode=s_axilite port=output bundle=control
#pragma HLS INTERFACE mode=s_axilite port=return bundle=control
#pragma HLS dataflow