Is this page helpful?

Distro Boot

Introduction

This article outlines the process of booting images using the Distro Boot mechanism. By enabling Distro Boot in U-Boot, you can boot any supported distribution for your platform by placing an image in a partitioned removable device with the corresponding boot configuration file. Here, you will see an example on how to boot an Archlinux image in a external media using Distro Boot.

Why Distro Boot

The lack of a standardized boot flow in ARM-based systems makes it challenging for system developers to deploy generic operating systems, as SoC vendors use diverse ways to boot their platforms. This has led to hardware vendors creating their own forked OS distributions, such as Raspbian and Bananian, which limits users to the vendor's software. As a result, generic OS distributors like SUSE, Redhat, and Fedora cannot reliably and consistently support every available platform.

U-Boot developers created the Generic Distro Configuration Concept, commonly known as Distro Boot, as an effort to create a standardized method for distributions to boot independently of the board used. However, while Distro Boot is a simple standard, it is currently only supported by U-Boot.

Support on Toradex Reference Images

Toradex does not maintain support for distro booting from external media like USB and SD Card due to the difficulty in maintaining this feature, particularly on newer NXP i.MX 8/8X SoCs with SECO/SCFW. While this feature may work on specific SoMs and BSP releases, it is not guaranteed, and developers are advised to avoid depending on it. However, those who still wish to attempt it can refer to the article Load Easy Installer From External Media (SD Card/USB Stick) for insights into distro booting other systems, though they do so at their own risk.

Prerequisites

In order to take advantage of the Distro Boot features you will need:

1. A running U-Boot that is Distro Boot compatible. Toradex Yocto Project Reference Images and Torizon OS provide U-Boot and its default environment compliant with Distro Boot.

2. You will need an image of the distribution you wish to boot that supports your Toradex platform and is compliant with the Distro Boot concept. However, some generic distributions may not be fully compatible with all Toradex platforms or may not adhere to the Distro Boot standard, so proceed at your own risk.

   info

   Toradex does not support either encourage the use of any non-partner distribution. Please carefully evaluate the maintenance efforts of using a distribution other than the one(s) supported by Toradex.

3. A boot configuration file named extlinux.conf or a U-Boot-specific script named boot.scr or boot.scr.uimg.

4. A removable storage media such as an SD card or a USB stick formatted and partitioned as explained at Boot From an SD Card / USB Stick / SATA drive.

Booting Process in Depth

Boot Sequence

By default, U-Boot (with Distro Boot feature enabled) will scan through all devices in search of a boot configuration file called extlinux.conf or, in its absence, a U-Boot-specific script called boot.scr or boot.scr.uimg. The following devices are scanned in order:

1. External SD card.
2. Internal flash memory (raw NAND or eMMC).
3. External USB storage.
4. External server whose location is fetched from a DCHP request at the address provided by the ${serverip} environment variable.

U-Boot searches for the first bootable partition in devices, falling back to the first valid partition if no bootable partition exists. Distro Boot supports FAT and ext2/3/4 filesystems, providing flexibility when preparing media. U-Boot looks for configuration files inside the partition and executes specific boot commands based on extlinux.conf or runs the commands in boot.scr/boot.scr.uimg. The next section explains how to generate these boot configuration files.

Configuration Files

As mentioned before, U-boot will search for the configuration files at the start of booting process. There are two types of configuration files available in a Distro Boot compliant system:

• extlinux.conf: The extlinux configuration file, typically used in the Syslinux/Extlinux bootloaders, needs to be stored in the extlinux installation directory. In spite of most GNU/Linux distributions being familiar with it, they are not very flexible in terms of how to boot images (e.g. the kernel image needs to be in a zImage format).
• boot.scr or boot.scr.uimg: These are scripts that leave you absolute control of the U-Boot environment (e.g. you can modify device trees, manually load images to specific addresses, etc.), but they are not used outside the U-Boot world.

The extlinux.conf File

U-boot will look after the configuration file on two directories: /extlinux/ and /boot/extlinux/. After U-Boot has found extlinux.conf, it executes the sysboot command on it, which parses the file and boots the system accordingly.

If you want to take a look at some configurable parameters and directives to write your extlinux.conf, you can refer to external documentation such as Syslinux, Comboot, and Arch Linux - syslinux configuration file wikis.

Example of extlinux.conf from an Arch Linux distribution

boot/extlinux/extlinux.conf

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

As you can see, the symbols are self-explanatory. The ui menu.c32 directive acts as an including for a menu module used in Syslinux. The important part here, though, is the label with the kernel image, the command line arguments, the device tree path, and the initramfs path. The paths used here refer to the same device and partition where the extlinux.conf is located. You can also use relative paths from the directory where extlinux.conf is located, as exemplified in the U-Boot documentation.

The boot.scr/boot.scr.uimg Files

After U-Boot has found a boot.scror boot.scr.uimg, U-Boot executes the contents of the files in its shell, allowing customization of the boot process using U-Boot commands. This means that you can (and should only) use any U-Boot command to customize your boot process.

Since the extlinux.conf doesn't provide a means to boot FIT images, containing kernel, device trees, and rootfs in a single file, you also need to ship a boot.scr that can be copied together with the FIT image in the first partition of the bootable media. You might also want to pass custom kernel parameters to the installer or modify the device trees. Refer to the tab Custom Boot in our Toradex Easy Installer page for an example script.

In order to make a boot.scr file, first create a file named boot.cmd with your desired U-Boot commands. For instance:

boot.cmd

setenv bootargs console=ttymxc0,115200 quiet video=mxcfb0:dev=hdmi,640x480@60,if=RGB24 video=mxcfb1:dev=lcd,640x480@60,if=RGB666 rootfstype=squashfs root=/dev/ram autoinstall ${teziargs}

# Reenable fdt relocation since in place fdt edits corrupt the ramdisk
# in a FIT image...
setenv fdt_high

# Load FIT image from location as detected by distroboot
load ${devtype} ${devnum}:${distro_bootpart} ${ramdisk_addr_r} ${prefix}tezi.itb

bootm ${ramdisk_addr_r}

The Toradex Distro Boot supports several boot options, which can help one widely customizing a boot process. If you are looking for U-boot environment variables to customize your boot process, refer to the Environment Variables at the U-boot article.

Now use the mkimage utility to create the script file as follows:

$ mkimage -A arm -O linux -T script -C none -a 0 -e 0 -n "Distro Boot Script" -d boot.cmd boot.scr

Your script file is now ready. Add it into the boot-flagged FAT or ext2/3/4 partition in your external media (or in the first partition if you are not using GPT flags) together with our tezi.itb FIT image.

Predefined Boot Commands

Toradex Embedded Linux and Yocto Project Reference Images uses a Distro Boot by default. To lookup for and run a Distro Boot script with current parameters, run the command:

> boot

Toradex U-Boot has a set of predefined commands to select the source of a booting system.

Command	Device with a booting system
bootcmd_mmc0	eMMC
bootcmd_mmc1	SD card
bootcmd_usb0	USB Flash Drive
bootcmd_dhcp	TFTP/NFS

To boot a system from, say, a USB Flash drive, go to the U-Boot command-line interface and run the command:

> run bootcmd_usb0    

If you want to follow the predefined booting sequence, issue the distro_bootcmd at your bootloader terminal.

> run distro_bootcmd    

Preparing the Media

The boot configuration files detailed in Configuration Files mainly determine how you will prepare your Distro Boot ready media. The minimal requirement is to format a single FAT or EXT4 partition.

1. Set a FAT boot partition of a few hundred megabytes (~500 MB) for the boot files and kernel
2. Set an EXT4 partition with the rest of the media size (1-2 GB should suffice) for the rootfs
3. Mount the specific partitions on mount points.
4. Get an image package that contains the kernel image (zImage format), the device trees (usually .dtb files), and the initramfs files, as well as the rootfs.
5. Copy the files to your boot partition. Remember to add your extlinux.conf in the /extlinux or the /boot/extlinux directory.

Refer to Boot From an SD Card / USB stick / SATA drive for detailed steps on how to create such partitioning in removable media. You will need an Refer to the documentation of your distribution for details on how to burn your image into external media.

Example: How to Distro Boot Archlinux Using an External 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.

info

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
$ wget http://os.archlinuxarm.org/os/ArchLinuxARM-armv7-latest.tar.gz

Prepare the Boot Media

Follow the steps at Boot From an SD Card / USB stick / SATA drive - Procedure to prepare the boot media for Toradex format images.

Create Distro Boot Configuration File

1. Create the /extlinux directory and 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 with the Toradex Embedded Linux BSP 5.7:

   # dmesg | grep "Kernel command line"
   [    0.000000] Kernel command line: ubi.mtd=ubi root=ubi0:rootfs rootfstype=ubifs ubi.fm_autoconvert=1 console=tty1 console=ttymxc0,115200n8 consoleblank=0

2. Edit the file extlinux.conf, as described in the related section. You can use the example as a template for your file, but keep in mind to change the append variable to be suitable to your case.

   info

   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 on how to build from source.

Boot on the Toradex Board

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

   $ umount boot rootfs

2. Power on the board and issue distro_bootcmd command or any specific predefined command for the external media you might be using:

   > run distro_bootcmd
   > run bootcmd_usb0