Raspberry Pi/Installation

This document describes how to install Gentoo on the Raspberry Pi 1, 2, and 3 in 32-bit mode.

Partitioning
The SD card must be properly prepared before installing Gentoo. Before partitioning, check to see if the SD card is listed as compatible in this list.

Create at least two partitions on the SD card. The partition should be FAT32. The root ( partition can be any preferred Linux filesystem, however since SD cards are flash-based media, there are many benefits to using F2FS.

For optimal compatibility, 255H/63S geometry is recommended.

Boot partition
The minimum setup for a correct partition requires the following proprietary firmware files, provided by the Raspberry Pi foundation:


 * kernel image(s)
 * DTB (Device Tree Blob) files
 * kernel image(s)
 * DTB (Device Tree Blob) files
 * DTB (Device Tree Blob) files

To boot the Raspberry Pi with  setting in, following files are required:



There are two video drivers for the Pi. The older one uses a fixed reserved GPU memory space. The Open Source VC4 driver uses the kernels contiguous memory allocator. Set gpu_mem=16 when you use the vc4 driver to avoid wasting RAM.

The proprietary firmware files are just an away:

Note that no longer installs  and  files after version 1.20190709. You can get those, as well as a pre-compiled Raspberry Pi kernel and modules, by emerging the package:

If you are planning to use a custom kernel, skip the package and emerge the live ebuild =sys-boot/raspberrypi-firmware-9999. This will install latest firmware directly from the repository of the Raspberry Pi foundation and will not install a kernel or modules.

The firmware ebuild created a file called which specifies any necessary kernel parameters. Make sure you adjust your root partition, if necessary. For example change the parameter to:

When the file does not exist, bootcode.bin defaults to sensible settings for most things On a Pi 1 the kernel is expected to be called kernel.img On a Pi 2 the kernel is expected to be called kernel7.img

On a Pi 3 if kernel8.img exists, the Pi is put into 64 bit mode and kernel8.img is booted. else kernel7.img is booted.

Stage 3
Download appropriate Stage 3 tarball.

For Raspberry Pi A, A+, B, B+:

For the Raspberry Pi 2 or a Raspberry Pi 3 running in 32-bit mode:

Extract the root filesystem to SD card:

For the Raspberry Pi A, A+, B, B+:

For the Raspberry Pi 2 or Raspberry Pi 3 running in 32-bit mode:

Adjust the make.conf file:

Do not forget to adjust the fstab file. The SD card is recognized as ).

Generate the root password hash:

Add the hash to the file.

Stage 4
NOOBS image. The NOOBS image will be created on a daily basis. I'd be pleased to get feedback...

NOOBS images can be downloaded from here: https://github.com/raspberrypi/noobs, then untar the NOOBS image from above in the OS directory.

Portage tree
Download the latest Portage tree:

Ensure there are enough inode blocks free on the root partition. Portage takes up approximately 181K inodes.

Extract Portage to the SD card:

Cross compiling
To aid the Raspberry Pi's low power processor and hasten the Gentoo installation process, adding another machine to help the Rpi with compile jobs is preferred. Gentoo developers have created a cross compiling tool called in order to assist with toolchain generation. Once the toolchain is generated on a stronger machine, the stronger machine can help with compilation tasks, which saves much time.

Crossdev
Install the wrapper scripts:

Create the cross toolchain for ARM, specifying the correct CPU architecture for the device as follows.

For the Raspberry Pi A, A+, B, B+:

For the Raspberry Pi 2 or Raspberry Pi 3 B in 32-bit mode (recommended):

For the Raspberry Pi 3 B in 64-bit mode:

If there are any errors or Portage warnings here, please fix them. It will take a while for the cross toolchain to be successfully built. Go grab a coffee!

Compiling using chroot
It is possible to use generic x86_64 or i386 PC to chroot into existing SD card with RaspberryPi system. This approach is significantly faster than compilation on RaspberryPi (in case of using modern 4 core CPUs it gives about half of 'native' performance) and is slower (but easier) than using cross compiling approach.

To do so static installation of is needed:

After emerging QEMU with `static-user` USE flag qemu-arm executable needs to be copied into chrooting system:

Once done it is necessary to register ARM executables interpreter in running kernel:

Before chrooting add necessary mounts to slave system:

It also wouldn't be a bad idea to make sure /etc/resolv.conf is updated so network access works properly:

Finally you can chroot into RaspberryPi system:

Kernel and modules
Download kernel sources for Raspberry Pi from GitHub

Alternatively, to get the 'bleeding edge' Raspberry Pi kernel sources:

Manual compilation
Configure and install kernel manually:

For the Raspberry Pi A, A+, B, B+:

For the Raspberry Pi 2 or Raspberry Pi 3 B in 32-bit mode (recommended):

Alternatively, use the following command to configure the kernel manually:

Genkernel
can be used to cross-compile the kernel for Raspberry Pi. With all the preferences can be saved in  file for later use. The values of these variables need to be changed in :

After saving the configuration file (for example to ), mount the RaspberryPi SD card to the INSTALL_MOD_PATH configured above. Assuming the Raspberry Pi root partition device is, run:

Now execute. For the Raspberry Pi A, A+, B, B+:

For the Raspberry Pi 2 or Raspberry Pi 3 B in 32-bit mode (recommended):

Save the above command to the custom script:

Now simply create kernel for the Raspberry Pi by executing:

Installing kernel image
For Raspberry Pi A, B, B+ (not 2 B!) create a file by:

If your Raspberry Pi does not boot with this kernel, you may have an older firmware, which requires kernel to be uncompressed. If so, you will need to:

or using the Raspberry Pi mkimage tool from GitHub:

Alternatively, some devices need the zImage to be processed using the mkknlimg script. To do this:

For Raspberry Pi 2 B just copy to :

Copy the updated device tree binaries (.dtb) and device tree overlay (.dto) files into the boot partition:

That's it!

WiFi
RPi 3 and Zero W builtin WiFi driver  requires binary firmware blobs  and their corresponding configuration  to work properly. These can be found in firmware-nonfree repository.

Fetch the firmware repository:

For Raspberry Pi 3 B and Zero W, copy the necessary files

For Raspberry Pi 3 B+, copy the necessary files

Bluetooth
The Raspberry Pi 3B/Zero W needs the firmware file, and the Raspberry Pi 3B+ needs the  firmware file. The firmware files can be found in the Raspbian bluez-firmware GitHub repository. The firmware files need to be placed in the directory.

Create the firmware directory:

Fetch the Raspberry Pi 3B, Zero W Bluetooth firmware:

Fetch the Raspberry Pi 3B+ Bluetooth firmware:

Attach the serial device to the Bluetooth stack using, which is provided by the  package:

Alternatively, can be used if  is built with the   USE flag enabled:

Both commands will create a HCI device (e.g. ) in and load the required firmware.

Serial
Serial port on RPi3 has some issues related to variable clock rate. A few workarounds/solutions are available.

Bootable 64-bit Gentoo Image for RPi3 / RPi4


Those interested in trying 64-bit Gentoo on their RPi3 (model B or B+) or RPi4 (model B) may wish to check out the (unofficial) bootable image available here, from which the above screenshot has been taken (see also this forum thread).

Leveraging recently improved 64-bit support in the official Raspberry Pi kernel tree, the image supports:
 * The Pi's onboard Ethernet, WiFi and Bluetooth adaptors;
 * ALSA sound playback, via headphone jack and HDMI
 * Accelerated VC4 graphics, via vc4-fkms-v3d / vc4 kernel module / Mesa.

The image contains a full Portage tree (and set) so that you can run  operations immediately.

The project's GitHub page additionally contains instructions for setting up crossdev and distcc to build for the 64-bit RPi3 / RPi4.

VideoCore4
To enable VideoCore4 GPU acceleration on RPi device add following to :

Also you need live raspberrypi-firmware-9999 ebuild to be installed (as others seems to be outdated and not compatible with latest kernels).

Finaly, add VideoCore4 configuration to mesa and rebuild it.

For more info refer to Raspberry Pi VideoCore4 page.

Tips and tricks

 * Storage is rather slow, even with the couple of compatible SDHC class 10 cards. If emerge will be running on the Raspberry Pi, putting on squashfs will speed up things dramatically.
 * There is no hardware RTC on the Raspberry Pi. Use the service to set the correct system time on boot. A fallback incremental clock can be archived by the  service (replaces the  service).
 * If more RAM is required for Linux, set the option  in . The smallest amount that can be set is 16 MB, default is 64 MB
 * More recent, unofficial kernel releases for the Raspberry Pi might be found at Chris Boot's repository:
 * Be sure to test the performance - if the numbers don't match up (for instance in the LINPACK benchmark), something is very wrong.
 * For instructions on how to build binary packages for the Raspberry Pi on an Android phone see this blog post:
 * If it is not possible to create a working ARM cross-toolchain, a precompiled kernel image is available from the firmware repository. The needs to be places in the boot partition and the contents of the modules directory copied to  on the SD card.
 * Put the root-fs on a NFS share and put only the kernel image on SD card (PXE boot client).

Troubleshooting

 * Problem: dmesg is full of  and/or page allocation failure messages:
 * Solution: Try to update all firmware files in, especially fixup.dat.
 * Solution: If the former fails, add  to kernel parameters, or   to


 * Problem: The following error shows up when running the command:
 * Solution: Try the following command instead :


 * Problem: On-board audio is inaccessible / non-functional.
 * Solution: Ensure that your contains the line , then reboot. Ensure that the PCM channel is unmuted.

External resources

 * Raspberry Pi Hub at eLinux wiki, with more advanced tutorials to get the most out of the Raspberry Pi
 * grbd@github: Putting Gentoo onto a RPI2 How-To install Gentoo Linux from Raspbian/NOOBS in an external USB disk in a Raspberry Pi 2.
 * genBerry Sort of Gentoo stage 4 for RaspberryPi with several tools.
 * gentoobs Gentoo on NOOBS.
 * gentoo-on-rpi3-64bit Bootable 64-bit Gentoo image for RPi3.
 * gentoo-pi maintained base headless Gentoo image, with distcc and sshd enabled.

Books

 * Heitz, Ryan. Hello! Raspberry Pi. Manning Publications (2015). pp. 225. ISBN 9781617292453