Search by Tags

Build U-Boot and Linux Kernel from Source Code

 

Article updated at 25 Sep 2019
Compare with Revision




Subscribe for this article updates

Summary

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

We provide OpenEmbedded recipes which build U-Boot and Linux as part of a complete image, hence if you plan to build a complete image follow the OpenEmbedded (core) article. This article also includes download and build of the software described further down.

Source Code

The source code of the U-Boot boot loader and the Linux kernel may be found on our Git server at git.toradex.com.

git clone -b <git-branch> git://git.toradex.com/u-boot-toradex.git
git clone -b <git-branch> git://git.toradex.com/linux-toradex.git

Note: 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).

The required git branch, U-Boot configuration and U-Boot/Linux binaries to be used depend on module type and image version.

Image Versions

Tegra Based Modules (Apalis/Colibri Txx)

Valid values for <board> are either apalis_t30, apalis-tk1, colibri_t20 or colibri_t30.

Tegra U-Boot Versions

Image Version U-Boot Git Branch U-Boot Configuration U-Boot Binary
V2.0 / V2.1 / V2.2 colibri <board>_config u-boot.bin
V2.3 beta 2 colibri <board>_config u-boot.bin
V2.3 beta 3 colibri (T20)
2014.10-toradex (T30)
<board>_defconfig u-boot.bin (T20)
u-boot-dtb-tegra.bin (T30)
V2.4 / V2.5 / V2.6 2015.04-toradex <board>_defconfig u-boot-dtb-tegra.bin
2.7 / 2.8 2016.11-toradex <board>_defconfig u-boot-dtb-tegra.bin
3.0 (TK1 only) toradex_2019.07 <board>_defconfig u-boot-dtb-tegra.bin

Tegra T20/T30 Linux Kernel Versions

Image Version Kernel git branch Kernel Configuration Device Tree Kernel Binary
V2.0 / V2.1 / V2.2 colibri <board>_defconfig - arch/arm/boot/uImage
V2.3 beta 2 tegra <board>_defconfig - arch/arm/boot/uImage
V2.3 beta 3 tegra <board>_defconfig - arch/arm/boot/uImage
V2.4 / V2.5 / V2.6 / 2.7 / 2.8b1 tegra <board>_defconfig - arch/arm/boot/zImage (T20)
arch/arm/boot/uImage (T30)
2.8b2 tegra <board>_defconfig - arch/arm/boot/zImage

Tegra K1 Linux Kernel Versions

Image Version Kernel git branch Kernel Configuration Device Tree Kernel Binary
V2.6 / 2.7b1 / 2.7b2 / 2.7b3 / 2.7b4 toradex_tk1_l4t_r21.5 <board>_defconfig tegra124-apalis-v1.2-eval.dtb
tegra124-apalis-eval.dtb
arch/arm/boot/uImage
2.7b5 / 2.8b1 toradex_tk1_l4t_r21.6 <board>_defconfig tegra124-apalis-v1.2-eval.dtb
tegra124-apalis-eval.dtb
arch/arm/boot/uImage
2.8b2 toradex_tk1_l4t_r21.6 <board>_defconfig tegra124-apalis-v1.2-eval.dtb
tegra124-apalis-eval.dtb
arch/arm/boot/zImage
2.8b3 / 2.8b4 / 2.8b5 toradex_tk1_l4t_r21.7 <board>_defconfig tegra124-apalis-v1.2-eval.dtb
tegra124-apalis-eval.dtb
arch/arm/boot/zImage
3.0 toradex_tk1_l4t_r21.7 <board>_defconfig tegra124-apalis-v1.2-eval.dtb
tegra124-apalis-eval.dtb
arch/arm/boot/zImage

Tegra K1 Mainline Linux Kernel Versions

Image Version kernel.org linux-stable.git branch Kernel Configuration Device Tree Kernel Binary Additional Patches
2.7 linux-4.9.y tegra_defconfig tegra124-apalis-v1.2-eval.dtb
tegra124-apalis-eval.dtb
arch/arm/boot/uImage morty patches
2.8b1 linux-4.14.y tegra_defconfig tegra124-apalis-v1.2-eval.dtb
tegra124-apalis-eval.dtb
arch/arm/boot/uImage rocko patches
2.8b2 linux-4.14.y tegra_defconfig tegra124-apalis-v1.2-eval.dtb
tegra124-apalis-eval.dtb
arch/arm/boot/zImage rocko patches
3.0 linux-4.14.y tegra_defconfig tegra124-apalis-v1.2-eval.dtb
tegra124-apalis-eval.dtb
arch/arm/boot/zImage thud patches

Vybrid Based Modules (Colibri VFxx)

Vybrid U-Boot Versions

Image Version U-Boot Git Branch U-Boot Configuration U-Boot Binary
V2.1 colibri_vf colibri_vf_config u-boot.nand
V2.2 / V2.3 beta 1 2014.04-toradex colibri_vf_config u-boot-nand.imx
V2.3 beta 3 2014.10-toradex colibri_vf_defconfig u-boot-nand.imx
V2.3 beta 5 2014.10-toradex colibri_vf_defconfig u-boot-nand.imx
V2.4 / V2.5 / V2.6 2015.04-toradex colibri_vf_defconfig u-boot-nand.imx
2.7 / 2.8 2016.11-toradex colibri_vf_defconfig u-boot-nand.imx

Note concerning U-Boot Binary: The recovery mode aka serial downloader uses the U-Boot Binary u-boot.imx. (e.g. using our update.sh script's -d argument which in turn uses the imx_uart utility).

Vybrid Linux Kernel Versions

Image Version Kernel git branch Kernel Configuration Device Tree Kernel Binary
V2.1 colibri_vf colibri_vf_defconfig - arch/arm/boot/uImage
V2.2 / V2.3 beta 1 colibri_vf colibri_vf_defconfig - arch/arm/boot/uImage
V2.3 beta 3 colibri_vf colibri_vf_defconfig - arch/arm/boot/zImage
V2.3 beta 5 toradex_vf_3.18 colibri_vf_defconfig vf500-colibri-eval-v3.dtb
vf610-colibri-eval-v3.dtb
arch/arm/boot/zImage
V2.4 beta 1 toradex_vf_4.0 colibri_vf_defconfig vf500-colibri-eval-v3.dtb
vf610-colibri-eval-v3.dtb
arch/arm/boot/zImage
V2.5 toradex_vf_4.1 colibri_vf_defconfig vf500-colibri-eval-v3.dtb
vf610-colibri-eval-v3.dtb
arch/arm/boot/zImage
V2.6 / 2.7 / 2.8 toradex_vf_4.4 colibri_vf_defconfig vf500-colibri-eval-v3.dtb
vf610-colibri-eval-v3.dtb
arch/arm/boot/zImage

i.MX 6 Based Modules (Apalis/Colibri iMX6)

Valid values for <board> are either apalis_imx6 or colibri_imx6.

Note: Starting with image V2.7 we use U-Boot together with an SPL to boot from eMMC. The SPL gets loaded by the bootrom into the SoC's SRAM, executes and initializes the DDR RAM according to module type, then it loads U-Boot to DDR and executes it. The Recovery Mode still uses a conventional U-Boot. On Apalis the recovery U-Boot is built for the IT modules RAM requirements which works well on both IT and non IT versions.

Note: For images older than V2.7, when building U-Boot for Apalis iMX6, be sure to use to distinguish between the IT (apalis_imx6_it) and the non-IT (apalis_imx6) versions of the module when configuring the U-Boot sources.

Note: For images older than V2.4, the U-Boot values are apalis_imx6q1g, apalis_imx6q2g, colibri_imx6s256m.

iMX6 U-Boot Versions

Image Version U-Boot Git Branch U-Boot Configuration U-Boot Binary
V2.2 toradex_imx6 <board>_config u-boot.imx
V2.3 2014.04-toradex <board>_config u-boot.imx
V2.4 / V2.5 / V2.6 2015.04-toradex <board>_defconfig u-boot.imx
2.7 / 2.8b1 2016.11-toradex <board>_defconfig
apalis_imx6_nospl_it_defconfig
colibri_imx6_nospl_defconfig
SPL, u-boot.img
u-boot.imx
u-boot.imx
2.8b2 2016.11-toradex <board>_defconfig SPL, u-boot.img
3.0 toradex_2019.07 <board>_defconfig SPL, u-boot.img

iMX6 Linux Kernel Versions

Image Version Kernel Git Branch Kernel Configuration Device Tree Kernel Binary
V2.2 toradex_imx6 <board>_defconfig - arch/arm/boot/uImage
V2.3 toradex_imx_3.10.17_1.0.0_ga <board>_defconfig imx6q-apalis-eval.dtb
imx6q-apalis-eval_v1_0.dtb
imx6dl-colibri-eval-v3.dtb
arch/arm/boot/uImage
V2.4 toradex_imx_3.10.17_1.0.0_ga <board>_defconfig imx6q-apalis-eval.dtb
imx6q-apalis-eval_v1_0.dtb
imx6dl-colibri-eval-v3.dtb
arch/arm/boot/uImage
V2.5 toradex_imx_3.14.28_1.0.0_ga <board>_defconfig imx6q-apalis-eval.dtb
imx6q-apalis-ixora.dtb
imx6q-apalis_v1_0-eval.dtb
imx6q-apalis_v1_0-ixora.dtb
imx6dl-colibri-eval-v3.dtb
arch/arm/boot/uImage
V2.6 toradex_imx_3.14.52_1.1.0_ga <board>_defconfig imx6q-apalis-eval.dtb
imx6q-apalis-ixora.dtb
imx6q-apalis_v1_0-eval.dtb
imx6q-apalis_v1_0-ixora.dtb
imx6dl-colibri-eval-v3.dtb
imx6dl-colibri-cam-eval-v3.dtb
arch/arm/boot/uImage
2.7 toradex_4.1-2.0.x-imx <board>_defconfig imx6q-apalis-eval.dtb
imx6q-apalis-ixora.dtb
imx6q-apalis-ixora-v1.1.dtb
imx6q-apalis_v1_0-eval.dtb
imx6q-apalis_v1_0-ixora.dtb
imx6dl-colibri-aster.dtb
imx6dl-colibri-cam-eval-v3.dtb
imx6dl-colibri-eval-v3.dtb
arch/arm/boot/uImage
2.8b1 toradex_4.9-1.0.x-imx <board>_defconfig imx6q-apalis-eval.dtb
imx6q-apalis-ixora-v1.1.dtb
imx6q-apalis-ixora.dtb
imx6dl-colibri-aster.dtb
imx6dl-colibri-cam-eval-v3.dtb
imx6dl-colibri-eval-v3.dtb
arch/arm/boot/uImage
2.8b2 toradex_4.9-1.0.x-imx <board>_defconfig imx6q-apalis-eval.dtb
imx6q-apalis-ixora.dtb
imx6q-apalis-ixora-v1.1.dtb
imx6dl-colibri-aster.dtb
imx6dl-colibri-cam-eval-v3.dtb
imx6dl-colibri-eval-v3.dtb
arch/arm/boot/zImage
2.8b5 toradex_4.9-2.3.x-imx <board>_defconfig imx6q-apalis-eval.dtb
imx6q-apalis-ixora.dtb
imx6q-apalis-ixora-v1.1.dtb
imx6dl-colibri-aster.dtb
imx6dl-colibri-cam-eval-v3.dtb
imx6dl-colibri-eval-v3.dtb
arch/arm/boot/zImage
3.0 toradex_4.14-2.0.x-imx <board>_defconfig imx6q-apalis-eval.dtb
imx6q-apalis-ixora.dtb
imx6q-apalis-ixora-v1.1.dtb
imx6q-apalis-ixora-v1.2
imx6dl-colibri-aster.dtb
imx6dl-colibri-cam-eval-v3.dtb
imx6dl-colibri-eval-v3.dtb
imx6dl-colibri-iris.dtb
imx6dl-colibri-iris-v2.dtb
arch/arm/boot/zImage

i.MX 6ULL Based Modules (Colibri iMX6ULL)

iMX6ULL U-Boot Versions

Image Version U-Boot Git Branch U-Boot Configuration U-Boot Binary
2.7b5 / 2.8 2016.11-toradex colibri-imx6ull_defconfig u-boot-nand.imx
3.0 toradex_2019.07 colibri-imx6ull_defconfig u-boot-nand.imx

iMX6ULL Linux Kernel Versions

Image Version Kernel Git Branch Kernel Configuration Device Tree Kernel Binary
2.7b5 toradex_4.1-2.0.x-imx colibri-imx6ull_defconfig imx6ull-colibri-eval-v3.dtb
imx6ull-colibri-wifi-eval-v3.dtb
arch/arm/boot/zImage
2.8b1 toradex_4.9-1.0.x-imx colibri-imx6ull_defconfig imx6ull-colibri-eval-v3.dtb
imx6ull-colibri-wifi-eval-v3.dtb
arch/arm/boot/zImage
2.8b5 toradex_4.9-2.3.x-imx colibri-imx6ull_defconfig imx6ull-colibri-aster.dtb
imx6ull-colibri-eval-v3.dtb
imx6ull-colibri-wifi-aster.dtb
imx6ull-colibri-wifi-eval-v3.dtb
arch/arm/boot/zImage
3.0 toradex_4.14-2.0.x-imx colibri-imx6ull_defconfig imx6ull-colibri-aster.dtb
imx6ull-colibri-eval-v3.dtb
imx6ull-colibri-iris.dtb
imx6ull-colibri-iris-v2.dtb
imx6ull-colibri-wifi-aster.dtb
imx6ull-colibri-wifi-eval-v3.dtb
imx6ull-colibri-wifi-iris.dtb
imx6ull-colibri-wifi-iris-v2.dtb
arch/arm/boot/zImage

i.MX 7 Based Modules (Colibri iMX7)

iMX7 U-Boot Versions

Image Version U-Boot Git Branch U-Boot Configuration U-Boot Binary
V2.6 2015.04-toradex colibri_imx7_defconfig u-boot-nand.imx
2.7 / 2.8 2016.11-toradex colibri_imx7_defconfig
colibri_imx7_emmc_defconfig
u-boot-nand.imx
u-boot.imx
3.0 toradex_2019.07 colibri_imx7_defconfig
colibri_imx7_emmc_defconfig
u-boot-nand.imx
u-boot.imx

iMX7 Linux Kernel Versions

Image Version Kernel Git Branch Kernel Configuration Device Tree Kernel Binary
V2.6 Alpha 1 toradex_imx_3.14.52_1.1.0_ga colibri_imx7_defconfig imx7d-colibri.dtb
imx7s-colibri.dtb
arch/arm/boot/zImage
V2.6 Beta 2 toradex_imx_4.1.15_1.0.0_ga colibri_imx7_defconfig imx7d-colibri-eval-v3.dtb
imx7s-colibri-eval-v3.dtb
arch/arm/boot/zImage
2.7 toradex_4.1-2.0.x-imx colibri_imx7_defconfig imx7d-colibri-aster.dtb
imx7d-colibri-emmc-aster.dtb
imx7s-colibri-aster.dtb
imx7d-colibri-eval-v3.dtb
imx7d-colibri-emmc-eval-v3.dtb
imx7s-colibri-eval-v3.dtb
arch/arm/boot/zImage
2.8b1 toradex_4.9-1.0.x-imx colibri_imx7_defconfig imx7d-colibri-aster.dtb
imx7d-colibri-emmc-aster.dtb
imx7s-colibri-aster.dtb
imx7d-colibri-eval-v3.dtb
imx7d-colibri-emmc-eval-v3.dtb
imx7s-colibri-eval-v3.dtb
arch/arm/boot/zImage
2.8b5 toradex_4.9-2.3.x-imx colibri_imx7_defconfig imx7d-colibri-aster.dtb
imx7d-colibri-emmc-aster.dtb
imx7s-colibri-aster.dtb
imx7d-colibri-eval-v3.dtb
imx7d-colibri-emmc-eval-v3.dtb
imx7s-colibri-eval-v3.dtb
arch/arm/boot/zImage
3.0 toradex_4.14-2.0.x-imx colibri_imx7_defconfig imx7d-colibri-aster.dtb
imx7d-colibri-emmc-aster.dtb
imx7d-colibri-emmc-eval-v3.dtb
imx7d-colibri-emmc-iris.dtb
imx7d-colibri-emmc-iris-v2.dtb
imx7d-colibri-eval-v3.dtb
imx7d-colibri-iris.dtb
imx7d-colibri-iris-v2.dtb
imx7s-colibri-aster.dtb
imx7s-colibri-eval-v3.dtb
imx7s-colibri-iris.dtb
imx7s-colibri-iris-v2.dtb
arch/arm/boot/zImage

i.MX 8/8X Based Modules (Apalis iMX8/Colibri iMX8X)

iMX8/8X U-Boot Versions

Image Version U-Boot Git Branch U-Boot Configuration U-Boot Binary
3.0 toradex_imx_v2018.03_4.14.78_1.0.0_ga-bringup apalis-imx8_defconfig
colibri-imx8qxp_defconfig
flash.bin

iMX8/8X Linux Kernel Versions

Image Version Kernel Git Branch Kernel Configuration Device Tree Kernel Binary
3.0 toradex_4.14-2.0.x-imx defconfig fsl-imx8qm-apalis.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
arch/arm64/boot/Image

Toolchain

Toolchain for Hard Float Calling Convention

Beginning with image 3.0, as part of our OpenEmbedded Thud update we transitioned to using version 8.2 of the gcc compiler. Arm releases well tested binary toolchains which can be used to cross compile software for our modules (choose gcc-arm-8.2-2019.01-x86_64-arm-linux-gnueabihf.tar.xz for 32bit Arm and gcc-arm-8.2-2019.01-x86_64-aarch64-linux-gnu.tar.xz for 64bit Arm):

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

Beginning with image 2.8, as part of our OpenEmbedded Rocko update we transitioned to using version 7.3 of the gcc compiler. Linaro releases well tested binary toolchains which can be used to cross compile software for our modules (choose gcc-linaro-7.3.1-2018.05-x86_64_arm-linux-gnueabihf.tar.xz):

https://releases.linaro.org/components/toolchain/binaries/7.3-2018.05/arm-linux-gnueabihf/

Beginning with image 2.7b2, as part of our OpenEmbedded Morty update we transitioned to using version 6.2 of the gcc compiler. Linaro releases well tested binary toolchains which can be used to cross compile software for our modules (choose gcc-linaro-6.2.1-2016.11-x86_64_arm-linux-gnueabihf.tar.xz):

https://releases.linaro.org/components/toolchain/binaries/6.2-2016.11/arm-linux-gnueabihf/

Beginning with image V2.6, as part of our OpenEmbedded Jethro update we transitioned to using version 5.2 of the gcc compiler. Linaro releases well tested binary toolchains which can be used to cross compile software for our modules (choose gcc-linaro-5.2-2015.11-2-x86_64_arm-linux-gnueabihf.tar.xz):

https://releases.linaro.org/components/toolchain/binaries/5.2-2015.11-2/arm-linux-gnueabihf/

Beginning with image V2.0, we transitioned to using the hard-float ABI:

https://releases.linaro.org/archive/14.11/components/toolchain/binaries/

Note: Since the 14.11 release Linaro only provides x86_64 toolchains. If you use 32-bit Linux on your host machine (check using uname -m), you can still download the older 14.09 release which is still 32-bit:

https://releases.linaro.org/archive/14.09/components/toolchain/binaries/

To install the toolchain on your host machine, unpack the tar.xz file:

cd
wget -c https://releases.linaro.org/components/toolchain/binaries/5.2-2015.11-2/arm-linux-gnueabihf/gcc-linaro-5.2-2015.11-2-x86_64_arm-linux-gnueabihf.tar.xz
tar xvf gcc-linaro-5.2-2015.11-2-x86_64_arm-linux-gnueabihf.tar.xz
ln -s gcc-linaro-5.2-2015.11-2-x86_64_arm-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.

For 32bit Arm:

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

For 64bit Arm:

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

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 PATH=~/gcc-linaro/bin/:$PATH" >> ~/export_compiler
echo "export CROSS_COMPILE=arm-linux-gnueabihf-" >> ~/export_compiler
source ~/export_compiler

Linux Image / Flashing Tools

The following instructions expect the latest Linux image to be extracted on your host machine.

The latest Linux images are available at: http://files.toradex.com/Colibri/Linux/Images

As an example we'll use Colibri_T20_LinuxImageV2.3_20150320.tar.bz2 which will create a directory Colibri_T20_LinuxImageV2.3.

To download and extract the image:

cd
wget http://files.toradex.com/Colibri/Linux/Images/Colibri_T20_LinuxImageV2.3_20150320.tar.bz2
sudo tar xjvf Colibri_T20_LinuxImageV2.3_20150320.tar.bz2

DTC

U-Boot compilation for some modules needs a device tree compiler (DTC) of version 1.3 or higher to be installed and executable. Ubuntu 12.04 LTS (Precise Pangolin) and later provide a version which is recent enough:

sudo apt-get install device-tree-compiler

To check the version:

$ dtc -v
Version: DTC 1.3.0

If you need to build a newer version, you can get the latest version (DTC 1.4.1 at the time of writing) from source:

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

Alternatively, one can use the tools built with an OpenEmbedded build. See the toolchain chapter above.

U-Boot Tools

The uImage target of the Linux kernel compilation needs a recent mkimage tool which is actually built during U-Boot compilation as explained further below. Ensure that one is included in PATH:

export PATH=$PATH:$HOME/u-boot-toradex/tools

Alternatively, one can simply install the Fedora package uboot-tools:

sudo dnf install uboot-tools

respectively the Debian/Ubuntu package u-boot-tools:

sudo apt-get install u-boot-tools

Alternatively, one can use the tools built with an OpenEmbedded build. See the toolchain chapter above.

Other Build Host Tools

You need some basic build tools to compile the kernel. Most are likely part of your distro's standard install.

For Fedora:

sudo dnf install bc gcc git ncurses-devel lzop make perl

For Debian/Ubuntu:

sudo apt-get install bc build-essential git libncurses5-dev lzop perl

U-Boot

For detailed information about which branch, configuration or binary to use, please consult the image version tables provided at the top of the article.

Source

Obtain the U-Boot source code using Git:

cd
git clone -b 2016.11-toradex git://git.toradex.com/u-boot-toradex.git
cd u-boot-toradex

Note: The 2016.11-toradex branch is used as an example. For detailed information about which branch to use, please consult the image version tables provided at the top of the article.

Configuration

Our latest board configurations are called as follows:

Tegra based modules

  • apalis_t30_defconfig
  • apalis-tk1_defconfig
  • colibri_t20_defconfig
  • colibri_t30_defconfig

Vybrid based modules

All Vybrid based modules share their configuration.

  • colibri_vf_defconfig

i.MX 6 based modules

  • apalis_imx6_defconfig
  • apalis_imx6_nospl_it_defconfig
  • colibri_imx6_defconfig
  • colibri_imx6_nospl_defconfig

i.MX 6ULL based modules

  • colibri-imx6ull_defconfig

i.MX 7 based modules

  • colibri_imx7_defconfig
  • colibri_imx7_emmc_defconfig

i.MX 8/8X based modules

  • apalis-imx8_defconfig
  • colibri-imx8qxp_defconfig

For detailed information about which configuration to use, please consult the image version tables provided at the top of the article.

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

make colibri_t20_config

Compilation

The following is the procedure to compile the boot loader.

make -j3 2>&1 | tee build.log

When using the cross compiler built by a 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'

Boot Container (Apalis iMX8/Colibri iMX8X)

The NXP i.MX 8QuadMax / i.MX 8QuadXPlus SoC boot process is a bit more involved than the typical SoC used by Toradex. This section describes how to build the boot container (including required integration of firmware and boot loader) 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 a specific offset (33kB for V1.0A modules booting from SD cards).

Note that if you already built an image with OpenEmbedded you already have the needed artefacts to assemble the final bootcontainer. They can be found in deploy/images/.

Obtain SECO

The SECO Firmware is provided by NXP in binary form. You will need to accept the NXP License Agreement as part of the unpacking process. The files are called mx8qm-ahab-container.img and mx8qx-ahab-container.img respectively.

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

wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.0.bin
chmod u+x firmware-imx-8.0.bin
./firmware-imx-8.0.bin
ls firmware-imx-8.0/firmware/seco/

Obtain SCU

The SCU firmware for Apalis iMX8QM and Colibri iMX8QXP may be found in our i.MX-System-Controller-Firmware GitHub repository.

E.g. use wget for download:

wget https://github.com/toradex/i.MX-System-Controller-Firmware/raw/master/src/scfw_export_mx8qm_b0/build_mx8qm_b0/scfw_tcm.bin
wget https://github.com/toradex/i.MX-System-Controller-Firmware/raw/master/src/scfw_export_mx8qx_b0/build_mx8qx_b0/scfw_tcm.bin

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 V1.0B imx_4.14.78_1.0.0_ga imx8qm build/imx8qm/release/bl31.bin
Colibri iMX8QXP V1.0B imx_4.14.78_1.0.0_ga imx8qxp build/imx8qxp/release/bl31.bin
git clone https://source.codeaurora.org/external/imx/imx-atf
cd imx-atf
git checkout <ATF Branch>

Build the firmware:

make PLAT=<Platform> bl31

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

U-Boot (Binary for Boot Container)

The binary u-boot.bin built as outlined above will be used in the final boot container.

Provide the imx-mkimage Utility

The utility imx-mkimage allows building the boot container.

git clone https://source.codeaurora.org/external/imx/imx-mkimage/
cd imx-mkimage
git checkout imx_4.14.78_2.0.0_ga

Assemble the Boot Container

Copy all binaries SCU Firmware, ARM Trusted Firmware, U-Boot and for V1.0B modules the SECO Firmware 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 deploy flash.bin to the module's boot device.

You either need to install your distributions devel package for linking against a static libc or remove '-static' from the CFLAGS in the Makefile.

Apalis iMX8

cp ../apalis-imx8-scfw-tcm.bin iMX8QM/scfw_tcm.bin
cp ../imx-atf/build/imx8qm/release/bl31.bin iMX8QM/
cp ../u-boot-toradex/u-boot.bin iMX8QM/
cp ../firmware-imx-8.0/firmware/seco/mx8qm-ahab-container.img iMX8QM/
make SOC=iMX8QM flash_b0

Colibri iMX8X

cp ../colibri-imx8qxp-scfw-tcm.bin iMX8QX/scfw_tcm.bin
cp ../imx-atf/build/imx8qxp/release/bl31.bin iMX8QX/
cp ../u-boot-toradex/u-boot.bin iMX8QX/
cp ../firmware-imx-8.0/firmware/seco/mx8qx-ahab-container.img iMX8QX/
make SOC=iMX8QX flash

Update

Toradex Easy Installer (Apalis TK1, Apalis/Colibri iMX6, Colibri iMX6ULL, Colibri iMX7) - U-Boot

Integrate Artefacts - U-Boot

Integrate above built artefacts into our regular Toradex Easy Installer package:

Note: For Apalis TK1 first manually convert u-boot-dtb-tegra.bin to apalis-tk1.img using

bootimage
from the legacy BSP package and its update.sh script.

Replace the U-Boot binary and if applicable the SPL in the unpacked Toradex Easy Installer directory.

Adjust Image.json - U-Boot

Now adjust the image.json to your liking (e.g. change at least the name and description for you to be able to distinguish it from our regular 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 - U-Boot

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

Legacy Images - U-Boot

Colibri T20

Image V2.3 & Older

The following procedure is to flash just the new boot loader (assumes target is already in recovery mode):

cd ~/Colibri_T20_LinuxImageV2.3/colibri-t20_bin
cp ~/u-boot-toradex/u-boot.bin ./u-boot-custom.bin
ln -fs u-boot-custom.bin u-boot.bin
cd ..
./update.sh -r 512 -u -v V1_2

Note: This example performs an update for the Colibri T20 512MB V1_2. Enter the update parameters according to the Colibri T20 version.

Image V2.4 & Newer

Refer to the Tegra based modules section below for the T20 U-Boot update procedure of V2.4+ images.

Tegra based modules (T20: Image V2.4+)

Replace the existing u-boot-dtb-tegra.bin in the extracted BSP package.

cd ~/Apalis_T30_LinuxImageV2.3/apalis-t30_bin
cp ~/u-boot-toradex/u-boot-dtb-tegra.bin ./u-boot-dtb-tegra-custom.bin
ln -fs u-boot-dtb-tegra-custom.bin u-boot-dtb-tegra.bin
cd ..

Prepare an SD card as described in the Flashing Embedded Linux to Tegra Modules article.

Boot the module to the U-Boot prompt and update U-Boot:

run setupdate
run update_uboot

Note: Refer to the Txx Recovery Mode article if the module is not able to boot into U-Boot.

After the update, reset or power cycle to execute the new U-Boot.

Vybrid, i.MX 6 & i.MX 7 Based Modules

Prepare an SD card as described in the articles below (according to the module of interest):

Flashing Embedded Linux to iMX6 Modules

Flashing Embedded Linux to iMX7 Modules

Flashing Embedded Linux to Vybrid Modules

Replace the existing U-Boot binary in the first partition of your SD card.

eMMC Based Modules (i.MX 6)
Starting with image V2.7 use the built u-boot-toradex/SPL and u-boot-toradex/u-boot.img files to replace SPL and u-boot.imx-spl on the update SD card (renaming u-boot.img to u-boot.imx-spl in the process).

For older images use u-boot.imx to replace u-boot.imx, or if you built for a Apalis iMX6 IT replace u-boot.imx-it or u-boot-it.imx.

Raw NAND Based Systems (Vybrid and i.MX 7)
Use u-boot-nand.imx for raw NAND based systems (Vybrid and i.MX 7).


cp ~/u-boot-toradex/u-boot.imx /media/<path-to-partition-1>/<board>/

Boot the module to the U-Boot prompt and update U-Boot:

run setupdate
run update_uboot

Note: Refer to the Flashing Embedded Linux articles above if the module is not able to boot into U-Boot.

After the update, reset or power cycle to execute the new U-Boot.

Note: This does not reset the U-Boot environment to the new default values.

Note: If the module fails to boot Linux after updating U-Boot, consider resetting the U-Boot environment.

To reset the environment to the updated default environment, enter the following from the command line of the updated U-Boot:

env default -a
saveenv

Note: Images V2.6 and older: On the Colibri iMX6DL the command patch_ddr_size must be executed after flashing U-Boot which is already taken care of by the update_uboot command given above.

Standalone Application

Note: If you don't know if you need to read this, you will not need to read this. U-Boot allows 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

Linux Kernel

Kernel Source

For detailed information about which branch to use, please consult the image version tables provided at the top of the article.

Obtain the kernel source code using Git:

git clone -b tegra git://git.toradex.com/linux-toradex.git 
cd linux-toradex

Note: The tegra branch is used as an example. For detailed information about which branch to use, please consult the image version tables provided at the top of the article.

Note: 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:

For detailed information about which configuration to use, please consult the image version tables provided at the top of the article.

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

Set the default configuration:

make colibri_t20_defconfig
...

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

For detailed information about which binary and device tree to use, please consult the image version tables provided at the top of the article.

Tegra T20/T30 Based Kernel (Colibri T20, Apalis/Colibri T30)

To compile the kernel:

make -j3 uImage 2>&1 | tee build.log

Using a GCC 4.8 or newer toolchain with the gold linker may cause the following issue:

arm-angstrom-linux-gnueabi-ld: error: arch/arm/boot/compressed/piggy.gzip.o: unknown CPU architecture
arm-angstrom-linux-gnueabi-ld: error: arch/arm/boot/compressed/lib1funcs.o: unknown CPU architecture

This is a known issue with older kernel versions and the gold linker (see this message by the gold creator). The recommended solution is to just revert to using the regular bfd linker as follows:

make -j3 uImage LD=${CROSS_COMPILE}ld.bfd | tee build.log

Tegra K1 Based Kernel (Apalis TK1)

To compile the kernel & device tree:

make -j3 uImage LOADADDR=0x80008000 2>&1 | tee build.log
make tegra124-apalis-eval.dtb

Vybrid Based Kernel (Colibri VFXX)

Since V2.3 Beta 3, the boot loader expects the kernel to be located within the root file system and in the zImage format.
Since V2.3 Beta 5 (i.e. branch colibri_vf_3.18) a device tree must additionally be built from the kernel sources.
Since V2.6 Beta 2, the boot loader expects the kernel/dtb to be located in their own static UBI volue and in the zImage format.

To compile the kernel & device tree:

make -j3 zImage | tee build.log
make vf610-colibri-eval-v3.dtb

The Linux kernel for our Vybrid based modules can show linking issues when using the gold linker:

arm-angstrom-linux-gnueabi-ld: --pic-veneer: unknown option
arm-angstrom-linux-gnueabi-ld: use the --help option for usage information

The recommended solution is to just revert to using the regular bfd linker as follows:

make -j3 zImage LD=${CROSS_COMPILE}ld.bfd | tee build.log

i.MX 6 Based Kernel (Apalis/Colibri iMX6)

Starting with Apalis iMX6 Image V2.3 Beta 1 and for all Colibri iMX6 kernels some additional parameters are required to compile the kernel plus a device tree is built from the kernel sources.

Valid device trees:

To compile the kernel & device tree:

make -j3 uImage LOADADDR=10008000 2>&1 | tee build.log
make imx6q-apalis-eval.dtb

i.MX 6ULL Based Kernel (Colibri iMX6ULL)

To compile the kernel & device tree:

make -j3 zImage 2>&1 | tee build.log
make imx6ull-colibri-eval-v3.dtb

The Linux kernel for our i.MX 6ULL based modules can show linking issues when using the gold linker:

arm-angstrom-linux-gnueabi-ld: --pic-veneer: unknown option
arm-angstrom-linux-gnueabi-ld: use the --help option for usage information

The recommended solution is to just revert to using the regular bfd linker as follows:

make -j3 zImage LD=${CROSS_COMPILE}ld.bfd | tee build.log

i.MX 7 Based Kernel (Colibri iMX7S/iMX7D)

To compile the kernel & device tree:

make -j3 zImage 2>&1 | tee build.log
make imx7d-colibri-eval-v3.dtb

The Linux kernel for our i.MX7 based modules can show linking issues when using the gold linker:

arm-angstrom-linux-gnueabi-ld: --pic-veneer: unknown option
arm-angstrom-linux-gnueabi-ld: use the --help option for usage information

The recommended solution is to just revert to using the regular bfd linker as follows:

make -j3 zImage LD=${CROSS_COMPILE}ld.bfd | tee build.log

Kernel Module Compilation, all Modules

Attention: If you recompile the 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 -j3 modules

Extract the kernel modules with:

mkdir modules
export INSTALL_MOD_PATH=modules
make modules_install

Create a kernel module tarball with:

cd modules
tar -czf ../modules.tar.gz .
cd -

Install the tarball on your module with:

tar -xzf modules.tar.gz -C /

Kernel Update

Toradex Easy Installer (Apalis TK1, Apalis/Colibri iMX6, Colibri iMX6ULL, Colibri iMX7)

Integrate Artefacts

Integrate above built artefacts into our regular Toradex Easy Installer package:

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

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

[user@host ~]$ tar xf ~/Downloads/Apalis-TK1_LXDE-Image-Tezi_2.8b1.64-20171229.tar
[user@host ~]$ cd Apalis-TK1_LXDE-Image-Tezi_2.8b1.64/
[user@host Apalis-TK1_LXDE-Image-Tezi_2.8b1.64]$ mkdir Apalis-TK1_LXDE-Image.bootfs
[user@host Apalis-TK1_LXDE-Image-Tezi_2.8b1.64]$ cd Apalis-TK1_LXDE-Image.bootfs/
[user@host Apalis-TK1_LXDE-Image.bootfs]$ tar xJf ../Apalis-TK1_LXDE-Image.bootfs.tar.xz
[user@host Apalis-TK1_LXDE-Image.bootfs]$ cp ~/linux-toradex/arch/arm/boot/dtbs/tegra124-apalis-eval.dtb .
[user@host Apalis-TK1_LXDE-Image.bootfs]$ cp ~/linux-toradex/arch/arm/boot/dtbs/tegra124-apalis-v1.2-eval.dtb .
[user@host Apalis-TK1_LXDE-Image.bootfs]$ cp ~/linux-toradex/arch/arm/boot/uImage .
[user@host Apalis-TK1_LXDE-Image.bootfs]$ tar cJf ../Apalis-TK1_LXDE-Image.bootfs.tar.xz *

Adjust Image.json

Now adjust the image.json to your liking (e.g. change at least the name and description for you to be able to distinguish it from our regular 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 above prepared Toradex Easy Installer package with the Toradex Easy Installer.

Legacy Images

Colibri T20

Image V2.3 & Older

To flash just the new kernel (assumes the target is already in recovery mode):

cd ~/Colibri_T20_LinuxImageV2.3/colibri-t20_bin
cp ~/linux-toradex/arch/arm/boot/uImage ./uImage-custom
ln -fs uImage-custom uImage
cd ..
./update.sh -k -r 512 -v V1_2

Note: This example performs an update for the Colibri T20 512MB V1_2. Enter the update parameters according to the Colibri T20 version.

Image V2.4 & Newer

Replace the existing zImage in the extracted BSP package:

cd ~/Colibri_T20_LinuxImageV2.4/rootfs/boot
cp ~/linux-toradex/arch/arm/boot/zImage ./zImage-custom
ln -fs /boot/zImage-custom zImage
cd ../..

Prepare an SD card as described in at: Flashing Embedded Linux to Tegra Modules

Boot the module to the U-Boot prompt and update the whole root file system which contains the new kernel in its /boot folder:

run setupdate
run update_rootfs

Note: Refer to the Txx Recovery Mode article if the module is not able to boot into U-Boot.

After the update, reset or power cycle to boot the updated kernel.

Image V2.6 Beta 2 & Newer

Prepare an SD card as described in at: Flashing Embedded Linux to Tegra Modules Then, copy the Kernel directly onto the SD card:

cp ~/linux-toradex/arch/arm/boot/zImage /media/<path-to-partition-1>/colibri-t20/

Boot the module to the U-Boot prompt and update the kernel in its UBI volume:

run setupdate
run prepare_ubi
run update_kernel

Note: Refer to the Txx Recovery Mode article if the module is not able to boot into U-Boot.

After the update, reset or power cycle to boot the updated kernel.

Vybrid Based Modules (V2.5 and older)

Replace the existing zImage & device trees in the extracted BSP package:

cd ~/Colibri_VF_LinuxImageV2.3/rootfs/boot
cp ~/linux-toradex/arch/arm/boot/zImage ./zImage-custom
cp ~/linux-toradex/arch/arm/boot/dts/vf500-colibri-eval-v3.dtb ./vf500-custom.dtb
cp ~/linux-toradex/arch/arm/boot/dts/vf610-colibri-eval-v3.dtb ./vf610-custom.dtb
ln -fs /boot/zImage-custom zImage
ln -fs /boot/vf500-custom.dtb vf500-colibri-eval-v3.dtb
ln -fs /boot/vf610-custom.dtb vf610-colibri-eval-v3.dtb
cd ../..

Prepare an SD card as described in Flashing Embedded Linux to Vybrid Modules.

Boot the module to the U-Boot prompt and update the whole root file system which contains the new kernel in its /boot folder:

run setupdate
run update_rootfs

i.MX 7 and Vybrid Based Modules (V2.6 and newer)

Prepare the SD card as described in Flashing Embedded Linux to Vybrid Modules resp. Flashing Embedded Linux to iMX7 Modules. Then, copy the Kernel and device tree directly onto the SD card (replace <board> with colibri-vf or colibri-imx7):

cp ~/linux-toradex/arch/arm/boot/zImage /media/<path-to-partition-1>/<board>/
cp ~/linux-toradex/arch/arm/boot/dts/vf500-colibri-eval-v3.dtb /media/<path-to-partition-1>/<board>/
cp ~/linux-toradex/arch/arm/boot/dts/vf610-colibri-eval-v3.dtb /media/<path-to-partition-1>/<board>/
run setupdate
run prepare_ubi
run update_fdt
run update_kernel

T30, TK1 & i.MX 6 Based Modules

Prepare an SD card as described in:

Replace the existing uImage and, if applicable, the device tree in the first partition of your SD card (replace <board> with apalis-t30, apalis-tk1, colibri-t30, apalis-imx6, or colibri-imx6).

cp ~/linux-toradex/arch/arm/boot/uImage /media/<path-to-partition-1>/<board>/
cp ~/linux-toradex/arch/arm/boot/dts/imx6q-apalis-eval.dtb /media/<path-to-partition-1>/<board>/

Boot the module to the U-Boot prompt and update the kernel and, if applicable, the device tree:

run setupdate
run update_kernel
run update_fdt

Note: Refer to the Flashing Embedded Linux articles above if the module is not able to boot into U-Boot.

Kernel Module Deployment

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

If kernel modules were compiled, they may be deployed 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 afterwards
  • directly to a NFS rootfs location
  • a temporary folder, after which the kernel modules must be separately installed on the target as follows:

    cd <path-to-rootfs>/
    tar cjvf kernel-modules.tar.bz2 lib/modules/*
    #copy the file to the target
    #extract on the target as follows:
    cd /
    tar xjvf kernel-modules.tar.bz2
    

    Alternatively in one command copying through ssh (using scp for the whole installation folder does not work well since the module tree contains a symlink to the kernel sources):

    cd <path-to-rootfs>/
    tar -cf - . | ssh root@192.168.10.70 'cd / && tar -xf -'
    

Note: The kernel and any kernel modules must to be deployed as matching versions.

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