Getting Started with the Kria KD240 in PetaLinux 2023.2

Since receiving my new Kria KD240 Drives Starter Kit and upgrading to the 2023.2 versions of Vivado, Vitis, and PetaLinux, I decided it was time for another one of my getting started tutorial series. So far I've covered creating a custom hardware deign for the Kria KD240 in Vivado, and a standalone application in Vitis Unified. This project tutorial follows up with creating a base Linux image for the Kria KD240 in PetaLinux 2023.2.

I will be using the extensible Vitis platform XSA that I exported from Vivado so it will have the hooks for accelerated application development which is one of the next project tutorial posts in this series. As I've previously mentioned, since there was a pretty big overhaul with the Vitis IDE going from Vitis Classic (2023.1) to Vitis Unified (2023.2) I can only vouch that these tutorials with work with the 2023.2 of all the AMD FPGA tools (Vivado, Vitis, and PetaLinux). Do not mix and match versions.

Download PetaLinux KD240 BSP

There are two Kria K24 board support packages on the AMD Downloads website under the Petalinux tab. One is for just the Kria K24 SOM itself, and the other is for the Kria K24 Starter Kits. Be sure download the one for the Kria K24 Starter Kits for the KD240.

Create PetaLinux Project from KD240 BSP

While it's definitely an option to create a PetaLinux project from scratch for the KD240, it is much easier to create a project from the BSP so everything is preconfigured for the kernel, device tree, root filesystem, etc. Then a hardware platform XSA can be imported into the PetaLinux project to pull in any custom hardware design created in the corresponding Vivado project (like my custom motor controller with AXI GPIO interface).

Use the following command to create a PetaLinux project from a BSP:

~$ petalinux-create -t project -s <path to downloaded BSP> --name <desired project name>

I personally like to create the PetaLinux project for a design in the top level directory of the Vivado project that I created the hardware platform in:

~$ cd ./Kria_KD240
~/Kria_KD240$ petalinux-create -t project -s ../Downloads/xilinx-kd240-starterkit-v2023.2-10140544.bsp --name kd240_linux_os

Once the PetaLinux project has been generated, change directories into it:

~/Kria_KD240$ cd ./kd240_linux_os

Import Custom XSA into Project

As I previously mentioned, I am pulling in a custom hardware platform I made for the KD240 in Vivado. Since I exported a couple different versions, I copied the target one (the extensible Vitis platform version) into the top level directory of the PetaLinux project so I wouldn't forget which one I used.

~/Kria_KD240/kd240_linux_os$ cp ../kd240_base.xsa ./

Use the following command to import the XSA hardware platform into the PetaLinux project:

$ petalinux-config --get-hw-description ./<path to XSA>
~/Kria_KD240/kd240_linux_os$ petalinux-config --get-hw-description ./

This will also launch the hardware configuration ASCII GUI:

I personally always like to disable TFTP boot because I never use it:

Exit the hardware configuration ASCII GUI, saving the changes when prompted.

Customize Linux Elements

Since I created this PetaLinux project from the BSP for the Kria KD240 board, all of the necessary kernel drivers, filesystem libraries, etc. are already enabled/configured in the project. However, if the need for a custom peripheral or new library arises where it is desired to build it into the base image, the following commands can be used to bring up the ASCII configuration editors for the kernel, root filesystem, and u-boot respectively:

~$ petalinux-config -c kernel 
~$ petalinux-config -c rootfs
~$ petalinux-config -c u-boot

My custom motor controller is just using an AXI GPIO interface, so it didn't need any other drivers enabled that weren't by default from the Kria's BSP.

Build PetaLinux Project

With the PetaLinux project configured, the next step is to build it:

~/Kria_KD240/kd240_linux_os$ petalinux-build

I've built a few 2023.2 PetaLinux projects so far since its release and I get these same QA Issue warnings every time in all of them:

The warning doesn't cause the build to fail, nor have I found any functional issues with the Linux images running on the target FPGA boards. So I've been ignoring these warnings.

Package WIC for SD Card

With the project successfully built, the next step is to create a wic image to flash an SD card with using a tool such as balenaEtcher.

The wic image handles automatically creating the two partitions on the SD card when imaging it for the FAT32 boot partition and the EXT4 root filesystem partition and placing the appropriate files in each partition. The wic image knows which files to put in what partition based on the flags used in the petalinux-package --wic command.

To create the wic image, point the petalinux-package command to the ./images/linux output directory in the PetaLinux project to pull the files for the SD card from with the --images-dir flag.

The KD240 requires the Ramdisk image, boot script, kernel image, and device tree blobs to go in the boot partition of the SD card. As I previously mentioned, flags used in the petalinux-package --wic command tell the wic image which partition to put what files into. The --bootfiles flag tells the wic image to put the specified files into the boot partition:

~/Kria_KD240/kd240_linux_os$ petalinux-package --wic --images-dir images/linux/ --bootfiles "ramdisk.cpio.gz.u-boot,boot.scr,Image,system.dtb,system-zynqmp-sck-kd-g-revA.dtb"

Packaging the wic image for the first time tends to take a few moments, and is usually around 6GBs in size. An 8GB SD card is the minimum, but I usually use 16GB or 32GB. And the high-speed class 10 rated SD cards are an absolute must. I've tried using cheap, lower spec SD cards in the past and all sorts of weirdness happened.

Update Kria Starter Kit Boot Firmware

The Kria KD240 comes with factory pre-programmed boot firmware located in the Kria SOM's QSPI flash. Since I got one of the first KD240 kits, I decided it would be a good idea to update the firmware before attempting to run my Linux image on it.

I previously wrote up the process for updating the boot firmware on my Kria KV260 using the boot image recovery tool imaged into the QSPI of the Kria. The process is still the same for the Kria KD240:

Further details and the download for the latest K24 boot firmware can be found on the Kria wiki here.

Create Boot Binary

Now the boot binary above should be sufficient unless Linux functionally such as the boot order, or root filesystem type are changed in the PetaLinux project. In that case, a new boot binary needs to be generated from the PetaLinux project using the following command:

~/Kria_KD240/kd240_linux_os$ petalinux-package --boot --u-boot --force

Since I disabled TFTP boot, I did need to create a new boot binary and upload it to the Kria's QSPI flash memory. I haven't figured out how to image the QSPI on the Kria from the new Vitis Unified IDE yet, so I have been using the boot image recovery tool as I outlined in the previous step.

Test on Hardware

After updating the boot binary in the QSPI of my Kria K24 with the version from my project, I imaged an SD card with the wic image:

While I have plans to add support for a USB Wifi dongle later on, I connected my KD240 to my router via ethernet for a network connection for now. Like I mentioned in my Vivado tutorial post, the default ethernet port that is connected to the Zynq MPSoC's MIO is the single port RJ45 connector J24:

Using Putty to connect to the serial UART port (J4) of the KD240, I powered the board to verify that the Linux image could boot correctly.

The default user as configured by the KD240 PetaLinux BSP is petalinux and it will prompt for a new password to be created upon the first boot.

The Kria SOM dashboard is also included as an application in the KD240 PetaLinux BSP, a link to which is printed at the end of the boot process right before the prompt for a user login comes up. This link can be copy+pasted into a web browser to access:

I've personally found that the Kria SOM dashboard application runs the best in FireFox, but it works in Chrome and Safari as well.

Like I mentioned at the beginning of this post, I used the extensible Vitis platform XSA that I exported from Vivado so the Linux image on my KD240 has the hooks for accelerated application development. So this PetaLinux project will be the starting point for my upcoming project posts for accelerated application development!