Skip to main content
Version: BSP 7.x.y

Build U-Boot From Source Code

Introduction​

This series of articles describes how to build the U-Boot without using a higher-level build system such as the Yocto Project/OpenEmbedded. This procedure mostly makes sense during bootloader development.

We provide OpenEmbedded recipes that build U-Boot and Linux as part of a complete BSP image. If you plan to build a full BSP image, follow the Build a Reference Image with Yocto Project/OpenEmbedded article.

This is an overview article of the necessary process for building the bootloader from source code. If you are looking for specific information regarding module- or SoC-specific instructions, check the Additional Module-specific Steps section.

Prerequisites​

Check out our Embedded Linux Release Matrix for a high-level overview of the BSP Versions. There you will find the version information of the Linux kernel, U-Boot, Yocto/OpenEmbedded, the Toradex BSP, and Linux images, along with release dates.

Prepare the Environment for Cross Compilation​

Install the GCC toolchain for bare-metal targets on your host machine. It's recommended to use the version 9.2 or higher of the ARM GNU Toolchain to cross-compile software for Toradex modules.

From the command line:

  1. Download and unpack the the 32-bit and/or 64-bit Arm cross-toolchain files:

    $ wget -O arm-gnu-toolchain-12.3.rel1-x86_64-aarch64-none-linux-gnu.tar.xz "https://developer.arm.com/-/media/Files/downloads/gnu/12.3.rel1/binrel/arm-gnu-toolchain-12.3.rel1-x86_64-aarch64-none-linux-gnu.tar.xz?rev=cf8baa0ef2e54e9286f0409cdda4f66c&hash=4E1BA6BFC2C09EA04DBD36C393C9DD3A"
    $ tar xvf arm-gnu-toolchain-12.3.rel1-x86_64-aarch64-none-linux-gnu.tar.xz

  2. Set the toolchain path:

    $ ln -s arm-gnu-toolchain-12.3.rel1-x86_64-aarch64-none-linux-gnu gcc-linaro-aarch64

  3. Prepare the environment variables:

    $ export ARCH=arm64
    $ export DTC_FLAGS="-@"
    $ export PATH=~/gcc-linaro-aarch64/bin/:$PATH
    $ export CROSS_COMPILE=aarch64-none-linux-gnu-

Install Tools and Dependencies​

  1. Install Bison, Flex, Swig and OpenSSL and other dependencies: The Bison, Flex and Swig packages are necessary to configure U-Boot from a defconfig and to build the device tree compiler, while the OpenSSL development package is used in the U-Boot compilation. Other dependencies listed are also necessary to complete the build process:

    $ sudo apt-get install bc build-essential git libncurses5-dev lzop perl libssl-dev bison flex swig libyaml-dev pkg-config python3-dev
    info

    Those dependencies are based on tests made for Ubuntu/Debian environments. Other distributions may have different dependencies.

  2. Install the Device Tree Compiler (DTC) Tool: U-Boot and the device tree overlays compilation for some modules need a device tree compiler (DTC). We recommend DTC version 1.6.0 or higher.

    $ git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git -b v1.6.0 ~/dtc
    $ cd ~/dtc
    $ make
    $ export PATH=$HOME/dtc/:$PATH
    info

    On Ubuntu 22.04, there have been reported DTC build errors libfdt/libfdt.h:251:28: warning: array subscript ‘struct fdt_header[0]’ is partly outside array bounds of ‘unsigned char[4]’ [-Warray-bounds].

    To disable treating warnings as errors, you can remove the flag -Werror from the CFLAGS on the Makefile.
    We have not evaluated the consequences of doing it, do it at your own risk!

  3. Install U-Boot Tools: The uImage target of the Linux kernel compilation needs a recent mkimage tool.

    $ sudo apt-get install u-boot-tools

    Alternatively, mkimage tool is also built during the U-Boot compilation. You can follow the U-Boot building instructions as explained further in this article, and after that, include it in PATH.

U-Boot Version Information​

The required git branch, U-Boot configuration, and U-Boot/Linux binaries to be used depend on the module type and the BSP version, as we will explain in this article.

SoCU-Boot Git BranchU-Boot ConfigurationU-Boot Binary
i.MX 8/8X/8MM/8MPtoradex_imx_lf_v2024.04apalis-imx8_defconfig
colibri-imx8x_defconfig
verdin-imx8mm_defconfig
verdin-imx8mp_defconfig		imx-boot
i.MX 7v2024.07colibri_imx7_defconfig
colibri_imx7_emmc_defconfig		u-boot-nand.imx
u-boot-dtb.imx
i.MX 6v2024.07apalis_imx6_defconfig
colibri_imx6_defconfig		u-boot.img
i.MX 6ULLv2024.07colibri-imx6ull_defconfig
colibri-imx6ull-emmc_defconfig		u-boot-nand.imx
u-boot.imx
TI AM62xtoradex_ti-u-boot-2024.04verdin-am62_a53_defconfig
verdin-am62_r5_defconfig		u-boot.img
tispl.bin
tiboot3-am62x-hs-fs-verdin.bin
TI AM69toradex_ti-u-boot-2024.04aquila-am69_a72_defconfig
aquila-am69_r5_defconfig		u-boot.img
tispl.bin
tiboot3-am69-hs-fs-aquila.bin

In the case of TI AM62x-based and AM69-based modules, both defconfig configurations are used.

The meta-toradex-bsp-common hashes for each BSP version to be used in the following steps are presented in the table below:

BSP VersionHash
7.0.06cdf564762805ec382409a2ba23d33bcde5bec9f

Building U-Boot​

In the following instructions, you will be directed to create a directory called ~/workdir to store all the source and build files. You can, of course, replace this directory name with any other name you prefer.

Fetch U-Boot Sources​

Obtain the U-Boot source code using Git. For upstream-based modules (i.e. NXP i.MX 6/6 ULL and 7) U-Boot is fetched from https://gitlab.com/u-boot/u-boot.git. For downstream-based modules (NXP i.MX 8/8X/8MM/8MP and TI AM62x/AM69), U-Boot is fetched from https://git.toradex.com/u-boot-toradex.git.

$ mkdir -p ~/workdir
$ cd ~/workdir
$ git clone https://source.denx.de/u-boot/u-boot
caution

The following section is only necessary if using an upstream-based module. If you are using a downstream-based module, please, go to the Configure U-Boot section.

Get and Apply the Necessary Patches (Upstream Only)​

  1. Once inside the root folder of you local copy of U-Boot repository, checkout to the <branch> according to the U-Boot Git Branch for your specific configuration. Check the section U-boot Version for this specific information. Then create a branch based on the <branch> to just checked out. Also create a patches directory to store the patches you will fetch.

    $ cd u-boot
    $ git checkout <branch>
    $ git checkout -b toradex-<branch>
    $ mkdir patches
    $ cd patches

  2. Get the patches from Toradex git in the BSP Common OE layer at meta-toradex-bsp-common.git - recipes common to all modules. The patches for U-boot are located inside the folder meta-toradex-bsp-common/recipes-bsp/u-boot/u-boot-toradex. Fetch the layer with git and checkout it to the hash of the BSP release version and then copy the patches to U-Boot patches directory.

    $ cd ~/workdir
    $ git clone https://git.toradex.com/cgit/meta-toradex-bsp-common.git
    $ cd meta-toradex-bsp-common
    $ git checkout <meta-toradex-bsp-common-hash>
    $ cp -r ../meta-toradex-bsp-common/recipes-bsp/u-boot/u-boot-toradex/*.patch ../u-boot/patches

  3. Apply the patches with git am <patch files> from patches directory. The patches must be applied in the correct order (check the TDX_PATCHES variable on this recipe) and the application should be clean (without any errors or conflicts).

    Note that you can apply multiple patches in a single command (keeping the correct order), as in the following example:

    $ cd ~/linux/patches

    $ git am [first-patch-file-name].patch \
    [second-patch-file-name].patch \
    [third-patch-file-name].patch \
    [fourth-patch-file-name].patch \
    [fifth-patch-file-name].patch \

    For a double check, use git log --oneline to see the patches commit messages.

    $ git log --oneline

Configure U-Boot​

  1. Find the right configuration file at the U-Boot Version Information table.

  2. Go to the u-boot directory and use make mrproper for a clean configuration. Then, execute make <board_defconfig> (check the board_defconfig in the table of the section U-boot Version Information) to configure U-boot from a defconfig:

    $ cd ~/workdir/u-boot
    $ make mrproper
    $ make <board_defconfig>

Compile U-Boot​

After the configuration process, the sources of U-Boot are ready to be built.

$ make -j$(nproc) 2>&1 | tee build.log

Additional Module-specific Steps​

The following articles contain mandatory specific steps for a full bootloader build and configuration:

Deploy the U-Boot binary to an Image​

To deploy your custom U-Boot binary to an image, follow the steps described bellow:

  1. Start from a Existing Sample Image: Download and extract one of the Toradex prebuilt images. Choose the appropriate image for your SoM in the Reference Images for Yocto Project Software Downloads
  2. Integrate Artifacts: Integrate the U-Boot artifacts into our regular Toradex Easy Installer package by replacing the U-Boot binary (according to the U-Boot Version Information) and, if applicable, the SPL in the unpacked Toradex prebuilt image downloaded above.
  3. Adjust Image.json: Now, adjust the image.json to your liking (e.g., change the name and description to distinguish it from the original package). You may, of course, also change any of the other properties as documented in the Toradex Easy Installer article on our developer website.
  4. Deploy the Toradex Easy Installer Image: You may now use the above prepared Toradex Easy Installer package with the Toradex Easy Installer.


Send Feedback!