OSPI + UFS Boot Flow

OSPI + UFS Boot Flow#

UFS Boot Flows for VEK385 (VE2)#

The VEK385 board has an onboard 64 GB UFS flash device that can be used as the primary boot device.

Note

The OSPI + UFS boot flow is supported only on VEK385 Rev B platforms. It is not supported on VEK385 Rev A.

  • UFS storage delivers high-performance, low-power managed NAND solutions (UFS 3.1) optimized for automotive platforms, with differentiated firmware features, advanced NAND technology, and industry-leading automotive reliability.

  • Faster booting using UFS (~3 GB/s) over OSPI SD (300 MB/s) booting.

Images required for the UFS flow are described in the following list:

File

Purpose

BOOT.bin

The VAIML bootloader binary is provided in the release package.

*ospi*.bin

The OSPI image for OSPI flash is provided in the release package.

rootfs.wic.ufs.xz

The VAIML Linux disk image for UFS is provided in the release package.

rootfs.wic.ufs.bmap

Block map file (optional, for faster flashing).

BOOT.bin#

The VAIML bootloader binary is provided in the release package. The BOOT.bin file contains the platform’s bootloader images required for initial booting up to U-Boot.

OSPI Image#

The OSPI image (*ospi*.bin) contains platform images (BOOT.bin) along with various tools, such as image recovery utilities for flashing the UFS image.

OSPI flash images are stored using a partitioned architecture with “Bank A” and “Bank B,” consisting of active and backup partitions.

UFS WIC image on UFS flash#

The VAIML Linux disk image for UFS is provided in the release package. This image contains VAIML BOOT.bin, Kernel, and rootfs.

UFS Device Initial Configuration#

Before flashing images, the UFS device must be properly configured. This is a one-time setup.

By default (on any new UFS device), all Logical Units are in a disabled state. This means the UFS memory cannot be accessed from user space unless the device is configured with the required number of Logical Units.

As part of device configuration, Logical Units must be enabled with the required amount of memory assigned to each. This UFS device configuration can be done using the open-source utility ufs-utils from Linux. A pre-created config file ufsconfig_64gb is used. Run the following command on the rootfs/Linux (Since it is a one-time setup, this can be done from the SD Card boot):

root# ufs-utils desc -t 1 -w /etc/ufs_config/ufsconfig_64gb -p /dev/bsg/ufs-bsg0
Config Descriptor was written to device

Minimum UFS device size: 16 GB. AMD disk images require a minimum of 16 GB.

After writing the configuration, reboot the device for the changes to take effect.

After reboot, verify the UFS is configured correctly.

Note

That step is required only when UFS is not configured. An SD card script handles this case.

Here is a command to verify whether UFS is configured:

root@amd-edf:~# lsblk -d -o NAME,MODEL,SIZE | grep MT064GBCAV1U31AA
sda        MT064GBCAV1U31AA 54G
sdb        MT064GBCAV1U31AA    1G
sdc        MT064GBCAV1U31AA    4G
root@amd-edf:~#

Another way to get the detailed UFS disk information for all Micron UFS Logical Units if it is configured:

root@amd-edf:~# cat get_ufs_info

sudo fdisk -l | awk '
/Disk \/dev\/sd/ {disk=$0}
/Disk model: MT064GBCAV1U31AA/ {print disk; print; show=1; next}
show && /Units:|Sector size|I\/O size/ {print}
/^$/ {if(show){print ""; show=0}}
'

root@amd-edf:~# ./get_ufs_info
Disk /dev/sda: 54 GiB, 57982058496 bytes, 14155776 sectors
Disk model: MT064GBCAV1U31AA
Units: sectors of 1 * 4096 = 4096 bytes
Sector size (logical/physical): 4096 bytes / 4096 bytes
I/O size (minimum/optimal): 4096 bytes / 524288 bytes

Disk /dev/sdb: 1 GiB, 1073741824 bytes, 262144 sectors
Disk model: MT064GBCAV1U31AA
Units: sectors of 1 * 4096 = 4096 bytes
Sector size (logical/physical): 4096 bytes / 4096 bytes
I/O size (minimum/optimal): 4096 bytes / 524288 bytes

Disk /dev/sdc: 4 GiB, 4294967296 bytes, 1048576 sectors
Disk model: MT064GBCAV1U31AA
Units: sectors of 1 * 4096 = 4096 bytes
Sector size (logical/physical): 4096 bytes / 4096 bytes
I/O size (minimum/optimal): 4096 bytes / 524288 bytes
root@amd-edf:~#

Different UFS Boot Flows#

Multi-Stage Boot Flow: OSPI + UFS (Currently Supported)#

In the multi-stage boot flow, OSPI flash is the primary boot device and UFS is the secondary boot device.

The system boots using BOOT.bin from the OSPI flash, while the kernel and root filesystem (rootfs) are loaded from the UFS device.

Overview of Multi-Stage Boot Flow#

This provides a complete procedure for setting up the VEK385 (VE2) evaluation board with an OSPI + UFS multi-stage boot flow. The boot architecture is:

  1. Primary boot (OSPI): The bootloader (PLM, TF-A, U-Boot) is stored in OSPI flash and executes on power-on.

  2. Secondary boot (UFS): The Linux kernel and root filesystem are stored on the UFS storage device and loaded by U-Boot.

The procedure consists of two main phases:

  • Phase 1: Program the OSPI flash with the boot firmware using the automated JTAG script.

  • Phase 2: Flash the Linux disk image (WIC) to the UFS storage device using the Image Recovery web tool.

Prerequisites#

Hardware#

  • AMD VEK385 Rev B evaluation board

  • USB-C cable (provides JTAG + serial console via FTDI)

  • Ethernet cable (for Image Recovery tool web interface)

  • External power supply for VEK385

Host Tools#

Install the following tools on your Linux host machine:

# Install expect (required for OSPI flash script)
sudo apt install expect

# Verify Vivado Lab Edition 2026.1+ is installed
ls /tools/Xilinx/Vivado_Lab/2026.1/

Vivado Lab Edition is a free, lightweight download that includes XSDB and JTAG programming tools without the full Vivado design suite. Download from AMD Downloads.

SW1 DIP Switch Reference#

Boot Mode

Mode Pins [0:3]

Mode SW1 [1:4]

JTAG Boot

0000

ON, ON, ON, ON

OSPI / QSPI Boot

0001

ON, ON, ON, OFF

SD Card Boot (SD1)

0111

ON, OFF, OFF, OFF

UFS Boot

1101

OFF, OFF, ON, OFF

Phase 1: OSPI Flash Programming#

Purpose#

Program the bootloader firmware into the VEK385 OSPI flash memory using the automated vek385-flash-ospi.exp script over JTAG. After programming, the board boots independently from OSPI flash.

Please refer to the OSPI+SD card flashing procedure for OSPI flash programming, as the OSPI flash programming steps are common to both the OSPI+SD and OSPI+UFS flows.

Phase 2: UFS Image Flashing via Image Recovery Tool#

Purpose#

Flash the Linux disk image (WIC) to the UFS storage device using the Image Recovery web-based tool.

Launch Image Recovery Shell#

  1. Ensure the OSPI image is programmed (Phase 1, described previously).

  2. Power OFF the board.

  3. Press and hold the FWUEN (SW14) push button while powering on the board.

  4. After 3-5 seconds, release the push button.

  5. This launches the Linux-based image recovery shell. Check the serial terminal for the boot log.

Launch Image Recovery Web Interface#

  1. 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.#
#                                                                                                #
##################################################################################################

    Warning

    If the Image Recovery shell does not show an IP address, configure a static IP manually on both the board and the host PC.

    On the Linux host (laptop/PC side):

    sudo ifconfig eth0 10.10.70.1 netmask 255.255.255.0 up

    On the Image Recovery shell (board side):

    sh-5.2# ip addr add 10.10.70.2/24 dev eth0
sh-5.2# ip link set eth0 up
sh-5.2# ip addr show eth0
3: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP qlen 1000
    link/ether 62:8f:6a:c2:40:96 brd ff:ff:ff:ff:ff:ff
    inet 10.10.70.2/24 scope global eth0
       valid_lft forever preferred_lft forever

sh-5.2# ping 10.10.70.1
PING 10.10.70.1 (10.10.70.1): 56 data bytes
64 bytes from 10.10.70.1: seq=0 ttl=128 time=0.784 ms
64 bytes from 10.10.70.1: seq=1 ttl=128 time=0.600 ms
^C
--- 10.10.70.1 ping statistics ---
4 packets transmitted, 4 packets received, 0% packet loss

    After configuring static IPs, navigate to http://10.10.70.2:8080 in your browser to access the Image Recovery web interface.

  2. On the host machine, open a browser (for example, Firefox) and navigate to the IP address shown: http://<board-ip>:8080

  3. The Image Recovery web interface opens with three tabs:

    • System Information - Board hardware details (name, revision, serial number)

    • Ethernet Recovery - Update images via network upload

    • USB Recovery - Update images from USB drive

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

Image Recovery Tool - System Information tab showing VEK385 board details and Bank A/B boot image status

Flash WIC Image to UFS#

From the Image Recovery web-based tool, flash the WIC image using either Ethernet Recovery or USB Recovery.

Ethernet Recovery

  1. Click the Ethernet Recovery tab.

  2. Update Linux Image:

    • Click on WIC Image radio button and select the WIC image file (for example, rootfs.wic.ufs.xz).

    • Click Upload. A pop-up confirms successful update (takes 3-10 minutes depending on file size).

In the Ethernet Recovery tab, select WIC Image, choose the rootfs.wic.ufs.xz file, set the target storage device to the UFS device (/dev/sda - UFS (MT064GBCAV1U31AA)), and click UPLOAD:

Ethernet Recovery - WIC Image selected with rootfs.wic.ufs.xz targeting the /dev/sda UFS device

A pop-up confirms the WIC image was flashed successfully to /dev/sda:

Upload Successful pop-up confirming the WIC image was flashed successfully to /dev/sda

USB Recovery

As an alternative to Ethernet Recovery, the WIC image can be flashed from a USB drive.

  1. Prepare the USB drive on your host PC:

    • Insert the USB drive and format it as FAT32.

    • Copy the WIC image (for example, rootfs.wic.ufs.xz) to the root of the USB drive. Do not rename the file or place it inside a folder.

  2. Insert the USB drive into the evaluation board.

  3. In the Image Recovery web interface, click the USB Recovery tab.

  4. Update Linux Image:

    • Click on WIC Image radio button and select the WIC image file (for example, rootfs.wic.ufs.xz).

    • Select the appropriate target storage device (for example, /dev/sda).

    • Click Upload. A pop-up confirms successful update.

Boot VEK385 in OSPI + UFS Mode#

Step 1: Set Boot Mode#

  1. Power OFF the board.

  2. Set SW1 DIP switch to OSPI boot mode (0001 = ON, ON, ON, OFF).

  3. Power ON the board.

Step 2: Select UFS Boot in U-Boot Menu#

After OSPI boots U-Boot, the U-Boot Boot Menu appears:

*** 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 appears as scsi 0 (or scsi 1) since UFS is connected via the SCSI interface.

  • Select scsi 0 and press ENTER to boot from UFS.

Step 3: First Boot Setup#

  • The system boots from OSPI (bootloader) followed by UFS (Linux kernel + rootfs).

  • On first boot, Linux requires a password to be set for the default user account.

  • Username: amd-edf

Step 4: Copy and Program the PL + AIE Overlay#

Note

This step is required in the OSPI + UFS boot flow. Unlike the OSPI + SD flow, where the overlay is copied and programmed automatically by the EOU (Easy of Use) scripts, the OSPI + UFS flow requires this to be done manually.

Copy the generated or prebuilt overlay folder into the /overlay directory present on the board. For example, using scp from the host (replace TARGET_IP with the board’s IP):

scp -r /path/on/host/overlay amd-edf@TARGET_IP:/overlay/

After copying the overlay files, obtain the device using one of the following methods:

  • Reboot the board so the overlay is programmed automatically during boot, or

  • Run the fpgautil command to program the PL + AIE overlay without rebooting:

    sudo fpgautil -b /overlay/x_plus_ml.pdi -o /overlay/x_plus_ml.dtbo

Note

Programming the PL + AIE overlay is a mandatory step before running any AI/ML (XRT host) application.

Step 5: Verify Boot#

After logging in, verify the boot configuration:

# Check boot device
lsblk

# Check UFS device
cat /proc/scsi/scsi

# Check kernel version
uname -a

Troubleshooting#

OSPI Flash Issues#

Symptom

Resolution

“Serial port locked” error

Kill minicom/screen: fuser -k /dev/ttyUSB1

“No targets found” (XSDB)

Check USB cable, verify SW1 = JTAG mode (0000)

U-Boot prompt timeout

Check DIP switch, verify board is powered on

sf probe fails

Hardware issue - flash not detected by U-Boot

sf erase timeout

256MB erase takes 2-5 minutes, wait longer

OSPI flash script hangs

Press Ctrl-C, check log file for details

UFS / Image Recovery Issues#

Symptom

Resolution

Image Recovery shell does not launch

Ensure FWUEN (SW14) is held during power-on for 3-5 seconds.

Cannot access web interface

Verify the Ethernet connection and check the IP address in the serial output. Configure a static IP if needed.

WIC upload fails

Check the file format (.wic.xz or .wic.ufs.xz) and verify file integrity.

UFS device not detected

Run the UFS initial configuration using ufs-utils.

Boot menu does not show SCSI devices

Verify the UFS LU configuration and re-run the ufs-utils configuration.

Boot Issues#

Symptom

Resolution

Board does not boot from OSPI

Verify SW1 = OSPI mode (0001), re-flash OSPI

U-Boot appears but no boot menu

UFS not detected, check UFS configuration

Linux boots but no login prompt

Wait for first-boot setup, check serial terminal

Multiple PARTUUID conflict

Only connect one boot media at a time (EDF 2025.05); EDF 2025.11 generates unique PARTUUIDs per build
Contents