Defining the HW_Link System Configuration - 2024.1 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)
Document ID
UG1393
Release Date
2024-07-03
Version
2024.1 English

V++ Linker Settings

The Hardware Link (hw_link) configuration file contains information used by the Vitis compiler (v++) 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 will open the Config File Editor in the central editor window as displayed 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. When not enabled the HLS component and the system design can be optimized but will not support debug.
Note: This specifies the -g option for the v++ --link command as described in 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 as described in Vitis Export to Vivado Flow.
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 feature will return an error.
Export Hardware
Specifies that an XSA file should be generated from the linked design produced by the v++ command. This option relates to param=compiler.addOutputTypes=hw_export as described at --advanced Options.
Trace Memory
When building the hardware target for the System project, this option lets you specify the type and amount of memory to use for capturing trace data. 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 ports and interfaces, and the debug and profile options available.

The specific options that can be set include:

  • CU Name: Lets you define the naming sequence when multiple compute units are generated from a PL kernel as described under the --connectivity Options.
  • Compute Units: Specifies the number of compute units to generate from a PL kernel. Also related to --connectivity.nk
  • Memory: Use this option to specify 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 as described in Mapping Kernel Ports to Memory.
  • SLR Assignment: is described in Assigning Compute Units to SLRs on Alveo Accelerator Cards
  • Protocol Checker: Described under --debug Options.
  • Chipscope Debug: Also described under --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: This option records the execution times of the kernel and provides minimum port data collection during the system run. This option relates to the --profile.exec command.
  • Stall Profiling: This option relates to the --profile.stall command. It adds stall monitoring logic to the device binary (.xclbin) which requires the addition of stall ports on the kernel interface. Therefore the stall option must be specified during both compilation and linking.
    Important: The --profile.stall command must be specified during compilation of the HLS component using syn.rtl.kernel_profile=1 in the HLS component config file (hls_config.cfg) to be implemented during v++ linking.

Adding Commands Using the Text Editor

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

Examine the configuration file commands that have bean added by the GUI, and be aware of any configuration commands to add to your design that are not presented by the GUI. The Text Editor offers the ability to add configuration commands, whether they are in the GUI or not.

An example of this applies to the use of the 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 will need to use. The Text Editor provides a good way to enter them.

Adding AI Engine Connectivity

  1. As explained in Linking the System, for AI Engine graph applications the Vitis compiler needs some instruction on how to make connections between the graph and PL kernels. The number of kernels to be instantiated is already configured in the IDE. However the definition of the connections between the PL kernels and the graph must be specified in the config file as shown 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

The connection scheme must be defined in the Text Editor, or manually added to the config file for the system project. 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.

The system.cfg file has some differences between the Vitis IDE and the command-line flow. The primary difference is that the IDE provides the connectivity nk options of the config file, instantiating a specified number of compute units (CUs) per kernels, as specified in the build settings. In addition, the IDE uses a naming convention for CUs in the form of <kernel>_#, where # indicates the CU instance. In the case where there is only one CU instance, it has the _1 extension. This means that for the Vitis IDE, the system.cfg should not specify the nk option, and the sc option should use the CU instance name from the IDE.