From Gentoo Wiki
Jump to:navigation Jump to:search

DISCLAIMER: This is an in-progress article about a package that is not yet in the ::gentoo repository

U-Boot is a bootloader commonly used on arm and arm64 platforms


Since U-Boot has a vast array of configuration possibilities, similar to the linux kernel (and using the same build system), U-Boot is installed as a source package in /usr/src/


Most armv8 platforms run the TF-A open source platform hypervisor, which is normally built into U-Boot. As such, sys-firmware/trusted-firmware-a-bin is pulled in by default. This is toggled with the tf-a useflag. TODO: implement useflag You can alternatively build sys-firmware-a/trusted-firmware-a yourself, however this may require special toolchains and as such we default to the binary package.


U-Boot uses Kbuild, the same build system as the linux kernel. As such, it can be configured via your preferred flavor of config menu, such as make menuconfig. In most cases, using your platforms defconfig should suffice. More on this below.


If your platform uses TF-A, you need to provide the location in your make arguments. See below.


Flashing U-Boot

On most platforms, U-Boot is not read as a file like on an UEFI system, but directly from the block layer similar to MBR booting. Thus, it must be flashed onto your block device with dd.

This is platform specific, please see below.

Installing the device tree =

Most ARM platforms lack ACPI or any form of autodetecting their hardware layout, instead the hardware is statically described in device trees. To install the device tree, mount your boot partition and run make dtbs && make dtbs_install in your kernel source directory. This device tree gets passed to the kernel by U-Boot. U-Boot uses its own device tree (often taken from the linux source tree) configured at build time. The device trees do not have to match.

Boot configuration

U-Boot can emulate an efi runtime on arm and arm64. If you intend to use U-Boot as an efi runtime, proceed as with a grub-efi installation.

Alternatively U-Boot can read a configuration file named extlinux.conf, similar to how grub reads grub.cfg. In fact, extlinux.conf uses the grub1 syntax. The extlinux.conf file should be placed in /boot/extlinux/extlinux.conf.

TODO: example file


If your platform is not listed, please get in contact with the sys-boot/u-boot package maintainers or file a bug.

Pine 64

  • TF-A: yes
  • U-Boot defconfig: make pine64-lts_defconfig or make pine64_plus_defconfig
  • U-Boot build arguments: make BL31=/usr/share/trusted-firmware-a/sun50i_a64/bl31.elf
  • U-Boot installation: ...


  • TF-A: yes
  • U-Boot defconfig: make rockpro64-rk3399_defconfig
  • U-Boot build arguments: make BL31=/usr/share/trusted-firmware-a/rk3399/bl31.elf
  • U-Boot installation: dd if=idbloader.img of=/dev/... seek=64 conv=notrunc,fsync && dd if=/boot/u-boot.itb of=/dev/... seek=16384 conv=notrunc,fsync

Pinebook Pro

based on the Rockpro64.

  • U-Boot defconfig: make pinebook-pro-rk3399_defconfig

Raspberry Pi 4

  • TF-A: optional
  • U-Boot defconfig: make rpi_4_defconfig
  • U-Boot build arguments: make ...
  • U-Boot installation: ...