Yocto Kria Support¶
Yocto contains support to generate Kria artifacts starting in 2023.1. Note that PetaLinux is an abstraction of Yocto - it is Yocto + Xilinx meta layers + extra tools such as XSCT, XSDB, etc. The process and commands of generating artifacts from Yocto vs PetaLinux are different, but the backend is the same (e.g. both are Yocto based).
The Yocto Project provides extensive documentation, and it is recommended to familiarize yourself with some of the core concepts before continuing. Xilinx specific Yocto information can be found on the 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 can be found in github in release branches for the perspective tool version.
Machine names and recipes for QSPI / boot image generation are listed below.
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 and onward, the artifacts are generated either using XSCT flow, or SDT flow. Refer to this page for more details on the new SDT flow.
| Machine Name | Bitbake Recipe | Availability | Description |
|---|---|---|---|
| k26-smk-sdt | kria-qspi | 2024.2 and newer | QSPI image supporting K26 Starter Kit SOM on KV and KR carrier card, using SDT flow |
| k26-smk | kria-qspi | 2023.1 and newer | QSPI image supporting K26 Starter Kit SOM on KV and KR carrier card, using XSCT flow |
| k24-smk-sdt | kria-qspi | 2024.2 and newer | QSPI image supporting K24 Starter Kit SOM on KD carrier card, using SDT flow |
| k24-smk | kria-qspi | 2023.1 and newer | QSPI image supporting K24 Starter Kit SOM on KD carrier card, using XSCT flow |
| k26-sm-sdt | xilinx-bootbin | 2024.2 and newer | boot.bin that supports production SOM K26i and K26c, using SDT flow |
| k26-sm | xilinx-bootbin | 2023.1 and newer | boot.bin that supports production SOM K26i and K26c, using XSCT flow |
| k24i-sm-sdt | xilinx-bootbin | 2024.2 and newer | boot.bin that supports production SOM K24i, using SDT flow |
| k24i-sm | xilinx-bootbin | 2023.2* and newer | boot.bin that supports production SOM K24i, using XSCT flow |
| k24c-sm-sdt | xilinx-bootbin | 2024.2 and newer | boot.bin that supports production SOM K24c, using SDT flow |
| k24c-sm | xilinx-bootbin | 2023.2* and newer | boot.bin that supports production SOM K24c, using XSCT flow |
* 2023.2 support for production is on repository tag xlnx-rel-v2023.2_update1
For .wic image generation, there are two groups of machines names - wic images with flat support (e.g. 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).
Below table list 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 SDT flow |
| k26-smk-kv | kria-image-full-cmdline | 2023.1 and newer | yes | flat wic image that supports KV260, not fully validated on target and meant for development enablement, using XSCT 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 SDT flow |
| k26-smk-kr | kria-image-full-cmdline | 2023.1 and newer | yes | flat wic image that supports KR260, not fully validated on target and meant for development enablement, using XSCT 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 SDT flow |
| k24-smk-kd | kria-image-full-cmdline | 2023.1 and newer | yes | flat wic image that supports KD240, not fully validated on target and meant for development enablement, using XSCT 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 |
| k26-sm | kria-image-full-cmdline | 2023.1 and newer | 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-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 SDT flow |
| k24i-sm | kria-image-full-cmdline | 2023.2* and newer | no | flat wic image that supports production SOM K24i, not fully validated on target and meant for development enablement, using XSCT 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 SDT flow |
| k24c-sm | kria-image-full-cmdline | 2023.2* and newer | no | flat wic image that supports production SOM K24c, not fully validated on target and meant for development enablement, using XSCT flow |
Below 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 SDT flow |
| k26-smk | kria-image-full-cmdline | 2023.1 and newer | yes | wic image that dynamically supports both KV260 and KR260, using XSCT flow |
| k24-smk-sdt | kria-image-full-cmdline | 2024.2 and newer | yes | wic image that dynamically supports KD240, using SDT flow |
| k24-smk | kria-image-full-cmdline | 2023.1 and newer | yes | wic image that dynamically supports KD240, using XSCT flow |
** refer to Build wic image for kria-zynqmp-generic section on how to generate .wic image with this MACHINE name
Build Host Requirements¶
Before starting, make sure the build host PC meets these requirements.
Besides installing the packages/tools specified by the requirement page, look in issues section for possible additional requirements.
Note that building using an NFS mount is not supported - use a local or scratch disk.
Besides installing the packages/tools specified by the requirement page, look in issues section for possible additional requirements.
Prepare the Build Environment¶
Install 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
# repo init to the Xilinx yocto project
repo init -u https://github.com/Xilinx/yocto-manifests.git -b <release-branch>
# Example: repo init -u https://github.com/Xilinx/yocto-manifests.git -b rel-v2023.2
# 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-v2023.2 --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
Build the Artifacts¶
To build the artifacts, use below command:
MACHINE=<machine name> bitbake <bitbake recipe>
For an example, to build QSPI image and wic image for K26 starter kits use below 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 can be found in $TMPDIR/deploy/images/k26-smk, and $TMPDIR is defined in build/conf/local.conf, by default in tmp/.
Note that the username for Yocto generated image is petalinux and you will be prompted to update password right away.
Build wic image for kria-zynqmp-generic¶
From 2024.2 onwards, user can generate a common wic image that dynamically supports all 3 Kria SOM starter kits. However, it requires a few extra steps to generate.
Build the DTB for k26 and k24 machines. Note, can also use -sdt machines if 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 prebuilt DTB build in above path to conf/local.conf in the wic image builds local.conf
PRECOMPILED_DTB_FILES_DIR = <DTB_PATH>
Build common WIC image:
MACHINE=kria-zynqmp-generic bitbake kria-image-full-cmdline
Note that in Yocto 2024.2, the SD card would be “locked in” to the started kit on which it first booted. E.g. once you have booted the common image on a KV260, you will not be able to re-use 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 will be locked in based on 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. This is the command:
MACHINE=<machine name> runqemu nographic slirp
Exit from QEMU with: ctrl-a,x
Note that during the build process, a QEMU configuration file is created in the output dir containing all of the configuration options set for the machine and used by the runqemu command. For example, for k26-smk, this file can be 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 in order 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¶
In case some libraries have specific version dependencies, they can be specified in recipes (.bb files). Refer to Yocto documentation for details.
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 we want to build the xmutil utility we can bitbake that recipe:
MACHINE=k26-smk bitbake xmutil
This will download and build 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. (example of local repo commented out below)
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 will pick 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, Kria Yocto project downloads .xsa files from artifactory to generate device trees for generating artifacts. If you wanted to use a local .xsa file, then you need to modify the corresponding .conf file in sources/meta-kria/conf/machine/<MACHINE name>.conf for the target MACHINE. Add the following after the line that specified HDF_MACHINE:
HDF_BASE = "file://"
HDF_PATH = "/path/to/XSA/file.xsa"
SRC_URI[<MACHINE name>.sha256sum] = "<sha value>"
<sha value> can be obtained with command sha256sum <name>.xsa.
Note that default values for the .conf files come from sources/meta-xilinx-tools/recipes-bsp/hdf/hdf-repository.inc.
Updating Default Bitstream¶
In Kria Starter Kits boot flow, the PL portion of the ZynqMPSoC is not programmed until during Linux boot, DFX_manager loads the default bitstream in /lib/firmware/xilinx/k26-starter-kits/ or /lib/firmware/xilinx/k24-starter-kits/. If user need to change the PL design that is loaded by default, they will need to update the firmware folder, which is managed by 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 an example, to update the PL firmware for K26 only, first comment out these 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"
Then put the firmware files into a folder with the same name as the .bb file k26-starter-kits:
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 into 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 will be loaded during Linux boot by dfx-manager.
Issues¶
If you see the error
error loading hsi package: couldn't load file "libxv_commontasks.so", it maybe missing libtinfo5 library which can be installed withsudo apt-get install -y libtinfo5
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.
Copyright© 2023 Advanced Micro Devices, Inc