WIP: Add Build instructions for compiling a 64-Bit kernel (raspberrypi#1653)

RyanHir · web-flow · commit a1839d77d223 · 2020-09-17T10:07:36.000+01:00
* Declare build instructions as 32-bit * Early 64-Bit guide. Needs Testing. * Added some formatting for the config and build * Move some instructions for CI that apply to both arches * Added some better seperators * Looks weird to read when generated into a web format so it has been clarified * Clarify headings and add seperators * Undo "Add Seperators" as it did not format well as I wished * Use correct pi 3 defconfig * Remove bad comment from code * Fix instructions after following guide to compile for Pi 3 * Use distro cross-compilers in kernel build * Fixed change after testing installation. Compiling is still the same * Remove binutils requirment already as it is a dep for gcc-arm * Remove zlib1g from instructions as mentioned in comments. * Modifed configuring the kernel build to add instructions for the 64bit build * Remove required packages as it is already in meta-package as rec * Revert "Remove required packages as it is already in meta-package as rec" This reverts commit d721932. * remove ccache instructions for when we were using the tools repo * combine dependencies and toolchain install instructions * Remove addition to title * Remove extra colon * Lowercase *-Bit to *-bit * Add README from build * Fixed Capitialization for reviewed change * Partially Undo Capitialization Fix * Updated header to help user choose which compiling guide to use * Revert "Updated header to help user choose which compiling guide to use" This reverts commit 12fb61d. * Lowercase "Bit" identifier * New Header provided from comments
diff --git a/linux/kernel/building.md b/linux/kernel/building.md
@@ -1,6 +1,13 @@
 # Kernel building
 
-There are two main methods for building the kernel. You can build locally on a Raspberry Pi, which will take a long time; or you can cross-compile, which is much quicker, but requires more setup.
+The default compilers and linkers that come with an OS are configured to build executables to run on that OS - they are native tools - but that doesn't have to be the case. A cross-compiler is configured to build code for a target other than the one running the build process, and using it is called cross-compilation.
+
+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.
+
+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.
 
 ## Local building
 
@@ -92,7 +99,7 @@ sudo cp arch/arm/boot/zImage /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.
 
-## Cross-compiling
+## Cross-compiling 
 
 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.
@@ -103,10 +110,21 @@ You can either do this using VirtualBox (or VMWare) on Windows, or install it di
 
 To build the sources for cross-compilation, make sure you have the dependencies needed on your machine by executing:
 ```bash
-sudo apt install git bc bison flex libssl-dev make libc6-dev libncurses5-dev crossbuild-essential-armhf
+sudo apt install git bc bison flex libssl-dev make libc6-dev libncurses5-dev
 ```
+
 If you find you need other things, please submit a pull request to change the documentation.
 
+#### Install the 32-bit toolchain for a 32-bit kernel
+```bash
+sudo apt install crossbuild-essential-armhf
+```
+
+#### Or, install the 64-bit toolchain for a 64-bit kernel
+```bash
+sudo apt install crossbuild-essential-arm64
+```
+
 ### Get sources
 
 To download the minimal source tree for the current branch, run:
@@ -121,6 +139,7 @@ See [**Choosing sources**](#choosing_sources) above for instructions on how to c
 
 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:
 
 ```bash
@@ -145,14 +164,36 @@ KERNEL=kernel7l
 make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- bcm2711_defconfig
 ```
 
-Then, for all:
+#### 64-bit configs
+For Pi 3, Pi 3+ or Compute Module 3:
+```bash
+cd linux
+KERNEL=kernel8
+make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- bcmrpi3_defconfig
+```
 
+For Raspberry Pi 4:
 ```bash
-make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- zImage modules dtbs
+cd linux
+KERNEL=kernel8
+make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- bcm2711_defconfig
 ```
 
+#### Build with configs
+
 **Note**: To speed up compilation on multiprocessor systems, and get some improvement on single processor ones, use `-j n`, where n is the number of processors * 1.5. Alternatively, feel free to experiment and see what works!
 
+##### For all 32-bit builds
+```bash
+make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- zImage modules dtbs
+```
+
+##### For all 64-bit builds
+**Note**: Note the difference between Image target between 32 and 64-bit.
+```bash
+make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- Image modules dtbs
+```
+
 ### Install directly onto the SD card
 
 Having built the kernel, you need to copy it onto your Raspberry Pi and install the modules; this is best done directly using an SD card reader.
@@ -190,14 +231,23 @@ sudo mount /dev/sdb6 mnt/fat32
 sudo mount /dev/sdb7 mnt/ext4
 ```
 
-Next, install the modules:
 
+Next, install the kernel modules onto the SD card:
+
+#### For 32-bit
 ```bash
 sudo env PATH=$PATH make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- INSTALL_MOD_PATH=mnt/ext4 modules_install
 ```
 
+#### For 64-bit
+```bash
+sudo env PATH=$PATH make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- INSTALL_MOD_PATH=mnt/ext4 modules_install
+```
+
 Finally, copy the kernel and Device Tree blobs onto the SD card, making sure to back up your old kernel:
 
+#### For 32-bit
+
 ```bash
 sudo cp mnt/fat32/$KERNEL.img mnt/fat32/$KERNEL-backup.img
 sudo cp arch/arm/boot/zImage mnt/fat32/$KERNEL.img
@@ -208,6 +258,18 @@ sudo umount mnt/fat32
 sudo umount mnt/ext4
 ```
 
+#### For 64-bit
+
+```bash
+sudo cp mnt/fat32/$KERNEL.img mnt/fat32/$KERNEL-backup.img
+sudo cp arch/arm64/boot/Image mnt/fat32/$KERNEL.img
+sudo cp arch/arm64/boot/dts/broadcom/*.dtb mnt/fat32/
+sudo cp arch/arm64/boot/dts/overlays/*.dtb* mnt/fat32/overlays/
+sudo cp arch/arm64/boot/dts/overlays/README mnt/fat32/overlays/
+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:
 
 ```
diff --git a/linux/kernel/configuring.md b/linux/kernel/configuring.md
@@ -22,12 +22,18 @@ Once you've got everything set up and ready to go, you can compile and run the `
 $ make menuconfig
 ```
 
-If you're cross-compiling,:
+If you're cross-compiling a 32-bit kernel:
 
 ```
 make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- menuconfig
 ```
 
+Or, if you are cross-compiling a 64-bit kernel:
+
+```
+make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- menuconfig
+```
+
 The `menuconfig` utility has simple keyboard navigation. After a brief compilation, you'll be presented with a list of submenus containing all the options you can configure; there's a lot, so take your time to read through them and get acquainted.
 
 Use the arrow keys to navigate, the Enter key to enter a submenu (indicated by `--->`), Escape twice to go up a level or exit, and the space bar to cycle the state of an option. Some options have multiple choices, in which case they'll appear as a submenu and the Enter key will select an option. You can press `h` on most entries to get help about that specific option or menu.
