Skip to main content
Version: BSP 2.8

Build U-Boot and Linux Kernel from Source Code

Introduction​

This article describes how to build the U-Boot boot loader and the Linux kernel without using a higher-level build system such as the Yocto Project/OpenEmbedded. This procedure mostly makes sense during U-Boot or Linux development.

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

You might also need to compile the Linux kernel driver backports. If this is the case, see the specific article Kernel Driver Backports Integration.

The U-Boot bootloader's source code, the Linux kernel, and the device tree overlays are available on our Git server at git.toradex.com.

Version Information​

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

For a high-level overview of the BSP Versions, check out our Embedded Linux Release Matrix. 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.

For the sake of this article, select the appropriate tab below to get a list of Git branches and configuration names.

Kernel Version​

i.MX 8/8X/8MM/8MP Downstream Linux Kernel Versions

BSP VersionKernel Git BranchKernel ConfigurationDevice TreeKernel Binary
5.3.0 - 5.4.0toradex_5.4-2.3.x-imxtoradex_defconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-v1.1-ixora-v1.1.dtb
imx8qp-apalis-v1.1-eval.dtb
imx8qp-apalis-v1.1-ixora-v1.1.dtb
imx8qxp-apalis-eval.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-dsihdmi-eval-v3.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-lvds-dual-eval-v3.dtb
imx8qxp-colibri-lvds-single-eval-v3.dtb
imx8mm-verdin-nonwifi-dahlia.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-wifi-dahlia.dtb
imx8mm-verdin-wifi-dev.dtb
imx8mp-verdin-nonwifi-dahlia.dtb
imx8mp-verdin-nonwifi-dev.dtb
imx8mp-verdin-wifi-dahlia.dtb
imx8mp-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
5.5.0toradex_5.4-2.3.x-imxtoradex_defconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-v1.1-ixora-v1.1.dtb
imx8qm-apalis-v1.1-ixora-v1.2.dtb
imx8qp-apalis-v1.1-eval.dtb
imx8qp-apalis-v1.1-ixora-v1.1.dtb
imx8qp-apalis-v1.1-ixora-v1.2.dtb
imx8dx-colibri-aster.dtb
imx8dx-colibri-eval-v3.dtb
imx8dx-colibri-iris.dtb
imx8dx-colibri-iris-v2.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-iris.dtb
imx8qxp-colibri-iris-v2.dtb
imx8qxp-colibri-lvds-dual-channel.dtb
imx8qxp-colibri-lvds-single-channel.dtb
imx8mm-verdin-nonwifi-dahlia.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-wifi-dahlia.dtb
imx8mm-verdin-wifi-dev.dtb
imx8mp-verdin-nonwifi-dahlia.dtb
imx8mp-verdin-nonwifi-dev.dtb
imx8mp-verdin-wifi-dahlia.dtb
imx8mp-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
View Information of Older Versions
BSP VersionKernel Git BranchKernel ConfigurationDevice TreeKernel Binary
3.0b1 / 3.0b2 / 3.0b3toradex_4.14-2.0.x-imxdefconfigfsl-imx8qm-apalis-eval.dtb
fsl-imx8qm-apalis-ixora-v1.1.dtb
fsl-imx8qxp-apalis-eval.dtb
fsl-imx8qxp-colibri-aster.dtb
fsl-imx8qxp-colibri-dsihdmi-eval-v3.dtb
fsl-imx8qxp-colibri-eval-v3.dtb
fsl-imx8qxp-colibri-lvds-dual-eval-v3.dtb
fsl-imx8qxp-colibri-lvds-single-eval-v3.dtb
fsl-imx8mm-verdin-dev.dtb		arch/arm64/boot/Image
3.0.4 / 4toradex_4.14-2.3.x-imxdefconfigfsl-imx8qm-apalis-eval.dtb
fsl-imx8qm-apalis-v1.1-eval.dtb
fsl-imx8qm-apalis-ixora-v1.1.dtb
fsl-imx8qxp-apalis-eval.dtb
fsl-imx8qxp-colibri-aster.dtb
fsl-imx8qxp-colibri-dsihdmi-eval-v3.dtb
fsl-imx8qxp-colibri-eval-v3.dtb
fsl-imx8qxp-colibri-lvds-dual-eval-v3.dtb
fsl-imx8qxp-colibri-lvds-single-eval-v3.dtb
fsl-imx8mm-verdin-nonwifi-dev.dtb
fsl-imx8mm-verdin-wifi-dev.dtb		arch/arm64/boot/Image
5.0.0toradex_5.4-2.1.x-imxdefconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qxp-apalis-eval.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-dsihdmi-eval-v3.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-lvds-dual-eval-v3.dtb
imx8qxp-colibri-lvds-single-eval-v3.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
5.1.0toradex_5.4-2.1.x-imxdefconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-v1.1-ixora-v1.1.dtb
imx8qp-apalis-v1.1-eval.dtb
imx8qp-apalis-v1.1-ixora-v1.1.dtb
imx8qxp-apalis-eval.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-dsihdmi-eval-v3.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-lvds-dual-eval-v3.dtb
imx8qxp-colibri-lvds-single-eval-v3.dtb
imx8mm-verdin-nonwifi-dahlia.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-nonwifi-v1.1-dahlia.dtb
imx8mm-verdin-nonwifi-v1.1-dev.dtb
imx8mm-verdin-wifi-dahlia.dtb
imx8mm-verdin-wifi-dev.dtb
imx8mm-verdin-wifi-v1.1-dahlia.dtb
imx8mm-verdin-wifi-v1.1-dev.dtb
imx8mp-verdin-nonwifi-dev.dtb
imx8mp-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
5.2.0toradex_5.4-2.3.x-imxtoradex_defconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-v1.1-ixora-v1.1.dtb
imx8qp-apalis-v1.1-eval.dtb
imx8qp-apalis-v1.1-ixora-v1.1.dtb
imx8qxp-apalis-eval.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-dsihdmi-eval-v3.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-lvds-dual-eval-v3.dtb
imx8qxp-colibri-lvds-single-eval-v3.dtb
imx8mm-verdin-nonwifi-dahlia.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-nonwifi-v1.1-dahlia.dtb
imx8mm-verdin-nonwifi-v1.1-dev.dtb
imx8mm-verdin-wifi-dahlia.dtb
imx8mm-verdin-wifi-dev.dtb
imx8mm-verdin-wifi-v1.1-dahlia.dtb
imx8mm-verdin-wifi-v1.1-dev.dtb
imx8mp-verdin-nonwifi-dev.dtb
imx8mp-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
U-Boot Version​

i.MX 8/8X/8MM/8MP U-Boot Versions

BSP VersionU-Boot Git BranchU-Boot ConfigurationU-Boot Binary
3.0b1 / 3.0b2 / 3.0b3toradex_imx_v2018.03_4.14.78_1.0.0_ga-bringupapalis-imx8_defconfig
apalis-imx8x_defconfig
colibri-imx8qxp_defconfig
verdin-imx8mm_defconfig		8/8X: u-boot.bin
8MM: spl/u-boot-spl.bin & u-boot-nodtb.bin & u-boot.dtb
3.0.4 / 4toradex_imx_v2018.03_4.14.98_2.3.0_bringupapalis-imx8_defconfig
apalis-imx8x_defconfig
colibri-imx8qxp_defconfig
verdin-imx8mm_defconfig		8/8X: u-boot.bin
8MM: spl/u-boot-spl.bin & u-boot-nodtb.bin & u-boot.dtb
5.0.0 / 5.1.0toradex_imx_v2020.04_5.4.24_2.1.0apalis-imx8_defconfig
apalis-imx8x_defconfig
colibri-imx8x_defconfig
verdin-imx8mm_defconfig
verdin-imx8mp_defconfig		8/8X: u-boot.bin
8MM/8MP: spl/u-boot-spl.bin & u-boot-nodtb.bin & u-boot.dtb
5.2.0 - 5.4.0toradex_imx_v2020.04_5.4.70_2.3.0apalis-imx8_defconfig
apalis-imx8x_defconfig
colibri-imx8x_defconfig
verdin-imx8mm_defconfig
verdin-imx8mp_defconfig		8/8X: u-boot.bin
8MM/8MP: spl/u-boot-spl.bin & u-boot-nodtb.bin & u-boot.dtb
5.5.0toradex_imx_v2020.04_5.4.70_2.3.0apalis-imx8_defconfig
colibri-imx8x_defconfig
verdin-imx8mm_defconfig
verdin-imx8mp_defconfig		8/8X: u-boot.bin
8MM/8MP: spl/u-boot-spl.bin & u-boot-nodtb.bin & u-boot.dtb
Device Tree Overlays Version​

i.MX 8/8X/8MM/8MP Downstream Device Tree Overlays Versions

BSP VersionDevice Tree Overlays Git BranchDevice Tree Overlays Binaries
4toradex_4.14-2.3.x-imx*.dtbo
5.0.0 / 5.1.0toradex_5.4-2.1.x-imx*.dtbo
5.2.0+toradex_5.4-2.3.x-imx*.dtbo

Prerequisites​

Basic Knowledge​

Make sure you understand the basic concepts of our Embedded Linux offerings, such as release cycles, distributions and images. Start with the following article:

Install the GNU Toolchain for Hard Float Calling Convention​

Select from the tabs below the Embedded Linux BSP release for which you want to install a compatible toolchain:

Beginning with BSP 5, as part of our OpenEmbedded Dunfell update we transitioned to using version 9.3 of the gcc compiler. Arm releases well tested binary toolchains which can be used to cross-compile software for our modules. At the time of this writing, Arm has not released gcc 9.3 compilers as of yet. Therefore, just use the version 9.2 ones for now:

  • For 32 bit Arm: gcc-arm-9.2-2019.12-x86_64-arm-none-linux-gnueabihf.tar.xz
  • For 64 bit Arm: gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu.tar.xz

https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads

You have to choose to download either the 32 bit or 64 bit Arm cross-toolchain, according to the architecture of your Computer on Module SoC. Select the correct one from the tabs below:

To install the toolchain on your host machine, download and unpack the tar.xz file. From the command-line:

$ cd ~
$ wget -O gcc-arm-9.2-2019.12-x86_64-arm-none-linux-gnueabihf.tar.xz "https://developer.arm.com/-/media/Files/downloads/gnu-a/9.2-2019.12/binrel/gcc-arm-9.2-2019.12-x86_64-arm-none-linux-gnueabihf.tar.xz?revision=fed31ee5-2ed7-40c8-9e0e-474299a3c4ac&la=en&hash=76DAF56606E7CB66CC5B5B33D8FB90D9F24C9D20"
$ tar xvf gcc-arm-9.2-2019.12-x86_64-arm-none-linux-gnueabihf.tar.xz
$ ln -s gcc-arm-9.2-2019.12-x86_64-arm-none-linux-gnueabihf gcc-linaro

The U-Boot and Linux makefiles use the environment variables ARCH/CROSS_COMPILE to configure and call the compiler correctly. Therefore, these environment variables must be exported in any shell instance that will run configure/compile commands to build U-Boot or Linux for the target module.

$ export ARCH=arm
$ export DTC_FLAGS="-@"
$ export PATH=~/gcc-linaro/bin/:$PATH
$ export CROSS_COMPILE=arm-none-linux-gnueabihf-

You can put those commands into a file and source that file to export it more easily, E.g.:

$ echo "export ARCH=arm" >> ~/export_compiler
$ echo "export DTC_FLAGS='-@'" >> ~/export_compiler
$ echo "export PATH=~/gcc-linaro/bin/:$PATH" >> ~/export_compiler
$ echo "export CROSS_COMPILE=arm-none-linux-gnueabihf-" >> ~/export_compiler
$ source ~/export_compiler

Other Tools and Dependencies​

Embedded Linux BSP 5​

Build Host Tools and Dependencies​

You need some essential build tools to compile the Kernel or DTC. Most are likely part of your distro's standard install.

For Fedora:

$ sudo dnf install bc gcc git ncurses-devel lzop make perl openssl-devel bison flex diffutils

For Debian/Ubuntu:

$ sudo apt-get install bc build-essential git libncurses5-dev lzop perl libssl-dev bison flex
Device Tree Compiler (DTC) Tool​

U-Boot and the device tree overlays compilation for some modules needs a device tree compiler (DTC). We recommend DTC version 1.6.0 or higher.

You can build the latest version (DTC 1.6.0 at the time of writing) from the source:

$ 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 Fedora and 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 errors as warnings, 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!

U-Boot Tools​

The uImage target of the Linux kernel compilation needs a recent mkimage tool.

One can install the Fedora package uboot-tools:

$ sudo dnf install uboot-tools

Or with the corresponding Debian/Ubuntu package u-boot-tools:

$ 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.

Building U-Boot​

info

In the following instructions, we will 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.

Source​

Obtain the U-Boot source code using Git:

$ mkdir -p ~/workdir
$ cd ~/workdir
$ git clone -b <branch> git://git.toradex.com/u-boot-toradex.git

Important: Replace <branch> by the U-Boot Git Branch for your specific configuration. Click below to expand the version information.

View U-Boot Git Branch information

i.MX 8/8X/8MM/8MP U-Boot Versions

BSP VersionU-Boot Git BranchU-Boot ConfigurationU-Boot Binary
3.0b1 / 3.0b2 / 3.0b3toradex_imx_v2018.03_4.14.78_1.0.0_ga-bringupapalis-imx8_defconfig
apalis-imx8x_defconfig
colibri-imx8qxp_defconfig
verdin-imx8mm_defconfig		8/8X: u-boot.bin
8MM: spl/u-boot-spl.bin & u-boot-nodtb.bin & u-boot.dtb
3.0.4 / 4toradex_imx_v2018.03_4.14.98_2.3.0_bringupapalis-imx8_defconfig
apalis-imx8x_defconfig
colibri-imx8qxp_defconfig
verdin-imx8mm_defconfig		8/8X: u-boot.bin
8MM: spl/u-boot-spl.bin & u-boot-nodtb.bin & u-boot.dtb
5.0.0 / 5.1.0toradex_imx_v2020.04_5.4.24_2.1.0apalis-imx8_defconfig
apalis-imx8x_defconfig
colibri-imx8x_defconfig
verdin-imx8mm_defconfig
verdin-imx8mp_defconfig		8/8X: u-boot.bin
8MM/8MP: spl/u-boot-spl.bin & u-boot-nodtb.bin & u-boot.dtb
5.2.0 - 5.4.0toradex_imx_v2020.04_5.4.70_2.3.0apalis-imx8_defconfig
apalis-imx8x_defconfig
colibri-imx8x_defconfig
verdin-imx8mm_defconfig
verdin-imx8mp_defconfig		8/8X: u-boot.bin
8MM/8MP: spl/u-boot-spl.bin & u-boot-nodtb.bin & u-boot.dtb
5.5.0toradex_imx_v2020.04_5.4.70_2.3.0apalis-imx8_defconfig
colibri-imx8x_defconfig
verdin-imx8mm_defconfig
verdin-imx8mp_defconfig		8/8X: u-boot.bin
8MM/8MP: spl/u-boot-spl.bin & u-boot-nodtb.bin & u-boot.dtb
info

Should your company firewall/gateway inhibit the git protocol, you may use HTTP or HTTPS instead (e.g. git clone https://git.toradex.com/u-boot-toradex.git).

Configuration​

Ensure the environment is configured for cross-compilation as explained in the toolchain chapter. Then choose one of those configurations and load it:

$ cd ~/workdir/u-boot-toradex
$ make <config>

Important: Replace <config> by the U-Boot Configuration for your specific configuration. Click below to expand the version information.

View U-Boot Configuration information

i.MX 8/8X/8MM/8MP U-Boot Versions

BSP VersionU-Boot Git BranchU-Boot ConfigurationU-Boot Binary
3.0b1 / 3.0b2 / 3.0b3toradex_imx_v2018.03_4.14.78_1.0.0_ga-bringupapalis-imx8_defconfig
apalis-imx8x_defconfig
colibri-imx8qxp_defconfig
verdin-imx8mm_defconfig		8/8X: u-boot.bin
8MM: spl/u-boot-spl.bin & u-boot-nodtb.bin & u-boot.dtb
3.0.4 / 4toradex_imx_v2018.03_4.14.98_2.3.0_bringupapalis-imx8_defconfig
apalis-imx8x_defconfig
colibri-imx8qxp_defconfig
verdin-imx8mm_defconfig		8/8X: u-boot.bin
8MM: spl/u-boot-spl.bin & u-boot-nodtb.bin & u-boot.dtb
5.0.0 / 5.1.0toradex_imx_v2020.04_5.4.24_2.1.0apalis-imx8_defconfig
apalis-imx8x_defconfig
colibri-imx8x_defconfig
verdin-imx8mm_defconfig
verdin-imx8mp_defconfig		8/8X: u-boot.bin
8MM/8MP: spl/u-boot-spl.bin & u-boot-nodtb.bin & u-boot.dtb
5.2.0 - 5.4.0toradex_imx_v2020.04_5.4.70_2.3.0apalis-imx8_defconfig
apalis-imx8x_defconfig
colibri-imx8x_defconfig
verdin-imx8mm_defconfig
verdin-imx8mp_defconfig		8/8X: u-boot.bin
8MM/8MP: spl/u-boot-spl.bin & u-boot-nodtb.bin & u-boot.dtb
5.5.0toradex_imx_v2020.04_5.4.70_2.3.0apalis-imx8_defconfig
colibri-imx8x_defconfig
verdin-imx8mm_defconfig
verdin-imx8mp_defconfig		8/8X: u-boot.bin
8MM/8MP: spl/u-boot-spl.bin & u-boot-nodtb.bin & u-boot.dtb

Compilation​

The following is the procedure to compile the boot loader.

$ make -j$(nproc) 2>&1 | tee build.log
$ ls u-boot.bin
info

Starting with BSP 3, we use U-Boot based on 2019.07 which changed certain make targets to include -dtb in their names. If you need backward compatibility with older BSPs, make sure you explicitly state the make target e.g., as follows: make u-boot.imx. Otherwise, the new target named u-boot-dtb.imx will be built. However, the two are equal apart from their name.

The resulting U-boot binary will be a file with the name u-boot.bin.

U-Boot Compilation Troubleshoot​

Click below to see info for U-Boot some common issues when building U-Boot.

Cannot find -lgcc

When using the cross compiler built by an OpenEmbedded build of our BSP V2.5 or later, the compiler might have an error during linking

arm-angstrom-linux-gnueabi-ld.bfd: cannot find -lgcc
make[2]: *** [examples/standalone/hello_world] Error 1
make[1]: *** [examples/standalone] Error 2
make: *** [examples] Error 2

The new cross compiler does not have a hard-coded default sysroot and hence needs the sysroot to be specified explicitly:

$ make CC='arm-angstrom-linux-gnueabi-gcc --sysroot=${HOME}/oe-core/build/out-glibc/sysroots/colibri-vf'

U-Boot: Standalone Application​

info

If you don't know if you need to read this, you will not need to read this.

U-Boot allows one to run standalone applications which may use callbacks into the U-Boot binary. One has to overcome some obstacles to get the hello_world example in the U-Boot sources up and running on an Arm-based CPU.

Details

1) The binary needs to be linked to an address where it eventually gets loaded and executed. I.e., set CONFIG_STANDALONE_LOAD_ADDR to your chosen address.

2) U-Boot and the standalone application must be compiled for the same ARM instruction set (arm vs. thumb) if you build both binaries from the same configured U-Boot tree that is inherently so.

3) If the binaries are built for thumb then one has to set the LSB in the address given to the go command. E.g. if the entry point is 0x12000000, then one has to start with 'go 12000001'.

Example for Colibri iMX6:

Link the standalone binary to 0x11000000 and build it as follows:

$ make CONFIG_STANDALONE_LOAD_ADDR=0x11000000 -j$(nproc)

Copy the resulting binary file to an SD card

$ cp examples/standalone/hello_world.bin <path to SD card>/

In U-Boot, load the binary to RAM and execute it. Note that for some time, we compile using the thumb instruction set.

Colibri iMX6 # load mmc 1:1 0x11000000 hello_world.bin
reading hello_world.bin
578 bytes read in 14 ms (40 KiB/s)
Colibri iMX6 # go 0x11000001 Hello World!
## Starting application at 0x11000001 ...
Example expects ABI version 9
Actual U-Boot ABI version 9
Hello World
argc = 3
argv[0] = "0x11000001"
argv[1] = "Hello"
argv[2] = "World!"
argv[3] = "<NULL>"
Hit any key to exit ...

## Application terminated, rc = 0x0
Colibri iMX6 #

Additional Mandatory Steps for Specific SoCs​

Some SoCs will require additional steps to build the components necessary for the boot. If you are targetting a different SoC, you can skip this session.

The NXP i.MX 8QuadMax / i.MX 8QuadXPlus SoC boot process is a bit more involved than the typical SoC used by Toradex and it requires a boot container. This section describes how to build the boot container (including required integration of firmware and boot loader) manually. The boot container is built with the Yocto recipe imx-boot. Nevertheless, if you want to build it manually, this section provides information on how to do it.

Please open this section to get information on how to create the boot container for i.MX 8 and i.MX 8X based modules:

Boot Container i.MX 8/8X

The NXP i.MX 8QuadMax / i.MX 8QuadXPlus boots using a Cortex-M4 boot CPU called System Controller Unit (SCU). The SCU firmware (SCFW) is in large part provided by NXP, but Toradex has slightly altered it for the Apalis iMX8/Apalis iMX8X and Colibri iMX8X. The firmware also loads an intermediate firmware running on the Cortex-A class CPUs: The ARM trusted firmware (ATF). The ARM trusted firmware then hands over control to U-Boot, which then can boot Linux.

To learn more about SCFW, see the Build Custom i.MX 8/8X System Controller Firmware (SCFW) article.

The DDR memory timings, the SCU firmware, the ATF and U-Boot, and any potential Cortex-M4 auxiliary firmware are all stored in a single boot container. This boot container is read by the boot ROM from the boot device, starting at a specific offset (33kB for V1.0A modules booting from SD cards).

Obtain the Security Controller (SECO) Firmware​

BSP VersionNXP BSP VersionNXP Firmware File NameNXP Firmware Path
L4.14.78_1.0.0_gafirmware-imx-8.0.binfirmware-imx-8.0/firmware/seco/mx8qm-ahab-container.img
firmware-imx-8.0/firmware/seco/mx8qx-ahab-container.img
3 / 4L4.14.98_2.3.0imx-seco-2.5.6.binimx-seco-2.5.6/firmware/seco/mx8qmb0-ahab-container.img
imx-seco-2.5.6/firmware/seco/mx8qxb0-ahab-container.img
imx-seco-2.5.6/firmware/seco/mx8qxc0-ahab-container.img
5.0.0 / 5.1.0L5.4.24_2.1.0imx-seco-3.6.3.binimx-seco-3.6.3/firmware/seco/mx8qmb0-ahab-container.img
imx-seco-3.6.3/firmware/seco/mx8qxb0-ahab-container.img
imx-seco-3.6.3/firmware/seco/mx8qxc0-ahab-container.img
5.2.0L5.4.70_2.3.0imx-seco-3.7.4.binimx-seco-3.7.4/firmware/seco/mx8qmb0-ahab-container.img
imx-seco-3.7.4/firmware/seco/mx8qxb0-ahab-container.img
imx-seco-3.7.4/firmware/seco/mx8qxc0-ahab-container.img
5.3.0L5.4.70_2.3.3imx-seco-3.8.1.binimx-seco-3.8.1/firmware/seco/mx8qmb0-ahab-container.img
imx-seco-3.8.1/firmware/seco/mx8qxb0-ahab-container.img
imx-seco-3.8.1/firmware/seco/mx8qxc0-ahab-container.img

E.g. use wget for download, and extract the firmware, for example:

$ cd ~/workdir
$ wget -c https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/imx-seco-3.7.4.bin
$ chmod u+x imx-seco-3.7.4.bin
$ ./imx-seco-3.7.4.bin
$ ls imx-seco-3.7.4/firmware/seco/
info

NXP provides the SECO firmware in binary form. You will need to accept the NXP End-User License Agreement (EULA) as part of the unpacking process.

The table below indicates the corresponding SECO Firmware File for each SoM:

Module VersionSECO Firmware File
Apalis iMX8mx8qmb0-ahab-container.img
Apalis iMX8X V1.1A and earliermx8qxb0-ahab-container.img
Apalis iMX8X V1.1B and latermx8qxc0-ahab-container.img
Colibri iMX8X V1.0B and earliermx8qxb0-ahab-container.img
Colibri iMX8X V1.0C and latermx8qxc0-ahab-container.img

Build the SCU Firmware (SCFW)​

The SCU firmwares for Apalis iMX8/Apalis iMX8X and Colibri iMX8X are available in our i.MX-System-Controller-Firmware GitHub repository.

BSP VersionNXP BSP VersionSCFW VersionSCFW Version Hash**Git HashCompatible ModulesSCFW Download
3L4.14.98_2.3.01.3.1b929edfe1bd54a5Apalis iMX8*mx8qm-apalis-scfw-tcm.bin
Apalis iMX8X*mx8qx-apalis-scfw-tcm.bin
Colibri iMX8X*mx8qx-colibri-scfw-tcm.bin
4L4.14.98_2.3.01.3.1b929edfeacfaf18Apalis iMX8mx8qm-apalis-scfw-tcm.bin
Apalis iMX8Xmx8qx-apalis-scfw-tcm.bin
Colibri iMX8Xmx8qx-colibri-scfw-tcm.bin
5.0.0 / 5.1.0L5.4.24_2.1.01.5.1732e719a1f184f1Apalis iMX8mx8qm-apalis-scfw-tcm.bin
Apalis iMX8Xmx8qx-apalis-scfw-tcm.bin
Colibri iMX8Xmx8qx-colibri-scfw-tcm.bin
5.2.0L5.4.70_2.3.01.7.00d54291f60d8c94Apalis iMX8mx8qm-apalis-scfw-tcm.bin
Apalis iMX8Xmx8qx-apalis-scfw-tcm.bin
Colibri iMX8Xmx8qx-colibri-scfw-tcm.bin
5.3.0L5.4.70_2.3.31.7.3bc122ee164fd890Apalis iMX8mx8qm-apalis-scfw-tcm.bin
Apalis iMX8Xmx8qx-apalis-scfw-tcm.bin
Colibri iMX8Xmx8qx-colibri-scfw-tcm.bin

* Not all module versions may support all SCFW versions.

** The SCFW Version Hash is the git-hash NXP used in their git-repository. U-Boot prints this hash when it starts and can be used to identify the SCFW version.

info

Toradex customers rarely need to rebuild SCFW. Therefore, in the following instructions, we will show how you can download the SCFW firmware. If you, for any reason, need to customize SCFW, see the Build Custom i.MX 8/8X System Controller Firmware (SCFW) article.

Use wget to download SCFW binary and rename it to scfw_tcm.bin:

$ mkdir -p ~/workdir/scfw-bin
$ cd ~/workdir/scfw-bin
$ wget https://github.com/toradex/i.MX-System-Controller-Firmware/raw/60d8c942f49012b6620f34800e2e9f11e45a9ef5/src/scfw_export_mx8qm_b0/build_mx8qm_b0/mx8qm-apalis-scfw-tcm.bin
$ mv mx8qm-apalis-scfw-tcm.bin scfw_tcm.bin

The relevant file renamed to scfw_tcm.bin is necessary for the final container.

Build the ARM Trusted Firmware (ATF)​

ModuleATF BranchPlatformBinary File
Apalis iMX8toradex_imx_5.4.70_2.3.0imx8qmbuild/imx8qm/release/bl31.bin
Apalis iMX8Xtoradex_imx_5.4.70_2.3.0imx8qxbuild/imx8qx/release/bl31.bin
Colibri iMX8Xtoradex_imx_5.4.70_2.3.0imx8qxbuild/imx8qx/release/bl31.bin

ATF can be obtained from our git servers, we have a few patches on top that are needed for our hardware:

$ cd ~/workdir
$ git clone git://git.toradex.com/imx-atf.git -b <ATF Branch>

Important: Replace <ATF Branch> by the ATF Branch for your specific configuration as indicated in the above table.

info

Should your company firewall/gateway inhibit the git protocol, you may use HTTP or HTTPS instead (e.g. git clone https://git.toradex.com/imx-atf.git).

Currently, there are no changes necessary for ARM Trusted Firmware. To be able to build the ATF firmware, first you'll need to download and setup the GNU Toolchain for Hard Float Calling Convention. When the toolchain is installed and you have the CROSS_COMPILE, ARCH and PATH correctly pointing to it, you can proceed to build the firmware directly:

$ cd imx-atf
$ make PLAT=<Platform> bl31

Important: Replace <Platform> by the Platform for your specific configuration as indicated in the above table.

The resulting binary file bl31.bin created in build/<Platform>/release/ is necessary for the final container.

Assemble the Boot Container​

Finally, to assembly the boot container, you need to obtain the imx-mkimage utility.

BSP releaseBranch
5.0.0 / 5.1.0imx_5.4.24_2.1.0
5.2 and laterimx_5.4.70_2.3.0

Git clone it from the repository:

$ cd ~/workdir
$ git clone -b <Branch> https://source.codeaurora.org/external/imx/imx-mkimage/

Important: Replace <Branch> by the Branch for your specific configuration as indicated in the above table.

Then, copy all binaries SCU Firmware, ARM Trusted Firmware, U-Boot, and the SECO Firmware to the corresponding SoC directories inside imx-mkimage.

caution

The binary u-boot.bin is necessary for the final boot container. Make sure you followed the previous instructions on how to build U-Boot.

Finally, use make to build the boot container.

$ cd ~/workdir/imx-mkimage/
$ cp ~/workdir/scfw-bin/scfw_tcm.bin iMX8QM
$ cp ~/workdir/imx-atf/build/imx8qm/release/bl31.bin iMX8QM
$ cp ~/workdir/u-boot-toradex/u-boot.bin iMX8QM
$ cp ~/workdir/imx-seco-3.7.4/firmware/seco/<SECO Firmware File> iMX8QM
$ make SOC=iMX8QM flash_b0
$ ls iMX8QM/flash.bin

Important: Replace <SECO Firmware File> by the SECO Firmware File for your specific configuration as indicated in the above table.

Rename the file flash.bin to imx-boot so it will be suitable for a Toradex Easy Installer Image.

$ mv iMX8QM/flash.bin iMX8QM/imx-boot

Deploying the U-Boot binary to an Image​

Start from a Existing Sample Image​

There are two types of Toradex Embedded Linux BSP images - which refers to how the image is packaged:

  • Toradex Easy Installer images
  • Compressed tarballs using Bash/U-Boot flashing scripts

Both of them have sample kernel and kernel module binaries, according to our BSP default configuration. You can use those pre-built images as a base for replacing the kernel and kernel driver binaries for testing.

caution

If the Toradex Easy Installer is supported for your SoM, you must use this format.

Select from the examples below the one that best suits your scenario:

Choose the appropriate image for your SoM in the Reference Images for Yocto Project Software Downloads.

Download it and extract the image. For example:

$ tar -xvf Apalis-iMX8_Reference-Minimal-Image-Tezi_5.2.0+build.7.tar

In the example above, this will extract the image to the directory Apalis-iMX8_Reference-Minimal-Image-Tezi_5.2.0+build.7.

Integrate Artifacts - U-Boot​

Integrate the U-Boot artifacts into our regular Toradex Easy Installer package: Replace the U-Boot binary and, if applicable, the SPL in the unpacked Toradex Easy Installer directory.

info

For Apalis TK1 only: first manually convert u-boot-dtb-tegra.bin to apalis-tk1.img using cbootimage from the legacy BSP package and its update.sh script.

Adjust Image.json - U-Boot​

Now adjust the image.json to your liking (e.g., change the name and description for you 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.

Deploy the Toradex Easy Installer Image​

You may now use the above prepared Toradex Easy Installer package with the Toradex Easy Installer.

Building Linux Kernel​

Download the Linux Kernel Source​

Obtain the kernel source code using Git:

$ mkdir -p ~/workdir
$ cd ~/workdir
$ git clone -b <branch> git://git.toradex.com/linux-toradex.git

Important: Replace <branch> by the Kernel Git Branch for your specific configuration. Click below to expand the version information.

View Kernel Git Branch information

i.MX 8/8X/8MM/8MP Downstream Linux Kernel Versions

BSP VersionKernel Git BranchKernel ConfigurationDevice TreeKernel Binary
5.3.0 - 5.4.0toradex_5.4-2.3.x-imxtoradex_defconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-v1.1-ixora-v1.1.dtb
imx8qp-apalis-v1.1-eval.dtb
imx8qp-apalis-v1.1-ixora-v1.1.dtb
imx8qxp-apalis-eval.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-dsihdmi-eval-v3.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-lvds-dual-eval-v3.dtb
imx8qxp-colibri-lvds-single-eval-v3.dtb
imx8mm-verdin-nonwifi-dahlia.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-wifi-dahlia.dtb
imx8mm-verdin-wifi-dev.dtb
imx8mp-verdin-nonwifi-dahlia.dtb
imx8mp-verdin-nonwifi-dev.dtb
imx8mp-verdin-wifi-dahlia.dtb
imx8mp-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
5.5.0toradex_5.4-2.3.x-imxtoradex_defconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-v1.1-ixora-v1.1.dtb
imx8qm-apalis-v1.1-ixora-v1.2.dtb
imx8qp-apalis-v1.1-eval.dtb
imx8qp-apalis-v1.1-ixora-v1.1.dtb
imx8qp-apalis-v1.1-ixora-v1.2.dtb
imx8dx-colibri-aster.dtb
imx8dx-colibri-eval-v3.dtb
imx8dx-colibri-iris.dtb
imx8dx-colibri-iris-v2.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-iris.dtb
imx8qxp-colibri-iris-v2.dtb
imx8qxp-colibri-lvds-dual-channel.dtb
imx8qxp-colibri-lvds-single-channel.dtb
imx8mm-verdin-nonwifi-dahlia.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-wifi-dahlia.dtb
imx8mm-verdin-wifi-dev.dtb
imx8mp-verdin-nonwifi-dahlia.dtb
imx8mp-verdin-nonwifi-dev.dtb
imx8mp-verdin-wifi-dahlia.dtb
imx8mp-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
View Information of Older Versions
BSP VersionKernel Git BranchKernel ConfigurationDevice TreeKernel Binary
3.0b1 / 3.0b2 / 3.0b3toradex_4.14-2.0.x-imxdefconfigfsl-imx8qm-apalis-eval.dtb
fsl-imx8qm-apalis-ixora-v1.1.dtb
fsl-imx8qxp-apalis-eval.dtb
fsl-imx8qxp-colibri-aster.dtb
fsl-imx8qxp-colibri-dsihdmi-eval-v3.dtb
fsl-imx8qxp-colibri-eval-v3.dtb
fsl-imx8qxp-colibri-lvds-dual-eval-v3.dtb
fsl-imx8qxp-colibri-lvds-single-eval-v3.dtb
fsl-imx8mm-verdin-dev.dtb		arch/arm64/boot/Image
3.0.4 / 4toradex_4.14-2.3.x-imxdefconfigfsl-imx8qm-apalis-eval.dtb
fsl-imx8qm-apalis-v1.1-eval.dtb
fsl-imx8qm-apalis-ixora-v1.1.dtb
fsl-imx8qxp-apalis-eval.dtb
fsl-imx8qxp-colibri-aster.dtb
fsl-imx8qxp-colibri-dsihdmi-eval-v3.dtb
fsl-imx8qxp-colibri-eval-v3.dtb
fsl-imx8qxp-colibri-lvds-dual-eval-v3.dtb
fsl-imx8qxp-colibri-lvds-single-eval-v3.dtb
fsl-imx8mm-verdin-nonwifi-dev.dtb
fsl-imx8mm-verdin-wifi-dev.dtb		arch/arm64/boot/Image
5.0.0toradex_5.4-2.1.x-imxdefconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qxp-apalis-eval.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-dsihdmi-eval-v3.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-lvds-dual-eval-v3.dtb
imx8qxp-colibri-lvds-single-eval-v3.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
5.1.0toradex_5.4-2.1.x-imxdefconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-v1.1-ixora-v1.1.dtb
imx8qp-apalis-v1.1-eval.dtb
imx8qp-apalis-v1.1-ixora-v1.1.dtb
imx8qxp-apalis-eval.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-dsihdmi-eval-v3.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-lvds-dual-eval-v3.dtb
imx8qxp-colibri-lvds-single-eval-v3.dtb
imx8mm-verdin-nonwifi-dahlia.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-nonwifi-v1.1-dahlia.dtb
imx8mm-verdin-nonwifi-v1.1-dev.dtb
imx8mm-verdin-wifi-dahlia.dtb
imx8mm-verdin-wifi-dev.dtb
imx8mm-verdin-wifi-v1.1-dahlia.dtb
imx8mm-verdin-wifi-v1.1-dev.dtb
imx8mp-verdin-nonwifi-dev.dtb
imx8mp-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
5.2.0toradex_5.4-2.3.x-imxtoradex_defconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-v1.1-ixora-v1.1.dtb
imx8qp-apalis-v1.1-eval.dtb
imx8qp-apalis-v1.1-ixora-v1.1.dtb
imx8qxp-apalis-eval.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-dsihdmi-eval-v3.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-lvds-dual-eval-v3.dtb
imx8qxp-colibri-lvds-single-eval-v3.dtb
imx8mm-verdin-nonwifi-dahlia.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-nonwifi-v1.1-dahlia.dtb
imx8mm-verdin-nonwifi-v1.1-dev.dtb
imx8mm-verdin-wifi-dahlia.dtb
imx8mm-verdin-wifi-dev.dtb
imx8mm-verdin-wifi-v1.1-dahlia.dtb
imx8mm-verdin-wifi-v1.1-dev.dtb
imx8mp-verdin-nonwifi-dev.dtb
imx8mp-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
info

Should your company firewall/gateway inhibit the git protocol, you may use HTTP or HTTPS instead (e.g. git clone https://git.toradex.com/linux-toradex.git).

info

If additional patches are provided, apply them as follows: git am <patch files>.

Kernel Configuration​

Our kernel tree provides default kernel configurations for our modules:

Ensure the environment is configured for cross-compilation as explained in the toolchain chapter.

Set the default configuration:

$ cd ~/workdir/linux-toradex
$ make <defconfig>

Important: Replace <defconfig> by the Kernel Configuration for your specific configuration. Click below to expand the version information.

View Kernel Configuration information

i.MX 8/8X/8MM/8MP Downstream Linux Kernel Versions

BSP VersionKernel Git BranchKernel ConfigurationDevice TreeKernel Binary
5.3.0 - 5.4.0toradex_5.4-2.3.x-imxtoradex_defconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-v1.1-ixora-v1.1.dtb
imx8qp-apalis-v1.1-eval.dtb
imx8qp-apalis-v1.1-ixora-v1.1.dtb
imx8qxp-apalis-eval.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-dsihdmi-eval-v3.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-lvds-dual-eval-v3.dtb
imx8qxp-colibri-lvds-single-eval-v3.dtb
imx8mm-verdin-nonwifi-dahlia.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-wifi-dahlia.dtb
imx8mm-verdin-wifi-dev.dtb
imx8mp-verdin-nonwifi-dahlia.dtb
imx8mp-verdin-nonwifi-dev.dtb
imx8mp-verdin-wifi-dahlia.dtb
imx8mp-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
5.5.0toradex_5.4-2.3.x-imxtoradex_defconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-v1.1-ixora-v1.1.dtb
imx8qm-apalis-v1.1-ixora-v1.2.dtb
imx8qp-apalis-v1.1-eval.dtb
imx8qp-apalis-v1.1-ixora-v1.1.dtb
imx8qp-apalis-v1.1-ixora-v1.2.dtb
imx8dx-colibri-aster.dtb
imx8dx-colibri-eval-v3.dtb
imx8dx-colibri-iris.dtb
imx8dx-colibri-iris-v2.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-iris.dtb
imx8qxp-colibri-iris-v2.dtb
imx8qxp-colibri-lvds-dual-channel.dtb
imx8qxp-colibri-lvds-single-channel.dtb
imx8mm-verdin-nonwifi-dahlia.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-wifi-dahlia.dtb
imx8mm-verdin-wifi-dev.dtb
imx8mp-verdin-nonwifi-dahlia.dtb
imx8mp-verdin-nonwifi-dev.dtb
imx8mp-verdin-wifi-dahlia.dtb
imx8mp-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
View Information of Older Versions
BSP VersionKernel Git BranchKernel ConfigurationDevice TreeKernel Binary
3.0b1 / 3.0b2 / 3.0b3toradex_4.14-2.0.x-imxdefconfigfsl-imx8qm-apalis-eval.dtb
fsl-imx8qm-apalis-ixora-v1.1.dtb
fsl-imx8qxp-apalis-eval.dtb
fsl-imx8qxp-colibri-aster.dtb
fsl-imx8qxp-colibri-dsihdmi-eval-v3.dtb
fsl-imx8qxp-colibri-eval-v3.dtb
fsl-imx8qxp-colibri-lvds-dual-eval-v3.dtb
fsl-imx8qxp-colibri-lvds-single-eval-v3.dtb
fsl-imx8mm-verdin-dev.dtb		arch/arm64/boot/Image
3.0.4 / 4toradex_4.14-2.3.x-imxdefconfigfsl-imx8qm-apalis-eval.dtb
fsl-imx8qm-apalis-v1.1-eval.dtb
fsl-imx8qm-apalis-ixora-v1.1.dtb
fsl-imx8qxp-apalis-eval.dtb
fsl-imx8qxp-colibri-aster.dtb
fsl-imx8qxp-colibri-dsihdmi-eval-v3.dtb
fsl-imx8qxp-colibri-eval-v3.dtb
fsl-imx8qxp-colibri-lvds-dual-eval-v3.dtb
fsl-imx8qxp-colibri-lvds-single-eval-v3.dtb
fsl-imx8mm-verdin-nonwifi-dev.dtb
fsl-imx8mm-verdin-wifi-dev.dtb		arch/arm64/boot/Image
5.0.0toradex_5.4-2.1.x-imxdefconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qxp-apalis-eval.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-dsihdmi-eval-v3.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-lvds-dual-eval-v3.dtb
imx8qxp-colibri-lvds-single-eval-v3.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
5.1.0toradex_5.4-2.1.x-imxdefconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-v1.1-ixora-v1.1.dtb
imx8qp-apalis-v1.1-eval.dtb
imx8qp-apalis-v1.1-ixora-v1.1.dtb
imx8qxp-apalis-eval.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-dsihdmi-eval-v3.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-lvds-dual-eval-v3.dtb
imx8qxp-colibri-lvds-single-eval-v3.dtb
imx8mm-verdin-nonwifi-dahlia.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-nonwifi-v1.1-dahlia.dtb
imx8mm-verdin-nonwifi-v1.1-dev.dtb
imx8mm-verdin-wifi-dahlia.dtb
imx8mm-verdin-wifi-dev.dtb
imx8mm-verdin-wifi-v1.1-dahlia.dtb
imx8mm-verdin-wifi-v1.1-dev.dtb
imx8mp-verdin-nonwifi-dev.dtb
imx8mp-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
5.2.0toradex_5.4-2.3.x-imxtoradex_defconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-v1.1-ixora-v1.1.dtb
imx8qp-apalis-v1.1-eval.dtb
imx8qp-apalis-v1.1-ixora-v1.1.dtb
imx8qxp-apalis-eval.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-dsihdmi-eval-v3.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-lvds-dual-eval-v3.dtb
imx8qxp-colibri-lvds-single-eval-v3.dtb
imx8mm-verdin-nonwifi-dahlia.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-nonwifi-v1.1-dahlia.dtb
imx8mm-verdin-nonwifi-v1.1-dev.dtb
imx8mm-verdin-wifi-dahlia.dtb
imx8mm-verdin-wifi-dev.dtb
imx8mm-verdin-wifi-v1.1-dahlia.dtb
imx8mm-verdin-wifi-v1.1-dev.dtb
imx8mp-verdin-nonwifi-dev.dtb
imx8mp-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz

At this point, one may alter the kernel configuration by either editing .config directly (e.g., setting CONFIG_* to either =y or =m aka as module) or use one of the kernel configuration utilities included, e.g.

$ make nconfig

Kernel Compilation​

Depending on the module, different kernel image types are used. Furthermore, some kernels require a device tree to describe the system's hardware (see Device Tree Customization for details).

Our kernel configurations build some drivers as kernel modules.

To assure module compatibility, the Kernel refuses to load modules with a 'vermagic' string that does not match its own. On top of that, the modules are stored under a directory named after the version string.

Thus one usually needs to compile and deploy the kernel modules together with the Kernel in order to use them.

i.MX 8/8X/8M Mini/8M Plus Based Kernel​

To compile the Kernel & device tree:

$ make -j$(nproc) Image.gz 2>&1 | tee build.log
$ make DTC_FLAGS="-@" freescale/<device-tree>.dtb

Important: Replace <device-tree> by the Device Tree for your specific configuration. Click below to expand the version information.

View Kernel Configuration information

i.MX 8/8X/8MM/8MP Downstream Linux Kernel Versions

BSP VersionKernel Git BranchKernel ConfigurationDevice TreeKernel Binary
5.3.0 - 5.4.0toradex_5.4-2.3.x-imxtoradex_defconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-v1.1-ixora-v1.1.dtb
imx8qp-apalis-v1.1-eval.dtb
imx8qp-apalis-v1.1-ixora-v1.1.dtb
imx8qxp-apalis-eval.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-dsihdmi-eval-v3.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-lvds-dual-eval-v3.dtb
imx8qxp-colibri-lvds-single-eval-v3.dtb
imx8mm-verdin-nonwifi-dahlia.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-wifi-dahlia.dtb
imx8mm-verdin-wifi-dev.dtb
imx8mp-verdin-nonwifi-dahlia.dtb
imx8mp-verdin-nonwifi-dev.dtb
imx8mp-verdin-wifi-dahlia.dtb
imx8mp-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
5.5.0toradex_5.4-2.3.x-imxtoradex_defconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-v1.1-ixora-v1.1.dtb
imx8qm-apalis-v1.1-ixora-v1.2.dtb
imx8qp-apalis-v1.1-eval.dtb
imx8qp-apalis-v1.1-ixora-v1.1.dtb
imx8qp-apalis-v1.1-ixora-v1.2.dtb
imx8dx-colibri-aster.dtb
imx8dx-colibri-eval-v3.dtb
imx8dx-colibri-iris.dtb
imx8dx-colibri-iris-v2.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-iris.dtb
imx8qxp-colibri-iris-v2.dtb
imx8qxp-colibri-lvds-dual-channel.dtb
imx8qxp-colibri-lvds-single-channel.dtb
imx8mm-verdin-nonwifi-dahlia.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-wifi-dahlia.dtb
imx8mm-verdin-wifi-dev.dtb
imx8mp-verdin-nonwifi-dahlia.dtb
imx8mp-verdin-nonwifi-dev.dtb
imx8mp-verdin-wifi-dahlia.dtb
imx8mp-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
View Information of Older Versions
BSP VersionKernel Git BranchKernel ConfigurationDevice TreeKernel Binary
3.0b1 / 3.0b2 / 3.0b3toradex_4.14-2.0.x-imxdefconfigfsl-imx8qm-apalis-eval.dtb
fsl-imx8qm-apalis-ixora-v1.1.dtb
fsl-imx8qxp-apalis-eval.dtb
fsl-imx8qxp-colibri-aster.dtb
fsl-imx8qxp-colibri-dsihdmi-eval-v3.dtb
fsl-imx8qxp-colibri-eval-v3.dtb
fsl-imx8qxp-colibri-lvds-dual-eval-v3.dtb
fsl-imx8qxp-colibri-lvds-single-eval-v3.dtb
fsl-imx8mm-verdin-dev.dtb		arch/arm64/boot/Image
3.0.4 / 4toradex_4.14-2.3.x-imxdefconfigfsl-imx8qm-apalis-eval.dtb
fsl-imx8qm-apalis-v1.1-eval.dtb
fsl-imx8qm-apalis-ixora-v1.1.dtb
fsl-imx8qxp-apalis-eval.dtb
fsl-imx8qxp-colibri-aster.dtb
fsl-imx8qxp-colibri-dsihdmi-eval-v3.dtb
fsl-imx8qxp-colibri-eval-v3.dtb
fsl-imx8qxp-colibri-lvds-dual-eval-v3.dtb
fsl-imx8qxp-colibri-lvds-single-eval-v3.dtb
fsl-imx8mm-verdin-nonwifi-dev.dtb
fsl-imx8mm-verdin-wifi-dev.dtb		arch/arm64/boot/Image
5.0.0toradex_5.4-2.1.x-imxdefconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qxp-apalis-eval.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-dsihdmi-eval-v3.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-lvds-dual-eval-v3.dtb
imx8qxp-colibri-lvds-single-eval-v3.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
5.1.0toradex_5.4-2.1.x-imxdefconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-v1.1-ixora-v1.1.dtb
imx8qp-apalis-v1.1-eval.dtb
imx8qp-apalis-v1.1-ixora-v1.1.dtb
imx8qxp-apalis-eval.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-dsihdmi-eval-v3.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-lvds-dual-eval-v3.dtb
imx8qxp-colibri-lvds-single-eval-v3.dtb
imx8mm-verdin-nonwifi-dahlia.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-nonwifi-v1.1-dahlia.dtb
imx8mm-verdin-nonwifi-v1.1-dev.dtb
imx8mm-verdin-wifi-dahlia.dtb
imx8mm-verdin-wifi-dev.dtb
imx8mm-verdin-wifi-v1.1-dahlia.dtb
imx8mm-verdin-wifi-v1.1-dev.dtb
imx8mp-verdin-nonwifi-dev.dtb
imx8mp-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz
5.2.0toradex_5.4-2.3.x-imxtoradex_defconfigimx8qm-apalis-eval.dtb
imx8qm-apalis-ixora-v1.1.dtb
imx8qm-apalis-v1.1-eval.dtb
imx8qm-apalis-v1.1-ixora-v1.1.dtb
imx8qp-apalis-v1.1-eval.dtb
imx8qp-apalis-v1.1-ixora-v1.1.dtb
imx8qxp-apalis-eval.dtb
imx8qxp-colibri-aster.dtb
imx8qxp-colibri-dsihdmi-eval-v3.dtb
imx8qxp-colibri-eval-v3.dtb
imx8qxp-colibri-lvds-dual-eval-v3.dtb
imx8qxp-colibri-lvds-single-eval-v3.dtb
imx8mm-verdin-nonwifi-dahlia.dtb
imx8mm-verdin-nonwifi-dev.dtb
imx8mm-verdin-nonwifi-v1.1-dahlia.dtb
imx8mm-verdin-nonwifi-v1.1-dev.dtb
imx8mm-verdin-wifi-dahlia.dtb
imx8mm-verdin-wifi-dev.dtb
imx8mm-verdin-wifi-v1.1-dahlia.dtb
imx8mm-verdin-wifi-v1.1-dev.dtb
imx8mp-verdin-nonwifi-dev.dtb
imx8mp-verdin-wifi-dev.dtb		arch/arm64/boot/Image.gz

Linux Kernel Module Compilation​

danger

If you compile and/or use a new kernel, you should update the kernel modules as well because they often have strong dependencies to a specific kernel build.

To compile the kernel modules as configured in .config (everything with CONFIG_*=m), run:

$ make -j$(nproc) modules

Kernel Module Deployment​

If kernel modules compiled successfully, you could extract them as follows:

$ sudo -E env "PATH=$PATH" make INSTALL_MOD_PATH=<path-to-rootfs>/ modules_install

Where <path-to-rootfs>/ either points to:

  • the rootfs folder of the previously extracted update package, in which case one has to remember to re-generate and re-flash the root file system image afterward.
  • directly to a NFS rootfs location.
  • a temporary folder, after which the kernel modules must be separately installed on the target as follows:

For example:

$ mkdir modules
$ export INSTALL_MOD_PATH=modules
$ make modules_install
$ cd modules
$ tar -czf ../modules.tar.gz .

Use scp to copy the tarball into your target:

$ scp modules.tar.gz root@<target-ip>:/home/root

In your target's Linux Terminal, extract the tarball in the rootfs as follows:

# cd ~
# tar -xzf modules.tar.gz -C /
info

You may also integrate your kernel modules into the root file system archive inside a Toradex Easy Installer package where applicable.

info

The Kernel and any kernel modules must be deployed as matching versions.

info

Run depmod on the target after deploying new or changed kernel modules.

Deploying the Kernel to an Image​

There are two methods to update the Linux kernel on the target hardware. For new modules, we only support the process based on the Toradex Easy Installer. However, for older modules and kernel versions, the legacy method may need to be used.

Please choose the appropriate tab below to select one of these two processes:

Toradex Easy Installer is the preferred method to update the Kernel for all the devices supported by the tool.

Toradex Easy Installer​

Integrate Artifacts​

Integrate the above-built artifacts into a suitable embedded Linux image packaged in Toradex Easy Installer format. You can download it from the Reference Images for Yocto Project Software Downloads.

For a module that uses raw NAND, simply replace the kernel binary and device tree(s) in the unpacked Toradex Easy Installer directory.

For a module that uses eMMC, the kernel binary and device tree(s) are part of the bootfs.tar.xz archive. Replace them in the archive.

$ tar xf ~/Downloads/Apalis-TK1_LXDE-Image-Tezi_2.8b1.64-20171229.tar
$ cd Apalis-TK1_LXDE-Image-Tezi_2.8b1.64/
$ mkdir Apalis-TK1_LXDE-Image.bootfs
$ cd Apalis-TK1_LXDE-Image.bootfs/
$ tar xJf ../Apalis-TK1_LXDE-Image.bootfs.tar.xz
$ cp ~/linux-toradex/arch/arm/boot/dts/tegra124-apalis-eval.dtb .
$ cp ~/linux-toradex/arch/arm/boot/dts/tegra124-apalis-v1.2-eval.dtb .
$ cp ~/linux-toradex/arch/arm/boot/zImage .
$ tar cJf ../Apalis-TK1_LXDE-Image.bootfs.tar.xz *

Adjust Image.json​

Now adjust the image.json to your linking (e.g., change at least the name and description for you to distinguish it from our 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.

Use Toradex Easy Installer​

You may now use the above prepared Toradex Easy Installer package with the Toradex Easy Installer.

Building the Device Tree Overlays​

caution

Device Tree Overlays were introduced in BSP 5. Therefore, this information does not apply to earlier BSPs.

Device Tree Overlays Source​

Device Tree Overlays (DTO) provide a way to modify the overall device tree without recompiling the complete device tree. See the Device Tree Overlays (Linux) article for more information about how to write a DTO for the Toradex Embedded Linux BSP.

Obtain the device tree overlays source code using Git:

$ cd ~/workdir
$ git clone -b <branch> git://git.toradex.com/device-tree-overlays.git
$ cd device-tree-overlays/

Important: Replace <branch> by the Device Tree Overlays Git Branch for your specific configuration. Click below to expand the version information.

View Device Tree Overlays Git Branch information

i.MX 8/8X/8MM/8MP Downstream Device Tree Overlays Versions

BSP VersionDevice Tree Overlays Git BranchDevice Tree Overlays Binaries
4toradex_4.14-2.3.x-imx*.dtbo
5.0.0 / 5.1.0toradex_5.4-2.1.x-imx*.dtbo
5.2.0+toradex_5.4-2.3.x-imx*.dtbo
info

Should your company firewall/gateway inhibit the git protocol, you may use HTTP or HTTPS instead (e.g. git clone https://git.toradex.com/device-tree-overlays.git).

Device Tree Overlays Compilation using make​

caution

This procedure requires the installation of the pre-requisite software, following the information on the Pre-Requisite Software section of this article.

Starting with BSP 5.2.0, we are maintaining a Makefile to compile the overlays. To make use of that, cd into the overlays directory.

$ cd overlays/

You also need a folder where the Linux Kernel is checked out and configured on the same kernel version. Then the path to this Kernel can be set on the environment variable, and the overlays be built with make.

$ export STAGING_KERNEL_DIR=/home/user/workdir/linux-toradex
$ make

You can also add your own DTBO by simply adding it to the Makefile located in the overlays folder:

dtb-y += <my overlay>.dtbo

Manual Device Tree Overlays Compilation​

caution

This procedure requires the installation of the pre-requisite software, following the information on the Pre-Requisite Software section of this article.

Depending on the module, different device tree overlays are used. Furthermore, device tree overlays require a base device tree to describe the system's hardware (see Device Tree Customization for details).

$ cd overlays/

To pre-process a device tree overlay (where ../../linux-toradex/ is the path to your kernel sources and verdin-imx8mm_lt8912_overlay.dts is your device tree overlay:

$ cpp -nostdinc -I ../../linux-toradex/arch/arm64/boot/dts -I ../../linux-toradex/include -undef -x assembler-with-cpp verdin-imx8mm_lt8912_overlay.dts verdin-imx8mm_lt8912_overlay.dts.preprocessed

To compile a device tree overlay from above pre-processed device tree overlay source (where verdin-imx8mm_lt8912_overlay.dtbo is the final device tree overlay binary):

$ dtc -@ -Hepapr -I dts -O dtb -i ../../linux-toradex/arch/arm64/boot/dts/ -o verdin-imx8mm_lt8912_overlay.dtbo verdin-imx8mm_lt8912_overlay.dts.preprocessed

Device Tree Overlays Update​

For instructions of how to deploy a Device Tree Overlay to a target, see the Device Tree Overlays (Linux) article.



Send Feedback!