syn.directive.interface - 2025.2 English - UG1702

Vitis Reference Guide (UG1702)
Document ID
UG1702
Release Date
2025-11-20
Version
2025.2 English

Description

Only the top-level function supports the syn.directive.interface directive. You cannot use this directive for sub-functions of the HLS component. The INTERFACE pragma or directive specifies how function arguments creates RTL ports during interface synthesis. See the Defining Interfaces section of the Vitis High-Level Synthesis User Guide (UG1399). The Vitis HLS tool automatically determines the I/O protocol used by any sub-functions.

Ports in the RTL implementation come from the following elements.

  • 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 syn.interface.xxx commands (see Interface Configuration).
  • syn.directive.interface.

Each function argument can have its own I/O protocol (such as valid handshake or acknowledge handshake).

Tip: Global variables required on the interface must be explicitly defined as an argument of the top-level function as described in the Global Variables section of the Vitis High-Level Synthesis User Guide (UG1399). However, if a global variable is accessed, but all read and write operations are local to the design, the resource is created in the design. There is no need for an I/O port in the RTL.

The interface also defines the execution control protocol of the HLS component. See the Block-Level Control Protocols section of the Vitis High-Level Synthesis User Guide (UG1399) for details. 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

syn.directive.interface=[OPTIONS] <location> <port>
  • <location> is the location (in the format function[/label]) where the function interface or registered output can be specified.
  • <port> is the parameter (function argument) to synthesize the interface. You do not need the port name with these block control modes: ap_ctrl_chain, ap_ctrl_hs, or ap_ctrl_none.

Options

Tip: Many of the options below have default values defined with syn.interface.xxx commands. You can define local values for the interface defined here to override the default values.
mode=<mode>

The following three categories illustrate the modes and how the tool implements them in RTL.

  1. Port-Level Protocols:
    ap_none
    No port protocol. The interface is a simple data port.
    ap_stable
    No protocol. The interface is a simple data port. The Vitis HLS tool assumes the data port is always stable after reset. Allows optimizations to remove unnecessary registers.
    ap_vld
    Implements the data port with an associated valid signal to indicate when the data is valid for reading or writing.
    ap_ack
    Implements the data port with an associated acknowledge signal to acknowledge writing or reading of data.
    ap_hs
    Implements the data port with both valid and acknowledge signals to provide a two-way handshake to indicate when the data is valid for reading and writing. Acknowledges that the data was read or written
    ap_ovld
    Implements the output data port with an associated valid signal to indicate when the data is valid for reading or writing.
    Tip: For ap_ovld Vitis HLS implements the input argument or the input half of any read/write arguments with mode ap_none.
    ap_memory
    Implements array arguments as a standard RAM interface. If you use the RTL design in Vivado IP integrator, separate ports make up the interface.
    ap_fifo
    Implements the port with a standard FIFO interface using data input and output ports with associated active-Low FIFO empty and full ports.
    Note: You can only use the ap_fifo interface on read arguments or write arguments. ap_fifo mode does not support bidirectional read/write arguments.
  2. 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 the syn.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.
  3. Block-Level Control Protocols:
    ap_ctrl_chain
    Implements a set of block-level control ports to perform the following actions.
    • Star the design operation with start
    • Indicate when the design is idle
    • Indicate when the design is done
    • New input data with ready
    ap_ctrl_hs
    Implements a set of block-level control ports to start the design operation. Also indicates when the design is idle, done, and ready for new input data.
    ap_ctrl_none
    No block-level I/O protocol.
    Note: Using the ap_ctrl_none mode can prevent the design from being verified using C/RTL co-simulation.
bundle=<string>

By default, the HLS tool groups (or bundles) function arguments that are compatible into a single interface port in the RTL code. All interface ports with compatible options, such as mode, offset, and bundle, are grouped into a single interface port.

Tip: This default can be changed using the syn.interface.m_axi_auto_max_ports command.

The bundle=<string> option lets you define bundles to group ports together, overriding the default behavior. The <string> specifies the bundle name. A combination of the mode and bundle provides the port name in the generated RTL. The name can also specify the port name.

Important: You must specify bundle names using lower-case characters.
clock=<string>
By default, the AXI4-Lite interface clock is the same clock as the system clock. This option specifies a separate clock for an AXI4-Lite interface. If the bundle option groups multiple top-level function arguments into a single AXI4-Lite interface, you only need to specify the clock option on one of bundle members.
channel=<string>
To enable multiple channels on an m_axi interface specify the channel ID. Multiple m_axi interfaces can be combined into a single m_axi adapter using separate channel IDs.
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 needed to specify the size of pointer arguments for RTL co-simulation.
interrupt=<int>
Only ap_vld/ap_hs uses this option. This option enables managing of I/O in interrupt. This option creates the corresponding bits in the ISR and IER in the s_axilite register file. The integer value N=16..31 specifies the bit position in both registers. By default, the bit position is assigned contiguously from 16.
latency=<value>
This option can be used on ap_memory and m_axi interfaces.
  • In an ap_memory interface, the option specifies the read latency of the RAM resource driving the interface. The default is a read operation of 1 clock cycle. This option allows modeling of external RAM with more than 1 clock cycle of read latency.
  • In an m_axi interface the option specifies the expected latency of the AXI4 interface, allowing the design to initiate a bus request the specified number of cycles (latency) before the read or write is expected. If this figure it too low, the design can be ready too soon and can stall waiting for the bus. If this figure is too high, bus access can be idle waiting on the design to start the access.
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 the AXI Burst Transfers section of the Vitis High-Level Synthesis User Guide (UG1399) for more information.
max_write_burst_length=<int>
For use with the m_axi interface, this option specifies the maximum number of data values written during a burst transfer.
max_widen_bitwidth=<int>
Specifies the maximum bit width available for the interface when automatically widening the interface. This overrides the default value specified by the syn.interface.m_axi_max_bitwidth command. Refer to Automatic Port Width Resizing in the Vitis High-Level Synthesis User Guide (UG1399) for more information.
name=<string>
Specifies a name for the port for the generated RTL to use. A combination of the mode and bundle specifies the port name. The exception is if name specifies the name.
num_read_outstanding=<int>
For use with the m_axi interface, 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, and a FIFO of size:
num_read_outstanding*max_read_burst_length*word_size
num_write_outstanding=<int>
For use with the m_axi interface. This option specifies how many write requests the AXI4 bus can take, without a response, before the design stalls. This implies internal storage in the design, and 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 the config_interface -m_axi_offset option and <string>. See the following for details.
    • off: Does not generate an offset port.
    • direct: Generates a scalar input offset port.
    • slave: Generates an offset port and automatically map it to an AXI4-Lite slave interface. This is the default offset.
register
Registers the signal and any associated protocol signals. Instructs the signals to persist until at least the last cycle of the function execution. The syn.interface.register_io command controls default registering of all interfaces on the top function, while this option lets you override the default for the current interface. This option applies to the following interface modes:
  • s_axilite
  • ap_fifo
  • ap_none
  • ap_stable
  • ap_hs
  • ap_ack
  • ap_vld
  • ap_ovld
Tip: The register option cannot be used on the return port of the function (port=return). Use the syn.directive.latency instead.
register_mode=(both|forward|reverse|off)
This option applies to AXI4-Stream interfaces, and specifies if registers are placed on the following places.
  • Forward path (TDATA and TVALID), or
  • The reverse path (TREADY) on both paths, or
  • None of the ports signals (off).
The default is register_mode=both.
Tip: AXI4-Stream side-channel signals are data signals. The signals register whenever the TDATA is register.
storage_impl=<impl>
For use with mode=s_axilite only, this options defines a storage implementation to assign to the interface. Supported <impl> values include auto, bram, and uram. The default is auto.
Tip: uram is a synchronous memory with a single clock for two ports available only on certain devices. Therefore uram cannot be specified for an s_axilite adapter with two clocks, or when the specified part does not support uram.
storage_type=<type>

For use with mode=ap_memory or mode=bram only, this options defines a storage type (for example, RAM_T2P) to assign to the variable.

Supported types include: ram_1p, ram_1wnr, ram_2p, ram_s2p, ram_t2p, rom_1p, rom_2p, and rom_np.

Tip: For objects on the interface of the top-level function, you can define this option using syn.directive.bind_storage.

Example 1

This example disables function-level handshakes for function func.

syn.directive.interface=mode=ap_ctrl_none func return

Example 2

Argument InData in function func has a ap_vld interface. The input need to be registered.

set_directive_interface=func InData mode=ap_vld register

See Also