Raspberry Pi Install Guide

Tip
This guide is intended to apply to all Raspberry Pis that can boot from removable storage

Overview

Having produced several arm64 Raspberry Pi install guides, first the the Pi3, then the Pi4, building on one another and the handbook, with the arrival of the Pi5, its becoming a house of cards. A new approach is required.

This Pi install guide aims to cover a general method, rather than a step by step guide. The method will work for any Pi and it will only depend on the handbook for the generic Gentoo things. The method should work for the Pi6 and beyond.

No chrooting into an arm/arm64 environment will be required. It will be installed to a (micro)SD card, including enough setup to boot and login before the arm/arm64 environment is required.

In short, its a Gentoo arm or arm64 stage3 on top of a Raspberry Pi Foundation binary kernel with some text files added to make it work. No target CPU code will be executed during the install.

Hardware table

Model	CPU	Architecture	Stage3
Raspberry PI Zero	BCM2708	ARM	ARMv6j stage 3]
Raspberry PI (Original)	BCM2708	ARM	ARMv6j stage 3]
Raspberry PI Zero w	BCM2708	ARM	ARMv6j stage 3]
Raspberry PI 2b Before Ver 1.2	BCM2709	ARM
Raspberry PI 2b Ver 1.2	BCM2710	ARM/ARM64
Raspberry PI 3b	BCM2710	ARM/ARM64
Raspberry PI 3b+	BCM2710	ARM/ARM64
Raspberry PI Zero 2	BCM2710	ARM/ARM64
Raspberry PI Zero 2 w	BCM2710	ARM/ARM64
Raspberry PI 4b	BCM2711	ARM/ARM64
Raspberry PI 5	BCM2712	ARM/ARM64
Raspberry PI 6	TBD	TBD

High Level Steps

In handbook order

• Preparing the disks
• Installing the Gentoo installation files
• Installing the Raspberry Pi Foundation files
• Configuring the system

The handbook uses a working Gentoo Install (the minimal ISO) to perform the install and requires that the host and target for the install are compatible. This guide assumes that the host and target are incompatible. No attempt is made to execute any target code on the install host.

Prerequisites

• A Raspberry Pi and peripherals
• Target media for the install
• A Linux install to write the target media (Random live media will probably work)

The detail

Preparing the disks

This page assumes that the (micro)SD card is fitted to a card to USB adapter for the install part of work on the install host. Therefore it will appear as /dev/sdX. This page uses /dev/sdi.

It further assumes that at boot time, in the Pi, it will be /dev/mmcblk0. USB booting the Pi3 and later is possible but requires a microSD card boot first, so is deliberately not covered here.

Readers with a SD slot on the install host will find that target SD card is /dev/sdX or /dev/mmcblkY depending on the hardware in use by the host.

Locate the target drive

The disk will be a (micro)SD card. The Pi3 and later can also boot from USB but that can require booting from SD first, to set up USB booting.

Modern bootcode.bin and firmware work with both MSDOS and GPT partition tables

The first partition on the SD card must be /boot, formatted VFAT.

Root (/) can be anything that is built into the kernel. EXT4 is known to work.

Important
An initrd/initramfs will not be used. The first boot will use the Foundation kernel

If the Pi will be used for building, swap will be useful.

The GPU does all the hard work for loading the CPU boot files. Indeed, the ARM CPU is held reset until the kernel, device tree binary and optionally, the initrd are all loaded into RAM. There is no grub/lilo/syslinux equivalent for the Pi family.

Plug the drive in to any desktop system and find it

root #dmesg

...
[ 1613.049729] scsi 11:0:0:0: Direct-Access     Samsung  SSD 870 EVO 1TB  0    PQ: 0 ANSI: 6
[ 1613.051603] sd 11:0:0:0: Attached scsi generic sg10 type 0
[ 1613.051811] sd 11:0:0:0: [sdi] 1953525168 512-byte logical blocks: (1.00 TB/932 GiB)
[ 1613.051938] sd 11:0:0:0: [sdi] Write Protect is off
[ 1613.051941] sd 11:0:0:0: [sdi] Mode Sense: 43 00 00 00
[ 1613.052096] sd 11:0:0:0: [sdi] Write cache: enabled, read cache: enabled, doesn't support DPO or FUA
[ 1613.052254] sd 11:0:0:0: [sdi] Preferred minimum I/O size 512 bytes
[ 1613.052256] sd 11:0:0:0: [sdi] Optimal transfer size 33553920 bytes
[ 1613.054759]  sdi: sdi1 sdi2 sdi3
[ 1613.055312] sd 11:0:0:0: [sdi] Attached SCSI disk

The Pi used for testing has already been configured for USB booting. Here, its /dev/sdi, on the Pi it will be /dev/sda.

Important
The next steps will destroy the data on the selected drive

Make a new disk label and partition

As /dev/sdi has been used, start with a new disk label.

root #fdisk /dev/sdi

Welcome to fdisk (util-linux 2.39.2).
Changes will remain in memory only, until you decide to write them.
Be careful before using the write command.

Make sure its the right device.

Command (m for help):p

Disk /dev/sdi: 931.51 GiB, 1000204886016 bytes, 1953525168 sectors
Disk model: SSD 870 EVO 1TB
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 33553920 bytes
Disklabel type: gpt
Disk identifier: 3D8E9053-4AD6-45AF-963A-96A42EB3CA89

Device         Start        End    Sectors   Size Type
/dev/sdi1	2048     501759     499712   244M EFI System
/dev/sdi2     501760  124999679  124497920  59.4G Linux filesystem
/dev/sdi3  124999680 1953523711 1828524032 871.9G Linux filesystem

Check against the dmesg output. If its OK, go ahead and destroy the data on the drive.

Command (m for help):g

Created a new GPT disklabel (GUID: BC6F5C13-002F-4B8C-B377-A26AFABDC45D)

Your disk lable will have its own GUID.

Make Partitions

Some good partition sizes are /boot, 256M, swap 8G, /home, if it will be separate 100G and the rest for root.

Make the partitions first and correct the types at the end.

Partitian 1 Must be VFAT. All the Pi foundation boot code will go here and a selection of kernels too. 256M is a good size.

Command (m for help):n

Partition number (1-128, default 1): 1
First sector (2048-1953525134, default 2048):
Last sector, +/-sectors or +/-size{K,M,G,T,P} (2048-1953525134, default 1953523711): +256M

Created a new partition 1 of type 'Linux filesystem' and of size 256 MiB.
Partition #1 contains a vfat signature.

Do you want to remove the signature? [Y]es/[N]o:
The signature will be removed by a write command.

The warning at the end is due to the drive being used and can be ignored.

Next 8G for swap.

Command (m for help):n

Partition number (1-128, default 1): 2):
First sector (526336-1953525134, default 526336):
Last sector, +/-sectors or +/-size{K,M,G,T,P} (526336-1953525134, default 1953523711): +8G

Created a new partition 2 of type 'Linux filesystem' and of size 8 GiB.

then 100G for /home

Command (m for help):n

Partition number (3-128, default 3):
First sector (17303552-1953525134, default 17303552):
Last sector, +/-sectors or +/-size{K,M,G,T,P} (17303552-1953525134, default 1953523711): +100G

Created a new partition 3 of type 'Linux filesystem' and of size 100 GiB.

Finally, the rest of the drive for root.

Command (m for help):n

Partition number (4-128, default 4):
First sector (227018752-1953525134, default 227018752):
Last sector, +/-sectors or +/-size{K,M,G,T,P} (227018752-1953525134, default 1953523711):

Created a new partition 4 of type 'Linux filesystem' and of size 823.3 GiB.

Trust but verify.

Command (m for help):p

Disk /dev/sdi: 931.51 GiB, 1000204886016 bytes, 1953525168 sectors
Disk model: SSD 870 EVO 1TB
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 33553920 bytes
Disklabel type: gpt
Disk identifier: BC6F5C13-002F-4B8C-B377-A26AFABDC45D

Device         Start        End    Sectors   Size Type
/dev/sdi1	2048     526335     524288   256M Linux filesystem
/dev/sdi2     526336   17303551   16777216     8G Linux filesystem
/dev/sdi3   17303552  227018751  209715200   100G Linux filesystem
/dev/sdi4  227018752 1953523711 1726504960 823.3G Linux filesystem

Filesystem/RAID signature on partition 1 will be wiped.

This drive was part of a mdadm raid set at one time. The warning can be ignored.

Set the types of partitions 1 and 2.

Command (m for help):t

Partition number (1-4, default 4): 1
Partition type or alias (type L to list all): 11

Changed type of partition 'Linux filesystem' to 'Microsoft basic data'.

Command (m for help): t
Partition number (1-4, default 4): 2
Partition type or alias (type L to list all): 19

Changed type of partition 'Linux filesystem' to 'Linux swap'.

Check once more

Command (m for help):p

Disk /dev/sdi: 931.51 GiB, 1000204886016 bytes, 1953525168 sectors
Disk model: SSD 870 EVO 1TB 
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 33553920 bytes
Disklabel type: gpt
Disk identifier: BC6F5C13-002F-4B8C-B377-A26AFABDC45D

Device         Start        End    Sectors   Size Type
/dev/sdi1	2048     526335     524288   256M Microsoft basic data
/dev/sdi2     526336   17303551   16777216     8G Linux swap
/dev/sdi3   17303552  227018751  209715200   100G Linux filesystem
/dev/sdi4  227018752 1953523711 1726504960 823.3G Linux filesystem

Filesystem/RAID signature on partition 1 will be wiped.

So far, the target drive has not been touched. The new disk label and partition table are in memory. After the next step, there is no going back.

Warning
Last Chance to Change Your Mind!!

Use 'q' to throw away the changes or 'w' to write them to disk

Command (m for help):w

The partition table has been altered.
Calling ioctl() to re-read partition table.
Syncing disks.

Make Filesystems

VFAT on the first partition, ext4 on /home and root and a swap label to swap

VFAT on /boot

root #mkfs -t vfat /dev/sdi1

ext4 on /home

root #mkfs -t ext4 /dev/sdi3

mke2fs 1.47.0 (5-Feb-2023)
Creating filesystem with 26214400 4k blocks and 6553600 inodes
Filesystem UUID: b7642a46-c15b-4453-9fe4-a2554c355fac
Superblock backups stored on blocks: 
        32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632, 2654208,
        4096000, 7962624, 11239424, 20480000, 23887872

Allocating group tables: done
Writing inode tables: done
Creating journal (131072 blocks): done
Writing superblocks and filesystem accounting information: done

Tip
Users installing to small SD cards may want to add the -i 8192 parameter to mkfs for root. The inode count cannot be changed after filesystem creation and can limit the number of files on a files system. The Gentoo repository alone needs over 17,000 inodes.

ext4 on root

root #mkfs -t ext4 /dev/sdi4

mke2fs 1.47.0 (5-Feb-2023)
Creating filesystem with 215813120 4k blocks and 53960704 inodes
Filesystem UUID: c09f4b30-f30d-43b7-a7e6-67f7bf6b25d7
Superblock backups stored on blocks:
        32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632, 2654208,
        4096000, 7962624, 11239424, 20480000, 23887872, 71663616, 78675968,
        102400000, 214990848

Allocating group tables: done
Writing inode tables: done
Creating journal (262144 blocks): done
Writing superblocks and filesystem accounting information: done

and a swap label on swap.

root #

mkswap /dev/sdi2
Setting up swapspace version 1, size = 8 GiB (8589930496 bytes)
no label, UUID=f351667c-3bf9-4bf5-a630-09da4fcc671f

Important
For the Pi 5 only

the --pagesize option is required, as the install host probably uses 4096B pages.

root #

mkswap --pagesize 16384 /dev/sdi2

Setting up swapspace version 1, size = 8 GiB (8589930496 bytes)
no label, UUID=f351667c-3bf9-4bf5-a630-09da4fcc671f

Installing the Gentoo installation files

Mount the newly created root filesystem. The traditional mount point is /mnt/gentoo, which will be used here.

root #mount /dev/sdi4 /mnt/gentoo

root #cd /mnt/gentoo

Choose the correct stage3 for your Pi from stage 3 downloads or the arm or arm64 sub pages.

The original Pi requires an ARMv6j stage 3

The Pi 2 up to the Rev 1.2 version, requires an ARMv7a stage 3

The Pi family from the Pi 2 Rev 1.2 onward are all 64 bit capable. The Pi 2 Rev 1.2 is really an underclocked Pi 3 without wifi.

From the Pi 2 Rev 1.2 and later, a 32 bit install requires an ARMv7a stage 3 and a 64 bit install requires an arm64 stage 3

Readers wanting to try MUSL are welcome to contribute.

Copy the link of your choice from https://www.gentoo.org/downloads/ or one of its sub pages. Then wget it into /mnt/gentoo. Do check the prompt.

This example uses the stage3-arm64-desktop-openrc stage3

/mnt/gentoo #wget https://distfiles.gentoo.org/releases/arm64/autobuilds/20231015T223200Z/stage3-arm64-desktop-openrc-20231015T223200Z.tar.xz

The checks for validating the stage 3 tarball described in the handbook are optional and only serve to authenticate the image contents.

Untar the stage 3. If this is done incorrectly it can destroy your host install.

Do check that the present working directory is /mnt/gentoo

/mnt/gentoo #ls

lost+found  stage3-arm64-desktop-openrc-20231015T223200Z.tar.xz

There is no root filesystem hierarchy there until the next step is complete.

/mnt/gentoo #tar xpvf stage3-*.tar.xz --xattrs-include='*.*' --numeric-owner

Thu v option writes filenames to the console, which slows things down.

If all is well, there is a root filesystem hierarchy in /mnt/gentoo together with the stage3 than provided it.

/mnt/gentoo #ls

bin   dev  home  lib64       media  opt   root  sbin                                                 sys  usr
boot  etc  lib   lost+found  mnt    proc  run   stage3-arm64-desktop-openrc-20231015T223200Z.tar.xz  tmp  var

Installing the Raspberry Pi Foundation files

Fetch the Raspberry Pi Foundation files

Some workspace and access to boot is required, so mount both /dev/sdi1 and /dev/sdi3 in our growing Raspberry Pi root filesystem tree.

/mnt/gentoo #mount /dev/sdi1 /mnt/gentoo/boot

/mnt/gentoo #mount /dev/sdi3 /mnt/gentoo/home

The Pi /home can be used as workspace.

/mnt/gentoo #cd /mnt/gentoo/home

Check that its empty

/mnt/gentoo/home #ls

lost+found

Fetch the binary kernel and Pi firmware from github

/mnt/gentoo/home #git clone --depth=1 https://github.com/raspberrypi/firmware

This is all the Raspberry Pi Foundation binary code to support the entire family of Raspberry Pis. Even Pi5 support is included.

/mnt/gentoo/home #ls firmware/

boot  documentation  extra  hardfp  modules  opt  README.md

For a 64 bit install, only boot and modules will be used.

Populate boot

Copy the content of boot to the vfat partition

/mnt/gentoo/home #cp -a firmware/boot/* /mnt/gentoo/boot/

and verify that it worked

/mnt/gentoo/home #ls /mnt/gentoo/boot

bcm2708-rpi-b.dtb	bcm2709-rpi-cm2.dtb	  bcm2711-rpi-400.dtb     bootcode.bin   fixup.dat        kernel.img        start_cd.elf
bcm2708-rpi-b-plus.dtb  bcm2710-rpi-2-b.dtb	  bcm2711-rpi-4-b.dtb     COPYING.linux  fixup_db.dat     LICENCE.broadcom  start_db.elf
bcm2708-rpi-b-rev1.dtb  bcm2710-rpi-3-b.dtb	  bcm2711-rpi-cm4.dtb     fixup4cd.dat   fixup_x.dat	  overlays          start.elf
bcm2708-rpi-cm.dtb	bcm2710-rpi-3-b-plus.dtb  bcm2711-rpi-cm4-io.dtb  fixup4.dat     kernel_2712.img  start4cd.elf      start_x.elf
bcm2708-rpi-zero.dtb    bcm2710-rpi-cm3.dtb	  bcm2711-rpi-cm4s.dtb    fixup4db.dat   kernel7.img	  start4db.elf
bcm2708-rpi-zero-w.dtb  bcm2710-rpi-zero-2.dtb    bcm2712-rpi-5-b.dtb     fixup4x.dat    kernel7l.img     start4.elf
bcm2709-rpi-2-b.dtb     bcm2710-rpi-zero-2-w.dtb  boot                    fixup_cd.dat   kernel8.img	  start4x.elf

Copy the kernel modules

Install the kernel modules

/mnt/gentoo/home # cp -a firmware/modules /mnt/gentoo/lib/

and verify

/mnt/gentoo/home #ls /mnt/gentoo/lib/modules/

6.1.58+  6.1.58-v7+  6.1.58-v7l+  6.1.58-v8+  6.1.58-v8_16k+

Kernel versions will change with time but the suffixes are probably fixed.

Raspberry Pi 5 WiFi/Bluetooth Firmware

Note
The Pi3 and Pi4 also have wifi/bluetooth but require different firmware files

Warning
Working WiFi at first boot also requires userspace tools that cannot be emerged until after the Pi has booted.

To use WIFI and bluetooth, firmware files need to be copied to /mnt/gentoo/lib/firmware folder.

WIFI

1. Clone wifi firmware repository

root #git clone --depth=1 https://github.com/RPi-Distro/firmware-nonfree.git

2. Create /mnt/gentoo/lib/firmware/brcm if it doesn't exist

root #mkdir -p /mnt/gentoo/lib/firmware/brcm

3. The wifi mode for raspberry pi 5 is brcmfmc43455, so we only need to copy files for brcmfmc43455.

root #cp firmware-nonfree/debian/config/brcm80211/cypress/cyfmac43455-sdio-standard.bin /mnt/gentoo/lib/firmware/brcm/brcmfmac43455-sdio.bin

root #cp firmware-nonfree/debian/config/brcm80211/cypress/cyfmac43455-sdio.clm_blob /mnt/gentoo/lib/firmware/brcm/brcmfmac43455-sdio.clm_blob

root #cp firmware-nonfree/debian/config/brcm80211/brcm/brcmfmac43455-sdio.txt /mnt/gentoo/lib/firmware/brcm/

4. When raspberry pi 5 boots, it looks for firmware names with model name, like raspberry,5-model-b, so we need to create symlinks for the firmware files, make sure you have following symlinks.

root #ls -l /mnt/gentoo/lib/firmware/brcm/

-rw-r--r-- 1 root root 643651 Jan 21 12:20 brcmfmac43455-sdio.bin
-rw-r--r-- 1 root root   2676 Jan 21 12:18 brcmfmac43455-sdio.clm_blob
lrwxrwxrwx 1 root root     22 Jan 21 12:23 brcmfmac43455-sdio.raspberrypi,5-model-b.bin -> brcmfmac43455-sdio.bin
lrwxrwxrwx 1 root root     27 Jan 21 12:23 brcmfmac43455-sdio.raspberrypi,5-model-b.clm_blob -> brcmfmac43455-sdio.clm_blob
lrwxrwxrwx 1 root root     22 Jan 21 12:24 brcmfmac43455-sdio.raspberrypi,5-model-b.txt -> brcmfmac43455-sdio.txt
-rw-r--r-- 1 root root   2074 Jan 21 12:19 brcmfmac43455-sdio.txt

Bluetooth

1. Clone bluetooth firmware repository

root #git clone --depth=1 https://github.com/RPi-Distro/bluez-firmware.git

2. Create /mnt/gentoo/lib/firmware/brcm if it doesn't exist

root #mkdir -p /mnt/gentoo/lib/firmware/brcm

3. For bluetooth, only BCM4345C0.hcd is needed.

root #cp bluez-firmware/debian/firmware/broadcom/BCM4345C0.hcd /mnt/gentoo/lib/firmware/brcm/

4. Similarly, we need to create a symlink for raspberry pi 5.

root #ln -s /mnt/gentoo/lib/firmware/brcm/BCM4345C0.hcd /mnt/gentoo/lib/firmware/brcm/BCM4345C0.raspberrypi,5-model-b.hcd

Important
You can't have wifi for the first boot, network tools must be installed before you can use wifi. NetworkManager is recommended to set up wifi.

• If you have ethernet, you can boot raspberrypi and use ethernet for emerging networkmanager.
• If not, you can use emerge -pf networkmanager to download all the files you need and copy them to /mnt/gentoo/var/cache/distfiles/.

Recap

The selected Gentoo stage3 is now installed on top of a universal Raspberry Pi Foundation set of kernels and GPU firmware. The Kernel and GPU firmware will work on any Pi as it is all there and what is required is auto detected at boot.

The stage3 is not so flexible.

This process will work for any Raspberry Pi provided the correct stage3 is selected.

Minimal Configuration

This involves describing the install to the Pi, from the Pi's view of the world.

No matter how the install host saw the target SD card, the Pi will see it as /dev/mmcblk0. As the files below here will be written on the install host to be read and used by the target, references to the SD card become /dev/mmcblk0.

Some text files need to be created so that the Pi will boot.

/mnt/gentoo/homecd /mnt/gentoo

Warning
there is no leading / on file names below. That would make the commands operate on the host install

cmdline.txt

/mnt/gentoo/nano boot/cmdline.txt

FILE /mnt/gentoo/boot/cmdline.txtcmdline.txt

dwc_otg.lpm_enable=0 console=tty root=/dev/mmcblk0p4 rootfstype=ext4 rootwait cma=256M@256M net.ifnames=0

Tip
cmdline.txt must be a single line

config.txt

config.txt is used to enable features, and if missing or empty will prevent a Pi5 from booting.

/mnt/gentoo/nano boot/config.txt

FILE /mnt/gentoo/boot/config.txtconfig.txt

# If using arm64 on a Pi3, select a 64 bit kernel
arm_64bit=1

# have a properly sized image
disable_overscan=1

# Enable audio (loads snd_bcm2835)
dtparam=audio=on

fstab

Important
Users installing to a SD card in a USB to SD adapter will find that their /dev/sd* during install becomes /dev/mmcblk0 at boot time

/mnt/gentoo/nano etc/fstab

FILE /mnt/gentoo/etc/fstabfstab

# <fs>                  <mountpoint>    <type>          <opts>          <dump> <pass>

#LABEL=boot             /boot           ext4            defaults        1 2
#UUID=58e72203-57d1-4497-81ad-97655bd56494              /               xfs             defaults                0 1
#LABEL=swap             none            swap            sw              0 0
#/dev/cdrom             /mnt/cdrom      auto            noauto,ro       0 0

/dev/mmcblk0p1          /boot           vfat            noatime,noauto,nodev,nosuid,noexec	1 2
/dev/mmcblk0p2          swap            swap            defaults                                0 0
/dev/mmcblk0p3          /home           ext4            noatime,nodev,nosuid,noexec             0 0
/dev/mmcblk0p4          /               ext4            noatime                                 0 0

Networking Information

Set the hostname.

Its not possible to install dhcpcd yet but the Pi will use dhcp to get started anyway.

Delay the dhcpcd install until after the @world update.

root password

Set the root password hash by editing the shadow file directly Replace the root line with the line shown below.

/mnt/gentoo/nano etc/shadow

FILE /mnt/gentoo/etc/shadowroot password hash

root:$6$xxPVR/Td5iP$/7Asdgq0ux2sgNkklnndcG4g3493kUYfrrdenBXjxBxEsoLneJpDAwOyX/kkpFB4pU5dlhHEyN0SK4eh/WpmO0::0:99999:7:::
halt:*:9797:0:::::
...

This sets the root password to raspberry. Don't leave it like that.

conf.d/keymaps

Skip this step if the default QWERTY US keymap works.

/mnt/gentoo/nano etc/etc/conf.d/keymaps

FILE /mnt/gentoo/etc/conf.d/keymapskeyboard setting

# Use keymap to specify the default console keymap.  There is a complete tree
# of keymaps in /usr/share/keymaps to choose from.
#keymap="us"
keymap="dvorak-uk"

configure sshd

Are you really not going to watch the console before the first login?

/mnt/gentoo/nano etc/ssh/sshd_config

FILE /mnt/gentoo/etc/ssh/sshd_configAllow password root logins

...
#LoginGraceTime 2m
#PermitRootLogin prohibit-password
PermitRootLogin yes
#StrictModes yes
...

Add the PermitRootLogin yes entry. Its a security hazard, revert that as soon as possible. Adding a ssh key is preferred.

OpenRC

Start the sshd service at boot time by adding a symbolic link to the default runlevel.

/mnt/gentoo/cd /mnt/gentoo/etc/runlevels/default/

/mnt/gentoo/etc/runlevels/defaultln -s /etc/init.d/sshd sshd

Systemd

Start the sshd service at boot time by adding a symbolic link to the service.

/mnt/gentoo/cd /mnt/gentoo

/mnt/gentooln -s /usr/lib/systemd/system/sshd.service etc/systemd/system/multi-user.target.wants/sshd.service

Tidy up and Test in the Pi

root #cd

root #umount /mnt/gentoo/boot

root #umount /mnt/gentoo/home

root #umount /mnt/gentoo

Remove the drive from the install host. Connect to the Pi and power up.

IMPORTANT After the First Boot

Warning
FIX YOUR SECURITY

It a really bad idea to use a root password from the internet - Change it as soon as your Pi boots.

root #passwd

and follow the on screen instructions.

Permitting a root password login over ssh is not much better. Use key based authentication or create a normal user with membership of the wheel group, then set up sudo. Key based ssh authentication everywhere is preferred.

Revert the /etc/ssh/sshd_config change as soon as possible.

Set the system time

Unless the system time is approximately correct, web site certificates will appear to be invalid.

Time will start at Thu Jan 1 00:00:00 -00 1970 every power on.

Even worse, time will not be monotonic.

The default hwclock is not useful without a battery backed RTC. Remove it from the default runlevel and replace it with swclock. swclock will ensure that time is monotonic by saving the time at shutdown and restoring it at power up.

OpenRC

Build systems require monotonic time.

localhost #rc-update add swclock boot

 * service swclock added to runlevel boot

localhost #rc-update del hwclock boot

 * service hwclock removed from runlevel boot

Check the system time

localhost #date

Thu Jan  1 00:24:05 -00 1970

Set the system time

root #date -s "YYYY-MM-DD HH:MM"

Check the system time again.

systemd

There is no swclock for systemd. The recommendation is to just install NTP service and run it. Either you can install and enable it with

localhost #emerge -v net-misc/openntpd

localhost #systemctl enable ntpd.service

localhost #systemctl start ntpd.service

Refer to NTP for systemd for the details.

Tip
Do this every boot until NTP time is available

CPU governor

The Raspberry Pi Foundation binary kernel is built to use the powersave CPU governor by default. That keeps the CPU at the lowest possible clock speed at all times. That's a bad choice for Gentoo. Changing it and actually making use of the change, requires a CPU heatsink since the Pi firmware looks after CPU thermal throttling, not the kernel.

root #cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

powersave

Make the file /etc/local.d/cpu_gov.start to set the schedutil CPU governor.

root #nano /etc/local.d/cpu_gov.start

FILE /etc/local.d/cpu_gov.startSet schedutil as CPU governor

#!/bin/bash
echo schedutil > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor 

# fixes all 4 CPUs

make it an executable file.

root #chmod +x /etc/local.d/cpu_gov.start

Clear the install leftovers

The stage 3 file in / and the firmware in /home are no longer required and may be removed.

Fix inittab

The stage3 tries to spawn agetty on the serial port at /dev/ttyAMA0 but the serial port is not set up or needed here. Console users will see repeated postings "INIT: Id "f0" respawning too fast: disabled for 5 minutes" every 5 minutes. To stop the repeated postings, disable agetty on the port by commenting out the last line of /etc/inittab and marking your edit as follows

localhost #nano /etc/inittab

FILE /etc/inittabinittab

# Architecture specific features
# [date][your id]: disabling as not needed for Raspberry Pi
# f0:12345:respawn:/sbin/agetty 9600 ttyAMA0 vt100

CPU Temperature and clock monitoring

localhost #cat /sys/class/thermal/thermal_zone0/temp

60374

Temp in milliCelcius or 60.374 Deg C.

localhost #cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq

1500000

CPU clock in kHz. or 1.5GHz

Everything skipped in the handbook

Not quite everything as some steps need to be omitted by design and others have already been accomplished by other means.

Until NTP is installed and configured, at every boot, time will be set from swclock, that is, the time at the last power off. Correct operation of https:// requires reasonably accurate time, so use date -s to set the time at every boot. This avoids "Certificate not valid errors" from the web.

The ordering is not the same as the handbook as some steps require packages to be installed and used. That requires a working emerge command. In turn that requires the ::gentoo repo to be installed.

Configuring compile options

Important
/mnt/gentoo is not required in path names as the Pi has already booted. Some of the steps below ale intended to be performed outside of the chroot

Setting COMMON_FLAGS requires a working portage and is covered below

COMMON_FLAGS="-march=native ... should be avoided on arm and arm64 systems.

Chrooting

This step has been avoided by design.

Gentoo ebuild repository

Fetch the ::gentoo repo snapshot from the web and update it.

Tip
We will use emerge to install some tools to provide data for the setup. emerge won't work without the ::gentoo repo, order matters.

Reading news items

Continue with reading the news.

Important
Missing some news, or not acting on it, can render the install unbootable

so it really is important that reading the news is a part of regular updates.

Choosing the right profile

The stage3 will have a profile already set. Follow choosing a profile to review and change it.

The profile will have /arm/ in its name for 32 bit installs or /arm64/ for 64 bit installs, not amd64 as illustrated. Arm64 does not support multilib, so that is not an option

Copy DNS info

The Pi is using the default DHCP to obtain DNS information so this step is not required unless networking is reconfigured later.

Mounting the necessary filesystems

Not Required. This step is preparation for chrooting.

Entering the new environment

Not Required. This step is entering the chroot.

Preparing for a bootloader

Already complete. The Pi has booted.

Configure locales

Follow configure locales to configure and select the system locales.

Selecting mirrors

Copy GENTOO_MIRRORS from make.conf on the install host, or follow Selecting mirrors on the Pi.

Follow configuring the Gentoo ebuild repository.

Important
The handbook performs this step before the chroot. The /mnt/gentoo part of the pathnames must not be used on the pathnames

Timezone

Follow Setting the timezone.

Updating the @world set

The handbook lists updating @world next. That can cause rebuilds due to changed USE settings later. Users building on the Pi may choose to configure the USE settings first, as this may save some rebuilds.

The VIDEO_CARDS variable is internally to portage, a USE flag too. Users intending to install a GUI set VIDEO_CARDS now.

Only fbdev, v3d and vc4 are useful on a Pi.

The tool cited in CPU_FLAGS will emit CPU_FLAGS_ARM. That's used on both arm and arm64.

COMMON_FLAGS="-march=native ... should be avoided on arm and arm64 systems.

Important
arm64 requires >=app-misc/resolve-march-native-3.0.0 which is ~arch at the time of writing

root #emerge -av app-misc/resolve-march-native

Then run it. A Pi 4 reports.

root #resolve-march-native

-mcpu=cortex-a72+crc

Note
There is no -march setting

A Pi 5 reports.

root #resolve-march-native

-mcpu=cortex-a76+crc+crypto

Use the output in COMMON_FLAGS. Add -OX -pipe where X is the selected optimisation level. -O3 should probably be avoided on RAM constrained systems, like the Pi.

Note
-mtune defaults to -mcpu if it is unset which breaks media-libs/libvpx and probably others.

Set -mtune=<CPU without the optional extras>

e.g. COMMON_FLAGS="-mcpu=cortex-a76+crc+crypto -mtune=cortex-a76 -O2 -pipe" for a Pi5.

With USE, VIDEO_CARDS, CFLAGS, CFLAGS and CPU_FLAGS_ARM all set, its time to actually update the @world set ... or maybe not.

Users wishing to run the @world update remotely will need to install app-misc/screen or app-misc/tmux first.

root #emerge -uDUav --jobs=2 --keep-going @world

Portage will warn

Warning
* Determining the location of the kernel source code

• Unable to find kernel sources at /usr/src/linux
• Please make sure that /usr/src/linux points at your running kernel,
• (or the kernel you wish to build against).

which is expected as no kernel source tree is installed.

ebuilds are unable to run kernel configuration checks.

dhcpcd

Follow Network settings.

Note
This step was deliberately delayed until the Pi was booted

Configuring the Linux kernel

Does not apply as the Pi is an arm/arm64 device.

Filesystem information

/etc/fstab is already complete.

• Networking information

System information

Follow System information

Installing system tools

Follow Installing system tools

Tip
File indexing may not be useful as its very slow

Time synchronization - Important with no RTC

Follow Time synchronization.

Filesystem tools

Follow Filesystem tools. Both sys-fs/e2fsprogs and sys-fs/dosfstools are required.

Choices for the root filesystem are limited by the filesystems built into the Raspberry Pi Foundation binary kernel.

Readers that can build their own kernel or kernel and initrd before the first boot, can use whatever root filesystem they choose.

Networking tools

Follow Networking tools.

Wireless networking tools are required but not sufficient to use WiFi. The kernel drivers are present but the firmware is not.

Tip
Users of USB WiFi dongles will need the tools described here too.

Configuring the bootloader

The Pi uses /boot/config.txt and /boot/cmdline.txt

Both are read by the GPU code at boot time. Reboot to test new configurations

Finalizing

Follow Finalizing.

Further Reading

Cross compiling

Once a cross toolchain is installed, pure cross compiling then installing the resulting binary packages is only a small step away.

It's not a silver bullet. Some packages have broken build systems, so that they are not cross compile aware. Others are cross compile hostile, as they build code for the target during the build then continue by attempting to execute it on the build host.

NEEDS a crossdev Refenence.

QEMU chroot

A QEMU chroot allows the build host to emulate (at the register level) the target CPU. It can bring the build hosts RAM, HDD space and CPU cores to bear but at reduced speed, due to the requirement to emulate the target CPU in software.

Its also possible to use cross distcc running on the host (outside the QEMU chroot) from inside the chroot. This exchanges the host CPU cycles required to emulate gcc with host CPU cycles for network emulation.

Cross distcc

That's ordinary distcc with a cross compiler on the helpers. See also distcc cross compiling.

Warning
Cross distcc is only included here for completness. The gains are not what may be expected and its not problem free either.

Only compiling is distributed. The Pi still performs the configure and link steps. Not everything can be distributed.

Do set up and test standard distcc before adding cross compiler(s). It will make debug easier.

Keeping versions of gcc in sync is a manual process which distcc cannot check.

Random Hints, Tips and Did You Know

Enable discard over USB

SSD/NVMe over USB users only. Trimming SD cards works by default, provided the SD card supports trim.

www-client/chromium

Given at least 1G of swap, its possible to emerge www-client/chromium on an 8G Pi 4.

root #genlop -t chromium

 * www-client/chromium

     Thu Oct 26 23:08:54 2023 >>> www-client/chromium-119.0.6045.21
       merge time: 3 days, 10 hours, 26 minutes and 57 seconds.

but it will probably be out of date by the time the emerge completes.

Widevine DRM

Digital Rights Management for Chromium and Firefox on arm64. Not required on 32 bit installs.

Install sys-fs/squashfs-tools as the widevine-installer script needs it.

root #emerge sys-fs/squashfs-tools

root #git clone https://github.com/AsahiLinux/widevine-installer

as it has to be run as root anyway.

root #cd widevine-installer

and read the widevine-installer script. Satisfy yourself that it will not do anything nasty beyond downloading a widewine squashfs image, unpacking and installing it for both Chromium and Firefox.

root #./widevine-installer

to install widevine and configure both Chromium and Firefox to use it.

If the browser(s) are already running, log out and back in again.

Default kernel configuration

root #modprobe configs

will provide /proc/config.gz which is the configuration file for the running kernel.

Zswap

Users with small SD cards may want to consider zswap which is a compressed area of ram for swap and other frequently written things. The idea being to avoid SD card writes.

Raspberry Pi 3

TODO Include the Pi3 specific parts here then depreciate that page.

Raspberry Pi 4

TODO Include the Pi4 specific parts here, then depreciate that page.

Raspberry Pi 5

Bluetooth

The file /lib/firmware/brcm/BCM4345C0.hcd is not in linux-firmware at the time of writing.

Real Time Clock

The Pi5 has a battery backed real time clock. The battery is an optional extra. When the battery is fitted, the hwclock service can be used in place of swclock.

The RTC can be used for alarms, wakeups without a backup battery, provided the Pi is always powered, to keep the clock alive.

Batteries are available in two types. Rechargeable and non-recharagable, like most PC motherboard CMOS batteries.

Battery charging is disabled by default, which is safe as attempting to recharge a non-recharagable lithium battery is both dangerous and bad for the battery lifetime.

Users who are sure that they have a rechargeable battery need to follow enabling trickle charging to turn on the battery charger. Heed the warning there too.

Wifi

The file brcmfmac43455-sdio.txt is required in /lib/firmware/brcm/ before the wifi interface will appear in

user $ip link

At the time of writing it was not included in linux-firmware.

Xorg on Pi5

The automatic setup fails on a Pi 5. The following xorg.conf fragment is required.

FILE /etc/X11/xorg.conf.d/99-vc4.conf99-vc4.conf

# Shamelessly copied from PiOS

Section "OutputClass"
  Identifier "vc4"
  MatchDriver "vc4"
  Driver "modesetting"
  Option "PrimaryGPU" "true"
EndSection