This document describes the Buildroot support for the following
Xilinx Versal Gen2 boards:

******************************************
Supported Versal Gen2 Boards:
Xilinx VEK385 board
******************************************

Evaluation board features can be found here with the links below.

VEK385:
https://www.amd.com/en/products/adaptive-socs-and-fpgas/evaluation-boards/vek385.html

How to build it
===============

Configure Buildroot:

    $ make versal2_vek385_defconfig

Compile everything and build the rootfs image:

    $ make

Result of the build
-------------------

After building, you should get a tree like this:

    output/images/
    +-- asufw.elf
    +-- bl31.elf
    +-- boot.bin
    +-- bootgen.bif
    +-- boot.pdi
    +-- boot.vfat
    +-- extlinux.conf
    +-- Image
    +-- plm.elf
    +-- rootfs.ext2
    +-- rootfs.ext4 -> rootfs.ext2
    +-- sdcard.img
    +-- system.dtb -> u-boot.dtb
    +-- tee-raw.bin
    +-- u-boot.dtb
    `-- u-boot.elf

How to write the SD card
========================

WARNING! This will destroy all the card content. Use with care!

The sdcard.img file is a complete bootable image ready to be written
on the boot medium. To install it, simply copy the image to an SD
card:

    # dd if=output/images/sdcard.img of=/dev/sdX

Where 'sdX' is the device node of the SD.

Eject the SD card, insert it in the board, and power it up.

Support for other boards:
=========================

If you want to build a system for other boards based on the same SoC, and the
board is already supported by the upstream kernel, U-Boot, and
xilinx-prebuilt, you simply need to change the following Buildroot options:

 - U-Boot (BR2_TARGET_UBOOT_CUSTOM_MAKEOPTS="DEVICE_TREE=<dts file name>")
 - xilinx-prebuilt (BR2_TARGET_XILINX_PREBUILT_BOARD)

Custom versal2 board support:

To generate a boot.bin image, Versal2 boards require a PDI (Programmable Device
Image) generated by Xilinx Vivado which contains all the hardware specific
boot information, such as clock, MIO and DDR initializations as well as any
customizations in the programmable logic. Since this PDI can only be generated
by Xilinx Vivado, Buildroot needs access to the prebuilt image. The Buildroot
xilinx-prebuilt package has support for Versal2 XSA files exported from Xilinx
Vivado.

Using the option BR2_TARGET_XILINX_PREBUILT_VERSAL_XSA, Buildroot can obtain
the prebuilt PDI from the XSA file.

1) Start with a defconfig supported by Buildroot (e.g. VEK385)
    make versal2_vek385_defconfig

2) make menuconfig
    Visit the following menu and enable BR2_TARGET_XILINX_PREBUILT_VERSAL_XSA

    Bootloaders  --->
        xilinx-prebuilt  --->
            [*] download a prebuilt Versal XSA

3) Within the same menuconfig, configure location of XSA. It can be in the
   local file system or downloadable from an https:// location.

    Bootloaders  --->
        xilinx-prebuilt  --->
            (<path to XSA>) URL of custom XSA

4) make

The resulting output/images will contain a boot.bin that includes the custom
PDI file extracted from the Xilinx Vivado exported XSA file.

How to write boot.bin to VEK385 OSPI boot flash
=======================================================

The VEK385 cannot be configured to boot from the SD card directly because it
is connected to the 2VE3858 by a USB to SD card bridge and not connected
directly. For this reason, the boot.bin needs to be in the OSPI flash for
booting the first boot stage, and u-boot can then boot Linux and the file
system from the SD card.

For writing the boot.bin file to the OSPI flash the first time, it is
recommended to use the board system controller with the instructions on the
wiki page below:
https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/2273738753/Versal+Evaluation+Board+-+System+Controller+-+Update+7

Once the first boot.bin has been flashed and the VEK385 is able to boot into
u-boot, u-boot can then be used for subsequent updates to the OSPI flash using
the instructions below.

VEK385 U-Boot Flashing Instructions:
    $ usb start
    $ sf probe
    $ fatload usb 0 0x40000000 boot.bin
    $ sf erase 0x0 +$filesize
    $ sf write 0x40000000 0x0 $filesize

If a valid boot.bin is already in the OSPI flash, it is possible to boot the
Buildroot generated SD card image without updating the OSPI boot.bin image, so
this is an optional step when just updating Linux and the file system.

IMPORTANT NOTES for the VEK385
=======================================================

1) The base-design.pdi on the https://github.com/Xilinx/soc-prebuilt-firmware
repo is designed for revB of the VEK385 and will not work properly on revA.
Users should either create their own Vivado XSA file if they have a revA
board, or make sure to get a VEK385 revB or newer board.

2) The default u-boot bootcmd is not the distro_bootcmd that buildroot
expects. When booting for the first time, please stop the boot in u-boot
and run the following commands:
    $ setenv bootcmd 'run distro_bootcmd'
    $ saveenv
    $ boot

3) When using the 2025.2 release, the default u-boot env value for fdt_addr_r
is 0x21000000 which overlaps with the OS image causing the following boot
failure:

Found /extlinux/extlinux.conf
Retrieving file: /extlinux/extlinux.conf
1:      linux
Retrieving file: /Image
append: console="ttyAMA1,115200" root="/dev/sdd2" rw rootwait
Retrieving file: /system.dtb
## Flattened Device Tree blob at 21000000
   Booting using the fdt blob at 0x21000000
ERROR: FDT image overlaps OS image (OS=20200000..21cf0000)
EXTLINUX FAILED: continuing...

This will be fixed with 2026.1 and future releases, but for 2025.2, users
must run the following u-boot commands to change the default value.
    $ setenv fdt_addr_r 0x31000000
    $ saveenv

4) Depending on the device tree used, the USB->SD card interface may not be
probed as /dev/sdd as the probing order can vary based on the device tree
configuration. To deal with this, users will need to change the last
parameter of BR2_ROOTFS_POST_SCRIPT_ARGS to sda2, sdb2 or sdc2 depending on
which corresponds to their configuration's USB->SD card.

For example, the default value in the versal2_vek385_defconfig:
BR2_ROOTFS_POST_SCRIPT_ARGS="ttyAMA1,115200 sdd2"

If the USB->SD card interface probed first, this would need to be changed to:
BR2_ROOTFS_POST_SCRIPT_ARGS="ttyAMA1,115200 sda2"
