How to Build a Linux Image Using Yocto

Author: Zhang Longley, AMD Engineer, Source: AMD Developer Community

All FPGA SoC devices from AMD XILINX (Zynq-7000, Zynq MPSoC, Versal) and soft cores (Microblaze) support building Linux images using Yocto. This blog demonstrates how to build a Linux image using Yocto. The blog uses version 2024.1 of the tools to quickly build a Linux image based on ZCU102 and its boot image, and briefly introduces how to import user designs and modify the device tree in Yocto.

1. Environment for Running Yocto

• Yocto has requirements for the host and its operating system. Please refer to this link for specific requirements: https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html#compatible-linux-distribution

• On a host and operating system that meet the requirements, first run the command below to install the software packages required by Yocto. The following command is based on the Ubuntu operating system:

$ sudo apt install gawk wget git diffstat unzip texinfo gcc build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping python3-git python3-jinja2 python3-subunit zstd liblz4-tool file locales libacl1$ sudo locale-gen en_US.UTF-8$ sudo apt install libtinfo5

(Installing libtinfo5 is based on this known issue https://support.xilinx.com/s/question/0D52E00006tcCJ9SAM)

• Configure the git user email and username

$ git config --global user.email "[email protected]"$ git config --global user.name "Your Name"

2. Build Linux and Its Boot Image Based on ZCU102

• Download repo

$curl https://storage.googleapis.com/git-repo-downloads/repo > repo$chmod a+x repo

• Download Yocto manifests

$python3 ./repo init -u https://github.com/Xilinx/yocto-manifests.git -b rel-v2024.1$python3 ./repo sync

• Configure Yocto environment

$source setupsdk

• Build the image

$MACHINE=zcu102-zynqmp bitbake petalinux-image-minimal

Other available MACHINES can be found in sources/meta-xilinx/meta-xilinx-bsp/conf/machine/, such as: zcu106-zynqmp, zc706-zynq7

3. Run the Image

• After the image is built, all images are located in the Yocto project directory build/tmp/deploy/images/zcu102-zynqmp/.

• In the image directory, copy the following images to the SD card and rename them. (The xxx in the names below represents the compilation time, which will change with each compilation)

• boot.scr

• BOOT-myhardware-zcu102-zynqmp-xxx.bin (rename to BOOT.BIN)

• Image–6.6.10-xilinx-v2024.1+git0+3af4295e00-r0.0-myhardware-zcu102-zynqmp-xxx.bin (rename to Image)

• petalinux-image-minimal-myhardware-zcu102-zynqmp-xxx.rootfs.cpio.gz.u-boot (rename to rootfs.cpio.gz.u-boot)

• system.dtb

• Insert the SD card into ZCU102 and set it to boot from the SD card. Power on and observe the serial output.

4. Import User Design in Yocto

4.1 Import XSA File

The user creates a Vivado project based on their own circuit board and compiles to export the XSA file. Then the user can follow the steps below to create a new MACHINE in Yocto and import the XSA file.

• Create a new layer

$bitbake-layers create-layer ../sources/meta-myhardware$bitbake-layers add-layer ../sources/meta-myhardware$mkdir ../sources/meta-myhardware/conf/machine

• Add user configuration (replace </path/to/my> with the directory path where the XSA file is located)

$cat << EOF > ../sources/meta-myhardware/conf/machine/myhardware-zcu102-zynqmp.conf$#Base this machine configuration off of the zcu102 board and then make changes below$require conf/machine/zcu102-zynqmp.conf$HDF_BASE = "file://"$# Replace with the path to your XSA file from hardware$HDF_PATH = "</path/to/my>/design.xsa"$EOF

• Modify conf/local.conf to set MACHINE to myhardware-zcu102-zynqmp

$sed -i "/MACHINE ??=/c\MACHINE ??= \"myhardware-zcu102-zynqmp\"" conf/local.conf

4.2 Modify Device Tree

The user can add system-user.dtsi to modify the device tree generated from the XSA file.

• Open ../sources/meta-xilinx-tools/recipes-bsp/device-tree/device-tree.bbappend with a text tool and add the following statements.

FILESEXTRAPATHS:prepend := "${THISDIR}/files:"SYSTEM_USER_DTSI ?= "system-user.dtsi"SRC_URI:append = " file://${SYSTEM_USER_DTSI}"do_configure:append() {        cp ${WORKDIR}/${SYSTEM_USER_DTSI} ${B}/device-tree        echo "/include/ \"${SYSTEM_USER_DTSI}\"" >> ${B}/device-tree/system-top.dts}

• Create and modify system-user.dtsi

mkdir sources/meta-xilinx-tools/recipes-bsp/device-tree/filesvim sources/meta-xilinx-tools/recipes-bsp/device-tree/files/system-user.dtsi

Below is an example of a modification:

  / {      };      &axi_iic_0 {          m24c08@50 {              compatible = "at,24c08";              reg = <0x50>;          };};

4.3 Build and Run the Image

• Run the command below to build the user Linux image

$bitbake petalinux-image-minimal

• Refer to point 3 above to run the image, located in the directory: build/tmp/deploy/images/myhardware-zcu102-zynqmp/

Reference Documentation:

https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html

https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18841883/Yocto

https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/2824503297/Building+Linux+Images+Using+Yocto

https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/2787311617/PetaLinux+to+Yocto+-+Command+Cross+Reference

[Live Broadcast Preview]