Raspberry Pi/Installation



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

The Raspberry Pi is series of single-board computers based on ARM devices. Raspberry Pi 1 is based on BCM2835 SoC and features a single core CPU (ARMv6), with 512 MB RAM. Earlier models had 256 MB RAM.

Raspberry Pi 2 is based on BCM2836 SoC and features a quad-core CPU (ARMv7) and 1 GB RAM. The model 1 uses an SD card for storage but the model 2 uses a microSD. All versions have a VideoCore IV GPU.

Raspberry Pi 3 B is based on BCM2837 SoC. According to, although the ARMv8 CPU in the Raspberry Pi 3 B is 64-bit, almost everything else is 32-bit, and therefore only 32-bit kernels are supplied from upstream for the machine. To boot a 64-bit kernel, it is necessary to add the  parameters to the boot loader. This is to enable 64-bit mode for the processor. The  kernel boot argument is also needed, otherwise "the boot loader will otherwise overwrite the code (without  ) at 0x100 with ATAGS . Therefore, for the Raspberry Pi 3 B, those who want to build a 32-bit kernel, simply walk through the Raspberry Pi 2 options listed below. Those who want to try to build a 64-bit kernel will need the mainline Linux kernel. Be aware there are very few people who are able to provide assistance for 64-bit attempts. Proceeding down the 64-bit path may enter a world of pain. Many things (such as Firefox ) may not work at all. Other things have issues but function (wifi)  . Be sure to remember to add the boot arguments!

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:



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



Create a file called to specify any necessary kernel parameters. For example:

The proprietary firmware files are just an away:

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 (recommended):

For the Raspberry Pi 3 running in 64-bit mode (experimental, unstable, and not recommended):

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 (recommended):

For the Raspberry Pi 3 running in 64-bit mode (experimental, unstable, and not recommended):

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
There is also an option of a self-booting Gentoo tarball (Stage 4), it can be downloaded from here. Please note this image appears to be outdated and unmaintained

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 can help with complication tasks, which saves much time.

crossdev
First, install Layman. Please visit the article if instructions are needed.

Add the crossdev overlay:

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!

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):

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 :

It may be necessary to copy updated dtb files into the boot partition:

That's it!

WiFi
RPi3 builtin WiFi driver  requires binary firmware blob   and it's configuration   to work properly. These can be found in firmware-nonfree repository. If these files are missing on Your system:

Bluetooth
RPi3 builtin BlueTooth driver requires  binary blob in  folder to work properly. This file can be found in OpenELEC/misc-firmware or ArchLinux AUR repository. Once downloaded  should be copied to.

The following needs to be done every time the system boots:

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


Those interested in trying 64-bit Gentoo on their RPi3 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.

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.

Books

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