Raspberry Pi 5 UEFI

This repository contains a TF-A + EDK2 UEFI firmware port for Raspberry Pi 5.

Getting started

Check the Supported OSes and Supported peripherals in UEFI sections to see what's currently possible with this firmware.

1. Prerequisites

• SD card, USB or NVME drive to store the firmware and/or operating system on

  Note: For OS, it is highly suggested to use a quality drive with good random I/O performance. In SD terms this means an A1/A2-rated card.

• Quality power supply and cable that can provide at least 5V 3A (15 W)

  Depending on the peripherals you use, more power may be needed. The recommended official power supply provides 5.1V 5A (25 W).

  Note: Using an inadequate supply can cause all sorts of issues, from underclocking to random crashes.

• HDMI display

• Some form of cooling (fan, heatsink)

  The device may thermal throttle otherwise.

Optionally, if display is not available or for debugging purposes, an UART serial adapter compatible with the special connector. Configuration is 115200 8n1.

2. Download the firmware image

The latest version can be obtained from Releases.

3. Flash the firmware

Prepare an empty boot drive by formatting the first partition as FAT32, then extract the archive downloaded above to the root of this partition.

Note: do not rename or delete any of the boot files.

4. Connect peripherals and power on the device

You should first see a QR code screen, then shortly after, a centered Raspberry Pi logo with progress bar at the bottom. This indicates that the UEFI firmware has loaded.

At this stage, you can press Esc to enter the firmware setup, F1 to launch the UEFI Shell, or, provided you also have an UEFI bootloader/app on a storage device, you can let the system automatically run that, which is the default behavior if no action is taken.

Check the configuration options described below, some of which may need to be changed depending on the OS used.

Configuration settings

The UEFI provides options that can be viewed and changed using the UI configuration menu.

Configuration through the user interface is fairly straightforward and help/navigation information is provided around the menus.

PCI Express

The PCIe connector is limited to Gen 2 speed by default. For other modes, go to Device Manager->Raspberry Pi Configuration->PCI Express and change Link Speed.

[!NOTE] Raspberry Pi 5 is not officially rated for PCIe Gen 3. Some devices and adapters may run into reliability issues at this speed, either due to signal integrity or insufficient power.

Linux

• If you're getting a Synchronous Exception when booting certain distros, go to Device Manager->EFI Memory Attribute Protocol and untick Enable Protocol.

• For maximum SD card performance, go to Device Manager->Raspberry Pi Configuration->ACPI / Device Tree and set Compatibility Mode to Full Bay Trail, then untick Limit UHS-I Modes.

  Warning: this may affect other OSes!

• To enable PCIe support, go to Device Manager->Raspberry Pi Configuration->ACPI / Device Tree and change ECAM Compatibility Mode to AMAZON GRAVITON.

• If you're running the RPi downstream kernel, enabling Device Tree instead of ACPI will provide better hardware support. To do so, go to Device Manager->Raspberry Pi Configuration->ACPI / Device Tree and change System Table Mode.

Status

Supported OSes

In ACPI mode

ACPI support is currently under development and limited to a few devices that have existing driver bindings.

In Device Tree mode

The included DTB is meant for the RPi downstream 6.1.y kernel.

Supported peripherals in UEFI

[!NOTE] Only devices relevant to the firmware itself (not OS) are listed below.

Building

This process assumes a Linux machine. On Windows, use WSL.

1. Install required packages:

   For Ubuntu/Debian:

   sudo apt install git gcc g++ build-essential gcc-aarch64-linux-gnu iasl python3-pyelftools uuid-dev
   

   For Arch Linux:

   sudo pacman -Syu
   sudo pacman -S git base-devel gcc dtc aarch64-linux-gnu-binutils aarch64-linux-gnu-gcc aarch64-linux-gnu-glibc python python-pyelftools iasl --needed
   

2. Clone the repository:

   git clone --recurse-submodules https://github.com/worproject/rpi5-uefi.git
   cd rpi5-uefi
   

3. Build the image:

   ./build.sh
   

   Append --help for more details.

If you get build errors, it is very likely that you're still missing some dependencies. The list of packages above is not complete and depending on the distro you may need to install additional ones. In most cases, looking up the error messages on the internet will point you at the right packages.

Licenses

Most files are licensed under the default EDK2 license, BSD-2-Clause-Patent.

For TF-A, see: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/license.rst