Linking the System - 2023.2 English

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

Document ID

UG1393

Release Date

2023-12-13

Version

2023.2 English

Tip: Set up the command shell or window as described in Setting Up the Vitis Environment prior to running the tools.

Figure 1. Linking the System Design

The preceding figure shows two paths through the linking process, starting with the v++ --link command. The first path is the Vitis Integrated Flow in which the v++ command links the elements of the system, automatically launches the Vivado tools for implementation of the design, and outputs an .xclbin or .xsa file. The second path is the Vitis Export to Vivado flow in which the v++ command links the elements of the system and outputs a .vma file for you to use in the Vivado tools for synthesis, implementation, and timing closure. These two paths are explained below.

Note: The Export to Vivado flow is currently only supported for custom Versal platforms.

Vitis Integrated Flow

As shown in the preceding figure, the PL kernel compilation process results in an 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 extensible platform to create the FPGA binary container file (.xclbin). For Versal adaptive SoC 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.

Note: The Integrated Flow automatically runs Vivado synthesis and implementation under the hood (hence the name "integrated"). This is a major difference.

The following is an example command line to link the vadd kernel (.xo) with a libadf.a graph archive and a Versal adaptive SoC platform, specifying the .xsa file as the output:

v++ -t hw_emu --platform xilinx_vck190_base_202310_1 --link vadd.xo libadf.a \
--config ./system.cfg -o binary_container.xsa

This command contains the following arguments:

-t <arg>: Specifies the build target. When linking, you must use the same -t and --platform arguments specified when compiling the PL kernels and AI Engine graph application.
--platform <arg>: Specifies the platform to link with the system design. In the example command above the custom_vck190 platform is a custom platform designed to work with the --export_archive command.
--link: Link the kernels, graph, and platform into a system design.
<input>.xo: Specifies the input 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.
--config ./system.cfg: Specify a configuration file that is used to provide v++ command options for a variety of uses. Refer to Vitis Compiler Configuration File for more information on the --config option.
-o binary_container.xsa: Specifies the output file name. The output file in the link stage will be an .xsa file due to the use of a Versal platform. The default output name is a.xsa.; Tip: For Alveo accelerator cards, or AMD Zynq™ MPSoC based platforms, the output of the link command will be an .xclbin file rather than the .xsa.

Vitis Export to Vivado Flow

Alternatively, for custom Versal platforms designed specifically to support this feature, v++ --link --export_archive creates a Vitis Metadata Archive (.vma) file for export to the Vivado Design Suite. This flow lets you open the linked system design in the Vivado tools for more directed synthesis, place and route, and timing closure.

Note: In this Export flow, the linker stops pre-synthesis.

An example command follows:

v++ --platform custom_vck190 --link vadd.xo libadf.a --config ./system.cfg \
--export_archive -o hw-vadd.vma

Important: The --export_archive command cannot be used with the --target (or -t) command. An error will be returned.

This command is similar to the prior command, with the following differences:

--export_archive: Specifies the creation of the .vma file to export to the Vivado Design Suite. This option stops v++ from automatically running Vivado synthesis and place and route, and instead lets you manually launch and direct the implementation and timing closure of the design as described in Vitis Export to Vivado Flow.
--platform custom_vck190: The --export_archive command can only be used with a custom Versal platform designed with block design containers (BDC) required for this design flow. Refer to the chapter on Introduction to Block Design Containers ( Vivado Design Suite User Guide: Designing IP Subsystems using IP Integrator (UG994)) for more information.
-o hw-vadd.vma: Specifies the output file name for the .vma file produced by the --export_archive command.

After Linking

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 the Analysis view of Vitis analyzer, and includes a Summary report, System Estimate providing timing and resources estimates, System Guidance offering any suggestions for improving linking and the performance of the system. Refer to Working with the Analysis View (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.

The linking process defines important architectural details of the system design. 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 PL kernel ports to global memory or to AI Engine applications. The following sections discuss some of these build options.