Step 3 - v++ linker – Building the System - 2022.2 English

Vitis Tutorials: AI Engine Development

Document ID
XD100
Release Date
2022-12-01
Version
2022.2 English

Now that you have a compiled graph (libadf.a), 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 need to 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, you will need to 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

Here you may notice some connectivity and clocking options.

  • 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. You can also define a FIFO on this line by adding a depth value to the end.

There are many more options available for v++. For a full list, see the documentation here.

  1. Modify the system.cfg file so that the second stream_connect has a stream depth of 1024. Replace the line with ai_engine_0.Dataout line with this: stream_connect=ai_engine_0.Dataout:s2mm.s:1024

    • Keep this file open for now.

  2. The data output of the AI Engine is at 32-bit and at a high clock frequency. To reduce the possibilities of dropping data, you can attach the s2mm kernel to the AI Engine with a larger datawidth (eg. 64-bits) and the clock frequency to s2mm to keep relative bandwidth the same. To do this, the Vitis Compiler will auto instantiate a Clock Converter block and Datawidth Converter block to make sure connectivity is achieved.

    • Open the s2mm.cpp in ./pl_kernels to see that the line 23 has 64-bit defined for both input and output.

  3. Because the s2mm kernel is running slower than thet for kernel compilation and linking is to make sure that clock is connected correctly. In the system.cfg file uncomment these lines:

    [clock]
    freqHz=200000000:s2mm.ap_clk
    tolerance=1000000:s2mm.ap_clk
    

    Here you are telling the v++ linker to override the default clock frequency to 200 MHz for the s2mm kernel, and setting the clock tolerance to 1 MHz. By setting a tolerance you are giving the linker a better chance to make sure a clock can be generated that meets your bandwidth.

  4. With the changes made you can now run the following command:

    v++ --link --target hw --platform $PLATFORM_REPO_PATHS/xilinx_vck190_base_202210_1/xilinx_vck190_base_202210_1.xpfm s2mm.xo \
        mm2s.xo polar_clip.xo ./aie/libadf.a --config system.cfg \
        --save-temps -o tutorial1.xclbin
    
| Flag/Switch | Description |
| --- | --- |
| `--link` | Tells `v++` that it will be 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 will build down to a bitstream) or hardware emulation (which will build the emulation models). |
| `--platform` |  Same from the previous two steps. |
| `--config` | This allows you to simplify the `v++` command-line if it gets too unruly and have items in an ini style file. |
  1. When the linking is complete you can view what the design looks like in the Vivado® tools. Navigate to _x/link/vivado/vpl.

    1. Run the command in the terminal: vivado -source openprj.tcl

    2. When the tool is open, locate the button on the left in the Flow Navigator and click, “Open Block Design”. You should see an output similar to the following figure. (The following figure has reduced nets visible to see the added FIFO, Datawidth Converter, and Clock Converter).

    IPI Diagram

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

    • From the changes made in the previous steps, you will notice a new clock, Datawidth Converter, Clock Converter, and a new FIFO on the s2mm kernel.

      • Do note that if you change a kernel or connectivity you have to re-run the v++ linker.

NOTE: Any change to the system.cfg file can also be done on the command-line. Make sure to familiarize yourself with the Vitis compiler options by referring to the documentation here.