Defining the Interface Specification - 2024.1 English

Vitis Model Composer User Guide (UG1483)

Document ID
Release Date
2024.1 English

Within the Simulink® environment, the inputs and outputs in your design are defined using "Inport" and "Outport" blocks. However, while moving from the software algorithm to an RTL implementation in hardware, these same input and output ports must be mapped to ports in the design interface, using a specific input-output (I/O) protocol, which typically operates with some real world delay. Part of developing your design is to specify how your design will communicate with other designs or IP in the system. You do this by specifying the interface to your design and choosing among a few standard I/O protocols.

Model Composer requires the use of the Interface Specification (Interface Spec) block to define this I/O protocol.

Interface synthesis is supported only in the top-level subsystem module in the design, which Model Composer generates C++ code for. In the following figure, the Edge Detection module is the top-level subsystem module and the Interface Spec block must be instantiated inside that module.

Tip: Any Interface Spec blocks instantiated in other subsystems modules, or nested subsystem modules are ignored.
Figure 1. Top-Level Subsystem Module Generated by Your Tool

The Interface Spec block lets you control what interfaces should be used for the design. The Interface Spec affects only output code generation; it has no effect on Simulink simulation of your design. If you do not add an Interface Spec block to the subsystem module, Model Composer assigns default interfaces that might not be appropriate for the target platform or device. Therefore, it is recommended that you use the Interface Spec block to define the requirements of your subsystem module. The default function-level protocol is Handshake to specify control signals, and AXI4-Lite Slave for the function return. The default I/O protocol is AXI4-Lite Slave for scalar ports, and AXI4-Stream for non-scalar ports.

The Interface Spec block specifies how RTL ports are created from the function definition during interface synthesis. The ports in the RTL implementation are derived from the following.

  • Any function-level protocol that defines control signals for the module.
  • Function input and output arguments, and return values.
  • Global variables accessed by the function but defined outside its scope.
    Note: If a global variable is accessed, but all read and write operations are local to the subsystem, the resource is created in the design, and does not require the definition of a port.
Figure 2. Interface Spec Block Generated by Your Tool
The Interface Spec block consists of three tabs defining the following information:
Function Protocol
This is the block-level interface protocol which adds signal ports to the subsystem telling the IP when to start processing data. It is also used by the IP to indicate whether it accepts new data, or whether it has completed an operation, or whether it is idle.
Input Ports
This tab automatically detects the input ports in your subsystem and lets you specify the interface protocol on those ports.
Output Ports
This tab automatically detects the output ports on the subsystem module, and lets you specify the interface protocol.
Important: The Interface Spec block has a current limitation of 8 input ports and 8 output ports on the subsystem module.

The Interface Specification displays and lets you configure the following features or parameters of the function or I/O port protocol.

Table 1. Function Protocol Tab
Attribute Description
Mode Specifies a block-level protocol to add control signals to the subsystem module. The supported block-level protocols are:
  • AXI4-Lite Slave: Implements the return port as an AXI4-Lite Slave interface, and adds the block-level control ports defined by the Handshake protocol. This is the default function protocol.
  • Handshake: Defines a set of block-level control ports for the function to start processing input, and indicate when the design is idle, done, and ready for new input data.
  • No block-level I/O protocol: No control ports are added to the subsystem.
Bundle Only valid with the AXI4-Lite Slave mode. Indicates that multiple ports should be grouped into the same interface. The bundle is specified by a <name> that cannot contain spaces or special characters.
Table 2. Input/Output Port Tabs
Attribute Description
Name Displays the port name, which cannot be changed from here.
Mode Specifies the port-level I/O protocols. The supported port-level protocols are:
  • Default: Uses AXI4-Lite Slave interface for scalar ports, or AXI4-Stream interface for non-scalar ports.
  • AXI4-Stream: Implements ports as an AXI4-Stream interface for high-speed streaming data.
  • AXI4-Stream (video): Implements ports as an AXI4-Stream interface, with the additional assignment of Video Format and Video Component attributes.
  • AXI4-Lite Slave: Implements the port as part of an AXI4-Lite Slave interface. All input or output ports with the same Bundle name are grouped into the same AXI4-Lite Slave interface.
  • FIFO: Implements the port with a standard FIFO interface, combining data input or output with associated active-Low FIFO empty and full control signals.
    Note: The FIFO interface is the most hardware-efficient approach for access to a memory element that is always sequential, that is, no random access is required. To read from non-sequential address locations, use the Block RAM interface.
  • Constant: The data applied to the input port remains stable during the function operation, but is not a constant value that can be optimized. This allows internal optimizations to remove unnecessary registers.
  • Valid Port: Implements a data port with an associated valid port to indicate when the data is valid for reading or writing.
  • No protocol: No protocol. Neither the input or output data signals have associated control ports to indicate when data is read or written.
  • Block RAM: Implements array arguments as a standard RAM interface. If you use the generated IP in Vivado IP integrator, the memory interface appears as a single port.

Used with the AXI4-Stream (video) interfaces that have more than one color component. In this case there should be one port for each color component, and the ports should specify the same bundle <name> so they will be grouped into the same AXI4-Stream (video) interface.

Also valid with the AXI4-Lite Slave mode. This parameter explicitly groups all interface ports with the same bundle <name> into the same AXI4-Lite Slave interface.

Offset Only valid with the AXI4-Lite Slave mode. This parameter specifies an address offset associated with the port in the AXI4-Lite Slave address map. The offset is specified as a non-negative integer, with a default value of 0.
Video Format Only valid with the AXI4-Stream (video) mode. This parameter specifies the color format for a video stream. Valid formats include:
  • YUV 4:2:2: Video format based on brightness (luminance) and color (chrominance), with reduced color content.
  • YUV 4:4:4: Video format based on brightness (luminance) and color (chrominance), with full color content.
  • RGB: Video format based on separate Red, Blue, and Green color signals.
  • Mono: Specifies an audio format for your video.
Video Component Only valid with the AXI4-Stream (video) mode. This parameter specifies the color component for a video format that uses more than one color component. Valid video components include:
  • Y, U, V: Specifies one component of the YUV video format.
  • R, G, B: Specifies one component of the RGB video format.

The choice of port-level interface protocol should take into account the following considerations:

  • Scalar ports can be implemented using any of the following protocols: Default, AXI4-Lite Slave, Constant, Valid Port, No protocol.
  • Large array or matrix ports should use a streaming protocol such as AXI4-Stream, FIFO, or AXI4-Stream (video).
  • Video signals can be transported over an AXI4-Stream (video) interface. In this case you also need to specify the video format YUV 4:2:2, YUV 4:4:4, RGB, or Mono. For video formats that have more than one color component, you also need to assign multiple ports to the same signal bundle, and you need to specify which port carries which color component. All of the ports that make up the video signal are implemented by a single AXI4-Stream interface that includes start-of frame and end-of-line sideband signals. For more information refer to AXI4-Stream Video IP and System Design Guide (UG934).