How to Patch PetaLinux

Modifying the kernel, drivers and standalone components

Posted on January 2, 2021 |Jeff Johnson

When we build PetaLinux for custom hardware we invariably need to modify components of the boot image: FSBL, U-Boot, or the kernel itself. I use the words “modify” and “patch” interchangably here because the accepted way to make changes to the boot components is to apply “patches” to them. A patch is simply a “diff” between the original source code and the modified source code. To generate the “diff” file, we can use Linux commanddiff

How are PetaLinux sources managed?

The first thing to understand is how the source code that goes into PetaLinux is managed. Each PetaLinux release is composed of a specific commit of several Git repositories. In this post we will only talk about four of those repositories; those containing the source code for the FSBL, U-Boot, Device tree and the kernel respectively:

• Standalone (including FSBL):embeddedsw
• U-Boot:u-boot-xlnx
• Device tree:device-tree-xlnx
• Kernel:linux-xlnx

To give an example, PetaLinux 2020.2 is composed of the following commits of those repositories, which are appropriately tagged:

• embeddedsw: tagxilinx-v2020.2
• u-boot-xlnx: tagxlnx_rebase_v2020.01_2020.2
• device-tree-xlnx
  : tagxilinx-v2020.2
• linux-xlnx: tagxlnx_rebase_v5.4_2020.2

To determine the corresponding tags for a specific version of PetaLinux, just look up the PetaLinux release notes. For example, the tags shown above were taken from thePetaLinux 2020.2 Release Notes.

General procedure for patching PetaLinux

The general procedure for patching a build component is the following:

1. Clone the source code usinggit cloneand checkout a specific release tag
2. Modify our local copy of the source code
3. Generate a patch file usinggit diff
4. Include the patch file in our PetaLinux project config (project-spec)

Now lets go into the details by looking at four specific examples: how to patch the FSBL, U-Boot, device tree and the kernel.

How to patch the FSBL

The FSBL is standalone software, and the source code for it is managed in theembeddedswGithub repository. By the way, theembeddedswrepository contains a whole lot more than the FSBLs, it also contains all of the standalone drivers for Xilinx IP, the light-weight IP library, and more.

1. The first step is to clone the repository and checkout the release tag.

git clone https://github.com/Xilinx/embeddedsw.git
cd embeddedsw
git checkout xilinx-v2020.2

1. Now you need to locate the source code of the FSBL that you want to modify, and apply the changes to your local copy of the repository. For example, if you wanted to modify the ZynqMP FSBL, you would find its sources inlib/sw_apps/zynqmp_fsbl/srcand you would edit those sources.

2. Once your changes are made, you need to generate the patch file by using this command from the directory of the local Git repository:git diff > fsbl.patch. I’ve chosen the filenamefsbl.patch. You should call it something that describes your patch, but you must keep the.patchextension.

3. Now we need to copy the patch file into our PetaLinux project configuration files. Copy the patch file to/project-spec/meta-user/recipes-bsp/fsbl/files/.

4. Now open this file in a text editor/project-spec/meta-user/recipes-bsp/fsbl/fsbl_%.bbappendand add this line to the top:SRC_URI += "file://fsbl.patch". If the file doesn’t exist, you can create it with the following text:

SRC_URI += " file://fsbl.patch"
  
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"

How to patch U-Boot

Xilinx manages its own version of U-Boot that supports all of its devices. If you need to modify Xilinx U-Boot, you’ll find the source code managed in theu-boot-xlnxrepository.

1. Clone theu-boot-xlnxrepository and checkout the appropriate release tag.

git clone https://github.com/Xilinx/u-boot-xlnx.git
cd u-boot-xlnx
git checkout xilinx-v2020.2

1. Make the changes to the local copy of the repository and save the changes.
2. Generate the patch file by running this command from the local repo directory:git diff > uboot.patch
3. Copy the patch file to/project-spec/meta-user/recipes-bsp/u-boot/files/
4. Edit the file/project-spec/meta-user/recipes-bsp/u-boot/u-boot-xlnx_%.bbappendand add the following line:SRC_URI += "file://uboot.patch"

The complete file might look like the following (note that this file is for PetaLinux 2020.2).

FILESEXTRAPATHS_prepend := "${THISDIR}/files:"

SRC_URI += "file://platform-top.h"
SRC_URI += "file://uboot.patch"

do_configure_append () {
	if [ "${U_BOOT_AUTO_CONFIG}" = "1" ]; then
		install ${WORKDIR}/platform-auto.h ${S}/include/configs/
		install ${WORKDIR}/platform-top.h ${S}/include/configs/
	fi
}

do_configure_append_microblaze () {
	if [ "${U_BOOT_AUTO_CONFIG}" = "1" ]; then
		install -d ${B}/source/board/xilinx/microblaze-generic/
		install ${WORKDIR}/config.mk ${B}/source/board/xilinx/microblaze-generic/
	fi
}

How to patch device-tree-xlnx

The device tree repository contains scripts that are used by PetaLinux to generate device trees from the Vivado design. Most of the times where I have had an issue with the generated device tree, it has been easier to fix the problem by adding a corrected device tree to my design. However if you prefer to fix the problem at the source, this is what you can do.

1. Clone thedevice-tree-xlnxrepository and checkout the release tag that you need to modify.

git clone https://github.com/Xilinx/device-tree-xlnx.git
cd device-tree-xlnx
git checkout xilinx-v2020.2

1. Make the changes to the local copy.
2. Create the patch file by running this command from the directory of the local repo:git diff > devtree.patch. Use a descriptive filename but keep the.patchextension.
3. Copy the patch file to/project-spec/meta-user/recipes-bsp/device-tree/files/
4. Open this file in a file editor:/project-spec/meta-user/recipes-bsp/device-tree/device-tree.bbappendand add this line to the file:SRC_URI += "file://devtree.patch"

The complete file might look like the following (this is for PetaLinux 2020.2). Note that in the file below, I’m also adding a custom device tree to the design calledmy-dev-tree.dtsiwhich would also be contained in thefilesdirectory, alongside the patch file.

FILESEXTRAPATHS_prepend := "${THISDIR}/files:"

SRC_URI += "file://my-dev-tree.dtsi"
SRC_URI += " file://emacps.patch"

python () {
    if d.getVar("CONFIG_DISABLE"):
        d.setVarFlag("do_configure", "noexec", "1")
}

export PETALINUX
do_configure_append () {
	script="${PETALINUX}/etc/hsm/scripts/petalinux_hsm_bridge.tcl"
	data=${PETALINUX}/etc/hsm/data/
	eval xsct -sdx -nodisp ${script} -c ${WORKDIR}/config \
	-hdf ${DT_FILES_PATH}/hardware_description.${HDF_EXT} -repo ${S} \
	-data ${data} -sw ${DT_FILES_PATH} -o ${DT_FILES_PATH} -a "soc_mapping"
}

How to patch the kernel

There are so many things that you might want to modify in the Linux kernel, but most of the time you probably just want to modify a driver that talks to some custom IP or some custom hardware that you have attached. Whatever the reason, the sources for the PetaLinux kernel are managed in thelinux-xlnxGit repository and you can use the following procedure for modifying them.

1. Clone thelinux-xlnxrepository and checkout the right release tag.

git clone https://github.com/Xilinx/linux-xlnx.git
cd linux-xlnx
git checkout xlnx_rebase_v5.4_2020.2

1. Modify the code in the local repo and save the changes.
2. Create the patch file by running this command from the directory of the local repo:git diff > kernel.patch. Use a descriptive name for the patch file but keep the.patchextension.
3. Copy the patch file to/project-spec/meta-user/recipes-kernel/linux/linux-xlnx/
4. Edit this file:/project-spec/meta-user/recipes-kernel/linux/linux-xlnx_%.bbappendand add the following line:SRC_URI += "file://kernel.patch"

The complete file could look like the following. Note that the below example also contains a.cfgfile containing some kernel configurations, and this file would also be contained in thefilesdirectory alongside our patch file.

FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"

SRC_URI += "file://user.cfg \
            file://kernel.patch \
            "

Rebuild

Now that you have included the patch files to your PetaLinux project configuration files, you need to rebuild the project usingpetalinux-buildand the patches will be applied.