Yocto Kria Support¶
Yocto contains support to generate AMD Kria™ artifacts starting in 2023.1. PetaLinux is an abstraction of Yocto; it is Yocto + Xilinx meta layers + extra tools such as XSCT, XSDB, and so on. The process and commands of generating artifacts from Yocto versus PetaLinux are different, but the backend is the same (that is, both are Yocto based).
The Yocto Project provides extensive documentation, and it is recommended that you familiarize yourself with some of the core concepts before continuing. Xilinx specific Yocto information can be found on the wiki.
Board Support Packages¶
AMD also release the Board Support Packages (BSPs) for each of the Kria platforms. More information are found in the Kria Wiki.
Machine Configurations for Kria¶
The machine configurations provided for Kria define the settings used for a given machine when building each recipe. Different artifacts would be built with each unique combination of machine name and bitbake recipe. Machine configuration files for Kria SOM and Starter Kits are found on GitHub in release branches for the perspective tool version.
Machine names and recipes for QSPI/boot image generation are listed the following:
Note that various support starts in different versions, so make sure to align Yocto release versions to the MACHINE + recipe desired.
Note that in 2024.2, some artifacts are generated either using XSCT flow, or SDT flow. Refer to this page for more details on the new SDT flow.
in 2025.1 and onward, XSCT flow is depreciated
| Machine Name | Bitbake Recipe | Availability | Description |
|---|---|---|---|
| k26-smk-sdt | kria-qspi | 2025.1** and newer | QSPI image supporting K26 Starter Kit SOM on KV and KR carrier card, using the SDT flow |
| k24-smk-sdt | kria-qspi | 2025.1** and newer | QSPI image supporting K24 Starter Kit SOM on KD carrier card, using the SDT flow |
| k26-sm-sdt | xilinx-bootbin | 2024.2 and newer | boot.bin that supports production SOM K26i and K26c, using the SDT flow |
| k24i-sm-sdt | xilinx-bootbin | 2024.2 and newer | boot.bin that supports production SOM K24i, using the SDT flow |
| k24c-sm-sdt | xilinx-bootbin | 2025.1 and newer | boot.bin that supports production SOM K24c, using the SDT flow |
| k26-smk | kria-qspi | 2023.1 through 2024.2 | QSPI image supporting K26 Starter Kit SOM on KV and KR carrier card, using the XSCT flow |
| k24-smk | kria-qspi | 2023.1 through 2024.2 | QSPI image supporting K24 Starter Kit SOM on KD carrier card, using the XSCT flow |
| k26-sm | xilinx-bootbin | 2023.1 through 2024.2 | boot.bin that supports production SOM K26i and K26c, using the XSCT flow |
| k24i-sm | xilinx-bootbin | 2023.2* through 2024.2 | boot.bin that supports production SOM K24i, using the XSCT flow |
| k24c-sm | xilinx-bootbin | 2023.2* through 2024.2 | boot.bin that supports production SOM K24c, using the XSCT flow |
* 2023.2 support for production is on the tag xlnx-rel-v2023.2_update1 repository.
** in 2025.1, image recovery cannot be generated in SDT flow. Therefore, the 2025.1 QSPI generation pulls image recovery prebuilt binary from an artifactory to build QSPI.
For .wic image generation, there are two groups of machines names: .wic images with flat support (that is, they only support one type of Kria SOM board) and .wic images with dynamic support (they can be used with multiple types of Kria SOM boards).
The following table list the flat image generation machine names:
| Machine Name | Bitbake Recipe | Availability | QEMU Support | Description |
|---|---|---|---|---|
| k26-smk-kv-sdt | kria-image-full-cmdline | 2024.2 and newer | yes | Flat wic image that supports KV260, not fully validated on target and meant for development enablement, using the SDT flow |
| k26-smk-kr-sdt | kria-image-full-cmdline | 2024.2 and newer | yes | Flat wic image that supports KR260, not fully validated on target and meant for development enablement, using the SDT flow |
| k24-smk-kd-sdt | kria-image-full-cmdline | 2024.2 and newer | yes | Flat wic image that supports KD240, not fully validated on target and meant for development enablement, using the SDT flow |
| k26-sm-sdt | kria-image-full-cmdline | 2024.2 and newer | no | Flat wic image that supports production SOM K26i and K26c, not fully validated on target and meant for development enablement, using SDT flow |
| k24i-sm-sdt | kria-image-full-cmdline | 2024.2 and newer | no | Flat wic image that supports production SOM K24i, not fully validated on target and meant for development enablement, using the SDT flow |
| k24c-sm-sdt | kria-image-full-cmdline | 2024.2 and newer | no | Flat wic image that supports production SOM K24c, not fully validated on target and meant for development enablement, using the SDT flow |
| k26-smk-kv | kria-image-full-cmdline | 2023.1 through 2024.2 | yes | Flat wic image that supports KV260, not fully validated on target and meant for development enablement, using the XSCT flow |
| k26-smk-kr | kria-image-full-cmdline | 2023.1 through 2024.2 | yes | Flat wic image that supports KR260, not fully validated on target and meant for development enablement, using the XSCT flow |
| k24-smk-kd | kria-image-full-cmdline | 2023.1 through 2024.2 | yes | Flat wic image that supports KD240, not fully validated on target and meant for development enablement, using the XSCT flow |
| k26-sm | kria-image-full-cmdline | 2023.1 through 2024.2 | no | Flat wic image that supports production SOM K26i and K26c, not fully validated on target and meant for development enablement, using XSCT flow |
| k24i-sm | kria-image-full-cmdline | 2023.2* through 2024.2 | no | Flat wic image that supports production SOM K24i, not fully validated on target and meant for development enablement, using the XSCT flow |
| k24c-sm | kria-image-full-cmdline | 2023.2* through 2024.2 | no | Flat wic image that supports production SOM K24c, not fully validated on target and meant for development enablement, using the XSCT flow |
The following table list dynamic image generation machine names:
| Machine Name | Bitbake Recipe | Availability | QEMU Support | Description |
|---|---|---|---|---|
| kria-zynqmp-generic** | kria-image-full-cmdline | 2024.2 and newer | no | wic image that dynamically supports KV260, KR260, and KD240 |
| k26-smk-sdt | kria-image-full-cmdline | 2024.2 and newer | yes | wic image that dynamically supports both KV260 and KR260, using the SDT flow |
| k24-smk-sdt | kria-image-full-cmdline | 2024.2 and newer | yes | wic image that dynamically supports KD240, using the SDT flow |
| k26-smk | kria-image-full-cmdline | 2023.1 through 2024.2 | yes | wic image that dynamically supports both KV260 and KR260, using the XSCT flow |
| k24-smk | kria-image-full-cmdline | 2023.1 through 2024.2 | yes | wic image that dynamically supports KD240, using the XSCT flow |
** For information on how to generate a .wic image with this MACHINE name, refer to Build wic image for kria-zynqmp-generic.
Build Host Requirements¶
Before starting, make sure the build host PC meets these requirements.
Besides installing the packages/tools specified by the requirement page, refer to the Issues section for possible additional requirements.
NOTE: Building using a NFS mount is not supported; use a local or scratch disk.
Besides installing the packages/tools specified by the requirement page, refer to the Issues section for possible additional requirements.
Prepare the Build Environment¶
Install the repo.
#download the Repo script:
curl https://storage.googleapis.com/git-repo-downloads/repo > repo
#Make it executable:
chmod a+x repo
#Move it on to your system path:
mv repo ~/bin/
#Add it to your path
PATH=$PATH:~/bin
#If it is correctly installed, you should see a Usage message when invoked with the help flag.
repo --help
Fetch all sources. Note that in 2024.2 and older, all images are generated with PetaLinux distribution. In 2025.1, the wic images are generated with EDF distribution, while the bootbin and QSPI images are still generated with PEtaLinux distribution. The repo init command below selects between the two distributions with the presence of a -m option.
# repo init to the Xilinx yocto project
repo init -u https://github.com/Xilinx/yocto-manifests.git -b <release-branch> #PetaLinux Distribution
repo init -u https://github.com/Xilinx/yocto-manifests.git -b rel-v2025.1 -m default-edf.xml #EDF Distribution
# Example: repo init -u https://github.com/Xilinx/yocto-manifests.git -b rel-v2025.1
# or for tags instead of branch: repo init -u https://github.com/Xilinx/yocto-manifests.git -b refs/tags/xlnx-rel-v2023.2_update1
# repo sync to get all sources
repo sync
# repo start a branch
repo start <release-branch> --all
# example: repo start rel-v2025.1 --all
# or for tags instead of branch: repo start xlnx-rel-v2023.2_update1 --all
Source environment:
#source the environment to build using bitbake
source setupsdk #PetaLinux Distribution only
source edf-init-build-env #EDF distibution only
Build the Artifacts¶
To build the artifacts, use the following command:
MACHINE=<machine name> bitbake <bitbake recipe>
For example, to build the QSPI image and wic image for the K26 starter kits, use the following command for 2023.1:
MACHINE=k26-smk bitbake kria-qspi
MACHINE=k26-smk bitbake kria-image-full-cmdline
The resulting QSPI image (kria-qspi-k26-smk.bin), .wic image (kria-image-full-cmdline-k26-smk.wic.xz), and their artifacts are found in $TMPDIR/deploy/images/k26-smk, and $TMPDIR is defined in build/conf/local.conf, by default in tmp/.
NOTE: The username for the Yocto generated image is
petalinuxfor 2024,2 and older,amd-edffor 2025.1 and newer, and you are immediately prompted to update the password.
Build wic image for kria-zynqmp-generic¶
From 2025.1 onward, you can generate a common wic image that dynamically supports all three Kria SOM starter kits with a single steo:
MACHINE=kria-zynqmp-generic bitbake kria-image-full-cmdline
In 2024.2 , you can generate a common wic image that dynamically supports all three Kria SOM starter kits with a few extra steps to generate.
# Build the DTB for K26 and K24 machines. You can also use -sdt machines if the SDT flow is desired.
MACHINE=k26-smk bitbake virtual/dtb
cp tmp/deploy/images/ k26-smk/devicetree/SMK-*.dtb <dtb_path>
MACHINE=k24-smk bitbake virtual/dtb
cp tmp/deploy/images/k24-smk/devicetree/SMK-zynqmp-sck-kd-g-revA.dtb <dtb_path>
# Add the prebuilt DTB build in above path to `conf/local.conf` in the .wic image builds `local.conf`.
PRECOMPILED_DTB_FILES_DIR = <DTB_PATH>
#Build the common .wic image:
MACHINE=kria-zynqmp-generic bitbake kria-image-full-cmdline
NOTE: In kria-zynqmp-generic generated wic image in 2024.2, the SD card is “locked in” to the started kit when first booted. That is, once you have booted the common image on a KV260, you are not be able to reuse the same SD card with the shared common Linux image on a KR260 or a KD240. This is because on initial boot, the default bitstream is locked in based on the EEPROM reading on first boot, and this is not updated on subsequent boots.
QEMU¶
Yocto can boot each of the various MACHINEs using QEMU once a build completes using the following command:
MACHINE=<machine name> runqemu nographic slirp
Exit from QEMU with ctrl-a,x.
During the build process, a QEMU configuration file is created in the output directory containing all of the configuration options set for the machine and used by the runqemu command. For example, for k26-smk, this file is found in $TMPDIR/deploy/images/k26-smk/kria-image-full-cmdline-k26-smk.qemuboot.conf.
In 2023.1, the combined starterkit k26-smk supports QEMU, and the default hardware which it emulates is KV260. To change it to KR260, update sources/meta-kria/conf/machine/k26-smk.conf according to the comment in the file.
Variables, Overrides, and the Environment¶
Most of the Yocto recipes and configuration files assign values to variables to influence the build. Machine specific overrides can be used to replace default or previously defined values with ones that are specific to the machine you are building for. Each machine will have a series of overrides which defines, in order of priority, which overrides will be considered when parsing all of the recipes and config files. It is possible to get a list of the MACHINEOVERRIDEs that are used for a given recipe as well as the log of how the system came to the final value of a variable by using the “-e” flag on a build:
MACHINE=k26-smk bitbake kria-image-full-cmdline -e
You can see if you redirect the output of bitbake -e to a file how each of the variables in the build got to its final value; for example, here is how SERIAL_CONSOLES was set for a recipe:
# $SERIAL_CONSOLES [5 operations]
# set? /scratch/jtoomey/2023/sources/poky/../meta-xilinx/meta-xilinx-core/conf/machine/zynqmp-generic.conf:46
# "115200;ttyPS0"
# set /scratch/jtoomey/2023/sources/poky/../meta-kria/conf/machine/include/kria-common.inc:14
# "115200;ttyPS1"
# set /scratch/jtoomey/2023/sources/poky/meta/conf/documentation.conf:380
# [doc] "Defines the serial consoles (TTYs) to enable using getty."
# set /scratch/jtoomey/2023/sources/poky/meta/conf/bitbake.conf:918
# [_defaultval] "${@d.getVar('SERIAL_CONSOLE').replace(' ', ';')}"
# override[qemuarm64]:set? /scratch/jtoomey/2023/sources/poky/../meta-virtualization/conf/distro/include/meta-virt-xen.inc:15
# "115200;ttyAMA0"
# pre-expansion value:
# "115200;ttyPS1"
SERIAL_CONSOLES="115200;ttyPS1"
Working with Libraries¶
If some libraries have specific version dependencies, they can be specified in recipes (.bb files). For details, refer to the Yocto documentation.
Working with Recipes¶
It is possible to work with individual components (such as recipes in github meta-kria) for the purpose of integration, debugging, or updates. For example, if you want to build the xmutil utility, you can bitbake that recipe:
MACHINE=k26-smk bitbake xmutil
This downloads and builds the xmutil sources, as well as any other recipes it depends on. For the purpose of development or debugging, it might be necessary to point the recipe to a different repo, branch, or commit by updating the SRC_URI or SRCREV (an example of the local repo commented out the following):
diff --git a/recipes-utils/xmutil/xmutil.inc b/recipes-utils/xmutil/xmutil.inc
index f83bcb3..2839b62 100644
--- a/recipes-utils/xmutil/xmutil.inc
+++ b/recipes-utils/xmutil/xmutil.inc
@@ -1,5 +1,5 @@
-REPO = "git://github.com/Xilinx/xmutil.git;protocol=https"
-SRCREV = "b5b1ad13bcc48d4cbd20476c97d05589bdfc7772"
+REPO = "git://gitenterprise.xilinx.com/jtoomey/xmutil.git;protocol=https"
+#REPO = "file:///path/to/xmutil;protocol=file"
+SRCREV = "0000000000000000000000000000000000000000"
BRANCH = "master"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
Once this has been updated, the package can be rebuilt, and bitbake picks up the new code.
MACHINE=k26-smk bitbake xmutil
It is also possible to clean in between builds to force a clean build:
MACHINE=k26-smk bitbake xmutil -c clean
Importing a New XSA File¶
By default, the Kria Yocto project downloads the .xsa files from artifactory to generate device trees for generating artifacts. To use a local .xsa file, modify the corresponding .conf file in sources/meta-kria/conf/machine/<MACHINE name>.conf for the target MACHINE. Comment out lines started with HDF_URI and add the following:
HDF_BASE = "file://"
HDF_PATH = "/path/to/XSA/file.xsa"
sha256sum is not needed for local files.
The default values for the .conf files come from sources/meta-xilinx-tools/recipes-bsp/hdf/hdf-repository.inc.
Updating Default Bitstream¶
In the Kria Starter Kits boot flow, the PL portion of the Zynq MPSoC is not programmed until during the Linux boot, DFX_manager loads the default bitstream in /lib/firmware/xilinx/k26-starter-kits/ or /lib/firmware/xilinx/k24-starter-kits/. If you need to change the PL design that is loaded by default, update the firmware folder, which is managed by the recipe located in $yocto_project_folder/sources/meta-kria/recipes-firmware/kria-base-firmware/. In that folder, the recipes can be updated to take the firmware from a local folder instead of from GitHub.
For example, to update the PL firmware for K26 only, comment out the the license and source lines in kria-base-firmware.inc:
#LICENSE = "Proprietary & GPL-2.0-only"
#LIC_FILES_CHKSUM = " \
# file://${WORKDIR}/git/LICENSE-BINARIES;md5=09db6fa082215924b1374f4f02a49f72 \
# file://${WORKDIR}/git/LICENSE-GPLv2;md5=9afdcd1be3f71bd3791fa5961075d776 \
# "
#BRANCH = "xlnx_rel_v2023.1"
#SRC_URI = "git://github.com/Xilinx/kria-base-firmware.git;protocol=https;branch=${BRANCH}"
#SRCREV = "d512881ad56fcb8ad3bffea543280c5b357bb9ea"
Put the firmware files into a folder with the same name as the k26-starter-kits.bb file :
ls /tmp/jues_yocto_2024.1_xen/sources/meta-kria/recipes-firmware/kria-base-firmware/k26-starter-kits/
k26_starter_kits.bit k26_starter_kits.dtsi shell.json
Add these lines in k26-starter-kits.bb to point to the local firmware:
SRC_URI = " \
file://k26_starter_kits.bit \
file://k26_starter_kits.dtsi \
file://shell.json \
"
Then rebuild Yocto; the added firmware are loaded during the Linux boot by dfx-manager.
Issues¶
If you see the error,
error loading hsi package: couldn't load file "libxv_commontasks.so", it might be missing the libtinfo5 library which can be installed withsudo apt-get install -y libtinfo5.
Copyright © 2023–2025 Advanced Micro Devices, Inc.