Essential U‑Boot Concepts and Practical Guide

1. Basic concepts and role of U‑Boot

Definition : Universal Bootloader, an open‑source, cross‑architecture (ARM, x86, MIPS, …) bootloader maintained by DENX, de‑facto standard in embedded systems.

Core functions :

Hardware initialization (DDR, clocks, UART, storage, network, …) to prepare the environment for the kernel.

Image loading (Linux kernel, device tree, root filesystem) from flash/eMMC/SD/network into memory.

Interactive debugging via a command‑line interface for hardware detection, parameter configuration, firmware upgrade, and fault diagnosis.

Environment management using key‑value variables to store boot parameters and hardware configuration.

Multi‑scenario adaptation (secure boot, multiple storage devices, network remote boot, …).

2. U‑Boot boot process

Phase 1 (assembly, arch/xxx/cpu/xxx/start.S )

Minimal hardware init: disable watchdog, disable interrupts, set CPU mode (e.g., ARM SVC), init stack.

DDR init: configure controller timing and bring up memory (required for further code execution).

Relocate main program: copy U‑Boot from on‑chip flash (e.g., SPI flash) to DDR.

Jump to Phase 2 by executing bl main to enter the C‑level entry point.

Phase 2 (C level, entry common/main.c )

Global init: set up exception vector table, UART, and print framework (U‑Boot logo).

Peripheral init: iterate over storage (eMMC/SD/NAND), network (Ethernet), …

Environment variable init: read variables such as bootcmd and bootargs from flash; fall back to defaults if missing.

Board detection: detect board version and storage status.

Boot decision:

Auto‑boot: execute bootcmd after countdown.

Manual: interrupt countdown (any key) to obtain the U‑Boot prompt.

3. U‑Boot environment variables

Definition and management

Key‑value pairs (e.g., ipaddr=192.168.1.100) that configure boot logic and hardware without source changes.

Commands: printenv – display all variables. setenv <key> <value> – set or modify a variable (e.g., setenv bootcmd "tftp 80800000 zImage; bootz"). saveenv – persist variables to storage (SPI flash, eMMC, …). resetenv – restore default variables.

Typical uses: bootargs passed to the kernel (e.g., root=/dev/mmcblk0p2 rw console=ttyS0,115200). bootcmd defines the automatic boot sequence. ipaddr / serverip configure TFTP/NFS parameters.

Custom default values

Edit the board configuration header (e.g., include/configs/s32k344_evb.h).

Add or modify the CONFIG_EXTRA_ENV_SETTINGS macro, for example:

#define CONFIG_EXTRA_ENV_SETTINGS \
"ipaddr=192.168.1.100\0" \
"serverip=192.168.1.200\0" \
"bootcmd=mmc read 80800000 0x10000 0x8000; bootz 80800000 - 81000000\0" \
"bootargs=root=/dev/mmcblk0p2 rw console=ttyS0,115200\0"

Re‑compile U‑Boot and flash; the default environment now contains the custom settings.

4. U‑Boot command system

Implementation principle

Each command is described by struct cmd_tbl_s (name, max args, repeatable flag, execution function pointer, short help, detailed help). Commands are registered with the U_BOOT_CMD macro, which adds them to a global linked list. At runtime the input line is tokenized, matched against the list, and the corresponding function is invoked.

Adding a custom command (practical steps)

Create a source file under cmd/, e.g. cmd_mycmd.c.

Define the command function:

static int do_mycmd(struct cmd_tbl *cmdtp, int flag, int argc, char * const argv[])
{
    printf("My Custom U‑Boot Command! argc=%d
", argc);
    if (argc > 1)
        printf("Arg1: %s
", argv[1]);
    return 0;
}

Register the command with U_BOOT_CMD:

U_BOOT_CMD(
    mycmd,    2,    0,    do_mycmd,
    "my custom command",
    "mycmd [arg] - Print custom message"
);

Add obj-y += cmd_mycmd.o; to cmd/Makefile.

Re‑compile and flash; the new command can be invoked as mycmd test.

5. U‑Boot device‑tree support

How U‑Boot uses a device tree

Compile‑time : enable CONFIG_OF_CONTROL and generate xxx.dtb with make dtbs.

Boot‑time :

Load the DTB to a fixed DDR address (e.g., 0x81000000).

Parse hardware nodes (UART, DDR, storage) and initialize the corresponding peripherals.

Pass the DTB address to the kernel with bootz zImage_addr -- dtb_addr.

Benefits

Hardware decoupling – no hard‑coded registers; modify the DTB to adapt new hardware.

Kernel alignment – the same DTB is handed to Linux, ensuring consistent hardware description.

Dynamic configuration – runtime DTB modifications via the fdt command.

6. U‑Boot network functions

Supported core features

TFTP – download kernel, DTB, or root filesystem.

NFS – mount an NFS root filesystem.

PING – test network connectivity.

DHCP – obtain IP address and server address automatically.

BOOTP – legacy automatic parameter allocation.

Network boot steps

Configure network variables:

setenv ipaddr 192.168.1.100   # board IP
setenv serverip 192.168.1.200 # TFTP server IP
saveenv

Download kernel and DTB:

tftp 80800000 zImage          # load kernel to 0x80800000
tftp 81000000 s32k344.dtb    # load DTB to 0x81000000

Boot the kernel:

bootz 80800000 - 81000000   # bootz [kernel] [ramdisk] [DTB]

7. U‑Boot storage device support

Supported storage types

Non‑volatile: SPI Flash, NAND Flash, NOR Flash.

Block devices: eMMC, SD card, SATA HDD, USB storage.

High‑end: NVMe SSD.

Boot command examples

eMMC: mmc read 80800000 0x10000 0x8000; bootz 80800000 - 81000000 SD Card:

mmc dev 1; mmc read 80800000 0x10000 0x8000; bootz 80800000 - 81000000

SPI Flash: sf read 80800000 0x20000 0x8000; bootz 80800000 - 81000000 NAND Flash:

nand read 80800000 0x20000 0x8000; bootz 80800000 - 81000000

8. U‑Boot secure boot

Secure boot uses encryption and signature verification to guarantee the integrity of the boot chain (U‑Boot → kernel → DTB). Implementation steps:

Enable macros such as CONFIG_SECURE_BOOT and CONFIG_BOOT_SECURITY.

Sign images (U‑Boot, kernel, DTB) with a private key to produce signature files.

U‑Boot contains a public key; at boot it verifies signatures using a hardware crypto module (HSM/TPM) or CPU secure unit.

If verification fails, boot is aborted; only verified images are loaded.

9. U‑Boot debugging techniques

Serial console : ensure CONFIG_SERIAL_CONSOLE is enabled; increase log level with CONFIG_LOGLEVEL=7 for verbose output.

JTAG/GDB : connect a debugger (e.g., J‑Link) and use GDB to set breakpoints in assembly or C code (e.g., DDR init).

Memory commands : md <addr> <len> – dump memory. mm <addr> – modify memory. mw <addr> <val> <len> – write memory.

QEMU simulation : run qemu-system-arm -M vexpress-a9 -kernel u-boot.bin on a PC to quickly validate logic.

Segmented debugging : verify Phase 1 (DDR init and relocation) first, then Phase 2 (peripheral init).

10. U‑Boot performance optimization

Feature trimming : disable unnecessary commands (e.g., CONFIG_CMD_NFS, CONFIG_CMD_USB) and turn off debug logging ( CONFIG_LOGLEVEL=0), hide the logo.

Init optimization : keep Phase 1 limited to core hardware (DDR, UART); defer peripheral init to the kernel; tighten DDR timing.

Image optimization : enable CONFIG_SYS_BOOT_GET_CMDLINE to skip environment loading; compress the U‑Boot image with CONFIG_SYS_BOOT_COMPRESSED.

SPL lightweight boot : use SPL (Secondary Program Loader) for fast DDR init and jump to the main image.

Parameter hardening : embed bootcmd and bootargs directly in code, bypassing environment reads.

11. U‑Boot customization and porting (ARM example)

Reference an existing board configuration (e.g., board/nxp/s32k3xx/).

Create a new config header include/configs/xxx_evb.h defining DDR size, UART base, flash parameters.

Set CONFIG_SYS_TEXT_BASE (U‑Boot run address) and CONFIG_SYS_INIT_SP_ADDR (stack address).

Implement board files under board/xxx/xxx_evb/ providing board_init_f (Phase 1) and board_init_r (Phase 2).

Adapt the device tree: create/modify xxx.dtb to describe DDR, UART, storage, network.

Compile with make xxx_evb_defconfig; make -j8, flash, and debug via serial.

Validate peripherals, network, and kernel boot flow.

12. U‑Boot vs. other bootloaders

U‑Boot : embedded focus, cross‑architecture, very feature‑rich, moderate boot speed, large code base, extensive ecosystem.

GRUB : x86 desktop/server focus, moderate feature set, slower boot, medium code complexity, rich x86 ecosystem.

Barebox : embedded lightweight, primarily ARM/RISC‑V, fast boot, low code complexity, smaller ecosystem.

Selection guidance:

Embedded (ARM/RISC‑V): prefer U‑Boot; for ultra‑light, consider Barebox.

x86 desktop/server: choose GRUB.

Requirements such as secure boot, multiple storage, network: U‑Boot is mandatory.

Fast start, minimal footprint: Barebox.