README
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 chrpath cmake coreutils debootstrap \
dialog device-tree-compiler diffstat docbook-utils flex \
g++ gcc gcc-multilib git-core golang gpart groff help2man \
lib32ncurses5-dev libarchive-dev libgl1-mesa-dev libglib2.0-dev \
libglu1-mesa-dev libsdl1.2-dev libssl-dev libtool lzop m4 make \
mtd-utils python3-git python3-m2crypto qemu qemu-user-static \
socat sudo texi2html texinfo u-boot-tools unzip
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-10.asc |
sudo gpg --import --no-default-keyring \
--keyring /usr/share/keyrings/debian-buster-release.gpg
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_buster_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 buster and install firmware to the filesystem rootfs, use:
sudo MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -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 run:
sudo MACHINE=revo-roadrunner-mx7 ./revo_make_debian.sh -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