set_directive_interface

Description

Specifies how RTL ports are created from the function description during interface synthesis. For more information, see Managing Interface Synthesis. The ports in the RTL implementation are derived from:

  • Any function-level protocol that is specified.
  • Function arguments and return.
  • Global variables (accessed by the top-level function and defined outside its scope)

Function-level handshakes:

  • Control when the function starts operation.
  • Indicate when function operation:
    • Ends
    • Is idle
    • Is ready for new inputs

The implementation of a function-level protocol:

  • Is controlled by modes ap_ctrl_none, ap_ctrl_hs or ap_ctrl_chain.
  • Requires only the top-level function name.

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

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. If however, the global variable is expected to be an external source or destination, specify its interface in a similar manner as standard function arguments. See the examples below.

TIP: The Vitis HLS tool automatically determines the I/O protocol used by any sub-functions. You cannot specify the INTERFACE pragma or directive for sub-functions.

Syntax

set_directive_interface [OPTIONS] <location> <port>
  • <location> is the location (in the format function[/label]) where the function interface or registered output is to be specified.
  • <port> is the parameter (function argument or global variable) for which the interface has to be synthesized. This is not required when modes ap_ctrl_none or ap_ctrl_hs are used.

Options

-bundle <string>: Groups function arguments into AXI ports. By default, Vitis HLS groups all function arguments specified as an AXI4-Lite interface into a single AXI4-Lite port. Similarly, Vitis HLS groups all function arguments specified as an AXI4 interface into a single AXI4 port. The -bundle option explicitly groups all function arguments with the same <string> into the same interface port and names the RTL port <string>.

-clock <string>: 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: 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 Vitis HLS creates for RTL co-simulation. This option is required for pointer interfaces using ap_fifo mode.

-latency <value>: This option can be used on ap_memory and AXIM 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 cylce of read latency to be modeled.
  • In an AXIM 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 may stall waiting for the bus. If this figure is too high, bus access may be idle waiting on the design to start the access.

-max_read_burst_length: For use with the AXIM interface, this option specifies the maximum number of data values read during a burst transfer.

-max_write_burst_length: For use with the AXIM interface, this option specifies the maximum number of data values written during a burst transfer.

-mode (ap_none|ap_vld|ap_ack|ap_hs|ap_ovld|ap_fifo|ap_memory|bram|axis|s_axilite|m_axi|ap_ctrl_none|ap_ctrl_hs|ap_ctrl_chain|ap_stable)
Following is a summary of how Vitis HLS implements the -mode options. Refer to Interface Synthesis I/O Protocols for more information..
  • ap_none: No protocol. The interface is a data port.
  • ap_vld: Implements the data port with an associated valid port to indicate when the data is valid for reading or writing.
  • ap_ack: Implements the data port with an associated acknowledge port to acknowledge that the data was read or written.
  • ap_hs: Implements the data port with associated valid and acknowledge ports 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 associated valid port to indicate when the data is valid for reading or writing.
    Note: Vitis HLS implements the input argument or the input half of any read/write arguments with mode ap_none.
  • 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 this interface on read arguments or write arguments. The ap_fifo mode does not support bidirectional read/write arguments.
  • ap_memory: Implements array arguments as a standard RAM interface. If you use the RTL design in Vivado IP integrator, the memory interface appears as discrete ports.
  • bram: Implements array arguments as a standard RAM interface. If you use the RTL design in Vitis IP integrator, the memory interface appears as a single port.
  • axis: Implements all ports as an AXI4-Stream interface.
  • s_axilite: Implements all ports as an AXI4-Lite interface. Vitis HLS produces an associated set of C driver files during the Export RTL process.
  • m_axi: Implements all ports as an AXI4 interface. You can use the config_interface command to specify either 32-bit (default) or 64-bit address ports and to control any address offset.
  • ap_ctrl_none: No block-level I/O protocol.
    Note: Using the ap_ctrl_none mode might prevent the design from being verified using the C/RTL co-simulation feature.
  • ap_ctrl_hs: Implements a set of block-level control ports to start the design operation and to indicate when the design is idle, done, and ready for new input data.
    Note: The ap_ctrl_hs mode is the default block-level I/O protocol.
  • ap_ctrl_chain: Implements a set of block-level control ports to start the design operation, continue operation, and indicate when the design is idle, done, and ready for new input data.
  • ap_stable: No protocol. The interface is a data port. Vitis HLS assumes the data port is always stable after reset, which allows internal optimizations to remove unnecessary registers.
-num_read_outstanding: For use with the AXIM 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: For use with the AXIM interface, 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, and a FIFO of size:
num_read_outstanding*max_read_burst_length*word_size

-offset <string>: Controls the address offset in AXI4-Lite and AXI4 interfaces. In an AXI4-Lite interface, <string> specifies the address in the register map. In an AXI interface, <string> specifies the following:

  • 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.

-register: Registers the signal and any relevant protocol signals and instructs the signals to persist until at least the last cycle of the function execution. This option applies to the following scalar interfaces for the top-level function:

  • ap_none
  • ap_ack
  • ap_vld
  • ap_ovld
  • ap_hs
  • ap_fifo

-register_mode (both|forward|reverse|off): This option specifies if registers are placed on the forward path (TDATA and TVALID), the reserve path (TREADY), on both paths (TDATA, TVALID, and TREADY), or if none of the ports signals are to be registered (off). The default is both. AXI4-Stream side-channel signals are considered to be data signals and are registered whenever the TDATA is registered.

-storage_type=<type>: For use with ap_memory and bram interfaces only. This options defines a storage type (for example, RAM_T2P) to assign to the variable. Supported types include: fifo, ram_1p, ram_1wnr, ram_2p, ram_s2p, ram_t2p, rom_1p, rom_2p, rom_np.
TIP: This can also be specified using the BIND_STORAGE pragma or directive for the variable for objects not on the interface.

Examples

Turns off function-level handshakes for function foo.

set_directive_interface -mode ap_ctrl_none foo

Argument InData in function foo is specified to have a ap_vld interface and the input should be registered.

set_directive_interface -mode ap_vld -register foo InData

Exposes global variable lookup_table used in function foo as a port on the RTL design, with an ap_memory interface.

set_directive_interface -mode ap_memory foo look_table

See Also