/
Buildroot

Buildroot

This page highlights AMD support for Buildroot as an alternative community Linux solution to Yocto.  Unofficial support for AMD architectures (Zynq, Zynq MPSoC, Kria SOMs and Versal Adaptive SoC) are available. The Buildroot configs directory provides a number of example defconfig files for common evaluation boards which use AMD devices.

Buildroot is not WTS supported and should only be used by experienced users. However, Buildroot does use the same supported software as Yocto from the https://www.github.com/Xilinx repository. Any issues with this underlying software which can be duplicated using Yocto or Vitis are supported by WTS. But any issues with configuring Buildroot for custom hardware should be addressed to the Buildroot community.

One exception to the above is the Zynq and Zynq MPSoC U-Boot Secondary Program Loader (SPL). While it is included with U-Boot and Buildroot, the WTS supported flow for the Zynq and Zynq MPSoC families is the First Stage Bootloader (FSBL). Experienced users are welcome to give the U-Boot SPL a try as it is documented here. However, if technical support is needed, the Xilinx recommendation is to build the boot.bin using the FSBL and bootgen. It is possible to use Yocto or Vitis for building a hardware specific boot.bin while still using Buildroot for building the Linux kernel and file system.

Table of Contents

General Information

Official Buildroot release activity and version information can be found at Releases - Buildroot

The following table correlates Buildroot LTS releases to the corresponding AMD releases. Starting with the 2025.02 release, Buildroot LTS releases are now maintained for 3 years and every other year will have an LTS release. Because Buildroot LTS releases happen in February, they will always be based on the prior year’s AMD Adaptive .2 release. For example, Buildroot 2025.02 is based on the xilinx_v2024.2 AMD release.

For more information about specific releases, please visit the release-specific page under Linux Prebuilt Images.

AMD Release Tag

Buildroot LTS Release

Linux Kernel LTS

xilinx_v2024.2

2025.02

6.6

xilinx_v2023.2

2024.02

6.1

xilinx_v2022.2

2023.02

5.15

Note: To test the latest AMD release before the next Buildroot February 2027 LTS release, it is possible to clone the Buildroot master branch which already includes the latest AMD release xilinx_v2025.2 or to use the latest 3 month stable release.

git clone https://gitlab.com/buildroot.org/buildroot.git

Supported AMD Evaluation Boards

Zynq

zynq_zc702_defconfig
zynq_zc706_defconfig
zynq_microzed_defconfig
zynq_zed_defconfig

Zynq UltraScale+

zynqmp_zcu102_defconfig
zynqmp_zcu104_defconfig
zynqmp_zcu106_defconfig

Kria SOM

zynqmp_kria_kd240_defconfig
zynqmp_kria_kr260_defconfig
zynqmp_kria_kv260_defconfig

Versal

versal_vck190_defconfig
versal_vek280_defconfig
versal_vpk120_defconfig
versal_vpk180_defconfig

Versal Gen 2

versal2_vek385_defconfig

Getting Started with Buildroot

This page provide a step by step guide to configuring buildroot to generate an embedded Linux system using the AMD Linux release.  Now that many defconfig examples have been added to buildroot mainline, the latest AMD software will now build and run on a variety of evaluation boards with very little effort.

Host System Requirements

Buildroot documents the requirements for the host Linux development machine here.

Build Steps

  1. Download the latest LTS version of Buildroot: https://buildroot.org/download.html

  2. Included with Buildroot is a nicely organized directory structure documented here.

  3. Inspect the following directories:

configs: includes build examples for AMD evaluation boards that can be used as a template for creating a build config for a custom target board.

board: includes a readme.txt file and open source build scripts for each AMD evaluation board family. The post-image.sh script operates on the genimage.cfg file for creation of the SD card image for booting. These files are intended as a simple example for each device family which can be modified according to user needs. Each target family has its own example board directory as outlined below.

board/zynq
board/zynqmp
board/zynqmp/kria
board/versal
board/versal2

  1. Configure Buildroot for an AMD evaluation board. Below is an example command for the AMD ZCU102, but any of the supported evaluation boards can be used by simply configuring with the appropriate defconfig.

make zynqmp_zcu102_defconfig

  1. Build the target images.

make

  1. Inspect the following output directories:

output/build: includes the sources of all of the packages which were built.
output/images: contains all of the target images that will run on the target board, including the sdcard.img for imaging an SD card for booting. Below is an example for the ZCU102 evaluation board.

output/images/ +-- atf-uboot.ub +-- bl31.bin +-- boot.bin +-- boot.vfat +-- Image +-- rootfs.ext2 +-- rootfs.ext4 -> rootfs.ext2 +-- sdcard.img +-- system.dtb -> zynqmp-zcu102-rev1.0.dtb +-- u-boot.itb `-- zynqmp-zcu102-rev1.0.dtb

  1. Image the SD card for booting:

dd if=output/images/sdcard.img of=/dev/sdX
* where sdX is the device node of the SD on the host

  1. Configure the target evaluation board for SD card boot mode.

  2. To login to buildroot, the default root password is root.

Welcome to Buildroot
buildroot login:

Buildroot Custom Hardware Device Tree

Buildroot expects custom hardware specifications to already be in Device Tree format. To create a device tree for custom hardware, it is recommended to use the supported Software Hardware Exchange Loop which is the same flow used by Yocto.

ZCU102 example with custom PL bitstream

  1. SDTGen: convert Vivado XSA file (system.xsa) to system device tree files

sdtgen -xsa zcu102.xsa -dir sdt_out -board_dts zynqmp-zcu102-rev1.0

  1. Lopper: strip out zynqmp_linux.dts and pl.dtsi files from system device tree files

export LOPPER_DTC_FLAGS="-b 0 -@"
git clone -b xilinx_v2025.2 https://github.com/Xilinx/lopper.git
mkdir -p ./lopper_out
lopper -f --enhanced ./sdt_out/system-top.dts ./lopper_out/system.dts -- xlnx_overlay_dt cortexa53-zynqmp full
lopper -f --enhanced -O ./lopper_out -i ./lopper/lopper/lops/lop-a53-imux.dts ./lopper_out/system.dts zynqmp_linux.dts -- gen_domain_dts psu_cortexa53_0 linux_dt

  1. Buildroot: change zynqmp_zcu102_defconfig to use Lopper generated zynqmp_linux.dts instead of in-tree dts

Copy zynqmp_linux.dts to a dir with “xilinx” in the directory name
mkdir -p ./buildroot_dts
mkdir -p ./buildroot_dts/xilinx
cp ./lopper_out/zynqmp_linux.dts ./buildroot_dts/xilinx

Modify <buildroot_dir>/configs/zynqmp_zcu102_defconfig
-BR2_LINUX_KERNEL_INTREE_DTS_NAME="xilinx/zynqmp-zcu102-rev1.0"
+BR2_LINUX_KERNEL_CUSTOM_DTS_DIR="./buildroot_dts"

Since the ZU9 bitstream is 26MB in size, it is probably a good idea to make the file system larger than the default 60MB size that Buildroot uses in order to have the space in the file system. To do this, the following config should be added to the zynqmp_zcu102_defconfig. Any size large enough for the desired file system plus the zcu102 bitstream will be sufficient.
+BR2_TARGET_ROOTFS_EXT2_SIZE="90M"

Configure and build with custom system.dts
make zynqmp_zcu102_defconfig
make

  1. DTC: build pl.dtbo overlay

dtc -I dts -O dtb -o ./lopper_out/pl.dtbo pl.dtsi

  1. Bootgen: convert bitstream.bit to bitstream.bin

bootgen.bif:
all: { [destination_device = pl] zcu102.bit /* Bitstream file name */ }

Run bootgen using above bootgen.bif:
bootgen -image bootgen.bif -arch zynqmp -o ./zcu102.bit.bin -w

  1. Install bitstream.bin and pl.dtbo to the target file system

mkdir -p <buildroot_dir>/output/target/lib/firmware/xilinx
cp ./lopper_out/pl.dtbo <buildroot_dir>/output/target/lib/firmware/xilinx
cp ./zcu102.bit.bin <buildroot_dir>/output/target/lib/firmware/xilinx

  1. Buildroot: re-generate rootfs.ext4 and sdcard.img with the new files in output/target by re-running make

make

  1. Image the SD card for booting:

dd if=output/images/sdcard.img of=/dev/sdX
* where sdX is the device node of the SD on the host

  1. To login to buildroot, the default root password is root.

Welcome to Buildroot
buildroot login:

  1. FPGA Utility: Load bitstream.bin and pl.dtbo from Linux rootfs

fpgautil -b /lib/firmware/xilinx/zcu102.bit.bin -o /lib/firmware/xilinx/pl.dtbo

VEK280 example with custom pld.pdi

  1. SDTGen: convert Vivado XSA file (system.xsa) to system device tree files

sdtgen -xsa vek280.xsa -dir sdt_out -board_dts versal-vek280-revb

  1. Lopper: strip out versal_linux.dts and pl.dtsi files from system device tree files

export LOPPER_DTC_FLAGS="-b 0 -@"
git clone -b xilinx_v2025.2 https://github.com/Xilinx/lopper.git
mkdir -p ./lopper_out
lopper -f --enhanced ./sdt_out/system-top.dts ./lopper_out/system.dts -- xlnx_overlay_dt cortexa72-versal full
lopper -f --enhanced -O ./lopper_out -i ./lopper/lopper/lops/lop-a72-imux.dts ./lopper_out/system.dts versal_linux.dts -- gen_domain_dts psv_cortexa72_0 linux_dt

  1. Buildroot: change versal_vek280_defconfig to use Lopper generated versal_linux.dts

Copy versal_linux.dts to a dir with “xilinx” in the directory name
mkdir -p ./buildroot_dts
mkdir -p ./buildroot_dts/xilinx
cp ./lopper_out/versal_linux.dts ./buildroot_dts/xilinx

Modify <buildroot_dir>/configs/versal_vek280_defconfig
-BR2_LINUX_KERNEL_INTREE_DTS_NAME="xilinx/versal-vek280-revB"
+BR2_LINUX_KERNEL_CUSTOM_DTS_DIR="./buildroot_dts"

Depending on the size of the pld.pdi, it is probably a good idea to make the file system larger than the default 60MB size that Buildroot uses in order to have the space in the file system. To do this, the following config should be added to the versal2_vek385_defconfig. Any size large enough for the desired file system plus the vek385 pld.pdi will be sufficient.
+BR2_TARGET_ROOTFS_EXT2_SIZE="90M"

Add custom XSA to build configuration. This will extract the boot.pdi and pld.pdi files from the XSA. The boot.pdi will be used to generate the boot.bin and the pld.pdi will be installed into the target file system in the /lib/firmware/xilinx directory.

+BR2_TARGET_XILINX_PREBUILT_VERSAL_XSA=y
+BR2_TARGET_XILINX_PREBUILT_VERSAL_XSA_LOCATION="./vek280.xsa"
+BR2_TARGET_XILINX_PREBUILT_VERSAL_PLD_PDI=y

A sha256 hash for the vek280.xsa file needs to be added to the Buildroot ./boot/xilinx-prebuilt/xilinx_v2025.2/xilinx-prebuilt.hash file. An example can be found below:

+sha256 f05f005665be109cefac271e10a54978f5add24ea5efccfff5cd82126777b9e1 vek280.xsa

Configure and build with custom system.dts
make versal_vek280_defconfig
make

  1. DTC: build pl.dtbo overlay

dtc -I dts -O dtb -o ./lopper_out/pl.dtbo pl.dtsi

  1. Install pl.dtbo to the target file system

mkdir -p <buildroot_dir>/output/target/lib/firmware/xilinx
cp ./lopper_out/pl.dtbo <buildroot_dir>/output/target/lib/firmware/xilinx

  1. Buildroot: re-generate rootfs.ext4 and sdcard.img with the new file in output/target by re-running make

make

  1. Image the SD card for booting:

dd if=output/images/sdcard.img of=/dev/sdX
* where sdX is the device node of the SD on the host

  1. To login to buildroot, the default root password is root.

Welcome to Buildroot
buildroot login:

  1. FPGA Utility: Load bitstream.bin and pl.dtbo from Linux rootfs

fpgautil -b /lib/firmware/xilinx/vek280_pld.pdi -o /lib/firmware/xilinx/pl.dtbo

VEK385 example with custom pld.pdi

  1. SDTGen: convert Vivado XSA file (system.xsa) to system device tree files

sdtgen -xsa vek385.xsa -dir sdt_out -board_dts versal2-vek385-revb

  1. Lopper: strip out versal2_linux.dts and pl.dtsi files from system device tree files

export LOPPER_DTC_FLAGS="-b 0 -@"
git clone -b xilinx_v2025.2 https://github.com/Xilinx/lopper.git
mkdir -p ./lopper_out
lopper -f --enhanced ./sdt_out/system-top.dts ./lopper_out/system.dts -- xlnx_overlay_dt cortexa78-versal2 full
lopper -f --enhanced -O ./lopper_out -i ./lopper/lopper/lops/lop-a78-imux.dts ./lopper_out/system.dts versal2_linux.dts -- gen_domain_dts cortexa78_0 linux_dt

  1. Buildroot: change versal2_vek385_defconfig to use Lopper generated versal2_linux.dts

Copy versal2_linux.dts to a dir with “xilinx” in the directory name
mkdir -p ./buildroot_dts
mkdir -p ./buildroot_dts/xilinx
cp ./lopper_out/versal2_linux.dts ./buildroot_dts/xilinx

Modify <buildroot_dir>/configs/versal2_vek385_defconfig
+BR2_LINUX_KERNEL_DTS_SUPPORT=y
+BR2_LINUX_KERNEL_CUSTOM_DTS_DIR="./buildroot_dts"

Depending on the size of the pld.pdi, it is probably a good idea to make the file system larger than the default 60MB size that Buildroot uses in order to have the space in the file system. To do this, the following config should be added to the versal2_vek385_defconfig. Any size large enough for the desired file system plus the vek385 pld.pdi will be sufficient.
+BR2_TARGET_ROOTFS_EXT2_SIZE="90M"

Add custom XSA to build configuration. This will extract the boot.pdi and pld.pdi files from the XSA. The boot.pdi will be used to generate the boot.bin and the pld.pdi will be installed into the target file system in the /lib/firmware/xilinx directory.

+BR2_TARGET_XILINX_PREBUILT_VERSAL_XSA=y
+BR2_TARGET_XILINX_PREBUILT_VERSAL_XSA_LOCATION="./vek385.xsa"
+BR2_TARGET_XILINX_PREBUILT_VERSAL_PLD_PDI=y

A sha256 hash for the vek385.xsa file needs to be added to the Buildroot ./boot/xilinx-prebuilt/xilinx_v2025.2/xilinx-prebuilt.hash file. An example can be found below:

+sha256 f05f005665be109cefac271e10a54978f5add24ea5efccfff5cd82126777b9e1 vek385.xsa

Configure and build with custom system.dts
make versal2_vek385_defconfig
make

  1. DTC: build pl.dtbo overlay

dtc -I dts -O dtb -o ./lopper_out/pl.dtbo pl.dtsi

  1. Install pl.dtbo to the target file system

mkdir -p <buildroot_dir>/output/target/lib/firmware/xilinx
cp ./lopper_out/pl.dtbo <buildroot_dir>/output/target/lib/firmware/xilinx

  1. Buildroot: re-generate rootfs.ext4 and sdcard.img with the new file in output/target by re-running make

make

  1. Image the SD card for booting:

dd if=output/images/sdcard.img of=/dev/sdX
* where sdX is the device node of the SD on the host

  1. To login to buildroot, the default root password is root.

Welcome to Buildroot
buildroot login:

  1. FPGA Utility: Load bitstream.bin and pl.dtbo from Linux rootfs

fpgautil -b /lib/firmware/xilinx/vek385_pld.pdi -o /lib/firmware/xilinx/pl.dtbo

Reference Resources