/
Discovery and Evaluation AMD Versal Device Portfolio

Discovery and Evaluation AMD Versal Device Portfolio

This page is a getting started guide providing walkthrough style examples using the AMD Embedded Development Framework (EDF). It covers initial board setup and running a pre-built disk image. For other personas and tasks, see the relevant page linked from Getting Started - Walkthrough Examples.

Table of Contents

Introduction

This section walks the user through the Discovery and Evaluation persona within AMD EDF, which covers initial board setup and exploration using a pre-built image. See other persona pages for on target development, deployment options, and custom flows.

 

All Persona: Getting Started - Walkthrough Examples

Discovery and Evaluation - Booting the board for the first time and exploration

image-20250328-112604.png

System Controller Enabled Evaluation Boards - System Controller Firmware Update

Evaluation boards that have a System Controller (SC) may require the SC firmware and BEAM application to be updated to the latest version to support functionality required by the AMD Embedded Development Framework, and the following tutorials.

  • System Controller might be used to program the OSPI / QSPI flash used by the target device (primary boot device)

  • See the System Controller Wiki evaluation board user guide for more information https://xilinx-wiki.atlassian.net/wiki/x/AYCGhw

 

AMD EDF 25.05 (VEK385 EA) - AMD Vivado™ Design Suite 2025.1

The System Controller Firmware on VEK385 Rev B Evaluation Boards might require updating to the latest version to enable programming of the target OSPI (AMD Versal™ AI Edge Series Gen 2 Primary Boot Device)

  • Download and install the latest System Controller Firmware from the System Controller Wiki or VEK385 lounge (if not available on the System Controller Wiki).

  • See also the System Controller Wiki and the evaluation board user guide for more information https://xilinx-wiki.atlassian.net/wiki/x/AYCGhw

 

How to Boot a Board Using the Pre-built Images

Basic board setup - Interfaces and power up

For evaluation board specific interface details, see the following pages. The VEK385 is used as an example below.

The basic board setup is as follows (the VEK385 is used as example below):

  1. Connect the external power supply to the "Power Input" connector

  2. Connect the USB-Type C connector labeled "FTDI USB" to the host PC

  3. Connect the RJ-45 Ethernet for DUT SoC to the local network

  4. Connect the RJ-45 Ethernet for the System Controller (this might be labeled "SC Ethernet") to the local network

Picture (VEK385)

image-20250414-075914.png

Powering the Board

Connect the board external power supply to an outlet, plug in the external supply to the board, and turn the board on with the power switch (the VEK385 is shown below as an example):

image-20250414-080128.png

UART Connections: FTDI-USB

Evaluation boards have multiple UART connections. When the FTDI-USB cable is plugged in, it will create multiple device nodes on the host PC.

For example, VEK385 Rev B has 4 serial / UART interfaces mapped as follows:

  • Device 0 (JTAG)

  • Device 1 (Versal™ PS-UART1)

  • Device 2 (Versal™ PS-UART0)

  • Device 3 (System Controller UART)

For evaluation board specific interface details, see:

 

VEK385 SC UART - VEK385 Rev B Evaluation Boards

Versal PS-UART1 is used by the primary user software, U-Boot and Linux® it can be directly accessed by the host PC via the FTDI UART. 

Versal PS-UART0 is used by default for auxiliary software (PLM, ASU, RPU) and in Rev B of the VEK385, PS-UART0 will be directly accessible via the FTDI-USB interface.

How to boot a board using the pre-built images: Multi-stage boot (QSPI / OSPI -> UFS/SD) - Setup

This section is for evaluation boards that support the EDF Default boot Architecture - multi-stage boot with deferred PL Load (VEK385 Rev B)

Writing the EDF boot firmware to the primary boot device / media using System Controller (SC)

AMD Production Evaluation Boards might not have the latest boot firmware pre-programmed

The following Evaluation boards require boot firmware to be programmed (they are not pre-populated) or updated to the latest available

  • Early Access (EA), Engineering Sample (ES) Evaluation Boards

If your evaluation board does not have a system controller the OSPI/QSPI can also be programed by using the AMD Vivado™ Design Suite

  • For more details, see the evaluation board user guide.

  1. Connect the FTDI-USB cable to the host PC. This will provide serial console interfaces to the PC as well as JTAG access to the Versal device. 

  2. Connect the System Controller (SC) Ethernet interface to a network accessible by the host PC.

  1. On power up, the System Controller (SC) should boot and automatically start the BEAM tool, which can be accessed via a web-interface at the IP address it notes. 

 System Controller Start

amd-edf login: **************************************** * * * BEAM Tool Web Address        * * * * http://10.10.71.1            * * http://amd-edf     * * * ****************************************

  1. The BEAM interface landing page is shown below.

If the Versal Device Control option is not visible, please update the System Controller Image and Application - Evaluation Board - System Controller (SC)

You should see the welcome screen as shown in the image. This will install the necessary drivers and support files required to connect and manage the evaluation board.

If the board support files are already installed, the welcome screen will not be displayed. Instead, you will see the board details screen directly. In this case, you can skip the 'Install Board Support' step, as it is not required

Click on "Install Board Support:

  • On the right side of the screen, click the Install Board Support button.

  • This will install the necessary drivers and support files required to connect and manage the evaluation board.

Wait for Installation:

  • The tool will begin installing the board support files. Wait for the process to complete.

  • Once the installation is successful, the tool will be ready to detect and connect to the board.

Screenshot (56)-20251121-105829.png

Board Details Screen:

  • The BEAM Tool should automatically detect the connected board.

  • Once the board is connected, the tool will display the board details (e.g., board name, serial number, etc.).

  • You can now proceed with further operations

  • To load the OSPI, select Versal Device Control.

Screenshot (96)-20251121-105632.png

  1. Then use the Choose File option under the Upload OSPI: menu and select Load OSPI aligned with the image uploaded.

Screenshot (64)-20251121-070414.png

  • Select the Program checkbox under the Load OSPI section.

  • If you want to verify the OSPI image after programming, select the Verify checkbox

  • Click the Apply button to start programming the OSPI flash memory.

  • Wait for the programming process to complete.

Screenshot (65)-20251121-115949.png

Once complete, the BEAM tool will return a success message.

If this process fails consult your FAE.

 

  1. Verify the programmed OSPI works and boots to U-Boot successfully by monitoring the FTDI-UART output after a power cycle: Board specific specifications and information

Set the boot mode switch (SW1 on VEK385, VEK280, VCK190) to QSPI / OSPI boot, and confirm the boot is successful.

SW 1 Boot Mode switch settings

 

Mode Pins [0:3]

Mode SW1 [1:4]

 

Mode Pins [0:3]

Mode SW1 [1:4]

SDCARD Boot (SD1)

0111

ON, OFF, OFF, OFF

OSPI / QSPI Boot

0001

ON, ON, ON, OFF

JTAG Boot

0000

ON, ON, ON, ON

See the screen capture below for reference (picture is taken from a VEK385).

VEK385_Boot_Mode_Setting.jpg
VEK385 SW 1 showing OSPI boot mode settings

ospi-boot-test (Taken from VEK385 boot)

[0.011]**************************************** [0.043]Xilinx Versal Aiepg2 Platform Loader and Manager [0.080]Release 2025.1 Mar 26 2025 - 02:13:26 [0.116]Platform Version: v1.0 PMC: v1.0, PS: v1.0 [0.154]BOOTMODE: 0x8, MULTIBOOT: 0x0 [0.181]**************************************** [0.366]Non Secure Boot [0.390]Device key init is skipped as no valid CDI is found [4.618]PLM Initialization Time [4.641]***********Boot PDI Load: Started*********** [4.715]Loading PDI from OSPI [4.737]Monolithic/Master Device [6.147]FlashID=0x2C 0x5B 0x1C [8.032]OSPI mode switched to DDR [10.318]5.640 ms: PDI initialization time [10.350]+++Loading Image#: 0x1, Name: lpd, Id: 0x04210002 [10.393]---Loading Partition#: 0x1, Id: 0xC [10.494]LPD T50 power sequence version 0.34 [10.541]lpd_scanclear [10.588]LPD scan clear pass [10.615]lpd_bisr [10.642]lpd_mbist [11.341]LPD MBIST pass [86.838]Done LPD power up [89.109] 78.682 ms for Partition#: 0x1, Size: 13984 Bytes [94.184]+++Loading Image#: 0x2, Name: fpd, Id: 0x0420C003 [99.239]---Loading Partition#: 0x2, Id: 0x8 [103.222]FPD T50 power sequence version 0.44 [107.068]fpd_scanclear [109.140]FPD scan clear pass [111.694]fpd_bisr [113.333]fpd_mbist [117.414]FPD MBIST pass [117.942]Done FPD power up [119.593]MMI T50 house cleaning sequence version 0.68 [124.324]mmi_scanclear [126.418]MMI scan clear pass [129.175]mmi_gpu_lbist [131.233]MMI GPU LBIST starts [135.410]MMI GPU LBIST pass [136.167]mmi_bisr [137.811]mmi_gtyp_bisr [139.868]mmi_mbist_clk_setup [142.471]mmi_mbist [149.989]MMI MBIST pass [150.024]mmi_gtyp_mbist [151.678]MMI GTYP MBIST pass [164.715]Done MMI power up [164.752] 61.648 ms for Partition#: 0x2, Size: 105968 Bytes [169.531]+++Loading Image#: 0x3, Name: pl_cfi, Id: 0x18700000 [174.929]---Loading Partition#: 0x3, Id: 0x5 [179.010]npd_preconfig [180.945]NPD T50 power sequence version 0.22 [184.914]npd_scanclear [187.376]check_npd_scanclear [189.534]NPD scan clear pass [192.110]npd_pre_memclear [194.425]unlock_ddrmc_ub [196.655]unlock_nxu [198.473]npd_bisr [200.093]bisr_ddrmc_ub [202.161]npd_memclear [204.132]ila_clk_enable_ddrmc [206.788]memclear_trigger_ddrmc [209.619]memclear_trigger_nmu [212.299]check_memclear_ddrmc [214.948]check_memclear_nmu [217.531]ila_clk_disable_ddrmc [220.182]NPD mem clear pass [222.668]nxu_odisable_assert [225.289]efuse_secure_transfer [228.017]unlock_ddrmc_mc [230.351]lock_ddrmc_mc [232.285]ub_initstate_deassert [235.032]lock_ddrmc_ub [237.094]lock_nxu [238.776]Done NPD power up. [1868.490]Polling 0xF6570008 Mask: 0x10 ExpectedValue: 0x10 [2244.050] 2065.169 ms for Partition#: 0x3, Size: 2245472 Bytes [2246.807]+++Loading Image#: 0x4, Name: asufw, Id: 0x1C000002 [2252.210]---Loading Partition#: 0x4, Id: 0xF [2258.419] 2.169 ms for Partition#: 0x4, Size: 448 Bytes [2261.234]---Loading Partition#: 0x5, Id: 0xB [2265.766] 0.494 ms for Partition#: 0x5, Size: 74000 Bytes [2270.443]+++Loading Image#: 0x5, Name: aie2_subsys, Id: 0x0421C028 [2276.357]---Loading Partition#: 0x6, Id: 0x7 [2280.469]aie2_preconfig [2282.639]AIE2ps T50 house cleaning sequence version 0.40 [2287.703]aie_efuse_secure_transfer [2290.913]aie_check_efuse_secure_transfer [2294.590]aie_scanclear [2297.211]AIE scan clear pass [2299.460]aie_pre_mbist [2301.565]Value at 0x2003C07FF20: 1 [2304.714]Value at 0x2003E07FF20: 1 [2307.893]Value at 0x2004007FF20: 1 [2311.073]Value at 0x2004207FF20: 1 [2314.301]aie_bisr [2315.983]aie_mbist [2317.817]AIE MBIST pass [2320.394]Done AIE power up [2322.506] 42.109 ms for Partition#: 0x6, Size: 12848 Bytes [2330.131]WARN XPmClock_RequestInt: Invalid parent clockIdx 0 [2338.917]+++Loading Image#: 0x6, Name: apu_ss, Id: 0x1C000000 [2341.578]---Loading Partition#: 0x7, Id: 0x0 [2345.820] 0.203 ms for Partition#: 0x7, Size: 58608 Bytes [2350.774]---Loading Partition#: 0x8, Id: 0x0 [2355.005] 0.192 ms for Partition#: 0x8, Size: 53296 Bytes [2359.969]---Loading Partition#: 0x9, Id: 0x0 [2364.105] 0.097 ms for Partition#: 0x9, Size: 26176 Bytes [2369.161]---Loading Partition#: 0xA, Id: 0x0 [2376.467] 3.269 ms for Partition#: 0xA, Size: 1219424 Bytes [2379.013]***********Boot PDI Load: Done*********** [2383.509]56.855 ms: ROM Time [2386.171]Total PLM Boot Time runtime console NOTICE: TF-A running on Silicon v0.0, RTL v8.6, PS v8.6, PMC v8.6 INFO: CPU Revision = 0x3 INFO: cpu_clock = 100000000Hz, uart_clock = 100000000Hz NOTICE: BL31: Executing from 0xbbf00000 NOTICE: BL31: Secure code at 0x1800000 NOTICE: BL31: Non secure code at 0x40000000 NOTICE: BL31: v2.12.0(debug):v1.1-15203-gf418a6916-dirty NOTICE: BL31: Built : 11:18:22, Mar 19 2025 INFO: GICv3 without legacy support detected. INFO: ARM GICv3 driver initialized in EL3 INFO: Maximum SPI INTID supported: 543 INFO: SCMI: Server initialized INFO: BL31: Initializing runtime services INFO: BL31: cortex_a78_ae: CPU workaround for CVE 2022_23960 was applied INFO: BL31: Preparing for EL3 exit to normal world INFO: Entry point address = 0x40000000 INFO: SPSR = 0x3c9 U-Boot 2025.01-g5a324e1e94ae-dirty (Mar 26 2025 - 10:13:21 +0000) CPU: Versal Gen 2 Silicon: v1.0 Chip: v1.0 Detected name: versal2-vek385-revA01 Model: AMD Versal VEK385 revA DRAM: 2 GiB (effective 8 GiB) EL Level: EL2 Core: 44 devices, 24 uclasses, devicetree: board MMC: Loading Environment from nowhere... OK In: serial@f1930000 Out: serial@f1930000 Err: serial@f1930000 Bootmode: OSPI_MODE Xilinx I2C FRU format at nvmem0: Manufacturer Name: XILINX Product Name: VEK385 Serial No: 519101A01113 Part Number: 5191-01 File ID: 0x0 Revision Number: A01 Net: ZYNQ GEM: f1a60000, mdio bus f1a60000, phyaddr 1, interface rgmii-id eth0: ethernet@f1a60000 ZYNQ GEM: ed920000, mdio bus ed920000, phyaddr 0, interface 10gbase-r Warning: ethernet@ed920000 (eth1) using random MAC address - f6:64:28:24:5c:9c , eth1: ethernet@ed920000 Device at ufs@f10b0000 up at:ufs-versal2-pltfm ufs@f10b0000: [RX, TX]: gear=[1, 1], lane[1, 1], pwr[SLOWAUTO_MODE, SLOWAUTO_MODE], rate = 0 scanning bus for devices... Hit any key to stop autoboot: 0 starting USB... Bus usb@f1c00000: Register 1000440 NbrPorts 1 Starting the controller USB XHCI 1.10 scanning bus usb@f1c00000 for devices... 3 USB Device(s) found scanning usb for storage devices... 1 Storage Device(s) found Device 0: Vendor: Generic Rev: 1.98 Prod: Ultra HS-COMBO Type: Removable Hard Disk Capacity: 60874.0 MB = 59.4 GB (124669952 x 512)

  1. Download the common EDF Linux® disk image, and write it to the secondary boot media. VEK385 Rev B uses UFS as the default storage media.

SD Boot Mode – SD cannot be used as the primary boot mode on the VEK385 or other newer boards. SD is only supported as a secondary boot device (for example, in multi‑stage boot flows such as OSPI → SD)

Writing the EDF Linux® Disk Images (wic) to the Secondary Boot Media: UFS device

The disk image may be -

  • A common disk image - Evaluation boards supporting the EDF default boot architecture - multi-stage boot with deferred PL load

See Downloads and Release Notes for download links for the EDF Linux® common disk image for supported Evaluation Boards

Write the common EDF Linux® disk image to the secondary boot media.

VEK385 Rev B Board - The secondary boot media is an UFS device

Minimum UFS device size 16 GB: AMD EDF disk images require a minimum of a 16 GB UFS device to work correctly.

The .wic.ufs.xz file be written to an UFS device using web-interface Image recovery tool:

Initial Setup for UFS device:

Before initializing the UFS device for normal operation, it must be configured by reading the Device Descriptor and Configuration Descriptor. These descriptors provide essential information about the device’s capabilities, such as supported features, logical unit configuration, boot LUN settings, and performance attributes. Using this data, the host can enable or adjust parameters like logical units, block sizes, and optional features (e.g., WriteBooster or RPMB) to ensure the device operates according to system requirements.

For UFS device configuration, first update the OSPI image using the BEAM tool Discovery and Evaluation AMD Versal Device Portfolio . Next, launch the Linux-based image recovery shell Discovery and Evaluation AMD Versal Device Portfolio and follow the steps outlined in the referenced wiki page UFS Linux driver to complete the UFS configuration process. Finally, reboot the board.

Flash WIC Image to UFS Storage device Using Image Recovery Tool and Boot VEK385 Board in OSPI + UFS Mode

After updating the OSPI image using the BEAM tool, follow the steps below to launch and update the WIC image using the Image Recovery tool.

Image Recovery Tool Instructions

  1. Launch Linux-based image recovery shell

  • The Image Recovery tools is a web-based tool that can be used to update either firmware or an new Linux image.

  • To launch Image Recovery, first power off the board.

  • Then, press and hold the FWUEN (SW14) push button while powering on the evaluation board (e.g., vek385_revB). After 3 to 5 seconds, release the push button.

  • This will launch Linux-based image recovery shell, Check the serial terminal for the image recovery boot log.

  1. Launch Image Recovery Web Interface using IP address

  • The web interface operates using an IP address (e.g., 10.10.70.2:8080), which is displayed on the UART console output (Image_recovery_boot.log) of the target when image recovery boot mode is triggered.

  • In the serial terminal, look for a message similar to:

    ################################################################################################## # # #Launching to Image Recovery shell, Use 10.140.187.142:8080 to launch the Image Recovery web app.# # # ##################################################################################################

  • On the host machine, launch a browser (e.g., Firefox) and navigate to: http://10.140.187.142:8080, This opens the image recovery web interface page.

  1. The Image Recovery web interface provides four tabs:

  • System Information

  • Ethernet Recovery

  • USB Recovery

  • Configuration Settings (UFS configuration)

The System Board Information section provides essential hardware details (such as VEK385 board name, revision, serial number, part number, and UUID), along with the boot image status of Bank A and Bank B.

Screenshot 2026-03-10 164438.png

Using the Image Recovery web interface to Update Boot Firmware and WIC Image:

Boot firmware or WIC image updates can be performed in two ways: via Ethernet or using a USB drive containing the respective images connected to the board.

The Image Recovery web interface provides two options:

  • Ethernet Recovery

  • USB Recovery

The web interface provides an option to update the UFS configuration

  • Configuration settings

A. Ethernet Recovery

To update the Boot Firmware and Linux image using Ethernet Recovery, click the Ethernet Recovery tab and follow the steps outlined below.

  1. Update Boot Firmware:

  • Click on Boot image and Select Boot.bin.

  • Click on Upload

Boot_img.png

  • A pop-up will confirm the successful update and display the message shown below (takes 1–2 minutes).

boot_upload.png

  1. Update Linux image:

  • Click on WIC and select a WIC image (e.g., wic.xz, wic.ufs.xz). Optionally, you can select a bmap file.

  • Choose the Storage device (e.g., UFS,USB)

  • Click on Upload

wic_img.png

  • A pop-up will confirm the successful update and display the message shown below (takes 3–10 minutes depending on file size and format).

wic_upload.png

B. USB Recovery

To update the Boot Firmware and Linux image using USB Recovery, click the USB Recovery tab and follow the steps outlined below.

Pre-requisites: Prepare the USB Flash Drive for USB Recovery (BOOT & WIC Images).

  • Insert USB drive into your Windows/Linux PC.

  • Format the USB as FAT32 (Right-click USB → Format → Select FAT32 → Start).

  • Copy the BOOT and WIC images into the root of the USB drive:

    • BOOT-versal-...bin

    • edf-linux-disk-image-...wic.ufs.xz

  • Do not rename the files and do not place them inside folders.

  • Insert the USB into the evaluation board (e.g., vek385_revB).

These steps ensure that USB Recovery web interface can scan the USB stick and display image files properly.

  1. Update Boot Firmware:

  • Click on Boot Image and select the partition where the images are copied.

  • Choose boot.bin

  • Click on Upload

usb_bootbin.png

  • A pop-up will confirm the successful update and display the message shown below (takes 1–2 minutes).

usbbootbin_upload.png

  1. Update Linux image:

  • Select the WIC image (e.g., .wic.ufs.xz) and choose the partition where the image is stored.

  • Select the WIC image.

  • Click on Upload

usb_wic.png

  • A pop-up will confirm the successful update and display the message shown below(takes 3–10 minutes depending on file size and format).

usb_wic_success.png

After successfully updating the images, Set the boot mode switch (SW1 on VEK385, VEK280, VCK190) to OSPI boot, and confirm the boot is successful.

C: Configuration settings

  1. To update the UFS configuration, go to Configuration Settings.

2df0d710-f477-4e20-9cb4-75bb4f4f8f2d.png

  1. Click on Query Device. This will dump the current UFS configuration.

  2. Under Logical Unit Configuration, configure the following two Logical Units (LUs):

  3. Logical Unit Parameters LU Enable Size Memory Type Boot LUN Write Protect Allocation Units (dNumAllocUnits) LU0 LU Enable: Yes Size: 20 GB Memory Type: Normal (0x0) Boot LUN: Boot A (0x1) Write Protect: None (0x0) Allocation Units: 0x1400 LU1 LU Enable: Yes Size: 2–4 GB Memory Type: Normal (0x0) Boot LUN: Boot B (0x0) Write Protect: None (0x0) Allocation Units: 0x0100

  4. Click on Write Configuration. This will store the configuration binary file in
    /tmp/log/image-recovery/.

ufs_write.png

  1. Recheck the configuration and reboot the device.

  2. After reboot, the updated UFS configuration will be applied.

Boot VEK385 board in OSPI + UFS by Setting OSPI boot mode

  • SW 1 Boot Mode switch settings

See board specific information / board user guide for more details and AMD EDF Board specific specifications and information/flows for information on other supported evaluation boards: Board specific specifications and information, https://docs.amd.com/r/en-US/ug1304-versal-acap-ssdg/Boot-Device-Modes

  • Turn off the evaluation board (e.g., vek385_revB) and then power it on again.

  • The U-Boot Boot Menu will appear with the following options:

*** U-Boot Boot Menu *** usb 0 usb 1 scsi 0 scsi 1 Exit Press UP/DOWN to move, ENTER to select, ESC to quit Booting: scsi 0

  • The UFS device is typically connected via the SCSI interface, which is why it appears as scsi 0 or scsi 1 in the boot menu.

  • If multiple SCSI devices are connected, ensure you select the correct device containing the bootable image.

Select the UFS Boot Option

  • Select scsi 0 (or the appropriate SCSI device for UFS boot).

  • Press ENTER to select the option.

Boot from UFS

  • After selecting scsi 0, U-Boot will attempt to boot from the UFS device.

  • It boots from OSPI initially, followed by the UFS device for the rootfs and kernel image.

  • Once Linux boots, Username for amd-edf 2025.2 is amd-edf and set password option will be prompted where user need to set a password.

Booting VEK385 using OSPI + UFS boot mode:

Writing the EDF Linux® Disk Images (wic) to the Secondary Boot Media: SD Card

The disk image may be -

  • A common disk image - Evaluation boards supporting the EDF default boot architecture - multi-stage boot with deferred PL load

  • A board specific disk image - Evaluation boards supporting single-stage boot from SD card

See Downloads and Release Notes or Downloads and Release Notes for download links for the EDF Linux® common disk image for supported Evaluation Boards

Write the common EDF Linux® disk image to the secondary boot media.

VEK386 Rev A, VEK280, VCK190 etc. Board - The secondary boot media is SD card

This is done using the Linux image, which is distributed as a WIC file and using an off-the-shelf tool, written to the physical SD card from a users PC. 

Minimum SD card size 16 GB: AMD EDF disk images require a minimum of a 16 GB SD card to work correctly.

balenaEtcher: Recent versions have been found to be unreliable when flashing, failing during the verify stage of writing. If you experience this issue, please use an alternative tool.

The .wic.xz file be written to an SD card using either an application such as Raspberry Pi Imager or balenaEtcher or a command line utility, such as dd or bmaptool:

image-2024-12-17_15-3-52.png

bmaptool instructions

On a Linux host computer, we can flash the WIC image to an SD card using bmaptool as follows:

The SD device name can vary! The following example needs to align with the sd* device name enumerated for the target SD card by your host system.

$ bmaptool copy edf-linux-disk-image-amd-cortexa78-mali-common.rootfs.wic.xz /dev/sdk bmaptool: info: discovered bmap file 'edf-linux-disk-image-amd-cortexa78-mali-common.rootfs.wic.bmap' bmaptool: info: block map format version 2.0 bmaptool: info: 2359297 blocks of size 4096 (9.0 GiB), mapped 227540 blocks (888.8 MiB or 9.6%) bmaptool: info: copying image 'edf-linux-disk-image-amd-cortexa78-mali-common.rootfs.wic.xz' to block device '/dev/sdk' using bmap file 'edf-linux-disk-image-amd-cortexa78-mali-common.rootfs.wic.bmap' bmaptool: info: 100% copied bmaptool: info: synchronizing '/dev/sdk' bmaptool: info: copying time: 4m 51.7s, copying speed 3.0 MiB/sec

WARNING: Booting multiple image with the same root file system partition UUID may result in boot issues. In EDF, the Linux kernel locates the correct root filesystem by passing the root=PARTUUID=XXXX parameter in the kernel command line.

In EDF 2025.05 the PARTUUID parameter is hard-coded meaning that it is not possible to have multiple image connected to a board - for example, an SD card and USB key with the same image. This may result in undetermined behaviour or boot errors as uboot and the linux kernel may enumerate the devices differently and the kernel will mount the first partition it finds with the matching PARTUUID.

In EDF 2025.11 the PARTUUID is randomly generated for each image (build) so it is possible to have different images on different media and have the system boot correctly. It is still not possible to have the same image on multiple media.

How to Boot a Board Using the Pre-built Images: Single-Stage Boot UFS/SD Mode - Setup

Writing the EDF Linux® Disk Image (wic) to the Boot Media: SD Card

This section is for evaluation boards that support single step boot from SD card as the default boot mode for pre-built images (VEK280, VCK190).

  1. Download the pre-built board specific EDF Linux disk image for SD boot for your Evaluation board, and write the image file to an to SD card

  1. After programming the SDCARD move to step Discovery and Evaluation AMD Versal Device Portfolio

Writing the EDF Linux® Disk Image (wic.ufs.xz) to the Boot Media: UFS device

This section describes how to boot the board from UFS as the primary boot media using the Image Recovery web-based tool

Prerequisites:

Get all artifacts which are required for boot

  1. BOOT.BIN

  2. A common disk image .wic.ufs.xz format (eg., edf-linux-disk-image-amd-cortexa78-mali-common.rootfs.wic.ufs.xz)

  3. Installed tools on the host: xz, wic, bmaptool, and standard core utilities.

  4. Target board must have proper UFS configuration as mentioned in Discovery and Evaluation AMD Versal Device Portfolio

See Downloads and Release Notes for download links for the EDF Linux® common disk image for supported Evaluation Boards.

wic.ufs.xz Image Preparation Steps:

Perform the following steps on the host system to prepare the UFS boot image.

Decompress

Decompress the existing .wic.ufs.xz file to obtain the raw .wic.ufs image. Replace file names and paths as appropriate for your environment.

xz -df <image-name>.rootfs.wic.ufs.xz # Example xz -df edf-linux-disk-image-amd-cortexa78-mali-common.rootfs.wic.ufs.xz

After this step, you should have an uncompressed file similar to:

edf-linux-disk-image-amd-cortexa78-mali-common.rootfs.wic.ufs

Inject BOOT.BIN

Use the wic cp command to copy the BOOT.BIN file into partition 1 of the .wic.ufs image. Ensure that the correct sector size is specified for the target media (4096 in this example).

$ wic cp --sector-size=4096 <boot-binary>.bin <image-name>.rootfs.wic.ufs:1 # Example # $ wic cp boot.bin --sector-size=4096 edf-linux-disk-image-amd-cortexa78-mali-common.rootfs.wic.ufs:1 $ wic ls --sector-size=4096 edf-linux-disk-image-amd-cortexa78-mali-common.rootfs.wic.ufs:1 Volume in drive : is esp Volume Serial Number is 9BC7-2DC2 Directory for ::/ EFI <DIR> 2011-04-05 23:00 IMAGE 32920064 2011-04-05 23:00 Image loader <DIR> 2011-04-05 23:00 xen cfg 347 2011-04-05 23:00 xen efi 1048592 2011-04-05 23:00 boot bin 5320016 2026-03-10 12:10 6 files 39 289 019 bytes 1 032 073 216 bytes free

Confirm that the command completes without errors before proceeding.

Generate the *.wic.ufs.xz image since the Image Recovery tool supports this format

Compress the generated *.wic.ufs image to *.wic.ufs.xz using the xz command as shown below.

$ xz -c edf-linux-disk-image-amd-cortexa78-mali-common.rootfs.wic.ufs > edf-linux-disk-image-amd-cortexa78-mali-common.rootfs.wic.ufs.xz

At this point, you should have modified .wic.ufs.xz image.

Flash wic.ufs.xz Image to UFS Storage media Using Image Recovery Tool and Boot VEK385 Board in UFS Mode

This section provides a complete procedure for wic.ufs.xz image updates through the image recovery web-interface using Ethernet and USB recovery methods.

Initial Setup for UFS device follows:Discovery and Evaluation AMD Versal Device Portfolio

After updating the OSPI image using the BEAM tool Discovery and Evaluation AMD Versal Device Portfolio , follow the steps below to launch and update the WIC image using the Image Recovery tool.

Image Recovery Tool Instructions

  1. Launch Linux-based image recovery shell

  • The Image Recovery tools is a web-based tool that can be used to update either firmware or a new Linux image.

  • To launch Image Recovery, first power off the board.

  • Then, press and hold the FWUEN (SW14) push button while powering on the evaluation board (e.g., vek385_revB). After 3 to 5 seconds, release the push button.

  • This will launch Linux-based image recovery shell, Check the serial terminal for the image recovery boot log.

  1. Launch Image Recovery Web Interface using IP address

  • The web interface operates using an IP address (e.g., 10.10.70.2:8080), which is displayed on the UART console output (Image_recovery_boot.log) of the target when image recovery boot mode is triggered.

  • In the serial terminal, look for a message similar to:

    ############################################################################################## # # #Launching to Image Recovery shell, Use 10.10.70.1:8080 to launch the Image Recovery web app.# # # ##############################################################################################

  • On the host machine, launch a browser (e.g., Firefox) and navigate to: http://10.10.70.1:8080, This opens the image recovery web interface page.

  1. The Image Recovery web interface provides three tabs:

  • System Information

  • Ethernet Recovery

  • USB Recovery

The System Board Information section providing basic information about the hardware (e.g., VEK385 board Name, Revision, Serial, Part, UUID).

Screenshot 2026-03-10 164438.png

Using the Image Recovery web interface to Update WIC Image:

WIC image updates can be performed in two ways: via Ethernet or using a USB drive containing the respective images connected to the board.

The Image Recovery web interface provides two update options:

  • Ethernet Recovery