Skip to main content

Modifying and Rebuilding U-Boot for Tachyon

Tachyon’s bootloader (U-Boot) is open source and can be customized to change low-level behavior, enable new hardware features at boot, or update the device’s firmware boot flow. This page explains how to build the tachyon-u-boot project and deploy a custom U-Boot on your Tachyon. This is an advanced topic – a mistake in the bootloader can prevent your device from booting, so proceed carefully and always have a recovery plan (e.g., the ability to use EDL mode to reflash).

Why Modify U-Boot?​

You might want to modify U-Boot if you need to:

  • Change boot timings or boot order.
  • Enable early debug (e.g., turn on verbose UART logs earlier).
  • Add support for a piece of hardware that needs initialization before the OS boots (for example, a regulator or FPGA configuration).
  • Modify the Device Tree that U-Boot passes to the kernel (though this can also be done in the kernel source, U-Boot’s DT is authoritative at boot).
  • Experiment with chain-loading or booting alternative OS images.

The Tachyon U-Boot is already configured to support EFI boot (for GRUB) and includes the baseline device tree. Customizations often involve editing configuration or device tree files, then rebuilding.

Cloning the U-Boot Source​

First, get the source code for Tachyon’s U-Boot:

git clone https://github.com/particle-iot/tachyon-u-boot.git
cd tachyon-u-boot

This repository is based on mainline U-Boot, with additional patches for QCM6490 support and Tachyon specifics (like the board name and device tree). Make sure you’re on the correct branch or tag corresponding to the version you intend to build (for example, v1.0.4 if you want to build the same version as the official image uses). You can list branches/tags via:

git branch -a
git tag

Building U-Boot​

Note on the Docker environment U-Boot must be built inside the same Docker image used by tachyon-composer. This means you need to have cloned the tachyon-composer repository, downloaded its Docker image, and run its Makefile at least once.

If you only want to drop into the build environment without doing a full system build, you can run the following from tachyon-composer repo and it will create the base container for you to use:

make docker/shell

(you can also insect the packages used by the Docker file in tachyon-composer if you want to do this outside of a container).

This creates the Docker container and gives you a shell you can use to build U-Boot. Once inside, cd into your tachyon-u-boot repo and follow the steps below.

Step-by-step build​

  1. From inside the tachyon-u-boot directory, run:
./docker.sh

This drops you into a build shell rooted at the U-Boot repo.

  1. In that shell, export the cross-compile prefix:
export CROSS_COMPILE=aarch64-linux-gnu-
  1. Configure the build for Tachyon (defconfig name may change as the repo evolves):
make qcm6490_defconfig
  1. Build U-Boot:
make -j$(nproc)
  1. When finished, the resulting binary will appear at the top of the repo as:
u-boot.bin

This u-boot.bin is the artifact that can be integrated into a Tachyon system image.

Using Your Custom U-Boot​

There are two common ways to use your new build:

  • Through the system image composer

Point the tachyon-composer tool at your local tachyon-u-boot directory. Composer will automatically pick up the u-boot.bin and include it in the next image build.

  • Direct EFI insertion

Advanced users can insert the U-Boot binary directly into the EFI image. The details for this flow are already built into composer; we’ll expand this documentation with examples in the future.

Editing the Source​

If you want to customize U-Boot before building:

  • Device Tree: Look under dts/upstream/src/arm64/qcom/qcm6490-tachyon.dts
  • Board code: Some initialization is under board/particle/tachyon/.
  • Boot flow or environment: Adjustments to boot order, boot delay, or GRUB handoff can be made in the environment defaults.

After changes, re-run the build steps above to produce an updated u-boot.bin.

Contributing Back​

If you have improved U-Boot (for example, added support for new hardware or fixed a bug), consider contributing your changes:

  • Follow Particle’s contribution guidelines (ensure you’ve signed the CLA – see “How to Get Involved”).
  • Open a Pull Request on the tachyon-u-boot GitHub repo.

We will review and merge contributions that benefit the community!