Generating DTSI and DTBO Overlay Files¶

In this step the AMD HW description captured in the custom PL design must be translated into a Linux understandable format. In Linux HW is described using a concept called device trees (DT). The human readable form of these are dts and dtsi files. The PL design is loaded post Linux boot, therefore this step generates a DT overlay. The overlay DT is slightly different than the Linux boot DT - it must define “fragments” that are added dynamically by Linux at runtime.

For reference, the .dtsi files associated with each platform (but organized by application) can be found in Kria app firmware

The dts/dtsi files can be generated in a number of ways, all of which require the HW description data captured in the XSA or bit file. After a .dtsi file is generated, it is then compiled into a binary .dtbo file. The .dtbo file is expected in firmware folder for each applications.

Here are the three recommended ways:

In AMD Software Command-Line Tools (XSCT), use Device Tree Generator (DTG) and .xsa file to generate .dtsi, and Device Tree Compiler (DTC) to compile a .dtbo file
Manually create .dtsi file, and in Yocto, use dfx_user_dts bbclass to create .dtbo
Manually create .dtsi file, and in PetaLinux, use fpgamanger_custom bbclass to create .dtbo
In PetaLinux, use fpgamanger_dtg bbclass tools and petalinux-build to generate .dtsi file from .xsa file, and compiling it into .dtbo.

Note that with any ways of generating DTSI files - the generated .dtsi file will likely require user modification before they can be fully functional.

Using XSCT, DTG and DTC¶

Tools and Input Required¶

XSCT (part of Vivado or Vitis installation)

DTG, make sure to check out the version that is aligned to rest of tool chain and BSP used:

git clone https://github.com/Xilinx/device-tree-xlnx
cd device-tree-xlnx
git checkout xlnx_rel_v<version>

DTC (part of Vitis installation, can also be obtained below:)

git clone https://git.kernel.org/pub/scm/utils/dtc/dtc.git
cd dtc
make
export PATH=$PATH:/<path-to-dtc>/dtc

More information about using Xilinx’s Device Tree Generator (DTG) and open source Device Tree Compiler (DTC) can be found in wiki page.

The following hardware design hand-off artifacts are required:

XSA file - applies to Vivado or Vitis designs

Generate .dtsi from .xsa using DTG¶

Use XSCT to call HSI & generate DTSI.

hsi open_hw_design <design_name.xsa>
hsi set_repo_path <path to device-tree-xlnx repository>
hsi create_sw_design device-tree -os device_tree -proc psu_cortexa53_0
hsi set_property CONFIG.dt_overlay true [hsi::get_os]
hsi set_property CONFIG.dt_zocl true [hsi get_os]          # if ZOCL is used
hsi generate_target -dir <desired_dts_filename>
hsi close_hw_design [current_hw_design]

[current_hw_design] name can be found in output of hsi open_hw_design <design_name.xsa>. An example script for above can be found in the linked example from Vitis Platform Flow here.

A folder <desired_dts_filename> will be created, pl.dtsi is the overlay .dtsi file to be used to compile into .dtbo file. The .dtsi file will require some user modification before it is ready to be compiled.

Compile the .dtsi to .dtbo using DTC¶

This step takes the human readable defined Linux HW description (dtsi file) generated (.pl.dtsi)and compiles it into a binary form that Linux can directly use. This is completed using the Linux Device Tree Compiler (DTC) which is an opensource tool. The actual command used to generate the desired dtbo from the dtsi file is shown below.

dtc -@ -O dtb -o pl.dtbo pl.dtsi

Rename the pl.dtbo to the appropriate name.

Using dfx_user_dts bbclass in Yocto¶

The dfx_user_dts bitbake class is a helper class that can be used by Yocto to generate a set of FPGA firmware binaries. This method requires that user hand write their own .dtsi file. This has been supported starting in 2024.1. The same bitbake class applies for PetaLinux, but this section aims to provide an example of how to use this bitbake class in Yocto.

Tools and Input required¶

Yocto of the appropriate version (but must be 2023.2 and later)
Yocto project for Kria SOM of the appropriate version, created by following instructions in Prepare the Build Environment

The following hardware design hand-off artifacts are required:

PL bitstream - applies to Vivado or Vitis designs
Device tree overlay source file - the user needs to create this file based on the PL hardware design
json file - specifies if the overlay is slotted or flat and required by dfx-mgr. More information can be found here
Xclbin file - only applies to Vitis designs

Creating .dtbo file¶

After following Prepare the Build Environment instructions, you should be in $yocto_workspace/build.

Create a folder $yocto_workspace/sources/meta-kria/recipes-firmware/<firmware-name>/files. Put the artifacts, <firmware-name>.dtsi, <firmware-name>.bit, <firmware-name>.xclbin, <firmware-name>.dtsi in the folder created.

Create a file $yocto_workspace/sources/meta-kria/recipes-firmware/<firmware-name>/<firmware-name>.bb with the following content. You can find the appropriate <machine-name> in Kria Yocto Support page.

LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"

inherit dfx_user_dts

SRC_URI = "\
    file://<firmware-name>.bit \
    file://<firmware-name>.dtsi \
    file://shell.json \
    file://<firmware-name>.xclbin \
    "

COMPATIBLE_MACHINE ?= "^$"
COMPATIBLE_MACHINE:<machine-name> = "<machine-name>"

In $yocto_workspace/build/conf/local.conf, add the following:

MACHINE_FEATURES += "fpga-overlay"
IMAGE_INSTALL:append = " \
        <firmware-name> \
        fpga-manager-script \
        "

You can then bitbake the recipe with the command:

   MACHINE=<machine-name> bitbake <firmware-name> 

You can find the compiled .dtbo files in various locations in $yocto_workspace/build using command find * -iname <firmware-name>.dtbo.

If you build the wic image using command below, you will then find the firmware(.bit.bin, .dtbo, .xclbin, .json files) on target in /lib/firmware/xilinx/<firmware-name>

MACHINE=<machine-name> bitbake kria-image-full-cmdline 

Using fpgamanger_custom bbclass in PetaLinux¶

The fpgamanager_custom bitbake class is a helper class to generate a set of FPGA firmware binaries. This method requires that user hand write their own .dtsi file. This has been depreciated starting in 2024.1. The same bitbake class applies for Yocto, but this section aims to provide an example of how to use this bitbake class in PetaLinux.

Tools and Input required¶

Petalinux of the appropriate version
SOM BSP of the appropriate release

The following hardware design hand-off artifacts are required:

PL bitstream - applies to Vivado or Vitis designs
Device tree overlay source file - the user needs to create this file based on the PL hardware design
json file - specifies if the overlay is slotted or flat and required by dfx-mgr. More information can be found here
Xclbin file - only applies to Vitis designs

Generate .dtbo file (Yocto)¶

Please refer to Kria apps firmware for example dtsi files based on the fpgamanager_custom class used in the AMD accelerated applications.

First. create

Generate .dtbo file¶

Please refer to Kria apps firmware for example dtsi files based on the fpgamanager_custom class used in the AMD accelerated applications.

First, run the following command to create a new Petalinux project from the provided SOM bsp file:

petalinux-create -t project -s xilinx-<board>-<version>.bsp
cd xilinx-<board>-<version>

The following steps assume you have created a petalinux project and built it. If the project has not been build, run this command to configure the project:

petalinux-config --silentconfig

Run the following command to generate a new firmware recipe:

petalinux-create -t apps --template fpgamanager -n user-firmware --enable --srcuri "user.bit user.dtsi user.xclbin shell.json"

The generated recipe will be located at project-spec/meta-user/recipes-apps/user-firmware/user-firmware.bb

The recipe contains the minimum required elements but can be further customized by the user for their needs.

Then the .dtbo file will be generated when building petalinux again.

petalinux-build

The newly generated .dtbo file can be found at $tmp_folder/sysroots-components/zynqmp_generic/user-firmware/lib/firmware/xilinx/user-firmware/user-firmware.dtbo $tmp_folder location can be found at project-spec/configs/config CONFIG_TMP_DIR_LOCATION=$tmp_folder

Using fpgamanger_dtg bbclass in PetaLinux¶

Alternatively, you can use the fpgamanager_dtg bitbake class which uses the AMD device tree generator (dtg) to generate a device tree overlay from a Vivado or Vitis-generated XSA file.

Tools and Input required¶

Petalinux of the appropriate version
SOM BSP of the appropriate release

The following hardware design hand-off artifacts are required:

XSA file (must include bitstream) - applies to Vivado or Vitis designs
json file - specifies if the overlay is slotted or flat and required by dfx-mgr. More information can be found here
Xclbin file - only applies to Vitis designs
dtsi file is not required and will be generated, but the user can optionally add a device tree source file that will be appended to the dtg-generated device tree file

Generate .dtbo file¶

First, run the following command to create a new PetaLinux project from the provided SOM bsp file:

petalinux-create -t project -s xilinx-<board>-<version>.bsp
cd xilinx-<board>-<version>

The following steps assume you have created a petalinux project and built it. If the project has not been build, run this command to configure the project:

petalinux-config --silentconfig

Run the following command to generate a new firmware recipe:

petalinux-create -t apps --template fpgamanager_dtg -n user-firmware --enable --srcuri "user.xsa user.xclbin shell.json"

The generated recipe will be located at project-spec/meta-user/recipes-apps/user-firmware/user-firmware.bb

The recipe contains the minimum required elements but can be further customized by the user for their needs. If you want to inspect the generated .dtsi file without petalinux/yocto cleaning things up after a successful build, add this variable into your recipe: RM_WORK_EXCLUDE += "${PN}" The .dtsi file can be found in <tmpworkspace>/work/zynqmp_generic-xilinx-linux/user-firmware/1.0-r0/build/user-firmware/pl.dtsi

Then the .dtbo file will be generated when building PetaLinux again.

petalinux-build

The newly generated .dtbo file can be found at $tmp_folder/sysroots-components/zynqmp_generic/user-firmware/lib/firmware/xilinx/user-firmware/user-firmware.dtbo $tmp_folder location can be found at project-spec/configs/config CONFIG_TMP_DIR_LOCATION=$tmp_folder

Example¶

A step by step example for generating the .dtbo file for smartcam from its platform .xsa file can be found here.

License¶

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.

You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.