Project-2: Build a Custom PetaLinux Image for Kria Board

Overview

In this tutorial, we’ll show how to build a custom PetaLinux image for your AMD Kria board using either an official BSP file or your own exported Vivado .xsa file.

This guide is a direct continuation of Project-1: Run PetaLinux in Docker: Isolated Development, where we prepared a Docker container with PetaLinux 2024.2 running in an isolated, portable development environment.

By the end of this guide, you’ll have a bootable SD card image built from scratch using the PetaLinux tools, completely inside Docker. This gives you full control of the boot and runtime environment for your Kria board, using official or customized hardware designs.

Prerequisites

• Completion of Project-1: Run PetaLinux in Docker: Isolated Development
• A working Docker container with PetaLinux 2024.2 installed (from Project-1)
• BSP file for your board (e.g., xilinx-kr260-starterkit-v2024.2-xxxxxxx.bsp)
• Optionally, a custom Vivado-generated .xsa file
• Optionally, a custom DTS file for Kria board

Start the Docker Container

We use the Docker image we created in the previous tutorial.

1. Start the Docker container:

cd kria-petalinux
./run.sh

2. Source the PetaLinux environment:

This is already set up in the container’s .bashrc file, but you can also run it manually if needed.

source /tools/petaLinux/2024.2/settings.sh

3. Create the PetaLinux Project:

We have several option how to create a new Kria project in PetaLinux:

• Option A: From a BSP file
• Option B: From a custom XSA (exported hardware) and DTO (Device Tree Overlay) files

Option A: Create Project from BSP file

1. Download the Official BSP

Visit the Xilinx Download Center and download the official BSP for your Kria board (e.g., xilinx-kr260-starterkit-v2024.2-12072024.bsp).

Save the file into your working directory.

2. Create the PetaLinux Project

Launch your Docker container (as set up in [Project-1]) and create a new project using the downloaded BSP:

petalinux-create -t project -s ./xilinx-kr260-starterkit-v2024.2-12072024.bsp --name kria_kr260_bsp_project

cd kria_kr260_bsp_project/.

If your project is created from official BSP, you can skip the Option-B for now and jump to the building section.

Option B: Create a PetaLinux Project from a Custom XSA and Device Tree Overlay

If you prefer working with a custom hardware design, you can generate the .xsa file from your Vivado project and use it to configure your PetaLinux build. In addition, a matching Device Tree Overlay (DTO) is often needed to complete the hardware description.

In this example, we’ll demonstrate the process using the .xsa and .dtso files extracted from the official Kria BSP, but the same steps apply to your own custom hardware exports.

1. Extract the .xsa File from the BSP

Use the following tar command to extract the kr260_base.xsa from the BSP archive:

tar -I unxz -xvf xilinx-kr260-starterkit-v2024.2-12072024.bsp --wildcards '*.xsa' --strip-components=4

This will locate and extract the hardware design file used as a base platform.

2. Extract the .dtso File from the BSP

Similarly, extract the Device Tree Overlay with:

tar -I unxz -xvf xilinx-kr260-starterkit-v2024.2-12072024.bsp --wildcards '*.dtso' --strip-components=3

This will extract zynqmp-sck-kr-g-revB.dtso, which is used to supplement the base device tree with additional configuration (e.g., peripherals, overlays).

3. Create a New Kria PetaLinux Project

Launch the Docker container you configured in [Project-1] and create a new PetaLinux project:

petalinux-create --type project --template zynqMP --name kria_kr260_project

Note: You may see a deprecation warning regarding the --type argument. It’s safe to ignore for now.

4. Apply the Hardware Platform (.xsa)

Navigate into the newly created project and configure it using the extracted XSA:

cd kria_kr260_project
petalinux-config --get-hw-description=../kr260_base.xsa

After this step, the configuration menu will launch automatically.

5. Update Yocto Machine Name

Inside the configuration menu:

• Go to Yocto Settings
• Set the Yocto Machine Name to:

xlnx_zynqmp_smk_k26_rev2

This ensures that the appropriate kernel and boot components are selected for the Kria KR260 SOM.

6. Set INITRD image name

Still within the configuration menu:

• Navigate to Image Packaging Configuration
• Set INITRAMFS/INITRD Image name to:

petalinux-initramfs-image

This ensures that PetaLinux uses the correct initramfs image during boot (specifically, rootfs.cpio.gz.u-boot) instead of attempting to locate a non-existent ramdisk.image.gz.

7. Add the Device Tree Overlay (DTO)

Still within the configuration menu:

• Navigate to DTG Settings
• Under Extra dts/dtsi files, specify the path to your overlay:.

${PROOT}/project-spec/dts_dir/zynqmp-sck-kr-g-revB.dtso

• Then, under the same submenu, navigate to Kernel Bootargs.
• In the Add Extra Boot Arguments field, add:

cma=900M

This ensures that the system reserves 900 MB of contiguous memory for the Contiguous Memory Allocator (CMA), which is crucial for hardware blocks like the VCU (Video Codec Unit) or other accelerators that require large, contiguous memory regions. Without this setting, high-resolution video encoding/decoding or similar operations may fail due to insufficient memory availability.

Then save and exit.

Now create the dts_dir directory and copy the .dtso file into it:

mkdir project-spec/dts_dir
cp ../zynqmp-sck-kr-g-revB.dtso project-spec/dts_dir/

8. Apply BSP Customizations

To finalize your custom Petalinux project setup, apply the following configuration customizations to the petalinuxbsp.conf file. These are adapted from the official BSP to ensure compatibility with the Kria KR260 Starter Kit:

Run this command from within the kria_kr260_project directory:

cat >> project-spec/meta-user/conf/petalinuxbsp.conf <<EOF
EXTRA_DTFILE_PREFIX = "system"
EXTRA_DTFILES_BUNDLE = "1"
UBOOT_IMAGE_BLOB:k26 = "0"
INITRAMFS_PACKAGES:append = " mac-config "
UBOOT_DTFILE_PREFIX:kria = "system"
UBOOT_DT_FILES:kria = "" 
QEMU_HWDTB_NAME:k26-kr = "board-zynqmp-k26-starterkit-virt.dtb"
EXTRA_IMAGEDEPENDS:append = " board-id-data"
MACHINEOVERRIDES =. "kria:" 
MACHINEOVERRIDES =. "k26-kr:"
MACHINEOVERRIDES =. "k26-kria:"
MACHINEOVERRIDES =. "k26-smk:"
MACHINE_FEATURES = "vcu"
DEVICE_TREE = "devicetree/system-zynqmp-sck-kr-g-revB.dtb"
SYMLINK_FILES:zynqmp = "system-zynqmp-sck-kr-g-revB.dtb:system.dtb"
UBOOT_MACHINE:zynqmp = "xilinx_zynqmp_kria_defconfig"
IMAGE_BOOT_FILES:zynqmp = "ramdisk.cpio.gz.u-boot boot.scr Image system.dtb"
EOF

Explanation of Key Parameters:

• EXTRA_DTFILE_PREFIX, UBOOT_DTFILE_PREFIX: Defines the prefix used for system device trees in Linux and U-Boot builds.
• EXTRA_DTFILES_BUNDLE = "1": Enables bundling of additional device tree files.
• UBOOT_IMAGE_BLOB:k26 = "0": Disables U-Boot image blob creation; typically not needed for Kria builds.
• INITRAMFS_PACKAGES:append = " mac-config ": Adds the mac-config utility to the initramfs, allowing early MAC address setup.
• UBOOT_DT_FILES:kria = "": Explicitly disables default U-Boot DT files to avoid conflicts.
• QEMU_HWDTB_NAME:k26-kr: Specifies the DTB for QEMU simulation (if used).
• EXTRA_IMAGEDEPENDS:append = " board-id-data": Adds board-specific identification support.
• MACHINEOVERRIDES: Provides flexibility by layering overrides for various Kria board naming conventions.
• MACHINE_FEATURES = "vcu": Enables the VCU (Video Codec Unit) features for hardware video encoding/decoding support.
• DEVICE_TREE: Sets the default Linux device tree blob to use in the build.
• SYMLINK_FILES: Ensures a symbolic link is created between the board-specific DTB and the standard system.dtb.
• UBOOT_MACHINE: Specifies the U-Boot configuration target for Kria boards.
• IMAGE_BOOT_FILES: Lists the required boot files, including the ramdisk, kernel image, boot script, and device tree.

These customizations ensure your project mirrors the behavior of the official BSP while remaining fully customizable.

Build the Project

1. Start the build process:

petalinux-build

If the build fails due to fetch errors, simply rerun the command — temporary fetch issues often resolve on retry.

After a successful build, you’ll find the bootable files and root filesystem in:

ls -l images/linux

Save Kernel Device Tree and rootfs Files

For use in later tutorial projects, you’ll need to extract the following files from the build output:

• Linux Kernel: Image
• Device Tree Blob: system.dtb
• Root File System: rootfs.tar.gz

Copy these (the actual files, not symbolic links) to a safe location for future use.

These files are also available in the tftpboot directory within your workspace, which we set up in the previous project.

Linux Kernel Source Files

The Linux kernel source directory—useful if you plan to build out-of-tree kernel modules—is typically located at:

ls build/tmp/work/xlnx_zynqmp_smk_k26_rev2-xilinx-linux/linux-xlnx/6.6.40+git/linux-xlnx_zynqmp_smk_k26_rev2-standard-build

Note: The xlnx_zynqmp_smk_k26_rev2 value is your Yocto Machine Name, which can be configured via:

petalinux-config → Yocto Settings → Yocto Machine Name

To make access easier, you can create a symbolic link to the kernel source directory from your project root:

ln -s kria_kr260_project/build/tmp/work/xlnx_zynqmp_smk_k26_rev2-xilinx-linux/linux-xlnx/6.6.40+git/linux-xlnx_zynqmp_smk_k26_rev2-standard-build ../linux

This will let you refer to it as ./linux from your workspace.

Optional: Additional Project Configuration Steps

If you’re using a custom XSA file, you may need to perform additional configuration steps before building your PetaLinux project. Run the following configuration commands from the root of your PetaLinux project. If your project doesn’t require changes, you can skip this section.

1. Kernel Configuration

petalinux-config -c kernel

2. RootFS Configuration

petalinux-config -c rootfs

3. Device Tree Configuration

petalinux-config -c device-tree

4. U-Boot Configuration

petalinux-config -c u-boot

5. Main Project Configuration

petalinux-config

6. Custom Bootargs Settings

If you need to define custom Linux kernel boot arguments, you can configure them in the main menu configuration:

• Run:

petalinux-config

• Navigate to: DTG Settings → Kernel Bootargs
• Uncheck: [ ] generate boot args automatically
• Provide your own bootargs, for example:

console=ttyPS1,115200 earlycon root=/dev/sda2 rw rootwait rootfstype=ext4

Bootargs Explanation:

• console=ttyPS1,115200: UART device for console output
• earlycon: Enables early kernel messages
• root=/dev/sda2: Use second partition on SD card as root filesystem
• rw: Mount root filesystem with read-write permissions
• rootwait: Wait until root device is available
• rootfstype=ext4: Specify the filesystem type

7. Rebuild the Project

After making any configuration changes, rebuild the PetaLinux project:

petalinux-build

Create the SD card Image

Package the boot components into a .wic image:

petalinux-package --wic --bootfiles "ramdisk.cpio.gz.u-boot boot.scr Image system.dtb"

The final .wic image will be located at:

ls -l images/linux/petalinux-sdimage.wic

Compress the image file:

gzip images/linux/petalinux-sdimage.wic

This generates a new file named:

ls -l images/linux/petalinux-sdimage.wic.gz

You can flash this image to an SD card and boot your Kria board to test the system.

Tip: In the next tutorials, you’ll learn how to streamline development by booting the Kria board over the network, avoiding repeated SD card flashing.

Generate the SDK

To build and install the PetaLinux SDK (Software Development Kit), follow these steps:

1. Build the SDK installer:

petalinux-build --sdk

This will generate an SDK installation script named sdk.sh located under images/linux.

2. Install the SDK:

Run the installer and provide an installation path (e.g., one level above the current project directory):

./images/linux/sdk.sh

When prompted, enter:

../sdk

This installs both the sysroot and cross-compilation toolchain required for building ARM64 user-space applications for the Kria board.

3. Initialize the SDK environment:

Before using the SDK, source the environment setup script:

cd ..
source sdk/environment-setup-cortexa72-cortexa53-xilinx-linux

4. Verify that the environment is correctly configured:

echo $CC
echo $ARCH
echo $CROSS_COMPILE

5. Optional – Verify Kernel Sources:

If you want to browse or build kernel modules, check that the kernel source tree is available:

ls -l linux/

Summary

You now have a fully set up SDK and a functional SD card image, built from either your custom Vivado hardware design or the official BSP.

Flash the image to an SD card, insert it into your Kria board, and boot directly into your custom PetaLinux system—entirely built and managed within Docker.

Next Step

In the next tutorial, we’ll show how to boot the Kria board via TFTP server and use an NFS-rooted filesystem, enabling quick development without needing to flash the SD card.