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​

The required git branch and Linux binaries to be used depend on the module type and BSP version, as we will explain in this article. For a BSP Versions overview, refer to the Embedded Linux Release Matrix.

Prepare the Environment for Cross-Compilation​

Install the GCC toolchain for bare-metal targets on your host machine. It's recommended to use 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 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 are known 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 prevent DTC from treating warnings as errors, remove the -Werror flag from the CFLAGS variable in the Makefile. Note: The implications of this change have not been fully evaluated. Proceed with caution.

  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 SourceU-Boot Git BranchU-Boot ConfigurationU-Boot Binary
TI AM69Downstreamtoradex_ti-u-boot-2024.04aquila-am69_a72_defconfig
aquila-am69_r5_defconfig		u-boot.img
tispl.bin
tiboot3-am69-hs-fs-aquila.bin
TI AM62xDownstreamtoradex_ti-u-boot-2024.04verdin-am62_a53_defconfig
verdin-am62_r5_defconfig		u-boot.img
tispl.bin
tiboot3-am62x-hs-fs-verdin.bin
i.MX 8MM/8MPUpstreamv2024.07verdin-imx8mm_defconfig
verdin-imx8mp_defconfig		imx-boot
i.MX 8/8XDownstreamtoradex_imx_lf_v2024.04apalis-imx8_defconfig
colibri-imx8x_defconfig		imx-boot
i.MX 7Upstreamv2024.07colibri_imx7_defconfig
colibri_imx7_emmc_defconfig		u-boot-nand.imx
u-boot.imx
i.MX 6Upstreamv2024.07apalis_imx6_defconfig
colibri_imx6_defconfig		u-boot.img
i.MX 6ULLUpstreamv2024.07colibri-imx6ull_defconfig
colibri-imx6ull-emmc_defconfig		u-boot-nand.imx
u-boot.imx

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
7.1.09ddc957972a0375d283e3871769bce48156d0d29
7.2.0354aebd1796c4ad5eaeee52b8dc768fcc2dad32d

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​

Clone the U-Boot source code using Git:

$ mkdir -p ~/workdir
$ cd ~/workdir
$ git clone https://gitlab.com/u-boot/u-boot.git

Once inside the root folder of your local copy of the U-Boot repository, checkout to the required <branch> according to the U-Boot Git Branch for your specific configuration. Check the section U-boot Version for this specific information.

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. Create a branch based on the <branch> you just checked out. Also, create a patches directory to store the patches you are going to fetch.

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

  2. Clone the meta-toradex-bsp-common repository, which contains recipes common to all modules. Checkout to the BSP release commit hash and copy the patches to the 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 recipes-bsp/u-boot/u-boot-toradex/*.patch ../u-boot/patches

  3. Apply the patches with git am <patch files> from within the 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 below:

  1. Start from an 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.
  1. Integrate artifacts: Integrate the U-Boot artifacts into the standard Toradex Easy Installer package by replacing the bootloader binaries listed in the U-Boot Version Information table with the ones you have built.

  1. Adjust image.json: When building U-Boot manually, the binaries' names might differ from the U-Boot Version Information table. Therefore, adjust the image.json file accordingly, ensuring the bootloader binaries are being loaded correctly. For example, the following snippet shows the configuration for the Verdin iMX8M Plus:

    image.json
    "name": "mmcblk0boot0",
    "erase": true,
    "content": {
        "filesystem_type": "raw",
        "rawfiles": [
            {
                "filename": "u-boot.imx",
                "dd_options": "seek=2"
            }
        ]
    }

    For more information about the available customizations, see the Toradex Easy Installer documentation.

  1. Deploy the Toradex Easy Installer image: You may now use the above prepared Toradex Easy Installer package with the Toradex Easy Installer.


Send Feedback!