How to Build an Image for Any Distribution for Libre Computer Boards

All of our boards are supported in upstream Linux and u-boot. This is a major difference between our products and those of other SBC vendors. Every board has usable drivers in both Linux and u-boot for major subsystems so you should be able to use the kernel from Linus or stable trees directly on our boards.

To build an image for a Linux based distribution, it is important to understand the components that make booting happen.

  1. On power on, a board runs the software BootROM built into the SoC. This is a fixed piece of code specific to that SoC that will search a sequence of devices like SD card or eMMC on a specific data block for firmware specific to that SoC. That means a MicroSD card or eMMC can only have a firmware for a specific board.
  2. The SoC loads the firmware and then executes the firmware. That firmware begins initializing things like RAM and various power regulators to enable peripherals like HDMI and USB.
  3. The firmware loads and executes the u-boot bootloader. u-boot is a very basic operating system that incorporates drivers for HDMI, USB, Ethernet, etc. Once u-boot is started, you get an user interface that you can interact with through mouse or keyboard or serial cable.
  4. u-boot will attempt to load an operating system that complies with the UEFI standard. It will read the partition table (MBR or GPT) in a particular device sequence defined by the boot_targets variable. Usually this sequence is mmc (SD card/eMMC), NVMe, then USB, then network. UEFI standard defines a FAT32 partition marked by the EF/EF00 partition code. In this EFI FAT32 partition, there’s a fixed path defined for each ISA architecture that will be searched. Once a file is found in the path, u-boot will load the file into memory and execute the code as defined by the UEFI standard.
  5. On typical Linux distributions images, the file is not the Linux kernel software but rather a piece of EFI application called GRUB. GRUB provides the selection menu of the Linux kernel to launch and possibly additional drivers for reading from filesystems. GRUB then loads the selected Linux kernel and pass the boot command line, initramfs, and other information before executing Linux.
  6. The Linux kernel can be compiled as an EFI application so it can also be launched without GRUB as well. However, this is usually done for tailored images and not general purpose distributions.

The critical conceptual breakdown is as follows:

  1. BootROM - Built into the SoC
  2. Firmware / u-boot Binary- UEFI “BIOS” that is specific to a board
  3. Operating System Image - UEFI image with GRUB and Linux

We provide prepackaged binaries that contain the board firmware and u-boot (2) for every one of our boards. These board binaries are located on our boot server as BOARD-boot.bin. Our newer boards include onboard memory that stores this binary so that the operating system image (3) does not have board-specific software in the image. This allows our boards to boot a common operating system image (+arm64). That means you can switch between boards and have the software work without changes, an industry first.

To generate your own distribution, you need to create a FAT32 partition and setup your bootloader in the UEFI architecture search path. Most major distributions provide an UEFI compliant image that should be readily bootable on boards with UEFI BIOS. For our boards like Le Potato and Renegade without UEFI BIOS, simply flash the bootloader via libretech-flash-tool onto the MicroSD card that is flashed with the image.


This sounds lovely, but what about the device tree? In particular, what about overlays, since no normal distro includes your unique (IME) overlay merging manager.

And can you actually boot it (a Sweet Potato) from the USB? My early attempts ran into what I assumed were issues with the OTG port messing the connection up by trying to figure out whether it should be working as host or device (didn’t have the TTY console setup at first). But I get what is probably the same issue since I came across a mention of which port was OTG and use one of the others. Flash drive or SATA disk on an adapter - both of which seem to be fine for non-boot access - all get a bunch of disk access errors pretty early (I’m not a btrfs guru, so I’m not certain what underlying cause it’s trying to tell me about).

Thanks for any light you can shed on this.

u-boot has a built-in device tree for the device that it passes to Linux. It also supports a fixed search path based on upstream device tree name that acts as an override. u-boot will automatically search for the override device tree and pass it to Linux. This is the facility that our wiring tool uses. It takes the base tree provided during boot and then merges overlays on top.

As for the USB boot issue, we have replicated it and are looking into it. It has to do with USB probing and stabilization during boot.

1 Like