Step 3 - v++ linker – Building the System - Step 3 - v++ linker – Building the System - 2025.2 English - XD100

Vitis Tutorials: AI Engine Development (XD100)
Document ID
XD100
Release Date
2026-03-27
Version
2025.2 English

Now that you have a compiled graph (libadf.a) and the PLIO kernels (mm2s.xo, s2mm.xo, and polar_clip.xo), you can link everything up for the VCK190 platform.

A few things to remember in this step:

  1. For PLIO kernels, you must specify their connectivity for the system.

  2. Specify the clocking per PL kernel.

  3. You need to determine the TARGET: hw or hw_emu.

To link kernels up to the platform and AI Engine, look at the system.cfg file. For this design, the config file looks like this:

[connectivity]
nk=mm2s:1:mm2s
nk=s2mm:1:s2mm
nk=polar_clip:1:polar_clip
stream_connect=mm2s.s:ai_engine_0.DataIn1
stream_connect=ai_engine_0.clip_in:polar_clip.in_sample
stream_connect=polar_clip.out_sample:ai_engine_0.clip_out
stream_connect=ai_engine_0.DataOut1:s2mm.s

Note some connectivity and clocking options here:

  • nk: This defines your PL kernels as such: <kernel>:<count>:<naming>. For this design, you only have one of each s2mm, mm2s, and polar_clip kernels.

  • stream_connect: This tells v++ how to hook up the previous two kernels to the AI Engine instance. Remember, AI Engine only handles stream interfaces.

With the changes made, run the following command. In v++ link command, there are three ways to direct clocking in linker stage: --clock-id=<id_value> , --freqhz, and –clock.freqHz

    v++ --link --target hw --platform $PLATFORM_REPO_PATHS/xilinx_vck190_base_202520_1/xilinx_vck190_base_202520_1.xpfm 
    pl_kernels/s2mm.xo pl_kernels/mm2s.xo pl_kernels/polar_clip.xo ./aie/libadf.a --freqhz=200000000:mm2s.ap_clk --freqhz=200000000:s2mm.ap_clk 
    --config system.cfg --save-temps -o tutorial1.xsa

OR use system.cfg file to direct the clock using global freqhz option and using [clock] directive.

    [connectivity]
	nk=mm2s:1:mm2s
	nk=s2mm:1:s2mm
	nk=polar_clip:1:polar_clip
	sc=mm2s.s:ai_engine_0.DataIn1
	sc=ai_engine_0.clip_in:polar_clip.in_sample
	sc=polar_clip.out_sample:ai_engine_0.clip_out
	sc=ai_engine_0.DataOut1:s2mm.s
	freqhz=200MHz:s2mm.ap_clk

    [clock]
	freqHz=100000000:polar_clip.ap_clk

Flag/Switch

Description

--link

Tells v++ that it is linking a design, so only the *.xo and libadf.a files are valid inputs.

--target

Tells v++ how far of a build it should go, hardware (which builds down to a bitstream) or hardware emulation (which builds the emulation models).

--platform

Same from the previous two steps.

--freqhz

Tells the Vitis compiler to use a specific clock defined by a nine digit number. Specifying this helps the compiler make optimizations based on kernel timing.

--config

to specify the kernel config file that contains settings for synthesis like top function, kernel name etc.

After linking completes, you can view clock report generated by v++ –link after pre-synthesis: automation_summary_pre_synthesis.txt

IPI Diagram

IMPORTANT: Do not change anything in this view. This is only for demonstration purposes.

  • As you can see, the AIE compile frequency= 200 MHz (same as given in command in step 1)

  • To compile, PL kernel frequency for mm2s = 150 MHz (same as given in command in step 2.1)

  • To compile, PL kernel frequency for s2mm = 150 MHz (same as given in command in step 2.2)

  • To compile, PL kernel frequency for Polar_clip = 200 MHz (same as given in command in step 2.3)

To check the platform frequency, give command at terminal:

platforminfo $PLATFORM_REPO_PATHS/xilinx_vck190_base_202520_1/xilinx_vck190_base_202520_1.xpfm

The Vitis platform derives the clock frequency used for linking in the following way:

  • Clock frequency used in linking for mm2s = 200 MHz (CLI)

  • Clock frequency used in linking for s2mm = 200 MHz (CLI)

  • Clock frequency used in linking for polar_clip = 100 MHz (config file)

Because these clock frequencies do not match the platform clock frequency, the Vitis platform picks the clock frequency from the platform which is within the default tolerance (+/- 10%) limit. If the link frequency is outside the limit of tolerance, the Vitis platform instantiates a new MMCM to generate the clock frequency used in linking.

So, for linking, the Vitis platform uses the clock frequency in the following way:

  • For mm2s:

    Frequency given during linking = 200 MHz

    Frequency used by Vitis = 208.33 MHz (platform clock coming under the default tolerance of clock frequency given in link command)

  • For s2mm:

    Frequency given during linking = 200 MHz

    Frequency used by Vitis = 208.33 MHz (platform clock coming under the default tolerance of clock frequency given in link command)

  • For polar_clip:

    Frequency given during linking = 100 MHz

    Frequency used by Vitis = 104.17 MHz (platform clock coming under the default tolerance of clock frequency given in link command)

NOTE: You can make any changes to the system.cfg file using the command line. Make sure to familiarize yourself with the Vitis compiler options by referring to the documentation here.