Linking a VSS Component - 2025.1 English

Linking a VSS Component - 2025.1 English - UG1701

Embedded Design Development Using Vitis User Guide (UG1701)

Document ID

UG1701

Release Date

2025-07-16

Version

2025.1 English

A Vitis Subsystem (VSS) is a platform-independent, reusable design component that can be customized with AI Engine and PL content. The VSS is integrated into a larger system using Vitis tools.

A configuration file is used to declare the specific PL kernels and AI Engine graphs to be used, as well as the interface connections between the kernels and graphs. The syntax is similar to how the Vitis linker connects components to an extensible platform, except with the additional declaration of kernels, graph, or other VSS components to be added to a VSS component. The VSS component can be defined as follows:

vss=amd.com:<vss_library_name>:<vss_component_name>:<version_number>:<list_of_instances of PL kernels and/or AI Engine graphs>

[connectivity]
nk=producer:2:p0,p1
nk=consumer:2:c0,c1

vss=amd.com:myLib:MyVSSComponent:1.0:p0,p1,c0,c1,ai_engine_0

stream_connect=p0.outs:c0:ins
stream_connect=p1:outs:ai_engine_0.si_0
stream_connect=ai_engine_0.so_0:c1:ins

Table 1. Description of the VSS Component Syntax
Item	Example	Description
vss_library_name	my_vss_lib	Identifier name to associate the VSS to a library.
vss_component_name	vss_top	Will be used as VSS archive name and concatenated with instance names to provide unique name when integrating VSS component to an extensible platform.
version_number	1.0	To keep track of library/component version.
list_of_instance	counter_0,ai_engine_0	Comma separated list of instance names. The names need to match kernel names declared with "nk" in the config file. Note: The ai_engine_0 instance name need to match the default AI Engine IP instance name in the Vivado HW platform.

Hierarchical VSS

The Vitis subsystem provides hierarchical constructs for organizing complex designs, allowing for multiple VSS components within a single VSS. PL kernels can be arranged within these VSS components. Each of these VSS components must be created independently before adding them in another VSS component.

To handle multiple independent AI Engine graphs, consider using the AI Engine partition feature. Every AI Engine partition must be prepended by the AI Engine instance IP name. There can only be a single instance of the AI Engine IP in a Versal AI Engine design.

During integration of a VSS component into another VSS or platform, the compiler flattens the design and resolves instance names by prepending the corresponding VSS component names based on the hierarchical structure.

Important: Proper naming convention for the kernels and VSS components is important when resolving the flattened instance name. Choose the names with care to avoid ambiguity.

The following example illustrates how VSS and kernel instance names are resolved in a hierarchical use case.

Figure 1. Hierarchical VSS Example

The innermost VSS component vss_a contains a RTL kernel with instance name my_rtl_kernel_0. The VSS component vss_b instantiates vss_a and a HLS kernel my_hls_kernel_0. In this example, the AI Engine contains a single graph with one input port named in0 and one output port named out0. It is placed in the VSS component vss_top together with vss_b, my_rtl_kernel_1 and my_hls_kernel_1.

# Declare VSS component A
vss=amd.com:my_vss_lib:vss_a:1.0:my_rtl_kernel_0

# Declare hierarchical VSS component B
vss=amd.com:my_vss_lib:vss_b:1.0:my_hls_kernel_0,vss_a
# Establish connection from kernel in vss_a  to kernel in vss_b
sc=vss_a_my_rtl_kernel_0.port_out0:my_hls_kernel_0.port_in0

# Declare  hierarchical VSS component top
vss=amd.com:my_vss_lib:vss_top:1.0:ai_engine_0,my_rtl_kernel_1,my_hls_kernel_1,vss_b

# Flattened names are used when connecting ports to instances:
# Connections in vss_top
sc=my_rtl_kernel_1.port_out0:ai_engine_0.in0
# Establish connection from vss_top  through vss_b into vss_a to connect to the RTL kernel
sc=ai_engine_0.out0:vss_b_vss_a_my_rtl_kernel_0.port_in0
# Establish connection from vss_b kernel  to kernel in vss_top
sc=vss_b_my_hls_kernel_0.port_out0:my_hls_kernel_1.port_in0

Generating the VSS Component

The VSS archive is generated using the linker with --mode vss. An example command is shown below:

v++ --link --mode vss --save-temps --part <part_name> --config ./src/vss_conn.cfg <list_of_xo> <list_of_libadf_partitions> --out_dir <build_folder>

Table 2. Description of Files and Folders Created When Generating a VSS Component
Folder	Files	Description
<build_folder>	`.log`, `.link_summary`	Output folder containing log files and summary from v++ linker.
<build_folder>/<vss_component_name>	`<vss_component_name>.vss`	VSS Component archive.
	`*.a`	AIE graph libadf files.
	`*.xo`	RTL and HLS packaged kernels.
<build_folder>/<vss_component_name>/ip_repo/*		Folders with files associated with packaged HLS and RTL kernels.
<build_folder>/<vss_component_name>/VitisRegion		Blockdesign metadata for VitisRegion.
<build_folder>/_x		Temporary work folder for v++ linker.