Build U-Boot for NXP i.MX 6/6ULL/7-based SoMs

Introduction

This article guides you on how to build from source and deploy U-Boot for Toradex's NXP i.MX6/6ULL/7-based System on Modules (SoMs), with either eMMC or NAND memory.

Install Tools and Dependencies

Run the command below to install the dependencies necessary to build U-Boot from source:

$ sudo apt-get install bc build-essential git wget libncurses5-dev lzop perl libssl-dev bison flex swig libyaml-dev pkg-config python3-dev python3-venv xz-utils xxd device-tree-compiler u-boot-tools

Prepare the Environment for Cross-Compilation

info

You can use versions 9.2 or higher of the Arm releases binary toolchains to cross-compile software for Toradex modules. The instructions below reference version 12.3, which is the version used in Toradex build environments.

To install the toolchain on your host machine, download and unpack the .tar.xz file with the command below. Alternatively, you can obtain the toolchain directly from the Arm website.

$ cd ~
$ wget -O arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-linux-gnueabihf.tar.xz "https://developer.arm.com/-/media/Files/downloads/gnu/12.3.rel1/binrel/arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-linux-gnueabihf.tar.xz?rev=9d73bfdd64a34550b9ec38a5ead7c01a&hash=774AAE1A6D6996CFB89FD7E367C0B59B"
$ tar xvf arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-linux-gnueabihf.tar.xz && rm arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-linux-gnueabihf.tar.xz
$ ln -s arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-linux-gnueabihf gcc-linaro-arm

U-Boot and Linux Makefiles use environment variables such as ARCH and CROSS_COMPILE to configure and call the appropriate compiler. Therefore, you must set these variables in the current shell when compiling the Kernel or U-Boot.

To facilitate this process, create an export-compiler-32 setup file with the commands below.

export-compiler-32

export ARCH=arm
export PATH=${HOME}/gcc-linaro-arm/bin/:${PATH}
export DTC_FLAGS='-@'
export CROSS_COMPILE=arm-none-linux-gnueabihf-

tip

Please note that creating the setup file is not mandatory, it serves only to simplify executing the commands above. You could also run each command individually on every new shell, or create a different environment setup file during the build process.

Then, source the setup file using the command below. Note that you will also need to source it every time you open a new shell to build the Kernel/U-Boot.

$ source ~/export-compiler-32

Get the Sources

Create a directory to store the build files and repositories:

$ mkdir -p ~/workdir
$ cd ~/workdir

Get the U-Boot source code: For the i.MX 6/6ULL/7 based modules, clone U-Boot from the Upstream source. Choose the <u-boot-git-branch> according to the table below.

$ git clone -b <u-boot-git-branch> https://gitlab.com/u-boot/u-boot.git

SoC	U-Boot Git Branch	U-Boot Configuration	U-Boot Binary
i.MX 7	v2024.07	colibri_imx7_defconfig colibri_imx7_emmc_defconfig	u-boot-nand.imx u-boot.imx
i.MX 6	v2024.07	apalis_imx6_defconfig colibri_imx6_defconfig	u-boot.img
i.MX 6ULL	v2024.07	colibri-imx6ull_defconfig colibri-imx6ull-emmc_defconfig	u-boot-nand.imx u-boot.imx

Apply Required Patches

1. Create a branch based on the <u-boot-git-branch>, and create a patches directory to store the patches you are going to apply.

   $ cd u-boot
   $ 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 (<meta-toradex-bsp-common-hash>) and copy the patches to the U-Boot patches directory. You can check the <meta-toradex-bsp-common-hash> for your BSP version on the table below.

   BSP Version	Hash
   7.5.0	3fead3b1e2dcf83e086647b4f0e4185a94f12f11
   7.4.0	c884e6b86563a011f43959c23eda075828f7d75d
   7.3.0	95c85e1a570732a4680a5b7a720bb691741b78b7

   $ 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 ~/workdir/u-boot/patches

3. Apply the patches with the commands below. You must apply the patches in the same order as the TDX_PATCHES variable from the Toradex U-Boot Upstream Recipe.

   $ cd ~/u-boot/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 \
   

   Check if the patches were applied using the command below. You should see the commit messages for each applied patch.

   $ git log --oneline

Build U-Boot

The i.MX 6/6ULL/7-based modules use the upstream U-Boot source tree. Therefore, you should follow the procedures described in the official U-Boot documentation.

When following these instructions, make sure to select the appropriate _defconfig for your specific module, as indicated in the previous table.

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 appropriate image for your SoM.

2. Integrate artifacts: Replace the bootloader binary by the one you built. You can find the name of the u-boot binary in the content/rawfiles/filename field of the image.json file. The following snippet shows, as an example, the image.json file for the Verdin iMX8M Plus.

   image.json

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

3. Adjust image.json: If you change the name of the U-Boot binary, change the name of the content/rawfiles/filename field on image.json

4. Deploy the Toradex Easy Installer image: Deploy the modified Toradex Easy Installer package with Toradex Easy Installer.