Building REVO board boot images

• Overview
• Prerequisites
• Fetch build suite and kernel sources
• Build U-Boot and Linux kernel
• Bootstrap root filesystem
• Bootstrap recovery filesystem
• Archive root and recovery filesystems
• Create bootable image file
• Flash bootable image to SD card or USB flash drive
• Enable booting from USB flash drive
• Subsequent builds

Overview

This is a Debian GNU/Linux build suite for REVO boards. The following build instructions have been verified on a Ubuntu 20.04 x86 host platform. It's important that the commands are run in the order listed.

Prerequisites

Verify that required tools and libraries are available by running (on the command line):

sudo apt update
sudo apt install -y autoconf automake autopoint binfmt-support \
    binutils bison build-essential cmake coreutils debootstrap \
    device-tree-compiler diffstat flex g++ gcc git golang gpart \
    groff help2man  libssl-dev libtool lzop m4 make qemu \
    qemu-user-static u-boot-tools unzip upx-ucl
sudo apt install -y binutils-arm-linux-gnueabihf
sudo apt install -y cpp-arm-linux-gnueabihf
sudo apt install -y gcc-arm-linux-gnueabihf
sudo apt install -y g++-arm-linux-gnueabihf

Import a Debian GPG-signing key to verify repository integrity:

curl -L https://ftp-master.debian.org/keys/release-11.asc |
    gpg --dearmor |
    sudo tee /usr/share/keyrings/debian-bullseye-release.gpg >/dev/null

Fetch build suite and kernel sources

Clone the build suite repository under the current directory:

git clone https://github.com/revolution-robotics/roadrunner-debian.git \
    -b debian_bullseye_rr01 roadrunner_debian

Download U-Boot and Linux kernel sources:

cd roadrunner_debian
MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -c deploy

Build U-Boot and Linux kernel

To build the primary (SPL) and secondary (U-Boot) bootloaders (and save them as output/SPL.mmc and output/u-boot.img.mmc, respecitvely.), use:

sudo MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -c bootloader

To build the Linux kernel + U-Boot wrapper (uImage) and compile Device Tree (DTS) files (and save them to output), use:

sudo MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -c kernel

Bootstrap root filesystem

To bootstrap Debian bullseye and install firmware to the filesystem rootfs, if Debian caching proxy server, Apt-Cacher NG, is installed and configured on localhost, use:

sops exec-env config/secrets.enc.json 'sudo -E CA_URL=$CA_URL CA_FINGERPRINT=$CA_FINGERPRINT MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -a -j $(nproc) -p http://$(hostname):3142/deb.debian.org/debian/ -c rootfs'

Otherwise, use:

sops exec-env config/secrets.enc.json 'sudo -E CA_URL=$CA_URL CA_FINGERPRINT=$CA_FINGERPRINT MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -a -j $(nproc) -c rootfs'

To install kernel modules and headers to rootfs, use:

sudo MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -c modules

Bootstrap recovery filesystem

The rescue filesystem, recoveryfs, can be built in either of two ways:

• By running Debian bootstrap a second time, or
• From a copy of rootfs.

Building recoveryfs from rootfs is fast, but requires some preparation, including that rootfs is fully populated with Debian, kernel modules (and headers) and firmware. See the script express_recoveryfs.sh for details. Choose which method to use by setting the variable USE_ALT_RECOVERYFS in the script revo_make_debian.sh. Then, if using Debian caching proxy server, run:

sops exec-env config/secrets.enc.json 'sudo -E CA_URL=$CA_URL CA_FINGERPRINT=$CA_FINGERPRINT MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -a -j $(nproc) -p http://$(hostname):3142/deb.debian.org/debian/ -c recoveryfs'
sudo MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -c recoveryfs

Otherwise, run:

sops exec-env config/secrets.enc.json 'sudo -E CA_URL=$CA_URL CA_FINGERPRINT=$CA_FINGERPRINT MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -a -j $(nproc) -c recoveryfs

To install kernel modules and headers to recoveryfs, use:

sudo MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -c remodules

Archive root and recovery filesystems

To archive the root and recovery filesystems (as output/rootfs.tar.gz and output/recoveryfs.tar.gz, respectively) run:

sudo MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -c fstar

Create bootable image file

To create a bootable image file (4 GB compressed and saved as output/${MACHINE}-${ISO8601}.img.gz), use:

sudo MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -c diskimage

Flash bootable image to SD card or USB flash drive

To flash a bootable image file (from subdirectory output, by default) to SD card or USB flash drive, use:

sudo ./revo_make_debian.sh -c flashimage

If multiple image files exist, you'll be prompted to select one. Likewise, if multiple removable drives exist.

Enable booting from USB flash drive

The U-Boot script that enables booting from USB flash drive is always read from either SD card or eMMC. To enable booting from USB flash drive without an SD card installed, it is necessary to first flash eMMC, which can be done as follows. Ensure that the pins labeled BMO are not jumpered,¹ then with a bootable SD card installed, power cycle the board. At the console, log in and run the command:

flash-emmc

This installs a U-Boot boot loader, Debian root file system and recovery file system onto eMMC. Once the flash-emmc command completes successfully, jumper the BMO pins and reboot. Now, whenever the system boots, it first looks for a USB flash drive and uses that if it's bootable.

¹ On currents boards, U-Boot is read from eMMC if the BMO pins are jumpered and SD otherwise. In future builds, this may be reversed.

Subsequent builds

After commiting changes to the kernel or U-Boot source trees, to incorporate the changes into new builds, update the file ${G_VENDOR_PATH}/${MACHINE}/${MACHINE}.sh. Then a new disk image can be created without re-running Debian bootstrap as follows:

sudo MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -c kernel
sudo MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -c modules
sudo MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -c remodules
sudo MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -c fstar
sudo MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -c diskimage

Likewise, after editing U-Boot sources, create a new disk image with:

sudo MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -c bootloader
sudo MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -c diskimage