Skip to content

2.5 How the board boots: EEPROM, U-Boot, and Devicetree handoff

When you press the power button on an x86 desktop or laptop, a standardised firmware interface (UEFI, the Unified Extensible Firmware Interface, stored in an on-board SPI NOR flash chip) initialises the CPU, trains the DDR memory controller, enumerates the PCIe bus, reads boot entries from battery-backed NVRAM, and loads the operating system bootloader (GRUB or the Windows Boot Manager).1

Embedded Arm and RISC-V gateways do not have a PC BIOS, nor do most of them have a self-enumerating bus for their on-board peripherals. When power is first applied to a Raspberry Pi 4 or a BeagleBone Black, the main external DRAM (512 MB to 8 GB) is not even usable yet: its clock controllers and DDR timing delays must be calibrated before a single byte can be written to RAM.

Therefore, every embedded Linux gateway boots through a multi-stage bootloader chain, stepping from a tiny immutable ROM etched inside the silicon up through progressively more capable loaders until the Linux kernel is decompressed into RAM, handed a Flattened Devicetree Blob (.dtb) that describes the board’s hardware, and started.


Stage-by-stage: comparing the Raspberry Pi and U-Boot boot chains

Section titled “Stage-by-stage: comparing the Raspberry Pi and U-Boot boot chains”

Two bootloader architectures cover most of the embedded Linux boards that you will meet in practice:

  1. The Raspberry Pi firmware / SPI EEPROM boot chain (used on the Raspberry Pi 4, Pi 5, and Compute Modules 4/5).
  2. Das U-Boot (Universal Boot Loader) (the open-source de facto standard across Texas Instruments Sitara/BeagleBone, NXP i.MX, STMicroelectronics STM32MP1, Rockchip, and Allwinner platforms).

Figure 2.12 traces both boot chains side by side from 0 ms power-on to PID 1 (systemd).

Figure 2.12

Two ways to boot Embedded Linux

Click a stage to see where it runs on the board.

Raspberry Pi 5: EEPROM boot
1BCM2712LPDDR4XRP1PHYPMICRaspberry Pi 5
BeagleBone Black: U-Boot SPL → U-Boot
P9P8AM335xDDR3eMMCPMICBeagleBone Black

Select a stage. The highlighted chip on the board is where that stage's code is stored or runs.

Figure 2.12. Side-by-side comparison of the Raspberry Pi 4/5 SPI EEPROM boot sequence and the industry-standard U-Boot SPL → U-Boot sequence on the BeagleBone Black.


Inside the Raspberry Pi 4 and Pi 5 boot sequence

Section titled “Inside the Raspberry Pi 4 and Pi 5 boot sequence”

On early Raspberry Pi models (Pi 1 through Pi 3B+), the SoC had no on-board flash memory at all: at power-on, the Arm CPU cores stayed held in reset while the VideoCore IV GPU woke up, read bootcode.bin and start.elf from the microSD card’s FAT partition, initialised the SDRAM, and finally released the Arm CPU to run Linux.2 If the microSD card was missing or corrupted, the board appeared completely dead.

Starting with the Raspberry Pi 4, Pi 5, and Compute Module 4/5, Raspberry Pi moved the second-stage bootloader, which replaces bootcode.bin, into an on-board SPI flash EEPROM (512 KB on the Pi 4, 2 MB on the Pi 5) soldered onto the PCB:3

  1. Stage 1 (SoC Boot ROM): When the 5 V rail stabilises, the on-die boot ROM reads the second-stage bootloader from the on-board SPI EEPROM.
  2. Stage 2 (SPI EEPROM Bootloader): Runs on the embedded processor, displays a diagnostic screen on HDMI if no bootable media is found, and executes the configured BOOT_ORDER (trying microSD first, then USB mass storage, PCIe NVMe on Pi 5, or PXE network boot).4
  3. Stage 3 (SDRAM Training & Firmware):
    • On the Raspberry Pi 4, the EEPROM loader reads start4.elf (the VideoCore VI firmware) and fixup4.dat (memory split relocation table) from the FAT32 boot partition.
    • On the Raspberry Pi 5, the boot architecture is streamlined further: the entire bootloader and SDRAM training sequence runs directly out of the on-board SPI EEPROM without needing a start4.elf file on the microSD card.3
  4. Stage 4 (config.txt and Devicetree Assembly): Before the Linux kernel is even loaded, the bootloader reads /boot/firmware/config.txt, probes ID_SD/ID_SC (I2C0) for any attached HAT EEPROM, loads the base Devicetree Blob for your exact board (e.g., bcm2711-rpi-4-b.dtb on Pi 4 or bcm2712-rpi-5-b.dtb on Pi 5), and merges in any dtoverlay= or dtparam= directives you specified into a single in-memory Devicetree structure.5
  5. Stage 5 (Kernel & initramfs Launch): Finally, the bootloader loads the compressed 64-bit Linux kernel (kernel8.img for 4 KB-page Arm64 on Pi 4, or kernel_2712.img optimised with 16 KB memory pages for the Cortex-A76 on Pi 5)5, loads initramfs8, reads the kernel command-line arguments from /boot/firmware/cmdline.txt, places the physical RAM address of the merged Devicetree into CPU register x0, and jumps into the Linux kernel.6

Inspecting /boot/firmware/ on modern Raspberry Pi OS

Section titled “Inspecting /boot/firmware/ on modern Raspberry Pi OS”

The following is an excerpt of the contents of /boot/firmware/ on a Raspberry Pi 4 (the full listing also holds the .dtb files for the other boards and further firmware files):

Terminal window
derek@rpi:~ $ ls -lh /boot/firmware/
-rwxr-xr-x 1 root root 49K Nov 7 12:00 bcm2711-rpi-4-b.dtb
-rwxr-xr-x 1 root root 76K Nov 7 12:00 bcm2712-rpi-5-b.dtb
-rwxr-xr-x 1 root root 160 Nov 7 12:00 cmdline.txt
-rwxr-xr-x 1 root root 1.3K Nov 7 12:00 config.txt
-rwxr-xr-x 1 root root 5.3K Nov 7 12:00 fixup4.dat
-rwxr-xr-x 1 root root 17M Nov 7 12:00 initramfs8
-rwxr-xr-x 1 root root 17M Nov 7 12:00 initramfs_2712
-rwxr-xr-x 1 root root 9.2M Nov 7 12:00 kernel8.img
-rwxr-xr-x 1 root root 9.3M Nov 7 12:00 kernel_2712.img
drwxr-xr-x 2 root root 36K Nov 7 12:00 overlays
-rwxr-xr-x 1 root root 2.2M Nov 7 12:00 start4.elf

Notice why a single microSD card can be unplugged from a Raspberry Pi 4 and plugged straight into a Raspberry Pi 5 and boot cleanly: /boot/firmware/ holds the .dtb, initramfs, and kernel*.img files for both architectures, and the firmware picks the matching set at boot.

You can also inspect (or edit with sudo -E rpi-eeprom-config --edit) the persistent parameters stored inside your board’s on-board SPI EEPROM:3

Terminal window
derek@rpi:~ $ rpi-eeprom-config
[all]
BOOT_UART=0
WAKE_ON_GPIO=1
POWER_OFF_ON_HALT=0
BOOT_ORDER=0xf41

Here, BOOT_UART=0 is the default: the EEPROM bootloader prints nothing on the header UART. Change it to BOOT_UART=1 and the bootloader prints its diagnostic messages at 115200 baud before the microSD card is read, which is useful when a board does not boot. BOOT_ORDER=0xf41 (read right to left) tells the bootloader to try the microSD card (1) first, then USB mass storage (4), and then loop (f).4

Anatomy of /boot/firmware/config.txt and cmdline.txt

Section titled “Anatomy of /boot/firmware/config.txt and cmdline.txt”

Because the Raspberry Pi has no BIOS setup screen (F2 / Del), /boot/firmware/config.txt serves as your hardware configuration file.5 We will explore its Devicetree overlay directives in depth in Chapter 4, but here are the core lines you will use immediately:

# /boot/firmware/config.txt (excerpt)
# Enable I2C1 on Pins 3 (SDA) and 5 (SCL)
dtparam=i2c_arm=on
# Enable SPI0 on Pins 19, 21, 23, 24, 26
dtparam=spi=on
# Enable the serial UART on Pins 8 (TXD) and 10 (RXD)
enable_uart=1
# Example Devicetree parameters and overlays (Chapter 4):
# Pulse the red PWR LED in a heartbeat pattern while the kernel is running
dtparam=pwr_led_trigger=heartbeat
# Shut Linux down cleanly when GPIO17 (Pin 11) is connected to ground
dtoverlay=gpio-shutdown,gpio_pin=17

The comments are on their own lines because config.txt does not reliably accept a comment after a setting on the same line.5 The gpio-shutdown overlay defaults to GPIO3 (Pin 5), but that pin is SCL1 of the I²C bus enabled on the first line, so this example moves the button to GPIO17 (Section 2.6).

Beside config.txt sits /boot/firmware/cmdline.txt, which must be a single line of space-separated arguments8 passed directly to the Linux kernel (you can always check what arguments the running kernel received by running cat /proc/cmdline):

console=serial0,115200 console=tty1 root=PARTUUID=738a4d62-02 rootfstype=ext4 fsck.repair=yes rootwait
  • console=serial0,115200 console=tty1: Sends kernel boot messages (printk) to both the hardware UART (serial0) at 115200 baud and the local HDMI virtual terminal (tty1).
  • root=PARTUUID=... rootfstype=ext4 rootwait: Tells the kernel which partition holds the ext4 root file system and instructs it (rootwait) to wait asynchronously until the slow microSD or USB bus finishes initialising before attempting to mount /.

How other boards boot: Das U-Boot on the BeagleBone

Section titled “How other boards boot: Das U-Boot on the BeagleBone”

What happens when you work on a gateway that isn’t a Raspberry Pi, such as a BeagleBone Black, BeagleY-AI, or an industrial board based on NXP i.MX8 or STM32MP1? Those platforms do not have a VideoCore GPU firmware; instead, they use Das U-Boot, an open-source bootloader written in C.9

Look back at the right column of Figure 2.12 (UBoot). Why does the BeagleBone need two U-Boot binaries (MLO and u-boot.img) instead of one?

  1. When the Texas Instruments AM335x SoC powers on, its external 512 MB DDR3 RAM chip is unconfigured and inaccessible. The only working memory on the board is the internal static RAM (SRAM) inside the processor, and the boot ROM limits the first-stage image that it loads there to about 109 KB.10
  2. Full u-boot.img (with its command-line shell, Ethernet TFTP stack, USB drivers, and file-system parsers) is over 400 KB, too large to fit into internal SRAM.
  3. Therefore, the U-Boot build compiles a tiny stripped-down first stage called the U-Boot SPL (Secondary Program Loader), which has the file name MLO on TI chips (~85 KB). The SoC’s internal Mask ROM loads MLO into internal SRAM; MLO configures the phase-locked loops (PLLs) and initialises the external 512 MB DDR3 DRAM, and then loads the full u-boot.img into DDR3 DRAM.11
  4. Full U-Boot prints a short autoboot countdown on the serial console (Hit any key to stop autoboot), reads its environment variables from uEnv.txt (or /boot/extlinux/extlinux.conf), loads the kernel image (zImage at 0x82000000) and the compiled Devicetree (am335x-boneblack.dtb at 0x88000000) into DRAM, and executes the U-Boot launch command:
    U-Boot# bootz 0x82000000 - 0x88000000
    (Note: In U-Boot, bootz <kernel_addr> <initrd_addr_or_dash> <fdt_addr> boots a compressed 32-bit Arm zImage,12 while booti boots an uncompressed 64-bit Arm64 Image).

Why the bootloader hands a Devicetree to the kernel

Section titled “Why the bootloader hands a Devicetree to the kernel”

Notice the common thread uniting the Raspberry Pi EEPROM bootloader and Das U-Boot: both bootloaders assemble a compiled Devicetree Blob (.dtb) in RAM and pass its memory address to the Linux kernel at the moment of launch.

Prior to 2011, the Linux kernel did not use Devicetrees on Arm. Every time someone designed a new Arm board, they had to write thousands of lines of C “board files” inside arch/arm/mach-*/ hardcoding every I²C address, interrupt line, and GPIO pin, and the bootloader passed a magic integer (machine type) and a tiny parameter list (ATAGS) to the kernel. This caused so much duplicated C code that Linus Torvalds threatened to stop merging Arm platform trees in 2011,13 which led to the adoption of the Flattened Devicetree across all Arm embedded Linux systems.14

With Devicetree:

  • One compiled Linux kernel image (kernel8.img or vmlinuz) can boot on dozens of different boards without recompiling a single line of C kernel source.15
  • The kernel discovers what hardware exists on the board (and which pins are routed where) entirely by parsing the .dtb tree handed to it by the bootloader (inspectable live under /proc/device-tree/).

In Chapter 4, we will see that Zephyr RTOS uses the exact same Devicetree syntax on our ESP32 leaf node,16 giving us a single hardware description language across both tiers of our architecture.

Concept Match

Match the boot file to its role

Quiz
Select 0/1

Why does the BeagleBone Black need two U-Boot binaries, MLO and u-boot.img?

Quiz
Select 0/1

rpi-eeprom-config shows BOOT_ORDER=0xf41. In what order does the bootloader try the boot devices?

Quiz
Select 0/2

Which of the following statements about the Devicetree that the bootloader hands to the kernel are correct?

  1. UEFI Forum, Unified Extensible Firmware Interface (UEFI) Specification, Release 2.11, Dec. 2024. Available: uefi.org/specs/UEFI/2.11. ↩

  2. Raspberry Pi Ltd, “Boot sequence,” Raspberry Pi computer hardware, Raspberry Pi Documentation. Available: raspberrypi.com/documentation/computers/raspberry-pi.html. ↩

  3. Raspberry Pi Ltd, “Raspberry Pi boot EEPROM” and “EEPROM boot flow,” Raspberry Pi computer hardware, Raspberry Pi Documentation. Available: raspberrypi.com/documentation/computers/raspberry-pi.html. ↩ ↩2 ↩3

  4. Raspberry Pi Ltd, “Raspberry Pi bootloader configuration” (BOOT_UART, BOOT_ORDER), Raspberry Pi computer hardware, Raspberry Pi Documentation. Available: raspberrypi.com/documentation/computers/raspberry-pi.html. ↩ ↩2

  5. Raspberry Pi Ltd, config.txt (“What is config.txt?”, “Boot options”: kernel, auto_initramfs, enable_uart), Raspberry Pi Documentation. Available: raspberrypi.com/documentation/computers/config_txt.html. ↩ ↩2 ↩3 ↩4

  6. The Linux Kernel Documentation, Booting AArch64 Linux. Available: docs.kernel.org/arch/arm64/booting.html. ↩

  7. Raspberry Pi Ltd, “boot folder contents,” Configuration, Raspberry Pi Documentation. Available: raspberrypi.com/documentation/computers/configuration.html. ↩

  8. Raspberry Pi Ltd, “Configure the kernel command line,” Configuration, Raspberry Pi Documentation. Available: raspberrypi.com/documentation/computers/configuration.html. ↩

  9. D. Molloy, Exploring BeagleBone: Tools and Techniques for Building with Embedded Linux, 2nd ed. Indianapolis, IN, USA: Wiley, 2019, ISBN 978-1-119-53316-0. ↩

  10. barebox, “Texas Instruments AM335x,” barebox documentation. Available: barebox.org/doc/latest/boards/am335x.html. ↩

  11. U-Boot, Secondary Program Loader (SPL), The U-Boot Documentation. Available: docs.u-boot.org/en/latest/usage/spl_boot.html. ↩

  12. U-Boot, bootz command, The U-Boot Documentation. Available: docs.u-boot.org/en/latest/usage/cmd/bootz.html. ↩

  13. J. Corbet, “ARM wrestling,” LWN.net, 6 Apr. 2011. Available: lwn.net/Articles/437162. ↩

  14. devicetree.org, Devicetree Specification, Release v0.4, 28 June 2023. Available: devicetree.org/specifications. ↩

  15. G. Likely, Linux and the Devicetree, The Linux Kernel Documentation. Available: docs.kernel.org/devicetree/usage-model.html. ↩

  16. Zephyr Project, Devicetree, Zephyr Project Documentation. Available: docs.zephyrproject.org/latest/build/dts/index.html. ↩