Buildroot and BR2_EXTERNAL

BR2_EXTERNAL

Buildroot supports an external tree mechanism called BR2_EXTERNAL. It allows project-specific defconfigs, kernel configs, packages, and overlay files to live outside the Buildroot source tree. RVComp uses this mechanism: RVComp/buildroot/ is the BR2_EXTERNAL tree.

When invoking make, the BR2_EXTERNAL variable is set to point at RVComp/buildroot/, making the defconfigs and packages in that tree visible to Buildroot.

Build Flow

UART Boot

uart_defconfig produces a single fw_payload.bin that bundles OpenSBI, the Linux kernel, and an initramfs. The system runs entirely from RAM.

uart_defconfig
└── fw_payload.bin  (OpenSBI + Linux kernel + initramfs)

MMC Boot

MMC boot requires two separate outputs. Because the payload and the root filesystem include different packages, they are built in two separate passes. Using the same base configuration (mmc_defconfig) for both passes avoids dependency and library version differences between the two builds.

First pass — payload:

mmc_defconfig
└── fw_payload.bin  (OpenSBI + Linux kernel + minimal initramfs)

Second pass — root filesystem:

mmc_defconfig + mmc_rootfs_second_pass.fragment
└── rootfs.ext4  (ext4, 64 MiB)

mmc_rootfs_second_pass.fragment is applied on top of mmc_defconfig. The fragment overrides only the differences: disabling the kernel and OpenSBI builds, switching the root filesystem format to ext4, and adding packages such as dropbear and curl.

Disk Layout

By default, the MMC boot disk image has the following layout:

Offset 0          Offset 32 MiB               Offset 96 MiB
│                 │                            │
▼                 ▼                            ▼
┌─────────────────┬────────────────────────────┐
│  fw_payload.bin │       rootfs.ext4          │
│    (32 MiB)     │         (64 MiB)           │
└─────────────────┴────────────────────────────┘

fw_payload.bin is padded to 32 MiB so that rootfs.ext4 always starts at a fixed offset. The rvcomp-mmc driver reads rootfs-offset from the device tree to know where the root filesystem begins.

Adding Packages to the Root Filesystem

To add packages to rootfs.ext4, add BR2_PACKAGE_* options to mmc_rootfs_second_pass.fragment. Only the differences from mmc_defconfig need to be listed in the fragment.

Adding packages increases the required rootfs size. Update BR2_TARGET_ROOTFS_EXT2_SIZE in mmc_rootfs_second_pass.fragment accordingly and rebuild.

Changing the 32 MiB Offset

If you need to change the offset, update both of the following and rebuild the bitstream:

bootrom/rvcomp.dts — rootfs-offset property (byte offset as a 64-bit value)
config.mk — BIN_SIZE (set to the new offset in bytes; 33554432 for 32 MiB)