Linking the System - 2024.2 English - UG1700

Data Center Acceleration Using Vitis User Guide (UG1700)
Document ID
UG1700
Release Date
2025-01-15
Version
2024.2 English
Tip: Set up the command shell or window as described in Setting Up the Vitis Environment in the Data Center Acceleration using Vitis (UG1700) prior to running the tools.
Figure 1. Linking the System Design

During the linking stage, one or more PL kernel objects (.xo files) are linked with the extensible platform to create the FPGA binary container file (.xclbin).

The linking stage is when the developer specifies the main characteristics of the accelerated system, including setting up the command shell or window as described in Setting Up the Vitis Environment in the Data Center Acceleration using Vitis (UG1700) prior to running the tools.

  • Which accelerators are to be included in the device
  • How many instances of each accelerator are needed
  • How are accelerators connected to system memory
  • How are accelerators connected between each other
  • Where are accelerators physically placed in the FPGA device

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_202420_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.
--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 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 in the Vitis Reference Guide (UG1702) 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 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) in the Vitis Reference Guide (UG1702) for additional information.

Tip: Refer to Output Directories of the v++ Command in the Vitis Reference Guide (UG1702) 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. The following sections discuss some of these build options.