Adding Hardware Interfaces - 2025.1 English - UG1701

General Requirements

• Every IP used in the platform design that is not part of the standard Vivado IP catalog should be local to the Vivado Design Suite project. References to IP repository paths external to the project are not supported when creating extensible XSA.
• Any platform interface, used for linking to kernels by the Vitis compiler, should be an AXI4, AXI4-Lite, AXI4-Stream, interrupt, clock, or reset type of interface.
  Note: Resets are optional, but must be associated with a clock when used.
• Any platform IP that has an AXI interface for linking to kernels by the Vitis compiler should also have associated clock pins to enable v++ to correctly infer and insert clock domain crossing logic when needed.

Adding Platform Interfaces

If a component in block design has a PFM property, this component can be recognized by the v++ linker and can be linked to Vitis components.

In the Vivado IDE, the platform interface (PFM) properties can be set in the Platform Setup tab if the project is created as an extensible platform project. Click Window menu > Platform Setup to open the settings.

Figure 1. Platform Setup

The four Platform Interface Tcl APIs include:

• AXI memory-mapped interfaces:

  set_property PFM.AXI_PORT { <port_name> {parameters} <port2> {parameters} ...} [get_bd_cells <cell_name>]

• AXI4-Stream interfaces:

  set_property PFM.AXIS_PORT { <port_name> {parameters} <port2> {parameters} ...} [get_bd_cells <cell_name>]

• Clocks and resets:

  set_property PFM.CLOCK { <port_name> {parameters} <port2> {parameters} ...} [get_bd_cells <cell_name>]

• Interrupts:

  set_property PFM.IRQ {pin_name {id id_number range irq_count}} [get_bd_cells <cell_name>]

The requirements for the PFM properties are:

• The value of the PFM interface properties must be specified as a Tcl dictionary, a list of name/"value" pairs.
  Important: The "value" must be quoted, and both the name and value are case-sensitive.
• A bd_cell can have multiple PFM interface definitions. However, for each type of PFM interface, all ports are required to be set in a single set_property Tcl command.
• For each PFM interface property, the name specified for the port object must match the name of an external port or interface on a bd_cell. Each external port or interface object can only have one PFM interface definition.
• Each different type of PFM interface can have different parameters.
• Setting the PFM property with a NULL ("") string deletes previously defined PFM interfaces.

Adding AXI-Stream Interfaces

To support AXI interfaces the platform needs to declare at least one AXI control interface with AXI memory-mapped master port (M_AXI) and one memory interface with AXI Slave port (S_AXI). They can be exported from the PS block directly or have an interconnect IP connected. If the platform does not support AXI4 kernels, these interfaces are not required.

The following is the Tcl command syntax:

set_property PFM.AXI_PORT { <port_name> {parameters} <port2> {parameters} ...} [get_bd_cells <cell_name>]

The AXI control interfaces and AXI memory interfaces share the same PFM.AXI property. They have different memport types.

Memport

AXI control interface can be defined as M_AXI_GP. Memory interfaces use other types:S_AXI_HP, S_AXI_ACP,S_AXI_HPC, S_AXI_NOC or MIG. The tag indicate how the port is intended to be used.

SP Tag ID

(Optional) A user-defined ID that should start with an alphabetic character. The ID is case-sensitive. The system port tag (sptag) is a symbolic identifier that represents a connection point to a platform resource, such as S_AXI_HP, S_AXI_ACP,... Multiple block design platform ports can share the same sptag. For more information on how sptags are used, see Mapping Kernel Ports to Memory.

Memory

(Optional) Specify the associated MIG IP instance and address_segment. The memory tag is a unique identifier that combines the Cell Name and Base Name columns in the IP integrator Address Editor. This tag is associated with connections to the Memory Subsystem HIP, where multiple block design platform ports can share the same memory tag.

This section outlines the requirements for exporting AXI interconnect master and slave ports on Versal, Zynq, and Zynq UltraScale+ MPSoC devices.

General Requirements

• All ports used within the platform must have a lower index than any declared platform interfaces.
• There should be no gaps in the port index numbering.
• The maximum number of master ports declared on an interconnect connected to an M_AXI_GP port is 64. Therefore, available master ports to declare must be one of {M00_AXI, M01_AXI, ..., M63_AXI}. Avoid declaring ports used within the platform itself.

AXI Ports

• The maximum number of master IDs for the S_AXI_ACP port is 8. Therefore, available master ports to declare must be one of {S00_AXI, S01_AXI, ..., S07_AXI}.
• The maximum number of master IDs for an S_AXI_HP, S_AXI_HPC, or MIG port is 16. Therefore, available master ports to declare must be one of {S00_AXI, S01_AXI, ..., S15_AXI}.
• Note: S_AXI_ACP, S_AXI_HPC, S_AXI_HP, and MIG ports are used for Zynq and ZynqMP devices
• The maximum number of master IDs for an S_AXI_NOC port is 28. Therefore, available master ports to declare must be one of {S00_AXI, S01_AXI, ..., S27_AXI}.
• S_AXI_NOC ports are only used for Versal devices. The maximum number is device dependent. Setting a lower number is used to deliberately constrain how many resources the design is allowed to use. Setting a higher number cause Vitis to share NMUs if resources are exhausted.

Following these requirements ensures that your exported AXI interconnect master and slave ports are compatible with the Vitis platform and avoids the use of cascaded interconnects.

The following Tcl script defines AXI master ports on AXI Interconnect IP:

set parVal []
for {set i 2} {$i < 64} {incr i} {
lappend parVal M[format %02d $i]_AXI \
{memport "M_AXI_GP"}
}
set_property PFM.AXI_PORT $parVal [get_bd_cells /axi_interconnect_0]

The following Tcl script defines AXI memory ports with MIG on SmartConnect IP:

set parVal []
for {set i 1} {$i < 16} {incr i} {
lappend parVal S[format %02d $i]_AXI 
{memport "MIG" sptag "Bank0"}
}
set_property PFM.AXI_PORT $parVal [get_bd_cells /smartconnect_0]

The following is an example of the PFM.AXI_PORT setting for control interface and memory interface for ZynqMP device.

set_property PFM.AXI_PORT {
M_AXI_HPM1_FPD {memport "M_AXI_GP"} 
S_AXI_HPC0_FPD {memport "S_AXI_HPC" sptag "HPC0" memory "zynq_ultra_ps_e_0 HPC0_DDR_LOW"}  
S_AXI_HPC1_FPD {memport "S_AXI_HPC" sptag "HPC1" memory "zynq_ultra_ps_e_0 HPC1_DDR_LOW"}  
S_AXI_HP0_FPD {memport "S_AXI_HP" sptag "HP0" memory "zynq_ultra_ps_e_0 HP0_DDR_LOW"}  
S_AXI_HP1_FPD {memport "S_AXI_HP" sptag "HP1" memory "zynq_ultra_ps_e_0 HP1_DDR_LOW"}  
S_AXI_HP2_FPD {memport "S_AXI_HP" sptag "HP2" memory "zynq_ultra_ps_e_0 HP2_DDR_LOW"}
} [get_bd_cells /ps_e]

The following is an example of the PFM.AXI_PORT setting for control interface and memory interface for Versal device.

set_property PFM.AXI_PORT {S00_AXI {memport "S_AXI_NOC" sptag "LPDDR"} S01_AXI {memport "S_AXI_NOC" sptag "LPDDR"} } [get_bd_cells /aggr_noc]

set_property PFM.AXI_PORT {M02_AXI {memport "M_AXI_GP" sptag "" memory ""} M03_AXI {memport "M_AXI_GP" sptag "" memory ""} M04_AXI {memport "M_AXI_GP" sptag "" memory ""}} [get_bd_cells /icn_ctrl_1]

Adding AXI Stream Interfaces

A platform can support AXI4-Stream connections to the Vitis subsystem. A PFM.AXIS_PORT attribute declares a platform stream attachment point for the v++ linker to connect PL kernels and AI Engine PLIOs, through the --connectivity.stream_connect (or --connectivity.sc) directive. Because AXI4-Streams are point-to-point, each such sptag must be unique.

The following is the Tcl command syntax:

set_property PFM.AXIS_PORT { <port_name> {type <type_value> sptag <sp_tag_value> is_range <true/false>} [get_bd_cells <cell_name>]

Argument Description

Port_name

AXI4-Stream port name.

Type

Type value: Streaming interface port type. Valid values for type include:

• M_AXIS: A AXI master port
• S_AXIS: A AXI slave port

SP Tag ID

A user-defined unique alphanumeric string that starts with an alphabetic character. The ID is case-sensitive. The system port tag (sptag) is a symbolic identifier that represents a connection point to a platform resource.

is_range

Metadata used by Vivado Integrated Design Environment (IDE).

Example

set_property PFM.AXIS_PORT {AXIS_P0 {type "S_AXIS" sp_tag "MY_AXIS_PORT0" is_range "false"}} [get_bd_cells /zynq_ultra_ps_e_0]

Figure 2. AXI4-Stream Register Slice

Adding Clocks and Resets

For information on AMD Versal™ device clocks, see Versal AI Core Series Data Sheet: DC and AC Switching Characteristics (DS957), Versal AI Edge Series Data Sheet: DC and AC Switching Characteristics (DS958), Versal Prime Series Data Sheet: DC and AC Switching Characteristics (DS956) and Versal Premium Series Data Sheet: DC and AC Switching Characteristics (DS959).

Figure 3. Platform Setup – Clock

You can export any clock source with the platform, but for each clock you must also export synchronized reset signals using a Processor System Reset IP block in the platform. For details of defining clocks and resets, see the Vitis-Tutorials/Vitis_Platform_Creation. The PFM.CLOCK property can be set on a BD cell, external port, or external interface.

In the preceding figure you can see the details of the platform clocks. There must be at least one clock enabled for the platform and one clock chosen as the default.

The following is the Tcl command for setting the PFM.CLOCK property:

set_property PFM.CLOCK { <port_name> {parameters} \
<port2> {parameters} ...} [get_bd_cells <cell_name>]

Clock Wizard Configuration in Vivado

When setting the clock configuration in the Vivado design using the clock wizard IP, the following rules are a recommended practice.

Figure 4. Clock Wizard - Output Clocks Configuration

• Using MBUFGCE:

  • Use MBUFGCE along with HARDSYNC option to lower clock skew.
  • When generating specific clock frequencies using MBUFGCE (for example, 1/1, 1/2, 1/4, and 1/8), it is recommended to use them with the HARDSYNC option. However, MBUFGCE clocks cannot be used as reference clocks for further clock generation.
  • In the Versal VCK190 base platform, the clocks with frequencies 625, 312.5, 156.25, and 78.125 MHz generated by MBUFGCE should not be used as reference clocks.
  • For example, if you need a 625 MHz reference clock, use the clk_out3 clock generated by BUFG instead of the clk_out4_o1_o1 clock generated by MBUFGCE. The former originates directly from the MMCM, while the latter uses MBUFGCE for enhanced skew control.
  Figure 5. Platform Setup:Clock Status Attribute
  
  

• PFM.CLK Status:

  • Clocks designated as fixed_non_refclocks can be used directly by IPs, however, cannot be used as a reference clock.

  • Clocks designated as fixed clocks can be used as reference clocks or directly by IPs.

  • The Tcl script to set the PFM clock attributes is as follows: set_property PFM.CLOCK ....... clk_out7 {id "6" is_default"false" proc_sys_reset"/psr_625mhz" status "fixed_non_ref"freq_hz "625000000"}} [get_bd_cells/clk_wizard_0]

Adding Interrupts

The Vitis linker automatically connects the kernel interrupt signal to an IRQ in the platform during the v++ linking stage. However, this requires the interrupts on the platform to be defined using the PFM.IRQ property as shown below:

set_property PFM.IRQ {pin_name {id id_number}} bd_cell
set_property PFM.IRQ {port_name {id id_number range irq_count}} [get_bd_cell <cell_name>]

Argument Description

Port_name

IRQ port name of bd_cell.

id_number

Integer from 0 to 127 to specify the IRQ number or the starting number if range is specified.

irq_count

Used for labeling interfaces that are otherwise subject to parameter propagation for specifying sizing of a bus (for example, interrupt controller intr interface).

The example shows how to enable 32 IRQ inputs to axi_intc_0 intr port.

set_property PFM.IRQ {intr {id 0 range 32}} [get_bd_cells /axi_intc_0]

The interrupts for AMD Versal™ CIPS IP core can be found on the IP customization dialog box by selecting the PS PMC configuration command and selecting Interrupts. Here you can enable the interrupts on the CIPS IP for use on the platform. Then you must enable the interrupts on the platform for connection by v++ during linking. On the Platform Setup tab of the Block Design, select Interrupt and then enable the visible interrupts on the CIPS IP as shown below. Refer to Creating a Hardware Platform for the Platform-Based Design Flow of the Versal Adaptive SoC Hardware, IP, and Platform Development Methodology Guide (UG1387) for more information.

Figure 6. Platform Setup – Interrupt

set_property PFM.IRQ {pl_ps_irq9 {is_range "false"} pl_ps_irq10 {is_range "false"}} [get_bd_cells /versal_cips]