How to Patch PetaLinux

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 command diff or other similar commands, but in this post we will use the command git diff. To get the most benefit from this post, you will need to have a good understanding of Git.

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: tag xilinx-v2020.2
• u-boot-xlnx: tag xlnx_rebase_v2020.01_2020.2
• device-tree-xlnx: tag xilinx-v2020.2
• linux-xlnx: tag xlnx_rebase_v5.4_2020.2

General procedure for patching PetaLinux

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

1. Clone the source code using git clone and checkout a specific release tag
2. Modify our local copy of the source code
3. Generate a patch file using git 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 the embeddedsw Github repository. By the way, the embeddedsw repository 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

2. 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 in lib/sw_apps/zynqmp_fsbl/src and you would edit those sources.

3. 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 filename fsbl.patch. You should call it something that describes your patch, but you must keep the .patch extension.

4. 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/.

5. Now open this file in a text editor /project-spec/meta-user/recipes-bsp/fsbl/fsbl_%.bbappend and 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 the u-boot-xlnx repository.

1. Clone the u-boot-xlnx repository 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

2. Make the changes to the local copy of the repository and save the changes.
3. Generate the patch file by running this command from the local repo directory: git diff > uboot.patch
4. Copy the patch file to /project-spec/meta-user/recipes-bsp/u-boot/files/
5. Edit the file /project-spec/meta-user/recipes-bsp/u-boot/u-boot-xlnx_%.bbappend and 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 the device-tree-xlnx repository 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

2. Make the changes to the local copy.
3. 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 .patch extension.
4. Copy the patch file to /project-spec/meta-user/recipes-bsp/device-tree/files/
5. Open this file in a file editor: /project-spec/meta-user/recipes-bsp/device-tree/device-tree.bbappend and 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 called my-dev-tree.dtsi which would also be contained in the files directory, 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 the linux-xlnx Git repository and you can use the following procedure for modifying them.

1. Clone the linux-xlnx repository 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

2. Modify the code in the local repo and save the changes.
3. 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 .patch extension.
4. Copy the patch file to /project-spec/meta-user/recipes-kernel/linux/linux-xlnx/
5. Edit this file: /project-spec/meta-user/recipes-kernel/linux/linux-xlnx_%.bbappend and 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 .cfg file containing some kernel configurations, and this file would also be contained in the files directory 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 using petalinux-build and the patches will be applied.