KRS Unleashed: 3) KRS Workspace

This Article covers how the newly separated 3 workspaces of KRS Unleashed play together and explains, how to generate cross-compiled artifacts and design new applications in KRS Unleashed. The previous article presented already who to obtain a sysroot for cross-compilation, but was independant of KRS.

Here, we will first talk about the folder structure and which packages are actually necessary in KRS Unleashed to cross-compile an application. Further, all relevant places to configure the selected sysroot or later HLS kernels will be explained.

Finally, commands will be shown to generate binaries for the Kria KR260 of an exemplary application.

Folder Structure

Due to releasing the work as part of a paper, the repository contains an exemplary application including configuration files to reproduce the results. The actual KRS Unleashed is hidden inside, but due to the changes applied to the original KRS, the KRS Unleashed core is way more visible and also way smaller.

The Overall repository is separated into 3 directories:

• krs; containing the ROS 2-related workspace
• os_workspace; containing the modules to create a sysroot and prepare SD cards
• vitis; containing the Vitis Workspace covered in the next article to create.xclbin files with the synthesized kernels

A ROS 2 workspace usually contains all packages inside a `src` folder. Here, the KRS Unleashed Core packages are put in a special directory called `base`. `adaptive_component` is optional and contains some nice utility. The residual packages ensure host-code compilation with Vitis supported flags/ are reminiscence of the old synthesis flow (`ament_acceleration`, `ament_vitis` and `vitis common`), configure the toolchain to cross-compile against the sysroot (`krs_firmware`) or introduce further tracing capabilities based on ros2-tracing (`tracetools_kernels`).

`Apriltag_*`, `minimal_image_pub` and `ros2_tracing` are just optional, application specific packages providing the hardware accelerated, software version and ROS 2 message definitions for the Apriltag algorithm, a simple message dummy node for testing and ros2-tracing (necessary to add to repo for cross-compilation).

The os_workspace has already been covered in the previous article, but to summarize its structure. We support currently two flows for the KR260 board, an Ubuntu-based flow inside `firmware_kr260_ubuntu` that contains a script to fetch a tar archive containing the sysroot and a patch script to alter the customize.sh shell script inside the tar archive/bin directory to install dependencies inside the sysroot. The firmware_kr260_petalinux flow is a bit more complex but similarly automated via the petalinux.sh script that first checks for some files from the artifacts folder to be present like the XSA file or the BSP (which needs to be downloaded) and then continues to create the petalinux project under `build_petalinux/images`. Afterwards a generated sdk.sh script is invoked to generate the firmware folder containing the sysroot. Further scripts for device tree generation are optionally provided and configuration can be applied on the configs in the `petalinx_config folder`

├── krs
│   └── src
│       ├── apriltag_accel
│       ├── apriltag_cpp
│       ├── apriltag_utils
│       ├── base
│       │   ├── acceleration
│       │   │   ├── adaptive_component
│       │   │   ├── ament_acceleration
│       │   │   ├── ament_vitis
│       │   │   └── vitis_common
│       │   ├── krs_firmware
│       │   │   ├── cmake
│       │   │   ├── CMakeLists.txt
│       │   │   ├── package.xml
│       │   │   └── template
│       │   └── tracetools_kernels
│       ├── minimal_image_pub
│       └── ros2_tracing
├── os_workspace
│   ├── firmware_kr260_petalinux
│   │   ├── artifacts
│   │   ├── build_petalinux
│   │   │   └── images
│   │   ├── firmware
│   │   │   └── sysroots
│   │   │       └── cortexa72-cortexa53-xilinx-linux
│   │   ├── petalinux.mixin
│   │   ├── petalinx_config
│   │   │   ├── config
│   │   │   ├── rootfs_config
│   │   │   └── user-rootfsconfig
│   │   └── scripts
│   │       ├── device_tree_gen.sh
│   │       ├── petalinux.sh
│   │       └── xsct.tcl
│   └── firmware_kr260_ubuntu
│       ├── firmware
│       │   └── sysroots
│       │       ├── aarch64-xilinx-linux
│       │       ├── bin
│       │       └── build-sysroot.sh
│       ├── patches
│       │   └── customize.patch
│       └── prepare_sysroot.sh
└── vitis
    ├── artifacts
    │   ├── kria_kr260.xsa
    │   └── shell.json
    ├── platform
    │   └── sd_dir
    │       └── NOT_IGNORE
    ├── scripts
    │   ├── configuration_manager.py
    │   ├── config.yaml
    │   ├── constants.py
    │   ├── create_hls.py
    │   ├── create_platform.py
    │   ├── simple_yaml_parser.py
    │   └── vitis_ws.py
    ├── sources
    │   ├── apriltag_smarobix
    │   ├── blur
    │   ├── decimate
    │   ├── hls_utils
    │   │   ├── cmd_line_parser.cpp
    │   │   ├── cmd_line_parser.hpp
    │   │   ├── params.hpp
    │   │   ├── xcl2.cpp
    │   │   └── xcl2.hpp
    │   ├── misc
    │   └── threshold
    │       ├── threshold_config_params.hpp
    │       ├── threshold_host_code.cpp
    │       ├── threshold_kernel.cpp
    │       ├── threshold_kernel.hpp
    │       ├── threshold_kernel_old.cpp
    │       ├── threshold_kernel_test.cpp
    │       └── threshold_kernel_test.hpp
    └── template
        ├── pl.dtbo
        └── shell.json

The vitis workspace will be covered in details in the next chapter, but the general structure doesn't require it to be placed next to ROS2 workspace, as its only dependency is on the employed OS. Kernels are organized in folders inside sources from where the scripts prepare the workspace and generate all the components. After successful execution, the results are stored inside an exports folder to be copied onto the board.

Native/local Build

As explained in the paper and in the first article, one of the main motivations for the revision was the complexity involved when altering the system like using a different version of Vitis or integrating another OS.

Compared to the original KRS flow, KRS Unleashed extracted these two steps into separate workspaces to make the links more tangible and adjustable. For the cross-compilation, the previous implicit sysroot preparation for Ubuntu was moved into the OS workspace, while the mixin generation was kept in the new krs_firmware repo inside ROS 2. krs_firmware defines some constants inside `base/krs_firmware/cmake/firmware_setup.cmake`, but only this line is currently really relevant:

set(FIRMWARE_DIR ${CMAKE_INSTALL_PREFIX}/../../../firmwares/firmware_kr260_ubuntu/firmware)  # <ws>/../firmware_kria_ubuntu

Here, the folder containing the `sysroots` folder to be used needs to be specified. Sadly, the Petalinux versions which would support ROS 2 humble (2022.1-2024.1) are based on a non-LTS Yocto version (Langdale) for which the ROS 2 layer never really worked because the maintainer changed during that version and one would need now to backport bugfixes for Kirkstone to Langdale..

Therefore, we used the ABI-compliant Ubuntu sysroot as a temporary workaround to cross-compile applications for Petalinux. This works fine for easier examples but causes issues when library versions differ like the case with OpenCV. Our current plan involves upgrading the whole toolchain to Jazzy/2025.1 as a next step.

After adjusting the variable firmware_dir to your liking, you simply need to execute the commands of the original KRS framework + the additional environment preparation:

1. add the missing libpython library for cross-compilation once which Ubuntu misses (use absolute path!!)

sudo ln -s /home/paul/.../os_workspace/firmware_kr260_ubuntu/firmware/sysroots/aarch64-xilinx-linux/usr/lib/aarch64-linux-gnu/libpython3.10.so.1.0 /usr/lib/aarch64-linux-gnu/libpython3.10.so -f

2. source ROS 2, Vitis and define some variables

source /opt/ros/humble/setup.<shell>
source /mnt/data/Programs/Xilinx/Vitis/2024.1/settings64.sh
unset RMW_IMPLEMENTATION
export PATH="/usr/bin":$PATH

Unset RMW Implementation is only necessary when you have multiple DDS installed for ROS 2, this is just a precaution step to prevent error messages - if you encounter some regarding DDS dependencies leave this simply out, export PATH is simply to prevent accidentally using Vitis Cmake,.. version

In case you have multiple OpenCV version installed locally to test Petalinux, you need to set some further variables for the native build:

export OPENCV_INCLUDE=/usr/include/opencv4
export OPENCV_LIB=/home/usr/lib
export LD_LIBRARY_PATH=/usr/lib:$LD_LIBRARY_PATH

3. build the application

colcon build --merge-install --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON-DCMAKE_BUILD_TYPE=Release

This will generate a build and install folder which a native build of the application which you can use for testing the software version of your application. Additionally, a colcon mixin has been installed on your system via krs_firmware which allows you next to cross-compile the application

Run the SW Application simply via normal ROS 2 commands:

source install/setup.<shell>
ros2 launch <package> <launchfile> ...

Cross Compilation Configuration and How Kernels are integrated

Afterwards, we need to source the generated setup script and run the cross-compilation command. Open a new terminal and run:

source /opt/ros/humble/setup.<shell>
source /mnt/data/Programs/Xilinx/Vitis/2024.1/settings64.sh
export PATH="/usr/bin":$PATH

colcon build --build-base=build-kr260 --install-base=install-kr260 --merge-install --mixin kr260 --cmake-args -DNOKERNELS=true -DCMAKE_BUILD_TYPE=Release

This will create a build-kr260 and an install-kr260 folder. To deploy the application on the board, simply copy the install-kr260 folder via scp:

scp -r install-kr260  ubuntu@192.168.2.2:/home/ubuntu/

Its important to note here, that this install folder only contains the cross-compiled binaries, launch files,.. The final synthesized kernels are missing and need to be generated and setup on the board separately via the vitis workspace flow in the next article.

The actual linking to the kernel files just happens on the host code, where the name of the xclbin, the top-level function and method signature need to match the kernels.