set_directive_interface - 2023.1 English - UG1399

Description

set_directive_interface is only supported for use on the top-level function, and cannot be used for sub-functions of the HLS component. The INTERFACE pragma or directive 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 this 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

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) for which the interface has to be synthesized. The port name is not required when block control modes are specified: ap_ctrl_chain, ap_ctrl_hs, or ap_ctrl_none.

Options

mode=<mode>

The supported modes, and how the tool implements them in RTL, can be broken down into three categories as follows:

1. Port-Level Protocols:
   • ap_none: No port protocol. The interface is a simple data port.
   • 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 that the data was read or written.
   • 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 and to acknowledge 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 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 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 config_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 start the design operation, continue operation, and indicate when the design is idle, done, and ready for new input data.
   • 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.
   • ap_ctrl_none: No block-level I/O protocol.
     Note: Using the ap_ctrl_none mode might 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 config_interface -m_axi_auto_max_ports command.

This -bundle <string> option lets you define bundles to group ports together, overriding the default behavior. The <string> specifies the bundle name. The port name used in the generated RTL code is derived automatically from a combination of the mode and bundle, or is named as specified by name.

Important: bundle names must be specified using lower-case characters.

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

-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 <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 for m_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 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 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.

-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 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 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. By default the port name is derived automatically from a combination of the mode and bundle unless specified by 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 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_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> 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.

-register

Registers the signal and any associated protocol signals and instructs the signals to persist until at least the last cycle of the function execution. The -register_io option of the config_interface command globally controls registering all inputs/outputs on the top function. This option applies to the following scalar interfaces for the top-level function:

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

Tip: The use of the register option on the return port of the function (port=return) is not supported. Instead use the LATENCY pragma or directive:

#pragma HLS LATENCY min=1 max=1

-register_mode (both|forward|reverse|off)

This option applies to AXI4-Stream interfaces, and specifies if registers are placed on the forward path (TDATA and TVALID), the reverse 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_impl=<impl>

For use with s_axilite only. This options defines a storage implementation to assign to the interface.

Supported implementation values include auto, bram, and uram. The default is auto.

Tip: uram is a synchronous memory with only a single clock for two ports. Therefore uram cannot be specified for an s_axilite adapter with a second clock.

-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: ram_1p, ram_1wnr, ram_2p, ram_s2p, ram_t2p, rom_1p, rom_2p, and rom_np.

Tip: This can also be specified using the BIND_STORAGE pragma or directive for the variable for objects that are not defined on the interface.

Examples

Turns off function-level handshakes for function func.

set_directive_interface -mode ap_ctrl_none func

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

set_directive_interface -mode ap_vld -register func InData

See Also

• pragma HLS interface
• set_directive_bind_storage