a Beaglebone black with attached serial cable in front

In May 2021 I worked through the Buildroot training by Bootlin on a Beaglebone black. This is not the wireless version the lab description expects, but it worked well nonetheless. I enjoyed this very much, the materials from Bootlin are excellent.

At the time they used the older uEnv.txt method for booting. Since I'm also playing with an STM32MP157C-DK2, which uses distro boot, I wanted to switch the Beaglebone black over to also use it, to get a more uniform configuration across my devices.

Distro Boot

Distro boot adapts the configuration file format of Syslinux to also support device trees. It is available in recent versions of U-Boot, here is a complete description.

Distro boot is becoming popular for booting embedded Linux systems, because it decouples the boot loader from the Linux system. It is no longer necessary to fiddle with U-Boot environment variables to tell U-Boot where the Linux kernel image, device tree and root file system are.

The starting point is a configuration file extlinux.conf. It must be in a bootable partition at either /extlinux/extlinux.conf or /boot/extlinux/extlinux.conf. In my case /boot/extlinux/extlinux.conf looks like this:

label buildroot
  kernel /boot/zImage
  devicetree /boot/am335x-boneblack.dtb
  append console=ttyO0,115200 root=/dev/mmcblk0p2 rootwait
It specifies the location of the kernel image zImage and the device tree am335x-boneblack.dtb, and adds some kernel parameters to specify the devices for the serial console and the root partition.

The kernel and the device tree are in the root partition, like on the STM32MP157C-DK2.

Beaglebone Black

The Beaglebone black uses a Texas Instruments AM3358 SoC. The boot loader in the ROM of the SoC loads the next stage boot loader from a file MLO in a bootable FAT partition.

The Beaglebone black has an internal 4GB eMMC (MMC1) and a slot for SD-cards (MMC0). The boot medium on power up depends on button S2:

  • If it is not pressed, the Beaglebone boots from eMMC.
  • If it is pressed, the Beaglebone boots from the SD-card in the slot.
If you press the reset button or reboot via Linux afterwards, it reuses the same boot medium that was used on power up.

U-Boot Configuration

MLO is provided by U-Boot and in turn loads the full U-Boot binary.

In the latest U-Boot version 2021.04 the default configuration for the Beaglebone black already supports distro boot. It searches all bootable partitions for an extlinux.conf file and boots the first one it finds. However, the older method via uEnv.txt is tried first, so if you are switching from the old to the new method, you need to remove this file, or at least remove the uenvcmd variable within.

Buildroot Configuration

I added the /boot/extlinux/extlinux.conf shown above to a rootfs overlay for the Beaglebone black.

To put the kernel image and the device tree into the root file system I set BR2_LINUX_KERNEL_INSTALL_TARGET=y.

The FAT partition no longer includes kernel image and device tree. My genimage.cfg now looks like this:

image boot.vfat {
	vfat {
		label = "boot"
		files = {
	size = 16M

image sdcard.img {
	hdimage {

	partition u-boot {
		partition-type = 0xC
		bootable = "true"
                image = "boot.vfat"

	partition rootfs {
		partition-type = 0x83
		bootable = "true"
		image = "rootfs.ext4"
		size = 512M

With this configuration my Beaglebone black boots into Linux, using only the U-Boot default environment without any manual settings.


In my setup I used Linux 5.10.55. For slightly older versions of Linux the numbering of the mmcblkN devices for SD-card and eMMC is not stable, and is likely to be reversed. In that case the setting for the root partition is incorrect. This patch fixes the issue and ensures that mmcblk0 is always the SD-card. The fix is included in Linux versions 5.10.29, 5.11.13 and 5.12.