Linking the System - 2022.1 English - UG1076

Versal ACAP AI Engine Programming Environment User Guide (UG1076)
Document ID
UG1076
Release Date
2022-05-25
Version
2022.1 English

After the AI Engine graph and the C/C++ kernels are compiled, and any RTL kernels are packaged, the Vitis v++ --link command links them with the target platform to build the platform file (XSA), used to package the design. For more information, see Linking the Kernels in the Application Acceleration Development flow of the Vitis Unified Software Platform Documentation .

The following is an example of the linking command for the Vitis compiler in the AI Engine design flow.

v++ --link -t hw_emu --platform xilinx_vck190_base_202210_1 -g \
<pl_kernel1>.xo <pl_kernel2>.xo ../libadf.a -o vck190_aie_graph.xsa \
--config ../system.cfg --save-temps

The v++ command uses the options in the following table.

Table 1. Vitis Compiler Link Options
Option Description
--link Specifies the linking process.
-t hw_emu Specifies the build target of the link process. For the AI Engine kernel flow, the target can be either hw_emu for emulation and test, or hw to build the system hardware.
Important: The v++ compilation and linking commands must use both the same build target (-t) and the same target platform (--platform).
--platform Specifies the path to the target platform.
-g Specifies the addition of debugging logic required to enable debug (for hardware emulation) and to capture waveform data.
<pl_kernel1>.xo <pl_kernel2>.xo Specifies the input compiled PL kernel object files (.xo) to link with the AI Engine graph and the target platform.
../libadf.a Specifies the input compiled AI Engine graph application to link with the PL kernels and the target platform.
-o Specifies the platform (XSA) file that is the output of the linking process.
--config Specifies a configuration file to define some of the compilation or linking options. 1
--save-temps Indicates that the temporary files created during the build process should be preserved for later examination or use. This includes output files created by Vitis HLS and the Vivado Design Suite.
  1. The --config option is used to simplify the v++ command line by moving many commands with extended syntax into a file that can be specified from the command line. For more information, see the Vitis Compiler Configuration file in the Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393).
Tip: The config file requirements for the command line are different from the requirements of the Vitis IDE, as discussed in Configuring the HW-Link Project.

For the AI Engine kernel flow, the Vitis compiler requires one specific section in the configuration file:[connectivity]. The following is an example configuration file.

[connectivity]
nk=mm2s:1:mm2s
nk=s2mm:1:s2mm
stream_connect=mm2s.s:ai_engine_0.DataIn1
stream_connect=ai_engine_0.DataOut1:s2mm.s

The [connectivity] section of the configuration file has options described in the following table.

Table 2. Connectivity Section Options
Option Description
nk Specifies the number of kernel- instances or CUs the v++ command adds to the platform (XSA) file.

The nk option specifies the kernel name, the number of instances, or CUs of that kernel, and the CU name for each instance. In the example, nk=mm2s:1:mm2s specifies the kernel mm2s should only have one instance and that instance should be called mm2s.

Multiple instances of the kernels are specified as nk=mm2s:2:mm2s_1.mm2s_2. This indicates that mm2s should have two CUs called mm2s_1 and mm2s_2. For more information, see Creating Multiple Instances of a Kernel in the Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393).
sc Defines AXI4-Stream connections between the ports of the AI Engine graph and the streaming ports of the PL kernels. Connections can be defined as the streaming output of one kernel connecting to the streaming input of a second kernel, or to a streaming input port on an IP implemented in the target platform. For more information, see --connectivity Options in the Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393).

The example stream_connect=mm2s.s:ai_engine_0.DataIn1 from the config file, defines a connection between the streaming output of the mm2s PL kernel, and the DataIn1 input port of the AI Engine graph.

The example stream_connect=ai_engine_0.DataOut1:s2mm.s defines a connection between the DataOut1 output port of the AI Engine graph, to the input port s of the PL kernel s2mm. For more information, see Specify Streaming Connections Between Compute Units in the Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393).

During the linking process, the Vitis compiler invokes the Vivado Design Suite to generate the platform file (XSA) for the target platform. The XSA file is used to package the design and includes the following information.

PDI
Programming information for the AI Engine array
Debug data
Debug information when included in the build
Memory topology
Defines the memory resources and structure for the target platform
IP Layout
Defines layout information for the implemented hardware design
Metadata
Various elements of platform meta data to let the tool load and run the XCLBIN file on the target platform

For more information on the XRT use of the XCLBIN file, see XRT.