Linking the Kernels - 2022.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID
Release Date
2022.2 English
Tip: Set up the command shell or window as described in Setting Up the Vitis Environment prior to running the tools.
The PL kernel compilation process results in a Xilinx object (.xo) file whether the kernel is written in C/C++ or RTL. During the linking stage, one or more PL kernels are linked with the platform to create the FPGA binary container file (.xclbin). In the case of Versal® ACAP devices, the linking process also includes an AI Engine graph application (libadf.a) and creates a fixed hardware platform (.xsa) for use by the Vitis packaging process as described in Packaging the System.
Important: Starting from the 2022.1 release, the v++ --link command generates a hardware definition file (.xsa) for Versal® device platforms (i.e. vck190, vck5000), for use by the v++ --package command to generate the .xclbin file. For Alveo™ data center accelerator cards, and embedded processor cards the v++ --link command generates an .xclbin file directly, though the v++ --package command might still be needed.
The following is an example command line to link the vadd kernel (.xo) with a libadf.a graph archive and a Versal ACAP platform, specifying the .xsa file as the output:
v++ -t hw_emu --platform xilinx_vck190_base_202210_1 --link vadd.xo libadf.a -o"binary_container_1.xsa" \
--config ./system.cfg

This command contains the following arguments:

-t <arg>
Specifies the build target. Software emulation (sw_emu) is used as an example. When linking, you must use the same -t and --platform arguments as specified when the input (XO) file was compiled.
--platform <arg>
Specifies the platform to link the kernels with.
Link the kernels and platform into a system design.
Input object file. Multiple object files can be specified.
Input AI Engine graph application.
Specify the output file name. The output file in the link stage will be an .xsa file. The default output name is a.xsa.
Tip: For Alveo accelerator cards, or Zynq MPSoC based platforms, the output of the link command will be an .xclbin file rather than the .xsa.
--config ./system.cfg
Specify a configuration file that is used to provide v++ command options for a variety of uses. Refer to v++ Command for more information on the --config option.

After the linking step is complete, any reports generated during this process are collected into the <kernel_name>.link_summary. This collection of reports can be viewed by opening the link_summary in Vitis analyzer, and includes a Summary report, System and Platform Diagrams to illustrate the hardware design, System Estimate providing timing and resources estimates, System Guidance offering any suggestions for improving linking and the performance of the system, and the Vivado Automation Summary providing design details such as interface connections, clocks, resets, and interrupts. Refer to Using the Vitis Analyzer for additional information.

Tip: Refer to Output Directories of the v++ Command to get an understanding of the location of various output files.

Beyond simply linking the Xilinx object (XO) files, the linking process is also where important architectural details of the design are specified. In particular, this is where the design is enabled for profiling or debug, where you specify the number of compute unit (CUs) to instantiate into hardware, where CUs are assigned to SLRs, and where you define connections from kernel ports to global memory or between streaming ports. The following sections discuss some of these build options.