Search by Tags

Flashing Embedded Linux to Tegra Modules

 

Article updated at 19 Feb 2019
Compare with Revision




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.

Note: Legacy flashing method does not imply that the embedded Linux image is legacy. There are pre-built Toradex images that are provided in both legacy and Toradex Easy Installer formats. Consult the image releases for a list of images in both formats.

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 article describes the legacy bring-up aka flashing resp. updating of Embedded Linux on the Tegra family of modules.

For information concerning the recovery mode refer to the following article Txx Recovery Mode.

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.

Note: Legacy flashing method does not imply that the embedded Linux image is legacy. There are pre-built Toradex images that are provided in both legacy and Toradex Easy Installer formats. Consult the image releases for a list of images in both formats.

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.

  1. 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
Tux 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
Tux Linux Console Image Colibri VFxx (2.8.7 | 2020-06-10) Linux Image without graphical user interface
Older releases
  1. 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!

  2. 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
  1. 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 T30

Apalis T30 Release Notes

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 updating from a V2.3 Beta 2 or older BSP:

  • Apply power or reset
  • Hit any key to stop auto booting
  • Using the SD/MMC 8bit (X18) socket on the EvalBoard use the following U-Boot commands:
Apalis T30 # setenv board_name apalis_t30
Apalis T30 # setenv drive 1
Apalis T30 # setenv interface mmc
Apalis T30 # setenv migrate_uboot 'mmc dev ${drive} 0; fatload ${interface} ${drive}:1 ${loadaddr} ${board_name}/${board_name}.img && mmc dev 0 1 && mmc write ${loadaddr} 0x0 0x500'
Apalis T30 # run migrate_uboot
  • Using the SD/MMC 4bit (X19) socket on the EvalBoard or the micro SD card socket (X10) on Ixora use the following U-Boot commands:
Apalis T30 # setenv board_name apalis_t30
Apalis T30 # setenv drive 2
Apalis T30 # setenv interface mmc
Apalis T30 # setenv migrate_uboot 'mmc dev ${drive} 0; fatload ${interface} ${drive}:1 ${loadaddr} ${board_name}/${board_name}.img && mmc dev 0 1 && mmc write ${loadaddr} 0x0 0x500'
Apalis T30 # run migrate_uboot

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
Apalis T30 # run setupdate
Apalis T30 # run update

If you updated from a V2.3 beta 2 or older BSP:

  • Power cycle or reset as requested and hit any key to stop auto booting
  • Use the 'run setupdate' U-Boot command and then
  • Use the 'run migrate_v2.3b2' U-Boot command
Apalis T30 # run setupdate
Apalis T30 # run migrate_v2.3b2

If you updated from an older image:

  • Power cycle or reset and hit any key to stop auto booting
  • 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 T30 # printenv
Apalis T30 # env default -a
Apalis T30 # saveenv

Apalis TK1

Apalis TK1 Release Notes

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, albeit in 4-bit only mode) 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)

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
Apalis TK1 # run setupdate
Apalis TK1 # run update

If you updated from an older image:

  • Power cycle or reset and hit any key to stop auto booting
  • 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 TK1 # printenv
Apalis TK1 # env default -a
Apalis TK1 # saveenv

Colibri T20

Stable V2.3 and earlier BSPs

Please consult the Colibri T20 Release Notes for detailed flashing instructions.

V2.4 Beta 1 and later BSPs

Colibri T20 Release Notes

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)

If updating from a V2.3 or older BSP:

  • Put the module into recovery mode and connect the USB client aka device cable to your development workstation according to the Txx Recovery Mode article
  • Download U-Boot directly into RAM using the -d aka debug parameter of the update.sh script
  • Initiate the actual flashing procedure as explained below

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 T20 # run setupdate
Colibri T20 # run update

If updating from a V2.3 or older BSP:

  • Power cycle or reset as requested and hit any key to stop auto booting
  • Use 'run setupdate' U-Boot command and then
  • Use 'run migrate_v2.3b7' U-Boot command
Colibri T20 # run setupdate
Colibri T20 # run migrate_v2.3b7

If you updated from an older image:

  • Power cycle or reset and hit any key to stop auto booting
  • 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
Colibri T20 # printenv
Colibri T20 # env default -a
Colibri T20 # saveenv

Colibri T30

Colibri T30 Release Notes

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)

If updating from a V2.3 Beta 1 or older BSP:

  • Apply power or reset
  • Hit any key to stop auto booting
  • Use the following U-Boot commands:
Colibri T30 # setenv board_name colibri_t30
Colibri T30 # setenv drive 1
Colibri T30 # setenv interface mmc
Colibri T30 # setenv migrate_uboot 'mmc dev ${drive} 0; fatload ${interface} ${drive}:1 ${loadaddr} ${board_name}/${board_name}.img && mmc dev 0 1 && mmc write ${loadaddr} 0x0 0x500'
Colibri T30 # run migrate_uboot

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 T30 # run setupdate
Colibri T30 # run update

If updating from a V2.3 Beta 1 or older BSP:

  • Power cycle or reset as requested and hit any key to stop auto booting
  • Use 'run setupdate' U-Boot command and then
  • Use 'run migrate_v2.3b1' U-Boot command
Colibri T30 # run setupdate
Colibri T30 # run migrate_v2.3b1

If you updated from an older image:

  • Power cycle or reset and hit any key to stop auto booting
  • 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
Colibri T30 # printenv
Colibri T30 # env default -a
Colibri T30 # saveenv

Flashing from Scratch

In case the module doesn't show any U-Boot boot loader output or hangs at very early stages or to transition from a WinCE/WEC installation refer to the Txx Recovery Mode article to download U-Boot directly into RAM.

Apalis/Colibri T30, Apalis TK1

Initiate the actual flashing using the 'run setupdate; run update' commands as detailed above on a per module type basis.

Colibri T20

From the U-Boot command prompt some additional commands makes sure that the whole NAND is erased and rewritten including the Toradex config block (production data such as serial number) is stored too.

Colibri T20 # nand erase.chip
Colibri T20 # cfgblock create
Is the module an IT version? [y/N] y
Enter the module version (e.g. V1.2A): V1.2A
Enter module serial number: 04815386
Toradex config block successfully written
Colibri T20 # run setupdate
Colibri T20 # run update
...

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

Troubleshooting

The update scripts should cope with the standard update and upgrade cases. However sometimes things can go wrong. This section helps to recover the module in those situations.

Upgrading fails with UBI init error 22

Since V2.4 we try not to delete the UBI volume to retain the erase counters and hence proper wear levelling information. This can lead to problems when using NAND flash with incompatible ECC modes or file systems (WinCE/WEC). In this case the UBI stack of U-Boot claims an "init error":

UBI: default fastmap pool size: 200
UBI: default fastmap WL pool size: 25
UBI: attaching mtd1 to ubi0
UBI: scanning is finished
UBI init error 22

To solve this issue a proper cleaning of the UBI partition is required before starting the update process:

Colibri T20 # nand erase.part ubi
...
Colibri T20 # run update
...

Bad CRC Warning

The following warning upon boot can be ignored as it just means that the U-Boot environment has never been written to flash yet and the default environment as compiled into the U-Boot binary is therefore used:

*** Warning - bad CRC, using default environment

Using the 'saveenv' command one can force writing the environment to flash:

Colibri T20 # saveenv

Update a Single Component

U-Boot

  • Use 'run setupdate' and then 'run update_uboot'
Apalis TK1 # run setupdate
Apalis TK1 # run update_uboot

Linux Kernel or Device Tree

  • Use 'run setupdate' and then 'run update_kernel' or 'run update_fdt' (where applicable) respectively.
Apalis TK1 # run setupdate
Apalis TK1 # run update_kernel
Apalis TK1 # run update_fdt

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.