Mainline U-Boot User Guide

Overview

This document describes the basic workflow for using mainline U-Boot on Rockchip platforms, including preparing the source code, selecting an existing board configuration, building, checking the output files, and flashing.

Mainline Rockchip U-Boot builds generally use two repositories together:

Preparing the Source Code

2.1 Obtaining the Source Code

It is recommended to place U-Boot and rkbin in the same working directory:

mkdir -p rockchip-mainline
cd rockchip-mainline

git clone https://github.com/u-boot/u-boot.git
git clone https://github.com/rockchip-linux/rkbin.git

Directory structure:

rockchip-mainline/
├── u-boot/
└── rkbin/

For product development, pin the repositories to a verified tag or commit. Following the continuously changing default branch directly in a production build is not recommended.

Check the current versions:

git -C u-boot describe --always --dirty --tags
git -C rkbin describe --always --dirty --tags

2.2 Adding a Board

To add a board, add its corresponding defconfig and device tree.

• Create a configuration for the board under configs/. You can use configs/evb-rk3588_defconfig as the base, add or remove configuration options according to the board's features, and generate a new configuration file such as roc-pc-rk3588s_defconfig.
• Mainline U-Boot 2024.05 enabled the OF_UPSTREAM feature, and many device trees were migrated to dts/upstream/src/arm64/. You no longer need to add the device tree to arch/arm/dts/Makefile. Instead, set the default device tree through CONFIG_DEFAULT_DEVICE_TREE in the defconfig. The device trees under dts/upstream/src/arm64/ are the same as those used by the Kernel, so you can copy the Kernel device tree there for use.

Building

3.1 Toolchain and Python

Install the AArch64 cross-compilation toolchain and basic dependencies. On Debian/Ubuntu, for example:

sudo apt update
sudo apt install \
  build-essential bc bison flex swig python3 python3-dev \
  device-tree-compiler libssl-dev libgnutls28-dev \
  gcc-aarch64-linux-gnu

3.2 Specifying TPL and BL31

Enter the U-Boot source directory:

cd rockchip-mainline/u-boot

Using the RK3588 firmware versions in the PDF as an example:

export ROCKCHIP_TPL=../rkbin/bin/rk35/rk3588_ddr_lp4_2112MHz_lp5_2400MHz_v1.18.bin
export BL31=../rkbin/bin/rk35/rk3588_bl31_v1.48.elf

ROCKCHIP_TPL is the DDR initialization firmware and must match the SoC, DDR type, and board-level design. BL31 is the ARM Trusted Firmware-A stage firmware. The rkbin file names change as versions are updated. If the example files do not exist, select versions matching the hardware from the current rkbin/bin/rk35/ directory:

find ../rkbin/bin/rk35 -maxdepth 1 \
  \( -name 'rk3588_ddr_*.bin' -o -name 'rk3588_bl31_*.elf' \) \
  -print

3.3 Running the Build

First, list the existing RK3588/RK3588S defconfigs in mainline U-Boot:

find configs -maxdepth 1 -name '*rk3588*_defconfig' -printf '%f\n' | sort

Select an existing defconfig that matches the target board. The following example uses the mainline EVB configuration:

export DEFCONFIG=evb-rk3588_defconfig

Clean the old configuration, load the defconfig, and then build:

make mrproper
make "$DEFCONFIG"
make CROSS_COMPILE=aarch64-linux-gnu- -j$(nproc)

Alternatively, export the architecture and toolchain as environment variables:

export ARCH=arm64
export CROSS_COMPILE=aarch64-linux-gnu-

make "$DEFCONFIG"
make -j$(nproc)

Record the version and configuration after the build:

git describe --always --dirty --tags
grep -E 'CONFIG_DEFAULT_DEVICE_TREE|CONFIG_OF_UPSTREAM' .config

TEE Warning

If BL32/OP-TEE is not specified, the following warning may appear near the end of the build:

Image 'simple-bin' is missing optional external blobs but is still functional: tee-os

When tee-os is optional external firmware in the selected configuration, this warning does not prevent U-Boot output files from being generated.

Build Output

Check the output files:

ls -lh idbloader.img u-boot.itb u-boot-rockchip*.bin

If any output file is missing, first check the build log, TPL/BL31 paths, defconfig, and target storage-medium configuration.

Flashing

6.1 SD Card or eMMC

u-boot-rockchip.bin already contains its component firmware at the correct offsets. The write location specified in the PDF starts at the 64th 512-byte sector of the storage device, which is an offset of 32 KiB:

sudo dd \
  if=u-boot-rockchip.bin \
  of=/dev/mmcblk0 \
  bs=32K \
  seek=1 \
  conv=fsync,notrunc \
  status=progress

Warning: dd directly overwrites a block device. of must be the entire target SD/eMMC device, not a file system partition, and it must not be the development host's system disk.

Before writing, it is recommended to run:

lsblk -o NAME,SIZE,MODEL,TYPE,MOUNTPOINTS

Unmount any mounted file systems on the target device before running dd. After writing is complete, run:

sync

6.2 SPI NOR Flash

After enabling the SPI boot configuration and generating u-boot-rockchip-spi.bin, use flashcp to write it to an MTD device:

sudo flashcp -v -p u-boot-rockchip-spi.bin /dev/mtd0

Before writing, confirm the MTD device, capacity, and existing partitions:

cat /proc/mtd
mtdinfo /dev/mtd0

Modifying the SPI boot firmware may prevent the device from booting. Back up the original firmware and prepare a Maskrom/Loader recovery procedure before proceeding.