Booting the Raspberry Pi 5 with the Mainline Linux Kernel

Hardware

In this tutorial, we assume you have the Raspberry Pi Debug Probe to access the board’s serial port. You could use the GPIO UARTs too, but they are neither enabled by default at the bootloader level nor as a kernel console. Enabling them for serial console access would slightly complicate these instructions.

These instructions can also be adapted for earlier Raspberry Pi boards, as the meta-raspberrypi layer supports all of them.

Install required packages

The following packages are necessary on Ubuntu 24.04 (see the Yocto Project manual):

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

Yocto Project / OpenEmbedded setup

Note that we’re using the master branch of the meta-raspberrypi layer, because it’s compatible with both the Styhead and Walnascar releases (currently in Poky’s master branch).

$ mkdir -p ~/oe/raspberrypi5
$ cd ~/oe/raspberrypi5
$ git clone -b styhead https://git.yoctoproject.org/poky
$ git clone git://git.yoctoproject.org/meta-raspberrypi
$ cd poky
$ source oe-init-build-env
$ bitbake-layers add-layer ../../meta-raspberrypi

Next, add the MACHINE setting to conf/local.conf:

MACHINE = "raspberrypi5"

You are now ready to generate an image:

$ bitbake core-image-minimal

Booting with the default kernel for Raspberry Pi 5

After building this image, you can flash it to a micro SD card:

sudo bmaptool copy tmp/deploy/images/raspberrypi5/core-image-minimal-raspberrypi5.rootfs.wic.bz2 /dev/mmcblk0

The micro SD card should now allow the board to boot to a command line. Before powering up the board, open a terminal emulator to access the serial console. For example:

$ sudo apt install tio
$ tio /dev/ttyACM0

Power up the board, see Linux boot. Log in as root (no password required) and run uname -r to check the Linux kernel version.

Create a meta-mainline layer

So, let’s create a custom layer to override the default kernel recipe for Raspberry Pi boards:

$ cd ~/oe/
$ bitbake-layers create-layer meta-mainline
$ bitbake-layers add-layer meta-mainline

Create a new linux-mainline recipe

Let’s store this new recipe in recipes-kernel in the layer, as for the standard Linux recipes.

cd meta-mainline
mkdir -p recipes-kernel/linux-mainline

Then, we can create the recipe files themselves. Let’s start with linux-mainline.inc, which is meant to be shared by recipe code for different versions:

DESCRIPTION = "Mainline Linux kernel"
LICENSE = "GPL-2.0-only"
LIC_FILES_CHKSUM = "file://COPYING;md5=6bc538ed5bd9a7fc9398086aedcd7e46"

inherit kernel
S = "${WORKDIR}/git"
SRC_URI += "file://defconfig"
PROVIDES = "virtual/kernel"

Then, let’s add linux-mainline_6.13.2.bb:

require linux-mainline.inc
SRC_URI += "git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git;branch=linux-6.13.y;protocol=https"
SRCREV = "055ac5ba52df091fc6fc45445fdc75481bccad49" # Linux 6.13.2

Create a Linux kernel configuration file

Since the recipe is referring to a defconfig kernel configuration file, let’s create one. Let’s clone the stable kernel tree to do this:

$ cd ~/oe/
$ git clone https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
$ cd linux

To produce a configuration file, we need to set the architecture for the board, and a cross-compiler too for this architecture. Luckily, LLVM on our host machine can be used as a cross-compiler for all architectures:

$ export ARCH=arm64
$ export LLVM=1
$ make defconfig

The last command above has created a standard configuration that supports all ARM64 boards at once. While the resulting kernel binary would work on our board, it would be unnecessarily bulky and slow to compile. I suggest to edit the configuration (make nconfig or make menuconfig) to remove:

• In Platform selection, only keep Broadcom SoC Support
• Also look for DRM and disable it. This removes unnecessary graphics and GPU support.

Then, after saving your changes, generate a defconfig file from your configuration (.config):

$ make savedefconfig

defconfig is the same as .config, except that only settings that have a non-default value are stored.

We then copy this configuration to our layer, in a version and machine specific subdirectory:

$ cd ~/oe/raspberrypi5/meta-mainline/recipes-kernel/linux-mainline
$ mkdir -p linux-mainline-6.13.2/raspberrypi5
$ cp ~/oe/linux/defconfig linux-mainline-6.13.2/raspberrypi5/

BitBake will look for the file:// files through version specific and machine specific directories. This way, the same recipe can be used to support multiple kernel versions and even different machines!

Here’s what our layer looks like now:

Local configuration edits

Add the below two lines to the conf/local.conf file:

MACHINE = "raspberrypi5"
PREFERRED_PROVIDER_virtual/kernel = "linux-mainline"
RPI_KERNEL_DEVICETREE_OVERLAYS = ""

• PREFERRED_PROVIDER_virtual/kernel chooses the virtual kernel recipe. Here we choose to use the one from our layer instead of the one provided by meta-raspberrypi.
• RPI_KERNEL_DEVICETREE_OVERLAYS is used in meta-raspberrypi to compile additional device tree overlays for add-on boards. We still want to use meta-raspberrypi to build the bootloader, but as we are only trying to support the base board, we can keep this setting empty.

Update the image and boot the board again

Update the image:

$ bitbake core-image-minimal

Reflash the micro SD once again, and boot the board through the serial line. Here’s what you should get:

Examples using Linux mainline on other boards

This tutorial was derived from a presentation I made at the OpenEmbedded Workshop 2025 in Brussels. It also shows how to boot the latest mainline kernel (and U-Boot, when applicable), on a QEMU virtual machine, on Beaglebone Black, on BeaglePlay and on Raspberry Pi 5. Click on the image below to view the entire presentation: