Search by Tags

Build Apalis iMX8/Colibri iMX8X OpenEmbedded/Yocto Project Bring-up Image


Article updated at 27 Sep 2019
Compare with Revision

Subscribe for this article updates

Attention: this content is obsolete in the context of Toradex BSPs and kept only for archiving purposes. Moving forward we provide (or will provide) support in our Embedded Linux BSP and Torizon. To build from source, please check our regular articles OpenEmbedded (core) and Build U-Boot and Linux Kernel from Source Code.

This article describes how to build the Yocto/OpenEmbedded validation image for the Apalis iMX8/Colibri iMX8X modules.

Module SoC NXP BSP on which the Image is based
Apalis iMX8QM V1.0A NXP® i.MX 8QuadMax A0 Silicon morty-4.9.51-8qm_beta2
Apalis iMX8QM V1.0B NXP® i.MX 8QuadMax B0 Silicon sumo-4.14.78-1.0.0_ga
Colibri iMX8QXP V1.0A NXP® i.MX 8QuadXPlus A0 Silicon rocko-4.9.123-2.3.0_8mm_ga
Colibri iMX8QXP V1.0B NXP® i.MX 8QuadXPlus B0 Silicon sumo-4.14.78-1.0.0_ga


The Yocto/OpenEmbedded layers for the image are stored on Github:

The U-Boot and Linux kernel source code with the Toradex hardware specific modifications is stored on When building an image using the OpenEmbedded/Yocto Project build system the U-Boot boot loader and Linux kernel will automatically be downloaded from those repositories during build.


Module Yocto Project Codename / Version manifest-branch manifest-file
Apalis iMX8QM V1.0A morty / 2.2 toradex-linux-morty toradex-4.9.51-8qm_beta2_bring_up.xml
Apalis iMX8QM V1.0B sumo / 2.5 toradex-linux-sumo toradex-4.14.78-1.0.0_ga.xml
Colibri iMX8QXP V1.0A rocko / 2.4 toradex-linux-rocko toradex-4.9.123-2.3.0-8mm_ga.xml
Colibri iMX8QXP V1.0B sumo / 2.5 toradex-linux-sumo toradex-4.14.78-1.0.0_ga.xml

Please make sure you use a supported Linux distribution and install required prerequisites as documented by the Yocto Project Reference Manual System Requirements chapter.

For easier git repository management the utility repo is used. The repo bootstrap binary can be installed using the following commands:

mkdir ~/bin
export PATH=~/bin:$PATH
curl > ~/bin/repo
chmod a+x ~/bin/repo

Build Environment Setup

Use the manifest-branch and manifest-file values from the table above.

mkdir imx-yocto-bsp
cd imx-yocto-bsp
repo init -u git:// -b <manifest-branch> -m <manifest-file>
repo sync

When this process is completed, the source code is checked out into the directory imx-yocto-bsp/sources.

Image Build

Module machine distro build directory
Apalis iMX8QM V1.0A apalis-imx8 fsl-imx-x11 build
Apalis iMX8QM V1.0B apalis-imx8 fsl-imx-xwayland build
Colibri iMX8QXP colibri-imx8qxp fsl-imx-xwayland build

Note: With the rocko-4.9.123-2.3.0_8mm_ga NXP dropped support for X11 on i.MX8, so we use XWayland instead.

MACHINE=<machine> DISTRO=<distro> source -b <build directory>

And build an image using

bitbake -k fsl-image-validation-imx

Depending on the performance of your machine this can take several hours. Once the build is completed you can find the build output in the folder tmp/deploy/images/<machine>/.
The file <image-recipe>-<machine>-<timestamp>.rootfs.sdcard.bz2 contains the compressed SD card image which was built. E.g. fsl-image-validation-imx-apalis-imx8-20181112152953.rootfs.sdcard.bz2.
The SD card image contains a completely bootable system, including the SCU firmware, boot loader, a FAT boot partition with the Linux kernel and device tree and an ext4 rootfs partition.

Image Deployment


Since Apalis iMX8/Colibri iMX8X V1.0A early access samples currently boot from an SD card, the image can be directly written to an SD card. Use lsblk or a similar utility to find the SD card on your Linux host machine. All data on it will be destroyed! Make sure to unmount any mounted partition first (e.g. using umount).

Write the resulting image to an SD card (depending on your Linux host replace <sdcard> with /dev/sdX or /dev/mmcblkX)

sudo umount /dev/<sdcard>?
bzcat fsl-image-validation-imx-apalis-imx8-20181112152953.rootfs.sdcard.bz2 | sudo dd of=/dev/<sdcard> bs=4M

Note: An SD Card of at least 8 GB is required.

eMMC Boot

Apalis iMX8/Colibri iMX8X V1.0B sample modules are strapped to boot from eFuses which are factory fused to boot from eMMC. To load U-Boot into the RAM of the module for recovery purpose the universal update utility (uuu) aka mfgtools 3.0 provided by NXP may be used. (universal update utility)

Extract the boot container (containing among other things U-Boot) from your image:

bunzip2 -c fsl-image-validation-imx-apalis-imx8-20190429141630.rootfs.sdcard.bz2 | dd of=flash.bin bs=512 count=2048 skip=64

, resp.:

bunzip2 -c fsl-image-validation-imx-colibri-imx8qxp-20190329152822.rootfs.sdcard.bz2 | dd of=flash.bin bs=512 count=2048 skip=64

Copy the extracted boot container to an SD-Card and mount it on the carrier board of your module.

Put the module into USB recovery aka serial downloader mode and connect its USB device to your development workstation host.

sudo ./uuu flash.bin

Note: If uuu fails to execute the creation of a symbolic link as follows might be necessary: sudo ln -s /usr/lib64/ /usr/lib64/

Connect to the module over the serial interface, then execute the following commands in U-Boot:

Flash the boot container to the module:

mmc dev 1
load mmc 1:1 $loadaddr flash.bin
setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt ${blkcnt} / 0x200
mmc dev 0 1
mmc write ${loadaddr} 0x0 ${blkcnt}

Enable UMS on the module to flash the image into eMMC:

ums 0 mmc 0

Find the eMMC block device with lsblk or similar on your host machine. Write the image directly to the Colibri iMX8X eMMC from your host:

bzcat fsl-image-validation-imx-apalis-imx8-20190429141630.rootfs.sdcard.bz2 | sudo dd of=/dev/<ums> bs=4M

, resp.:

bzcat fsl-image-validation-imx-colibri-imx8qxp-20190329152822.rootfs.sdcard.bz2 | sudo dd of=/dev/<ums> bs=4M

Stop UMS on the module with CTRL + C and set the environment to default:

env default -a; saveenv

More Resources