Linking a VSS Component - Linking a VSS Component - 2026.1 English - UG1701

Hierarchical VSS

The Vitis subsystem provides hierarchical constructs for organizing complex designs, which allow multiple VSS components within a single VSS. You can arrange PL kernels within these VSS components. You must create each VSS component independently before adding it to another VSS component.

You can include multiple independently compiled AI Engine graphs, each of which defines a soft partition. A Versal AI Engine design can contain only a single instance of the AI Engine IP.

When you integrate 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.

The following example shows how VSS and kernel instance names resolve in a hierarchical use case.

Figure 1. Hierarchical VSS Example

The innermost VSS component vss_a contains an RTL kernel with instance name my_rtl_kernel_0.

The VSS component vss_b instantiates vss_a and an HLS kernel named my_hls_kernel_0.

In this example, the AI Engine defines a single graph.

The graph includes one input port named in0 and one output port named out0.

The top-level VSS component vss_top contains 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
# Connect a kernel in vss_a to a 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

# Use flattened names when connecting ports to instances:
# Connections in vss_top
sc=my_rtl_kernel_1.port_out0:ai_engine_0.in0
# Connect from vss_top through vss_b into vss_a to reach the RTL kernel
sc=ai_engine_0.out0:vss_b_vss_a_my_rtl_kernel_0.port_in0
# Connect a kernel in vss_b to a kernel in vss_top
sc=vss_b_my_hls_kernel_0.port_out0:my_hls_kernel_1.port_in0

Inferring a Software-Controllable Subsystem Reset

This feature allows the Vitis linker to infer a hardware-controllable and software-controllable reset network for the VSS.

The following example enables the VSS reset through a configuration file:

[advanced]
param=compiler.enableVssReset=true

The following example enables the VSS reset on the command line:

v++ -l --mode vss --advanced.param compiler.enableVssReset=true

The following figures show the result of enabling the VSS reset on the Versal Vitis Subsystem Flow tutorial.

Figure 2. Example Before Inferring the VSS Reset

The example uses two clock domains. Rebuilding with the VSS reset enabled inserts two processor system reset blocks and one AXI4-Lite instance.

Figure 3. Example After Inferring the VSS Reset

Asserting aresetn on the vss_top_rst instance puts the VSS in reset. You can also control each reset from software by writing gen_reset=1 to assert reset or gen_reset=0 to release reset.

For VSS designs that include AI Engine, the reset procedure requires reloading aie.pdi before you write 0 to the gen_reset register. Reloading ensures that all internal states are in a known relationship to the PL after reset.

VSS reset networks are generated only at platform integration time and, consequently, are global to all subcomponents of the VSS.

Generating the VSS Component

You generate the VSS archive with the linker using --mode vss. The following example shows the command:

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>