Flashing Embedded Linux to iMX6 Modules

Applicable for

Apalis iMX6 | Colibri iMX6

BSP Layers / Reference Images for Yocto (Linux)

Prerequisites

The preparation steps need to be executed on a x86-64 development host running a Linux distribution (e.g. Fedora or Ubuntu). Please note that there is no support for 32 bit hosts.

The following host applications and libraries are a pre-requisite for executing the update script and the 64-bit host tools contained in the image tarball.

E.g. for Ubuntu 14.04 (64-bit)

sudo apt-get update
sudo apt-get install dosfstools e2fsprogs gawk mtools parted
sudo apt-get install zlib1g liblzo2-2 libuuid1 libusb-1.0-0

E.g. for Fedora 21 (64-bit)

yum install dosfstools e2fsprogs gawk mtools parted 
yum install zlib lzo libuuid libusbx

On older distros (e.g. Ubuntu 12.04) the tool to create a FAT filesystem was named mkfs.vfat while the update.sh script uses mkfs.fat. If you get an error that mkfs.fat is missing then find the full path to mkfs.vfat and create a symlink by doing the following:

trdx@trdx:~$ sudo sh -c "command -v mkfs.vfat"
/sbin/mkfs.vfat
trdx@trdx:~$ sudo ln -s /sbin/mkfs.vfat /sbin/mkfs.fat

Preparation

It is possible to flash an embedded Linux image to a target module using two methods:

Toradex Easy Installer flashing: the preferred method for flashing. Check out the Toradex Easy Installer article for comprehensive information, including supported and pre-installed modules.
Legacy flashing: the flashing method prior to Toradex Easy Installer, uses bash script.

Attention: If your Computer on Module is supported by the Toradex Easy Installer, the legacy flashing method is considered deprecated and you shouldn't use it.

This prepares a SD card or USB flash drive for later use on the carrier board with the module which is to be flashed.

Download the binary image and extract it with root permissions. The binary image files are named as follows:
- Starting with version 2.7.2: <module-type>_<image-name>_<version>.tar.bz2 where <module_type> is one of Apalis TK1, Apalis T30, Apalis/Colibri iMX6, Colibri iMX7, Colibri-T20, Colibri-T30, or Colibri-VF and is one of LXDE-Image or Console-Image.
- Older versions: <module_type>_LinuxImageVx.yz.tar.bz2 where <module_type> is one of Colibri_T20, Colibri_T30 or Colibri_VF.

You can find all the latest pre-built images in Binary Images, both in the legacy as well as the Toradex Easy Installer formats, or conveniently in the tables below, only in the legacy image format:

Toradex Embedded Linux Stable Releases

	OS Image	Supported Modules/Download Link	Summary Overview
	Linux LXDE Image	Apalis TK1 (2.8.7 \| 2020-06-10) Apalis TK1 Mainline (2.8.7 \| 2020-06-10) Apalis T30 (2.8.7 \| 2020-06-10) Apalis iMX6 (2.8.7 \| 2020-06-10) Colibri T30 (2.8.7 \| 2020-06-10) Colibri T20 (2.8.7 \| 2020-06-10) Colibri iMX6 (2.8.7 \| 2020-06-10) Colibri iMX7 (2.8.7 \| 2020-06-10) Colibri VFxx (2.8.7 \| 2020-06-10)	Angstrom LXDE desktop environment image
	Linux Console Image	Colibri VFxx (2.8.7 \| 2020-06-10)	Linux Image without graphical user interface

Older releases

Use any FAT formatted SD/uSD card or USB flash drive with enough free space (1GB or more recommended).

Note: U-Boot expects a partition table (MBR) on the SD card or USB flash drive and the FAT partition to be the first partition!
Find the mount point of your SD/uSD card or USB flash drive by e.g. using df or lsblk:

    [user@host ~]$ df
    Filesystem              1K-blocks      Used Available Use% Mounted on
    ...
    /dev/mmcblk0p1            7582228   2808272   4773956  38% /media/KERNEL
    [user@host ~]$ lsblk
    NAME                         MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINT
    ...
    mmcblk0                      179:0    0   7.3G  0 disk  
    └─mmcblk0p1                  179:1    0   7.3G  0 part  /media/KERNEL

Run the update.sh script with the -o argument pointing to the mount point of the SD card or USB flash drive. For example assuming the SD card is mounted at /media/KERNEL:

    ./update.sh -o /media/KERNEL/

At this point the SD/uSD card or USB flash drive should contain U-Boot, optionally the Linux kernel, the flashing scripts and the ext3 (for eMMC modules) resp. UBI (for NAND modules) root file system images.

Apalis iMX6

Apalis iMX6 Release Notes

For information concerning the recovery mode refer to Section 6 i.e. Recovery mode of the Apalis iMX6 datasheet and to the iMX Recovery Article.

Warning: Make sure there is no SD card inserted in the carrier board in order to enter recovery mode properly

EvalBoard V1.0A/V1.1A:

Depending on JP10/12 connect the serial debug console to the lower X28 using a null modem RS-232 cable or X29 using a regular USB cable.
Insert the SD card as prepared above into the SD/MMC 8bit (X18) or SD/MMC 4bit (X19) socket.

Ixora V1.0A:

Connect the serial debug console to X22 using a null modem RS-232 cable and a 10 pin IDC to 9 pin D-sub male connector (DTK or Intel standard).
Insert the micro SD card as prepared above into the SD card socket (X10).
If you update from a V2.2 BSP either use an EvalBoard for update or on Ixora use the following U-Boot commands:

Apalis iMX6 # setenv drive 2
Apalis iMX6 # setenv setupdate 'fatload mmc ${drive}:1 ${loadaddr} flash_mmc.img; source ${loadaddr}'
Apalis iMX6 # saveenv

Boot to U-Boot Prompt and Start the Update:

Apply power or reset.
Hit any key to stop auto booting.
Use the 'run setupdate' U-Boot command and then
For image version prior to V2.7 use 'run update_it' for an industrial temperature grade module, use 'run update' for a commercial temperature grade module.
For image version V2.7 and later use 'run update'

Apalis iMX6 # run setupdate
Apalis iMX6 # run update_it

If you updated from an older BSP (without a device tree).

Power cycle or reset and hit any key to stop autobooting.
Use 'printenv' to get your current U-Boot environment.
Use 'env default -a' to set the U-Boot environment to its default value.
Optionally change the environment to your needs.
Use 'saveenv' to make the changes permanent.

Apalis iMX6 # printenv
Apalis iMX6 # env default -a
Apalis iMX6 # saveenv

If you update to a BSP V2.6 Beta 1 or later, the update scripts will migrate to eMMC Fast Boot mode. The article Linux - Booting provides detailed information about eMMC Fast Boot mode. During the update, you will be asked to power cycle the board, and perform fusing.

...
MMC write: dev # 0, block # 2, count 614 ... 614 blocks written: OK
done.
successfully updated U-Boot, power-cycle and enter "run setupdate; run migrate" to complete update
Apalis iMX6 #

At this point, it is important to turn the module off and back on. Then continue with:

Apalis iMX6 # run setupdate; run migrate
...
MMC write: dev # 0, block # 2, count 614 ... 614 blocks written: OK
done.
Fuse 0, 5:     5062
Warning: Programming fuses is an irreversible operation!
         Updating to fast boot mode prevents easy
         downgrading to previous BSP versions.

Really perform this fuse programming? 
y
...

Update a Single Component

U-Boot

For image version prior to V2.7 use 'run update_uboot_it' for an industrial temperature grade module, use 'run update_uboot' for a commercial temperature grade module.
For image version V2.7 and later use 'run update_uboot'.

Apalis iMX6 # run setupdate
Apalis iMX6 # run update_uboot_it

Linux Kernel or Device Tree

Use 'run setupdate' and then 'run update_kernel' or 'run update_fdt' respectively.

Apalis iMX6 # run setupdate
Apalis iMX6 # run update_kernel
Apalis iMX6 # run update_fdt

SPL

Image version V2.7 and later use an additional bootloader component called SPL. It usually need not be updated.

Apalis iMX6 # run setupdate
Apalis iMX6 # run update_spl

Colibri iMX6

Colibri iMX6 Release Notes

For information concerning the recovery mode refer to Section 6. Recovery mode of the Colibri iMX6 datasheet and to the iMX Recovery Article.

Warning: Make sure there is no SD card inserted in the carrier board in order to enter recovery mode properly

EvalBoard V3.1A/V3.2A:

Depending on JP17/19 connect the serial debug console to UARTA aka FFUART (lower X25) using a null modem RS-232 cable resp. X27 using a regular USB cable
Insert the SD card as prepared above into the SD/MMC socket (X15)

Iris V1.1A:

Connect the serial debug console to UARTA aka FFUART X13 using a null modem RS-232 cable and a 10 pin IDC to 9 pin D-sub male connector (DTK or Intel standard).
Insert the micro SD card as prepared above into the micro SD card socket (X10)

Boot to U-Boot Prompt and Start the Update:

Apply power or reset
Hit any key to stop auto booting
Use the 'run setupdate' U-Boot command and then
Use the 'run update' U-Boot command

Colibri iMX6 # run setupdate
Colibri iMX6 # run update

...
MMC write: dev # 0, block # 2, count 614 ... 614 blocks written: OK
done.
successfully updated U-Boot, power-cycle and enter "run setupdate; run migrate" to complete update
Colibri iMX6 #

At this point, it is important to turn the module off and back on. Then continue with:

Colibri iMX6 # run setupdate; run migrate
...
MMC write: dev # 0, block # 2, count 614 ... 614 blocks written: OK
done.
Fuse 0, 5:     5062
Warning: Programming fuses is an irreversible operation!
         Updating to fast boot mode prevents easy
         downgrading to previous BSP versions.

Really perform this fuse programming? 
y
...

Update a Single Component

U-Boot

Use 'run setupdate' and then 'run update_uboot'

Colibri iMX6 # run setupdate
Colibri iMX6 # run update_uboot

Kernel or Linux Device Tree

Use 'run setupdate' and then 'run update_kernel' or 'run update_fdt' respectively

Colibri iMX6 # run setupdate
Colibri iMX6 # run update_kernel
Colibri iMX6 # run update_fdt

SPL

Image version V2.7 and later use an additional bootloader componenent called SPL. It usually need not be updated.

Colibri iMX6 # run setupdate
Colibri iMX6 # run update_spl

Flashing from Scratch

In case the module doesn't show any boot loader output, hangs at very early stages or for migration from WinCE follow the iMX Recovery Mode article.

Warning: Make sure there is no SD card inserted in the carrier board in order to enter recovery mode properly

USB speed:

If the host is USB 2.0 high speed capable this will be used. So make sure that the carrier board supports USB high speed. All Apalis carrier boards and Iris & EvalBoard V3.1a are OK, for other carrier boards see http://developer.toradex.com/knowledge-base/usb-2.0-high-speed-%28480mbps%29.

Recovery Mode:

After entering Recovery Mode, load U-Boot over USB to the module's RAM:
- lsusb on host should show a 15a2:0054 NXP/Freescale Semiconductor, Inc. device if the module is in recovery mode.
- run ./update.sh -d on host.
- stop at the U-Boot prompt
- for image version V2.7 and later execute run setupdate; run update_spl in U-Boot.
- begin the update as stated for the respective modules above.

Config Block

A module can get its Config Block erased which is indicated by the following warning in the U-Boot output.

...
Out:   serial
Err:   serial
Missing Toradex config block
Model: Toradex Apalis iMX6 1GB
...

To recover it run the U-Boot cfgblock command:

Apalis iMX6 # cfgblock create
Is the module an IT version? [y/N] n
Enter the module version (e.g. V1.1B): V1.0A
Enter module serial number: 12582964
Toradex config block successfully written

Note: The cfgblock create command is available since BSP release V2.4 Beta 1 (U-Boot 2015.04). To recover the config block for older U-Boot versions use the configblock.sh script and copy the configblock.bin file to the SD card. Then use 'run setupdate && run update_configblock'.

Serial Console

Please note that to be at the U-Boot prompt one needs to open the /dev/ttySx or /dev/ttyUSBx port with a terminal emulation program like minicom on Linux or a CoMx port on Windows with puTTY with a baud rate of 115200 baud, 8 data bits, no parity and one stop bit without any hardware/software flow control.

Need more help?

Ask the experts in our Community!