Linking the System - 2020.2 English

Versal ACAP AI Engine Programming Environment User Guide (UG1076)
Document ID
UG1076
Release Date
2020-11-24
Version
2020.2 English

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

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_202020_1 -g \
<pl_kernel1>.xo <pl_kernel2>.xo ../libadf.a -o vck190_aie_graph.xclbin \
--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 device binary (XCLBIN) 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 Application Acceleration Development flow of the Vitis Unified Software Platform Documentation (UG1416).
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 two specific sections in the configuration file: [connectivity] and [advanced]. 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
[advanced]
param=compiler.addOutputTypes=hw_export

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 kernels instances or CUs the v++ command adds to the device binary (XCLBIN).
Important: This applies to PL kernels that are not included in the AI Engine graph, because those kernels are specified in the graph code.

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 Application Acceleration Development flow of the Vitis Unified Software Platform Documentation (UG1416).
sc Defines connections between the ports of the AI Engine graph and streaming ports of PL kernels that are not included in the graph. 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 Application Acceleration Development flow of the Vitis Unified Software Platform Documentation (UG1416).

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=mm2s.s:ai_engine_0.DataIn1 defines a connection between the DataOut1 output port of the AI Engine graph, to the input port of the PL kernel s2mm. For more information, see Specify Streaming Connections Between Compute Units in the Application Acceleration Development flow of the Vitis Unified Software Platform Documentation (UG1416).

[advanced]param=compiler.addOutputTypes=hw_export specifies the creation of a new XSA for the target platform. The exported XSA has the name of the output file specified by the -o option, with the file extension of .xsa.

Tip: The exported XSA is required for building the fixed platform in the bare-metal flow as described in Building a Bare-metal System.

During the linking process, the Vitis compiler invokes the Vivado Design Suite to generate the device binary (XCLBIN) for the target platform. The XCLBIN file is used to program the device 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.