Skip to content

Various tweaks and tidyups to kernel-building instructions #2428

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 16, 2022
Merged

Various tweaks and tidyups to kernel-building instructions #2428

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1465465
Various tweaks and tidyups to kernel-building instructions
lurch Feb 15, 2022
677278f
kill stray comma
lurch Feb 15, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 19 additions & 18 deletions documentation/asciidoc/computers/linux_kernel/building.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ The default compilers and linkers that come with an OS are configured to build e
Cross-compilation of the Raspberry Pi kernel is useful for two reasons:

* it allows a 64-bit kernel to be built using a 32-bit OS, and vice versa, and
* even a modest laptop can cross-compile a Pi kernel significantly faster than the Pi itself.
* even a modest laptop can cross-compile a Raspberry Pi kernel significantly faster than the Raspberry Pi itself.

The instructions below are divided into native builds and cross-compilation; choose the section appropriate for your situation - although there are many common steps between the two, there are also some important differences.

=== Building the Kernel Locally

On a Raspberry Pi, first install the latest version of https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-32-bit[Raspberry Pi OS]. Then boot your Pi, plug in Ethernet to give you access to the sources, and log in.
On a Raspberry Pi, first install the latest version of https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-32-bit[Raspberry Pi OS]. Then boot your Raspberry Pi, log in, and ensure you're connected to the internet to give you access to the sources.

First install Git and the build dependencies:

Expand Down Expand Up @@ -51,9 +51,9 @@ Configure the kernel; as well as the default configuration, you may wish to xref
[[default_configuration]]
===== Apply the Default Configuration

First, prepare the default configuration by running the following commands, depending on your Raspberry Pi version:
First, prepare the default configuration by running the following commands, depending on your Raspberry Pi model:

For Raspberry Pi 1, Pi Zero, Pi Zero W, and Compute Module default build configuration
For Raspberry Pi 1, Zero and Zero W, and Raspberry Pi Compute Module 1 default (32-bit only) build configuration

[,bash]
----
Expand All @@ -62,7 +62,7 @@ KERNEL=kernel
make bcmrpi_defconfig
----

For Raspberry Pi Zero 2 W, Pi 2, Pi 3, Pi 3+, and Compute Module 3 default build configuration
For Raspberry Pi 2, 3, 3+ and Zero 2 W, and Raspberry Pi Compute Modules 3 and 3+ default 32-bit build configuration

[,bash]
----
Expand All @@ -71,7 +71,7 @@ KERNEL=kernel7
make bcm2709_defconfig
----

For Raspberry Pi 4 default build configuration (32 bit)
For Raspberry Pi 4 and 400, and Raspberry Pi Compute Module 4 default 32-bit build configuration

[,bash]
----
Expand All @@ -80,7 +80,7 @@ KERNEL=kernel7l
make bcm2711_defconfig
----

For Pi Zero 2 W, Pi 3, Pi 3+, Pi 4, Pi 400, and Compute Modules 3, 3+ and 4 default build configuration (64 bit)
For Raspberry Pi 3, 3+, 4, 400 and Zero 2 W, and Raspberry Pi Compute Modules 3, 3+ and 4 default 64-bit build configuration
[,bash]
----
cd linux
Expand All @@ -102,7 +102,7 @@ You can also change that setting graphically as shown in xref:linux_kernel.adoc#

==== Building the Kernel

Build and install the kernel, modules, and Device Tree blobs; this step can take a *long* time depending on the Pi model in use. For the 32-bit kernel:
Build and install the kernel, modules, and Device Tree blobs; this step can take a *long* time depending on the Raspberry Pi model in use. For the 32-bit kernel:

[,bash]
----
Expand All @@ -128,10 +128,11 @@ sudo cp arch/arm64/boot/Image /boot/$KERNEL.img

NOTE: On a Raspberry Pi 2/3/4, the `-j4` flag splits the work between all four cores, speeding up compilation significantly.

If you now reboot, your Raspberry Pi should be running your freshly-compiled kernel!

=== Cross-Compiling the Kernel

First, you will need a suitable Linux cross-compilation host. We tend to use Ubuntu; since Raspberry Pi OS is
also a Debian distribution, it means many aspects are similar, such as the command lines.
First, you will need a suitable Linux cross-compilation host. We tend to use Ubuntu; since Raspberry Pi OS is also a Debian distribution, it means many aspects are similar, such as the command lines.

You can either do this using VirtualBox (or VMWare) on Windows, or install it directly onto your computer. For reference, you can follow instructions online http://www.wikihow.com/Install-Ubuntu-on-VirtualBox[at Wikihow].

Expand Down Expand Up @@ -177,7 +178,7 @@ Enter the following commands to build the sources and Device Tree files:

===== 32-bit Configs

For Pi 1, Pi Zero, Pi Zero W, or Compute Module:
For Raspberry Pi 1, Zero and Zero W, and Raspberry Pi Compute Module 1:

[,bash]
----
Expand All @@ -186,7 +187,7 @@ KERNEL=kernel
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- bcmrpi_defconfig
----

For Pi Zero 2 W, Pi 2, Pi 3, Pi 3+, or Compute Module 3:
For Raspberry Pi 2, 3, 3+ and Zero 2 W, and Raspberry Pi Compute Modules 3 and 3+:

[,bash]
----
Expand All @@ -195,7 +196,7 @@ KERNEL=kernel7
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- bcm2709_defconfig
----

For Raspberry Pi 4:
For Raspberry Pi 4 and 400, and Raspberry Pi Compute Module 4:

[,bash]
----
Expand All @@ -206,7 +207,7 @@ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- bcm2711_defconfig

===== 64-bit Configs

For Pi Zero 2 W, Pi 3, Pi 3+, Pi 4, Pi 400, and Compute Modules 3, 3+ and 4:
For Raspberry Pi 3, 3+, 4, 400 and Zero 2 W, and Raspberry Pi Compute Modules 3, 3+ and 4:

[,bash]
----
Expand Down Expand Up @@ -247,7 +248,7 @@ sdb
sdb2
----

with `sdb1` being the FAT (boot) partition, and `sdb2` being the `ext4` filesystem (root) partition.
with `sdb1` being the `FAT` filesystem (boot) partition, and `sdb2` being the `ext4` filesystem (root) partition.

Mount these first, adjusting the partition letter as necessary:

Expand Down Expand Up @@ -306,12 +307,12 @@ sudo umount mnt/fat32
sudo umount mnt/ext4
----

Another option is to copy the kernel into the same place, but with a different filename - for instance, kernel-myconfig.img - rather than overwriting the kernel.img file. You can then edit the config.txt file to select the kernel that the Pi will boot into:
Another option is to copy the kernel into the same place, but with a different filename - for instance, `kernel-myconfig.img` - rather than overwriting the `kernel.img` file. You can then edit the `config.txt` file to select the kernel that the Raspberry Pi will boot:

----
kernel=kernel-myconfig.img
----

This has the advantage of keeping your kernel separate from the kernel image managed by the system and any automatic update tools, and allowing you to easily revert to a stock kernel in the event that your kernel cannot boot.
This has the advantage of keeping your custom kernel separate from the stock kernel image managed by the system and any automatic update tools, and allowing you to easily revert to a stock kernel in the event that your kernel cannot boot.

Finally, plug the card into the Pi and boot it!
Finally, plug the card into the Raspberry Pi and boot it!