Defining the HW_Link System Configuration - Defining the HW_Link System Configuration - 2026.1 English - UG1702

Vitis Reference Guide (UG1702)
Document ID
UG1702
Release Date
2026-06-23
Version
2026.1 English

V++ Linker Settings

The Hardware Link (hw_link) configuration file contains information that Vitis compiler (v++) uses for linking the system. To open the config file from the vitis-sys.json file for the System Project, click the hw_link/binary_container-link.cfg hyperlink. This opens the Config File Editor in the central editor window as (see below).

Figure 1. Configuring the Hardware Linker Settings

Note: All of the options found in the binary_container-link.cfg are v++ command line options (see v++ Command).

The V++ linker settings provides the following options:

Debug
Enable debug file generation. If you do not enable this option, you can optimize the HLS component and the system design, but cannot debug them.
Note: This specifies the -g option for the v++ --link command. See v++ General Options. To enable debug for the HLS component, you must specify syn.debug.enable in the HLS component config file (hls_config.cfg).
Report Level
Specify the level of detail included in reports generated by the v++ --link command.
Hardware Optimization
This option specifies the optimization level of the AMD Vivado™ implementation results.
Export Archive
Indicates the export of the .vma file for use in the Vivado Design Suite. See Packaging for Vitis Export to Vivado Flow in the Embedded Design Development Using Vitis (UG1701).
Note: This feature requires the use of a Versal platform or XSA designed with a block design container. If your System Project does not meet this requirement, the extensible XSA returns an error. Vitis does not require BDC (Block Design Containers).
Export Hardware
Specifies that you need to generate a Fixed XSA from the linked design that the v++ command produces. This is the default output for Versal devices.
Trace Memory
For specifying the type and amount of memory to use for capturing trace data when the hardware target for the System Project. This option relates to the --profile.trace_memory command as described at --profile Options.

Kernel Data

For each PL kernel in the System Project, there are additional settings available under the Kernel Data heading.

Figure 2. Configuring Kernel Data

The Kernel Data section refers to config commands that specifically apply to the PL kernels generated from the HLS component. The config commands also apply to ports and interfaces, and the debug and profile options available.

The specific options include:

  • CU Name: Defines the naming sequence when you generate multiple compute units from a PL kernel as described under --connectivity Options.
  • Compute Units: Specifies the number of compute units to generate from a PL kernel. Relates to --connectivity.nk as well.
  • Memory: Specifies the connection of kernel ports to system ports within the platform. A primary use case for this option is to connect kernel arguments to specific memory resources. See Mapping Kernel Ports to Memory in the Data Center Acceleration using Vitis (UG1700).
  • SLR Assignment: see Assigning Compute Units to SLRs on Alveo Accelerator Cards in the Data Center Acceleration using Vitis (UG1700)
  • Protocol Checker: See --debug Options.
  • Chipscope Debug: See --debug Options.
  • Data Transfer: Enables monitoring of data ports through special monitor IP that are added into the design for profiling. This option relates to the --profile.data command.
  • Execute Profiling: Records the execution times of the kernel and provides minimum port data collection during the system run. Relates to the --profile.exec command.
  • Stall Profiling: Relates to the --profile.stall command. Adds stall monitoring logic to the device binary (.xclbin). Requires the addition of stall ports on the kernel interface. Therefore, you need to specify the stall option during both compilation and linking.
    Important: During v++ linking, you must specify the --profile.stall command during compilation of the HLS component. Specify the command with the syn.rtl.kernel_profile=1 in the HLS component config file (hls_config.cfg).

Adding Commands Using the Text Editor

After selecting config items using the Config File, take a look at the Text Editor view. You can toggle between the table view and the Text Editor view by using the commands in the toolbar.

Examine the configuration file commands that you added to the GUI. Be aware of any configuration commands you need to add to your design that are not in the GUI. The Text Editor offers the ability to add configuration commands, whether they are in the GUI or not.

An example adding a command is when you need to use an AI Engine component in a System Project. The AI Engine component must be connected into the platform or to PL kernels using the --connectivity.sc command. You can also map the system port to a memory using the --connectivity.sp command to specify a connection of a GMIO to a specific memory.

Tip: Keep in mind that the GUI does not provide access to all the command options for linking the system. Think about which options your design need to use. The Text Editor provides a good way to enter them.

Adding AI Engine Connectivity

For AI Engine graph applications, the Vitis compiler needs instructions on how to connect the graph and PL kernels. See Linking the System in the Data Center Acceleration using Vitis (UG1700) for details. The Vitis Unified IDE already configures the number of kernels to instantiate. However, you need to specify the definition of the connections between the PL kernels and the graph in the config file below.
[connectivity]
stream_connect=mm2s_1.s:ai_engine_0.DataIn1
stream_connect=ai_engine_0.clip_in:polar_clip_1.in_sample
stream_connect=polar_clip_1.out_sample:ai_engine_0.clip_out
stream_connect=ai_engine_0.DataOut1:s2mm_1.s

You need to define the connection scheme in the Text Editor for the System Project. You can also manually add the connection scheme to the config file. You can define connections as the streaming output of one kernel connecting to the streaming input of a second kernel. You can also define connections to a streaming input port on an IP that you implement on the target platform.

The system.cfg file differs between the Vitis IDE and the command-line flow. The IDE provides connectivity nk options and instantiates a specified number of compute units per kernel. Specify the number of compute units in the build settings. The IDE names compute units as <kernel>_#, where # identifies the instance. When one instance exists, the IDE uses the _1 suffix. For the Vitis tool, system.cfg omits the nk option. Use the sc option with the IDE-assigned compute unit name.