Official NixOS Wiki

NixOS on ARM/Raspberry Pi 5: Difference between revisions

← Older editNewer edit →
VisualWikitext
Various corrections
Give overall page more structure and mention working undesirable but already working NixOS setup
Line 13: Line 13:
|-
|-
!Bootloader
!Bootloader
|Custom or UEFI
|Custom, UEFI or u-boot
|-
|-
!Boot order
!Boot order
Line 31: Line 31:
== Status ==
== Status ==


'''NixOS works on Raspberry Pi 5 but is currently experimental'''.
NixOS doesn't run out-of-box, but relies on several tweaks on the boot process that are maintained by different individuals and spread over multiple repositories.


The Raspberry Pi 5's boot process follows the [https://youtu.be/UvFG76qM6co?t=308 typical boot stages on embedded devices], and has the following boot loader steps by default:
  1. ROM -> 2. EEPROM -> Pi-custom Firmware/Kernel -> PiOS (custom Debian)
'''The pain points for NixOS support''' are the Pi's [https://github.com/raspberrypi/rpi-eeprom custom EEPROM boot bootloader], its  [https://github.com/raspberrypi/firmware proprietary, closed-source firmware] (code to use to hardware components) and [https://github.com/raspberrypi/linux its separately maintained Linux kernel], all of which we would need to '''update, build and test constantly and separately''' from the other NixOS Linux kernel variations, '''which is a large, unmaintainable burden for the NixOS community''' when the Pi 5 is not the only supported SoC; so we don't want that.


'''Support for the Raspberry Pi 5 is currently downstream and experimental'''.  
Instead our goal is to '''migrate towards the standard, generic boot process''' with UEFI:
It will not be fully supported until mature support exists in the upstream Linux kernel and
  1. ROM -> 2. EEPROM -> 3. UEFI boot loader -> 4. systemd-boot boot loader -> Generic Kernel -> NixOS
the [https://github.com/u-boot/u-boot U-Boot] boot loader, but using an '''UEFI bootloader already provides a workable solution'''.
We can't affect the ROM and EEPROM boot loaders as they come built-in into the hardware. However, [https://de.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface UEFI] is also used for booting normal Intel/AMD computers, and the [https://www.freedesktop.org/software/systemd/man/latest/systemd-boot.html systemd-boot] boot loader is THE software that allows us to have and select from multiple NixOS generations on boot (and perform rollbacks if we messed up). '''The currently required manual steps are roughly listed further down below''' and require lots of Linux and NixOS understanding.


The Raspberry Pi 5's boot process follows the [https://youtu.be/UvFG76qM6co?t=308 typical boot stages on embedded devices], some of which have to be adapted to work with NixOS. For that it's helpful to understand more about the stages:
Alternatively, '''if you want to get up-and-running quickly in the mean-time''' there's a setup that '''reuses all pi-custom software''' (non-desired approach but works)
  1. ROM -> 2. EEPROM -> Pi-custom Firmware/Kernel -> NixOS
and creates a hard disk image that you can flash onto an SD card or NVMe SSD. The heavy lifting has been done and is maintained at https://github.com/tstat/raspberry-pi-nix (just follow the example and hints at https://github.com/tstat/raspberry-pi-nix/issues/13) and has the best out-of-the-box experience. You have to remote-build many Nix packages, probably the kernel as well, yourself (e.g. using the [https://wiki.nixos.org/wiki/Distributed_build Pi without NixOS as an intermediate remote builder]) and that can take several hours though.
 
It will also likely get [https://github.com/u-boot/u-boot U-Boot] support soon (likely only interesting for people that need more exotic hardware support like hats):
  1. ROM -> 2. EEPROM -> Pi-custom Firmware/Kernel -> U-Boot boot loader -> NixOS
 
== Raspberry Pi Boot stages ==
To understand the adaptions for NixOS better, it's helpful to understand more about the stages:


1. '''ROM boot loader''': The first-stage boot loader comes "burned in" on the Pi in a tiny
1. '''ROM boot loader''': The first-stage boot loader comes "burned in" on the Pi in a tiny
Line 88: Line 101:
[https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#differences-on-raspberry-pi-5 official documentation].
[https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#differences-on-raspberry-pi-5 official documentation].


'''Adaptations for booting NixOS''':
== Setup generic UEFI NixOS ==
 
   1. ROM -> 2. EEPROM -> 3. UEFI boot loader (EDK2) -> 4. systemd-boot boot loader -> Pi 5-adapted NixOS Kernel -> NixOS
In order to boot NixOS with it's default boot loader systemd-boot we need UEFI support, so replace the
1. '''Install EDK2''' (UEFI firmware implementation):
  1. ROM -> 2. EEPROM -> Kernel -> NixOS
workflow with third-stage and fourth-stage boot loaders (both as firmware on an SD card or NVMe SSD etc.)
   1. ROM -> 2. EEPROM -> 3. EDK2 (UEFI implementation) -> 4. systemd-boot -> Kernel -> NixOS
as follows:
 
1. '''Install EDK2''':


We need the first partition of the SD card (or NVMe SSD, etc.) again to be formatted as FAT
We need the first partition of the SD card (or NVMe SSD, etc.) again to be formatted as FAT
Retrieved from "https://wiki.nixos.org/wiki/NixOS_on_ARM/Raspberry_Pi_5"