Search by Tags

Build Apalis iMX8/Colibri iMX8X Boot Image/Linux from Scratch

Applicable for

Compare with Revision

Subscribe for this article updates

Note: What's described on this page is automated as part of Build Apalis iMX8/Colibri iMX8X OpenEmbedded/Yocto Project Bring-up Image. This page is useful for U-Boot or Linux kernel development where one wants to avoid the much longer development cycle times if one uses an OpenEmbedded setup for this.

The NXP i.MX 8QuadMax / i.MX 8QuadXPlus SoC boot process is a bit more involved than the typical SoC used by Toradex. This article describes how to build the boot container (including required integration of firmware and boot loader) and Linux manually.


The NXP i.MX 8QuadMax / i.MX 8QuadXPlus boots using a Cortex-M4 boot CPU called System Controller Unit (SCU). The SCU firmware is to a large part provided by NXP, but has been slightly altered by Toradex for the Apalis iMX8QM/Colibri iMX8QXP. 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 is able to boot Linux.

The DDR memory timings, the SCU firmware, the ATF and U-Boot as well as 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 offset 33kB.

Prepare Cross Compiler

The Linaro cross-toolchain for AArch64 is required to build the Bootloaders/Linux from scratch. The toolchain can be found at The latest aarch64-linux-gnu toolchain should work fine. At Toradex we tested the 2017.11 release which comes with GCC 7.2.1.

Make sure you extract the toolchain and setup the environment accordingly:

cd ~/
tar xJf gcc-linaro-7.2.1-2017.11-x86_64_aarch64-linux-gnu.tar.xz
export ARCH=arm64
export PATH=~/gcc-linaro-7.2.1-2017.11-x86_64_aarch64-linux-gnu/bin/:$PATH
export CROSS_COMPILE=aarch64-linux-gnu-

Build the Boot Container

Obtain SCU

Currently the SCU Firmware for Apalis iMX8QM and Colibri iMX8QXP is stored in the Bring-up BSP layer.

E.g. use wget for download:


The relevant file renamed to scfw_tcm.bin will be used in the final container.

Build ARM Trusted Firmware

Currently, there are no changes necessary for ARM Trusted Firmware. Hence ATF can be built directly from sources provided by NXP:

Module atf-branch platform binary-file
Apalis iMX8QM imx_4.9.51_imx8_beta2 imx8qm build/imx8qm/release/bl31.bin
Colibri iMX8QXP imx_4.9.123_imx8mm_ga imx8qxp build/imx8qxp/release/bl31.bin
git clone
cd imx-atf
git checkout <atf-branch>

Build the firmware:

make PLAT=<platform> bl31

The resulting binary file bl31.bin created in <platform>/release/ will be used in the final container.

Build U-Boot

Module U-Boot Git Branch U-Boot Configuration
Apalis iMX8QM toradex_imx_v2017.03_4.9.51_imx8_beta2-bring_up apalis-imx8_defconfig
Colibri iMX8QXP toradex_imx_v2017.03_4.9.123_imx8mm_ga-bring_up colibri-imx8qxp_defconfig

Toradex uses a customized version of the U-Boot boot loader provided by the NXP BSP. It can be found on our git server in the u-boot-toradex repository.

git clone
cd u-boot-toradex
git checkout <U-Boot Git Branch>
make <U-Boot Configuration>
make -j 4

The binary u-boot.bin will be used in the final container.

Provide the imx-mkimage Utility

The utility imx-mkimage allows building the boot container. It needs small modifications which are available as patches from the Bring-up BSP layer.

Apalis iMX8QM
Colibri iMX8QXP

Assemble the Boot Container

Copy all three binaries SCU Firmware, ARM Trusted Firmware and U-Boot into a SoC-specific directory, iMX8QM for Apalis iMX8QM, iMX8QX for Colibri iMX8QXP. Rename the SCU Firmware to scfw_tcm.bin while copying. Then use make to build the boot container and dd to write the boot container onto the boot device.

Assemble Apalis iMX8QM
Assemble Colibri iMX8QXP

Build Linux

Module Kernel Git Branch Kernel Configuration Device Tree Kernel Binary
Apalis iMX8QM toradex_imx_4.9.51_imx8_beta2-bring_up defconfig arch/arm64/boot/dts/freescale/fsl-imx8qm-apalis.dtb arch/arm64/boot/Image
Colibri iMX8QXP toradex_imx_4.9.123_imx8mm_ga-bring_up defconfig arch/arm64/boot/dts/freescale/fsl-imx8qxp-colibri-eval-v3.dtb arch/arm64/boot/Image
git clone
cd linux-toradex
git checkout <Kernel Git Branch>
make defconfig
make -j 4

By default, the U-Boot boot scripts try to load the Linux kernel and device tree from the first FAT partition of the SD card. Check Build U-Boot and Linux Kernel from Source Code on how to deploy kernel modules.