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.

⚠️ Advanced topic
A mistake in the bootloader can prevent your device from booting. Proceed carefully and always have a recovery plan (for example, the ability to use EDL mode to reflash).

Desktop vs On-Device Builds (Overview)​

You can build U-Boot either on a desktop (recommended for most developers) or directly on the Tachyon device:

  • Desktop builds

    The current integration flow uses tachyon-composer to build the entire system image for the disk.
    You can also build standalone U-Boot from the tachyon-u-boot repo using its Dockerized script ./build.sh.
    The Dockerfile pins all tools and sources needed for a clean build.
    If you're on an arm64 Linux host and prefer not to use Docker, you can install the equivalent packages manually using the Dockerfile as a reference.

  • On-device builds

    Build directly on the Tachyon device with similar steps.
    After building, run ./install.sh to install the resulting u-boot.bin onto the disk.
    This script reads back the existing partition, merges it, and writes it back.

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).

Building U-Boot (Desktop)​

There are two desktop paths: full system image via tachyon-composer (integrated flow), or standalone U-Boot using this repo’s Dockerized build script.

Option A - Full System Image (via tachyon-composer)​

The current desktop integration flow builds the entire system image for the disk, which pulls in your local U-Boot.

  1. Docker image

In the tachyon-composer repo, fetch the build container and open a shell:

make docker/shell

You can also inspect the packages in the Dockerfile there if you prefer to recreate the environment outside of a container.

  1. Run the shell commands

From that shell, cd to your local tachyon-u-boot clone and build (see manual steps below), or point composer at your U-Boot tree so it picks up the resulting u-boot.bin during the next image build.

Option B - Standalone U-Boot (Dockerized ./build.sh)​

If you only want to build U-Boot without composing a full image:

  1. From the tachyon-u-boot directory:
./build.sh

This runs a Dockerized build using the repo’s Dockerfile, which includes all required toolchains and sources.

  1. When finished, the resulting binary appears at the top of the repo as:
u-boot.bin

Building without Docker (arm64 Linux only):

If your desktop is arm64 Linux, you can install the same packages the Dockerfile uses and build natively. Use the Dockerfile as a reference for dependencies.

Manual Build Steps (Advanced)​

If you prefer to run the U-Boot make flow yourself (inside Docker or a correctly provisioned host):

  1. Open a build shell (Docker or native), then from the tachyon-u-boot directory:

Only needed if cross-compiling from x86_64 to aarch64:

export CROSS_COMPILE=aarch64-linux-gnu-
  1. Configure for Tachyon (defconfig name may evolve):
make qcm6490_tachyon_config
  1. Build:
make -j8
  1. Output artifact:
u-boot.bin

Building on the Device (Tachyon)

Building natively on Tachyon is similar to the manual steps above, but you typically do not set CROSS_COMPILE (the device is already aarch64):

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

Optional: ensure required packages match the Dockerfile if building without Docker.

make qcm6490_tachyon_config
make -j8

After a successful build, install to the disk:

sudo ./install.sh
  • install.sh takes the freshly built u-boot.bin, reads back the existing partition, merges it, and writes it back.
  • Expect this to require elevated privileges and exclusive access to the target disk/partition.
  • Make backups and ensure you have an EDL recovery path before running.

Using Your Custom U-Boot

You can deploy your new build in a couple of ways:

  • Through the system image composer (desktop) Point the tachyon-composer tool at your local tachyon-u-boot directory. Composer will automatically pick up u-boot.bin and include it in the next full image build for the disk (the current desktop integration flow).

  • On-device install (native) After building on the Tachyon itself, run sudo ./install.sh. The script reads the existing partition, merges in the new U-Boot, and writes it back.

  • Direct EFI insertion (advanced) Advanced users can insert the U-Boot binary directly into the EFI image. The details for this flow are 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: dts/upstream/src/arm64/qcom/qcm6490-tachyon.dts
  • Board code: board/particle/tachyon/
  • Boot flow or environment: Adjust defaults for boot order, boot delay, or GRUB handoff.

After changes, rebuild to produce an updated u-boot.bin and redeploy using one of the methods above.

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!