Linking the System - 2023.1 English

AI Engine Tools and Flows User Guide (UG1076)
Document ID
UG1076
Release Date
2023-06-23
Version
2023.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_202310_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 and Positional Parameters
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. This is a positional parameter.
../libadf.a Specifies the input compiled AI Engine graph application to link with the PL kernels and the target platform. This is a positional parameter.
-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, connections from the AI Engine to PL kernels and to platform IPs are specified in the [connectivity] section of a configuration file. 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 compute units the v++ command adds to the platform (XSA) file.

The nk option specifies the kernel name, the number of instances, or compute units 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 compute units 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 in the Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393).
sp Specifies the connection between memory and a system port. This option can be used to specify connection of a GMIO to s specific memory. The example sp= toai_engine_0.DataOut2:LPDDR specifies the connection between the GMIO output DataOut2 and the LPDDR memory.

To obtain information for memory available in the platform run the platforminfo command line utility which reports platform meta-data including information on interface, clock, valid SLRs and allocated resources, and memory in a structured format.

During the linking process, the Vitis compiler invokes the Vivado Design Suite to generate the hardware design, which is encapsulated in a fixed platform file (XSA) for packaging and embedded software development.