Search by Tags

Distro Boot

Applicable for

Subscribe for this article updates

Distro Boot also referred to as Generic Distro Configuration Concept, comprises a set of standards and features that are required for a Linux distribution to support a specific board in a generic way. This concept is comprehensively explained in the U-Boot documentation - Generic Distro Configuration Concept.

The Embedded Linux BSP supported by Toradex provides U-Boot and its default environment compliant with Distro Boot since version 2.7b1.

Warning: Distro Boot has a known issue on Colibri iMX6 and Apalis iMX6 modules. Please check the current status on the Release Details.

How to Use

Prepare a boot media compliant to Distro Boot (see section Preparing a Distro Boot Media below), for instance, an SD card or USB stick, and insert it in the corresponding connector of the Toradex carrier board.

Note: Fedora for ARM®-based Computers is known to comply with the Distro Boot concept out-of-the-box at least for the 32-bit armhfp images. One may just write such an image to its boot media without any kind of further manual preparatory steps required.

Power-on the board and stop the U-Boot bootloader. If you are unsure how to access the U-Boot terminal, learn how to access the serial console by watching the Using the Serial Console with Toradex Computer Modules video or go through the lessons of the Module 1 of the Toradex Getting Started Guide.

One Time Boot

Run the Distro Boot command:

# setenv fdtfile ${soc}-colibri-${fdt_board}.dtb && run distro_bootcmd

The Computer on Module will boot from the external media once. After a power-cycle, it will revert to the default behaviour of booting from the internal flash. See the next section to make Distro Boot the default behaviour after reset.

Distro Boot by Default

To make Distro Boot the default U-Boot command, you can invert the default bootcmd logic which is configured trying to boot from the on-module flash storage first. See the example below for a raw NAND Computer on Module:

Colibri iMX7 # env print bootcmd
bootcmd=run ubiboot; setenv fdtfile ${soc}-colibri-${fdt_board}.dtb && run distro_bootcmd;
Colibri iMX7 # env set bootcmd 'setenv fdtfile ${soc}-colibri-${fdt_board}.dtb && run distro_bootcmd; run ubiboot;'
Colibri iMX7 # env save
Saving Environment to NAND...
Erasing NAND...
Erasing at 0x380000 -- 100% complete.
Writing to NAND... OK

The Computer on Module will boot from the external media every time the system is rebooted. In case the external media is absent it will fall back to booting from the on-module flash storage.

Preparing a Distro Boot Media

This section provides an example of how to prepare a media compliant with Distro Boot. The Linux distribution chosen for the example is Arch Linux ARM. Notice that instructions may vary among distributions and how they are provided.

Note: Toradex doesn't support Arch Linux ARM as its Embedded Linux BSP, neither recommends its usage with Toradex Computer on Modules nor any other Linux Distributions that may be provided for the ARM architecture. Please carefully evaluate the maintenance efforts of using a distribution other than the one(s) supported by Toradex.

Download a Linux Distribution

On your host PC, create a folder and download the Arch Linux ARM release from the Arch Linux ARM Downloads Section. Make sure you select an image compatible with the SoC architecture, e.g. for Colibri iMX7 which is equipped with the NXP i.MX7 SoC, choose any of the ARMv7 releases.

mkdir distro_boot && cd distro_boot

Create two directories where you will mount the boot and rootfs partitions of the media:

mkdir boot rootfs

Prepare the Boot Media

Format the media with a primary partition formatted as FAT and size of 100MB, and a secondary partition formatted as EXT4 and using all the space left in the media device. You can use a GUI tool such as Gparted or do it from command-line using fdisk and mkfs, as described below:

Create partition table:

fdisk /dev/<path-to-media>
# For instance: fdisk /dev/mmcblk0
# Press "o" to wipe the current partition table,
# Press "n" to create a new partition, "1" to make it the first partition, "ENTER" to accept the default first sector and type "+100M" to make it have 100MB.
# Press "t" and then "c" to make the first partition FAT formatted.
# Press "n" to create a new partition, "2" to make it the first partition, "ENTER" to accept the default first sector and "ENTER" to accept the default last sector.
# Press "w" to save and exit.

Create filesystems:

mkfs.vfat /dev/<path-to-media-first-partition>
mkfs.ext4 /dev/<path-to-media-second-partition>
# For instance
mkfs.vfat /dev/mmcblk0p1
mkfs.ext4 /dev/mmcblk0p2

Mount the filesystems into the previously created directories:

mount /dev/<path-to-media-first-partition> boot
mount /dev/<path-to-media-second-partition> rootfs
# For instance
mount /dev/mmcblk0p1 boot
mount /dev/mmcblk0p2 rootfs

Extract the downloaded rootfs:

bsdtar -xpf ArchLinuxARM-armv7-latest.tar.gz -C rootfs

Move the boot files to the first partition:

mv rootfs/boot/* boot

Create Distro Boot Configuration File

Create a directory extlinux and an extlinux.conf file in the boot partition. You may have to tweak the append parameter, which passes command-line options to the Linux kernel. See the bootparam documentation for more information, or inspect the default values set in the Toradex BSP by booting the board and using dmesg, for instance for Colibri iMX7D 512MB V1.1C with the Toradex Embedded Linux BSP 2.8b3:

| | .-. o o
| | |-----.-----.-----.| | .----..-----.-----.
| | | __ | ---'| '--.| .-'| | |
| | | | | |--- || --'| | | ' | | | |
'---'---'--'--'--. |-----''----''--' '-----'-'-'-'
-' |
The Angstrom Distribution colibri-imx7 ttymxc0
Angstrom v2017.12 - Kernel
Colibri-iMX7_LXDE-Image 2.8b3.111 20180627
colibri-imx7 login: root
root@colibri-imx7:~# dmesg | grep "Kernel command line"
[ 0.000000] Kernel command line: user_debug=30 ubi.mtd=ubi root=ubi0:rootfs rw rootfstype=ubifs ubi.fm_autoconvert=1 console=tty1 console=ttymxc0,115200n8 consoleblank=0 video=mxsfb:640x480M-16@60

Create the file:

ui menu.c32 menu autoboot Arch Boot. Automatic boot in # second{,s}. Press a key for options. menu title Arch Boot Options. menu hidden timeout 50 default Arch label Arch kernel /zImage append root=/dev/mmcblk0p2 rw rootfstype=ext4 rootwait consoleblank=0 no_console_suspend=1 console=ttymxc0,115200n8 fdtdir /dtbs initrd /initramfs-linux.img

Note: In this example, the kernel, device-tree and initramfs being used are the default ones that came with the distribution. You may choose to replace them with custom ones. See Build U-Boot and Linux Kernel from Source Code and Initramfs and tmpfs for instructions how to build from source.

Boot on the Toradex Board

Unmount, remove the media device from your computer and plug it into the Toradex carrier board:

umount boot rootfs

Power on the board and, if required, refer to the beginning of this guide on how to boot using Distro Boot.