KRS Unleashed: 4) Vitis Workspace

This article will cover the newly develop automated Vitis Workspace flow. The original KRS flow which automatically generated the kernels into a xclbin configured inside the CMakeLists.txt of ROS 2 packages was kept, but is currently unused. While it was nice that the original flow allowed to directly generate kernels inside ROS 2, the flow was hard to use when developing new kernels. As the majority of the v++ output is hidden behind CMake commands, the developers gets almost no feedback. Further, testing and adjusting configurations was not trivial and needed to be configured explicitly inside CMake. Because the v++ compiler was directly invoked, no project existed afterwards to inspect the results in a more graphical way requiring further expertise.

The Vitis Unified Software Platform Flow

The usual way how one develops HLS Kernels is by using the Vitis Unified Software Platform IDE provided by AMD/Xilinx. Here, one first creates a platform component capturing the Vivado Base Platform, the Board including CPU architecture, sysroot and so one.

Next, HLS and Application (Host Code) Components are created per kernel and configured with correct dependencies, linker flags,.. to synthesize designs and explore tradeoffs.

In a final step, all kernels are put together with the platform inside a System Component to generate the final xclbin. The automatic flashing and debugging features sadly doesn't work for the Kria boards, so the flow needs to stop after generating successfully the bitstream. After creation of a component, the developer can still adjust its files and configuration or go back to other components, allowing to explore the system without always rebuilding everything from scratch.

The Vitis Flow Conceptually

The new Vitis Workspace Flow realizes exactly this flow in an semi-automated manner via the new Python API. A simplified configuration file is used to create all of these components and pre-configure them. By following certain naming conventions, the flow allows to generate not only the xclbin file automatically and retrieve it in an export folder for usage on the board, but further creates the whole development workspace to fine/develop the system.

A dry mode was added when starting with a fresh program which just configures all the components but doesn't trigger builds. The flow further allows to re-trigger individual phases, namely clean the workspace, create a workspace (ws) with a platform component, add HLS components including application code and assemble the final system and export it. The flow currently does not support to automatically get updates performed inside of Vitis, so the user need to make sure to copy the source files/adjusted configurations over to the KRS/vitis folders beforehand.

under a newly created exports/ folder are the respective files at the end to copy them over to the board.

Using the Vitis Flow

The flow is invoked via a script:

first prepare the environment by sourcing vitis and potentially necessary dependencies:

source /mnt/data/Programs/Xilinx/Vitis/2024.1/settings64.sh
export LD_LIBRARY_PATH=/home/paul/.local/lib:$LD_LIBRARY_PATH
export OPENCV_LIB=/home/paul/.local/lib 
export OPENCV_INCLUDE=/home/paul/.local/include/opencv4

The OpenCV sourcing is necessary for Vitis Vision library host code - if you dont intent on using them, you can skip this.

Make sure that you config.yaml is correct and defines the intended behavior:

Project:
name: "smarobix_apriltag"
board: "KR260"
target_clock: "5ns"
vitis_library_path: "/opt/xilinx/Vitis-Libraries"
opencv_include_path: "/home/paul/.local/include/opencv4"
opencv_library_path: "/home/paul/.local/lib"
kernels:
- name: "decimate"
top_level_function: "cvtcolor_rgb2gray"
use_opencv: true
vitis_library: "vision"
- name: "blur"
top_level_function: "gaussian_filter_accel"
use_opencv: true
vitis_library: "vision"
- name: "threshold"
top_level_function: "adaptive_threshold"
use_opencv: true
vitis_library: "vision"
platform:
create_new: true
name: "kria_kr260_base_accel"
xsa_file_path: "/mnt/data/tmp/KRS-Unleashed/vitis/artifacts/kria_kr260.xsa"
petalinux_dir: "/mnt/data/tmp/KRS-Unleashed/os_workspace/firmware_kr260_petalinux"

• each kernel needs a name and a top-level function, vitis libraries and opencv dependencies are optional

You can check if your settings are correct via a separate script:

python3 scripts/check_config.py

Its necessary to do this in a separate script, because the Python API of Vitis is not a simple module that you install but comes with its own python interpreter where you can't install dependencies easily.

Afterwards, simply invoke the script via:

vitis -s scripts/vitis_ws.py full

If you see the following output, everything went successful and you should see an exports folder with your final artifacts ready for the setup on the board.