Search by Tags

Build U-Boot and Linux Kernel from Source Code

 

Article updated at 11 Nov 2021
Compare with Revision




Subscribe for this article updates

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 Version Kernel Git Branch Kernel Configuration Device Tree Kernel Binary
5.3.0 / 5.4.0 toradex_5.4-2.3.x-imx toradex_defconfig imx8qm-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
View Information of Older Versions

i.MX 7 Downstream Linux Kernel Versions

BSP Version Kernel Git Branch Kernel Configuration Device Tree Kernel Binary
5.2.0 / 5.3.0 / 5.4.0 toradex_5.4-2.3.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
View Information of Older Versions

i.MX 7 Upstream Linux Kernel Versions

BSP Version Kernel Git Branch Kernel Configuration Device Tree Kernel Binary
5 toradex_5.4.y toradex-imx_v6_v7_defconfig imx7d-colibri-aster.dtb
imx7d-colibri-emmc-aster.dtb
imx7d-colibri-emmc-eval-v3.dtb
imx7d-colibri-eval-v3.dtb
imx7s-colibri-aster.dtb
imx7s-colibri-eval-v3.dtb
arch/arm/boot/zImage
View Information of Older Versions

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

i.MX 6 Downstream Linux Kernel Versions

BSP Version Kernel Git Branch Kernel Configuration Device Tree Kernel Binary
5.2.0 / 5.3.0 / 5.4.0 toradex_5.4-2.3.x-imx <board>_defconfig imx6q-apalis-eval.dtb
imx6q-apalis-ixora.dtb
imx6q-apalis-ixora-v1.1.dtb
imx6q-apalis-ixora-v1.2.dtb
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
View Information of Older Versions

i.MX 6 Upstream Linux Kernel Versions

BSP Version Kernel Git Branch Kernel Configuration Device Tree Kernel Binary
5 toradex_5.4.y toradex-imx_v6_v7_defconfig imx6q-apalis-eval.dtb
imx6q-apalis-ixora.dtb
imx6q-apalis-ixora-v1.1.dtb
imx6q-apalis-ixora-v1.2.dtb
imx6dl-colibri-eval-v3.dtb
arch/arm/boot/zImage
View Information of Older Versions

i.MX 6ULL Downstream Linux Kernel Versions

BSP Version Kernel Git Branch Kernel Configuration Device Tree Kernel Binary
5.2.0 / 5.3.0 / 5.4.0 toradex_5.4-2.3.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
View Information of Older Versions

i.MX6 ULL Upstream Linux Kernel Versions

BSP Version Kernel Git Branch Kernel Configuration Device Tree Kernel Binary
5 toradex_5.4.y toradex-imx_v6_v7_defconfig imx6ull-colibri-eval-v3.dtb
imx6ull-colibri-wifi-eval-v3.dtb
arch/arm/boot/zImage
View Information of Older Versions

Vybrid Linux Kernel Versions

BSP 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

Note: Valid values for <board> are either apalis_t30, colibri_t20 or colibri_t30.

Tegra T20/T30 Downstream Linux Kernel Versions

BSP 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 and later tegra <board>_defconfig - arch/arm/boot/zImage

Tegra K1 Downstream Linux Kernel Versions

BSP 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 and later / 3 toradex_tk1_l4t_r21.7 <board>_defconfig tegra124-apalis-v1.2-eval.dtb
tegra124-apalis-eval.dtb
arch/arm/boot/zImage

Tegra K1 Mainline/Upstream Linux Kernel Versions

BSP 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 and later linux-4.14.y tegra_defconfig tegra124-apalis-v1.2-eval.dtb
tegra124-apalis-eval.dtb
arch/arm/boot/zImage rocko patches
3 linux-4.14.y tegra_defconfig tegra124-apalis-v1.2-eval.dtb
tegra124-apalis-eval.dtb
arch/arm/boot/zImage thud patches
4 linux-4.14.y tegra_defconfig tegra124-apalis-v1.2-eval.dtb
tegra124-apalis-eval.dtb
arch/arm/boot/zImage zeus patches
5 linux-5.4.y tegra_defconfig tegra124-apalis-v1.2-eval.dtb
tegra124-apalis-eval.dtb
arch/arm/boot/zImage toradex_5.4.y branch

U-Boot Version

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

BSP Version U-Boot Git Branch U-Boot Configuration U-Boot Binary
3.0b1 / 3.0b2 / 3.0b3 toradex_imx_v2018.03_4.14.78_1.0.0_ga-bringup apalis-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 / 4 toradex_imx_v2018.03_4.14.98_2.3.0_bringup apalis-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.0 toradex_imx_v2020.04_5.4.24_2.1.0 apalis-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 toradex_imx_v2020.04_5.4.70_2.3.0 apalis-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

i.MX 7 U-Boot Versions

BSP 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 / 4 toradex_2019.07 colibri_imx7_defconfig
colibri_imx7_emmc_defconfig
u-boot-nand.imx
u-boot.imx
5 toradex_2020.07 colibri_imx7_defconfig
colibri_imx7_emmc_defconfig
u-boot-nand.imx
u-boot.imx

Note: Valid values for <board> are either apalis_imx6 or colibri_imx6. Note: Starting with BSP 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 BSPs 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 BSPs older than V2.4, the U-Boot values are apalis_imx6q1g, apalis_imx6q2g, colibri_imx6s256m.

i.MX 6 U-Boot Versions

BSP 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 and later 2016.11-toradex <board>_defconfig SPL, u-boot.img
3 / 4 toradex_2019.07 <board>_defconfig SPL, u-boot.img
5 toradex_2020.07 <board>_defconfig SPL, u-boot.img

i.MX 6ULL U-Boot Versions

BSP 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 / 4 toradex_2019.07 colibri-imx6ull_defconfig u-boot-nand.imx
5 toradex_2020.07 colibri-imx6ull_defconfig u-boot-nand.imx

Vybrid U-Boot Versions

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

Note: Valid values for <board> are either apalis_t30, colibri_t20 or colibri_t30.

Tegra U-Boot Versions

BSP 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

Tegra U-Boot Versions

BSP Version U-Boot Git Branch U-Boot Configuration U-Boot Binary
V2.4 / V2.5 / V2.6 2015.04-toradex apalis-tk1_defconfig u-boot-dtb-tegra.bin
2.7 / 2.8 2016.11-toradex apalis-tk1_defconfig u-boot-dtb-tegra.bin
3 / 4 toradex_2019.07 apalis-tk1_defconfig u-boot-dtb-tegra.bin
5 toradex_2020.07 apalis-tk1_defconfig u-boot-dtb-tegra.bin

Device Tree Overlays Version

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

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

i.MX 7 Downstream Device Tree Overlays Versions

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

iMX7 Upstream Device Tree Overlays Versions

BSP Version Device Tree Overlays Git Branch Device Tree Overlays Binaries
4 / 5 toradex_5.4.y *.dtbo

i.MX 6 Downstream Device Tree Overlays Versions

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

i.MX 6 Upstream Device Tree Overlays Versions

BSP Version Device Tree Overlays Git Branch Device Tree Overlays Binaries
4 / 5 toradex_5.4.y *.dtbo

i.MX 6ULL Downstream Device Tree Overlays Versions

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

i.MX 6ULL Upstream Device Tree Overlays Versions

BSP Version Device Tree Overlays Git Branch Device Tree Overlays Binaries
4 / 5 toradex_5.4.y *.dtbo

Tegra K1 Upstream Device Tree Overlays Versions

BSP Version Device Tree Overlays Git Branch Device Tree Overlays Binaries
5 toradex_5.4.y *.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

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-aarch64-none-linux-gnu.tar.xz "https://developer.arm.com/-/media/Files/downloads/gnu-a/9.2-2019.12/binrel/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu.tar.xz?revision=61c3be5d-5175-4db6-9030-b565aae9f766&la=en&hash=0A37024B42028A9616F56A51C2D20755C5EBBCD7"
$ tar xvf gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu.tar.xz
$ ln -s gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu 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=arm64
$ export DTC_FLAGS="-@"
$ export PATH=~/gcc-linaro/bin/:$PATH
$ export CROSS_COMPILE=aarch64-none-linux-gnu-

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

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

Beginning with BSP 4, as part of our OpenEmbedded Zeus update we transitioned to using version 8.3 of the gcc compiler. Arm releases well tested binary toolchains which can be used to cross-compile software for our modules:

  • For 32 bit Arm: gcc-arm-8.3-2019.03-x86_64-arm-linux-gnueabihf.tar.xz
  • For 64 bit Arm: gcc-arm-8.3-2019.03-x86_64-aarch64-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-8.3-2019.03-x86_64-arm-linux-gnueabihf.tar.xz "https://developer.arm.com/-/media/Files/downloads/gnu-a/8.3-2019.03/binrel/gcc-arm-8.3-2019.03-x86_64-arm-linux-gnueabihf.tar.xz?revision=e09a1c45-0ed3-4a8e-b06b-db3978fd8d56&la=en&hash=93ED4444B8B3A812B893373B490B90BBB28FD2E3"
$ tar xvf gcc-arm-8.3-2019.03-x86_64-arm-linux-gnueabihf.tar.xz
$ ln -s gcc-arm-8.3-2019.03-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.

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

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

$ cd ~
$ wget -O gcc-arm-8.3-2019.03-x86_64-aarch64-linux-gnu.tar.xz "https://developer.arm.com/-/media/Files/downloads/gnu-a/8.3-2019.03/binrel/gcc-arm-8.3-2019.03-x86_64-aarch64-linux-gnu.tar.xz?revision=2e88a73f-d233-4f96-b1f4-d8b36e9bb0b9&la=en&hash=167687FADA00B73D20EED2A67D0939A197504ACD"
$ tar xvf gcc-arm-8.3-2019.03-x86_64-aarch64-linux-gnu.tar.xz
$ ln -s gcc-arm-8.3-2019.03-x86_64-aarch64-linux-gnu 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=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=arm64" >> ~/export_compiler
$ echo "export PATH=~/gcc-linaro/bin/:$PATH" >> ~/export_compiler
$ echo "export CROSS_COMPILE=aarch64-linux-gnu-" >> ~/export_compiler
$ source ~/export_compiler

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:

  • For 32 bit Arm: gcc-arm-8.2-2019.01-x86_64-arm-linux-gnueabihf.tar.xz
  • For 64 bit Arm: gcc-arm-8.2-2019.01-x86_64-aarch64-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-8.2-2019.01-x86_64-arm-linux-gnueabihf.tar.xz "https://developer.arm.com/-/media/Files/downloads/gnu-a/8.2-2019.01/gcc-arm-8.2-2019.01-x86_64-arm-linux-gnueabihf.tar.xz?revision=c69ea519-a965-4359-84a4-cbd440ff4130&la=en&hash=09C47C70EEE96D17EA036A7A59AE961972320A31"
$ tar xvf gcc-arm-8.2-2019.01-x86_64-arm-linux-gnueabihf.tar.xz
$ ln -s gcc-arm-8.2-2019.01-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.

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

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

$ cd ~
$ wget -O gcc-arm-8.2-2019.01-x86_64-aarch64-linux-gnu.tar.xz "https://developer.arm.com/-/media/Files/downloads/gnu-a/8.2-2019.01/gcc-arm-8.2-2019.01-x86_64-aarch64-linux-gnu.tar.xz?revision=21270570-4ec0-4bad-a9e1-09707614066a&la=en&hash=AFEDF645AF5B94336DB4E1E608806CEC87A02B8A"
$ tar xvf gcc-arm-8.2-2019.01-x86_64-aarch64-linux-gnu.tar.xz
$ ln -s gcc-arm-8.2-2019.01-x86_64-aarch64-linux-gnu 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=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=arm64" >> ~/export_compiler
$ echo "export PATH=~/gcc-linaro/bin/:$PATH" >> ~/export_compiler
$ echo "export CROSS_COMPILE=aarch64-linux-gnu-" >> ~/export_compiler
$ source ~/export_compiler

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:

  • For 32 bit Arm: gcc-linaro-7.3.1-2018.05-x86_64_arm-linux-gnueabihf.tar.xz
  • For 64 bit Arm: Embedded Linux BSP 2.8 does not support any 64 bit Arm SoMs by Toradex.

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

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

$ cd ~
$ wget -O 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/gcc-linaro-7.3.1-2018.05-x86_64_arm-linux-gnueabihf.tar.xz"
$ tar xvf gcc-linaro-7.3.1-2018.05-x86_64_arm-linux-gnueabihf.tar.xz
$ ln -s gcc-linaro-7.3.1-2018.05-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.

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

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/

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:

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

Note: on Fedora, 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.

Older Versions

U-Boot Tools

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

One can simply 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.

Build Host Tools and Dependencies

You need some essential 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 openssl-devel

For Debian/Ubuntu:

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

Building U-Boot

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

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

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

Compilation

The following is the procedure to compile the boot loader.

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

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

U-Boot: Standalone Application

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

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 8M Mini/8M Plus requires a boot container. 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 8M Mini/8M Plus family-based modules:

Boot Container Verdin iMX8M Mini/Verdin iMX8M Plus

Starting with BSP 3, we use U-Boot based on 2019.07, which dropped the NAND make targets (only required for Colibri iMX6ULL and the NAND based Colibri iMX7).

You may manually create u-boot-nand.imx as follows:

$ dd bs=10k count=1 if=/dev/zero | cat u-boot.imx - > u-boot.imx.zero-padded

# U-Boot is flashed 1k into a NAND block, create a binary which prepends
# U-boot with 1k of zeros to ease flashing
$ dd bs=1024 count=1 if=/dev/zero | cat - u-boot.imx.zero-padded > u-boot-nand.imx

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.

Warning: 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.

As an example of compressed tarball using Bash/U-Boot flashing scripts we'll use the stable release 2.8 of Linux LXDE Image for Colibri T20.

Choose the appropriate image for your SoM in the Legacy Image Format binary images list. Download it to your home directory and extract the image. From the command-line:

$ cd ~
$ wget https://developer.toradex.com/files/toradex-dev/uploads/media/Colibri/Linux/Images/Colibri-T20_LXDE-Image_2.8b6.184-20190401.tar.bz2
$ sudo tar xjvf Colibri-T20_LXDE-Image_2.8b6.184-20190401.tar.bz2

The procedure above will extract the image to the directory Colibri-T20_LXDE-Image_2.8.6 under your home.

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.

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

Colibri T20

Image V2.3 & Older

The following procedure is to flash just the new boot loader (assumes the 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

Warning: 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 &amp; 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 BSP 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 BSPs 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: BSPs 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.

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

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/linux-toradex.git).

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:

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

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 7 Based Kernel (Colibri iMX7S/iMX7D)

To compile the kernel & device tree for BSP 3 or newer:

$ make -j$(nproc) zImage 2>&1 | tee build.log
$ make DTC_FLAGS="-@" <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

To compile the kernel & device tree for BSP 2.8 or older:

$ make -j$(nproc) zImage 2>&1 | tee build.log
$ make <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

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 -j$(nproc) zImage LD=${CROSS_COMPILE}ld.bfd | tee build.log

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

Starting with Apalis iMX6 BSP V2.3 Beta 1 and 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 for BSP 2.8b2 or newer:

$ make -j$(nproc) zImage LOADADDR=10008000 2>&1 | tee build.log
$ make DTC_FLAGS="-@" <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

To compile the kernel & device tree for BSP 2.8b1 or older:

$ make -j$(nproc) uImage LOADADDR=10008000 2>&1 | tee build.log
$ make <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 6ULL Based Kernel (Colibri iMX6ULL)

To compile the kernel & device tree for BSP 3 or newer:

$ make -j$(nproc) zImage 2>&1 | tee build.log
$ make DTC_FLAGS="-@" <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

To compile the kernel & device tree for BSP 2.8 or older:

$ make -j$(nproc) zImage 2>&1 | tee build.log
$ make <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

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 -j$(nproc) zImage LD=${CROSS_COMPILE}ld.bfd | tee build.log

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 volume and in the zImage format.

To compile the Kernel & device tree:

$ make -j$(nproc) zImage | tee build.log
$ make <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

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 -j$(nproc) zImage LD=${CROSS_COMPILE}ld.bfd | tee build.log

Tegra K1 Based Kernel (Apalis TK1)

To compile the kernel & device trees for BSP 3 or newer:

Everything at once:

$ make -j12 | tee build.log

Only the device tree:

$ make DTC_FLAGS="-@" <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

For BSPs prior to BSP 2.8b2 where the Linux kernel binary was still deployed in the uImage format one had to build things separately e.g. as follows:

$ make -j$(nproc) uImage LOADADDR=0x80008000 2>&1 | tee build.log
$ make <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

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

To compile the Kernel:

$ make -j$(nproc) 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 -j$(nproc) uImage LD=${CROSS_COMPILE}ld.bfd | tee build.log

Linux Kernel Module Compilation

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 -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 /

Note: You may also integrate your kernel modules into the root file system archive inside a Toradex Easy Installer package where applicable. Note: The Kernel and any kernel modules must be deployed as matching versions. Note: 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.

Legacy BSP Images

Colibri T20

BSP 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

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

BSP 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 on 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.

BSP 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 &amp; 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.

Building the Device Tree Overlays

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

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/device-tree-overlays.git).

Device Tree Overlays Compilation using make

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

Warning: 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.