OSPI and SD Card Boot Flow

OSPI and SD Card Boot Flow#

This section introduces the boot flow that uses OSPI and an SD card with deployment scripts that handle the bring-up steps end-to-end.

Prerequisites#

Before proceeding, complete the board setup in Board Setup, including physical connections (power, USB-UART, Ethernet, JTAG) and driver installation. No more than 1 board should be connected to the host for the OSPI programming scripts to work as expected. Then follow the deployment instructions below.

Install Required Tools#

Ensure you get the Vitis AI source package from amd/Vitis-AI, which contains the following files:

versal_2ve/tools/ospi_sd_flash/
  docs/                                  # Documentation directory
  runtime_env.sh                         # Runtime environment setup script
  setup_overlay.sh                       # FPGA overlay programming script
  vek385-flash-ospi.exp                  # OSPI flash automation (expect script)
  vek385-flash-sdcard.sh                 # SD card flash automation (bash script)
  vek385-setup.service                   # Systemd service for automatic boot configuration
  configure_ufs.sh                       # UFS flash configuration script
  ufsconfig_64gb                         # UFS config file

Ensure your host machine has installed:

  • expect

  • bmap-tools

  • Vivado Lab Edition 2025.2

Note

Vivado Lab Edition is a lite version of Vivado and is sufficient to support hardware download operations. The scripts have only been verified with local tool installation of Vivado.

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

# Install bmap-tools (required for SD card flash script)
sudo apt install bmap-tools

# Verify Vivado Lab Edition 2025.2 is installed
ls <path to Vivado Lab 2025.2>

Prepare Boot Images Directory#

Ensure your host machine boot images directory contains the following files:

/path/to/boot_images/
  BOOT.bin                                    # Bootloader binary (OSPI flash required)
  edf-ospi-versal2-vek385-sdt-full.bin        # OSPI image (auto-detected by script, matches *ospi*.bin)
  rootfs.wic.xz                               # Root filesystem image for SD card (required by SD card flash)
  rootfs.wic.bmap                             # Block map for sparse SD card flash (optional but recommended)
  rootfs.wic.ufs.xz                           # Root filesystem image for UFS (compressed)
  rootfs.wic.ufs.bmap                         # Block map for sparse UFS flash
  overlay/                                    # PL/AIE overlay files
    x_plus_ml.pdi                             # FPGA bitstream
    x_plus_ml.dtbo                            # Device tree overlay
    image_processing.cfg                      # XRT configuration
    x_plus_ml.xclbin                          # XRT acceleration metadata

Hardware Configuration#

  • Power OFF the VEK385 board

  • Set SW1 DIP switch to JTAG boot mode (0000 = all ON)

SW1 DIP Switch

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

  • Connect the VEK385 board to the host machine via USB cable (provides both JTAG and serial interfaces)

  • Power ON the board

Boot Flow Overview#

The boot flow includes three main sections:

../../_images/ospi_block.png

  • Section 1 (OSPI Programming): Use the vek385-flash-ospi.exp script to flash the bootloader to the board OSPI memory through JTAG, then switch the board to boot from OSPI. If the board already boots from OSPI, skip this section.

  • Section 2 (SD Card Setup): Use the vek385-flash-sdcard.sh script to flash the Linux root filesystem image to an SD card and copy all required application files, FPGA overlays, and setup scripts.

  • Section 3 (Board Boot): Boot the system from OSPI and SD card. The overlay programming and runtime configuration happen automatically through a systemd service – no manual commands required.

Note

The deployment scripts consolidate multiple bring-up steps into single commands with built-in error checking, safety validations, and automatic device detection. Section 3 configuration happens automatically on boot.

Quick Reference: Essential Boot Steps#

This is a concise reference for the essential steps to boot up the board. For detailed instructions, explanations, and troubleshooting, refer to the complete sections below.

Step 1: Flash OSPI

  • Set board to JTAG boot mode (0000 = all ON)

  • Run command:

cd <path to versal_2ve/tools/ospi_sd_flash/>

# (Optional) Dry run: validate the environment, arguments, and image paths without writing to OSPI flash
./vek385-flash-ospi.exp \
  --vivado-dir <path to Vivado Lab 2025.2> \
  --boot-images /path/to/boot_images \
  --dry-run

# Actual run: program the OSPI flash with the boot images
./vek385-flash-ospi.exp \
  --vivado-dir <path to Vivado Lab 2025.2> \
  --boot-images /path/to/boot_images

Example output of the OSPI flash dry run:

  [INFO]  Auto-detected OSPI image: edf-ospi-versal2-vek385-sdt-full.bin
  [INFO]  OSPI image size: 0x4D0000 (4.8 MB)
  [INFO]  Auto-detected serial port: /dev/ttyUSB1

========================================================================
  VEK385 OSPI Flash Tool
  Automates UG1787 (Board Setup)
========================================================================

  Vivado:       <path to Vivado Lab 2025.2>
  Boot images:  <path to boot_images>
  BOOT.bin:     BOOT.bin
  OSPI image:   edf-ospi-versal2-vek385-sdt-full.bin
  Image size:   0x4D0000 (4.8 MB)
  Serial port:  /dev/ttyUSB1
  XSDB port:    3121
  Log file:     <path>/vek385-flash-ospi_<timestamp>.log
  Mode:         DRY RUN (no hardware operations)

========================================================================
  Dry run complete -- all paths and settings validated
========================================================================

  All prerequisites satisfied. Re-run without --dry-run to flash.

Example output after the OSPI flash completes successfully:

========================================================================
  OSPI programming complete!
========================================================================

  Log file: <path>/vek385-flash-ospi_<timestamp>.log

  Next steps:
    1. Prepare the SD card (Section 2) using vek385-flash-sdcard.sh
    2. Power OFF the board
    3. Set SW1 DIP switch to OSPI mode (0001 = ON, ON, ON, OFF)
    4. Power ON the board

Note

The flashing process might take several minutes depending on image size. A progress indicator (.) appears every 5 seconds during erase and programming.

Step 2: Flash SD Card

Insert the SD card into your Ubuntu host machine, then run the following commands:

cd <path to versal_2ve/tools/ospi_sd_flash/>

# (Optional) Dry run: validate the SD card device and image paths without writing to the SD card
sudo ./vek385-flash-sdcard.sh \
  --boot-images /path/to/boot_images \
  --dry-run

# Actual run: flash the boot images to the SD card
sudo ./vek385-flash-sdcard.sh \
  --boot-images /path/to/boot_images

Example output of the SD card flash dry run:

========================================================================
  VEK385 SD Card Flash Tool
  Automates UG1787 (SD Card Setup)
========================================================================

  Boot images:   <path to boot_images>
  Rootfs image:  rootfs.wic.xz
  Bmap file:     rootfs.wic.bmap (found)
  SD device:     /dev/sdb
  Device size:   59GB
  Device model:  Micro SD
  Log file:      <path>/vek385-flash-sdcard_<timestamp>.log
  Mode:          DRY RUN (no hardware operations)

    NAME    MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
    sdb       8:16   1 59.6G  0 disk
    |-sdb1    8:17   1    1G  0 part
    |-sdb2    8:18   1    1G  0 part
    `-sdb3    8:19   1 57.4G  0 part

========================================================================
  Dry run complete -- all paths and settings validated
========================================================================

  All prerequisites satisfied. Re-run without --dry-run to flash.

Example output after the SD card flash completes successfully:

========================================================================
  Finalizing SD card
========================================================================
  [INFO]  Syncing...
  [INFO]  Unmounting /mnt/vek385-sd...
  [INFO]  Ejecting /dev/sdb...
  [INFO]  SD card ejected.

========================================================================
  SD card is ready!
========================================================================

  Log file: <path>/vek385-flash-sdcard_<timestamp>.log

  Next steps:
    1. Insert the SD card into the VEK385 board
    2. Ensure SW1 DIP is set to OSPI mode (0001 = ON, ON, ON, OFF)
    3. Power on the board

Step 3: Boot the Board

  • Insert SD card

  • Set board to OSPI mode (0001 = ON, ON, ON, OFF)

  • Open serial console (for example, minicom -D /dev/ttyUSB1 -b 115200 or Tera Term) with 115200 baud rate

  • Power ON the board

Log in with the username amd-edf (the password can be chosen by the user). After logging in, verify that the automatic board setup (overlay and runtime environment) completed successfully:

systemctl status vek385-setup.service

Expected output (simplified key lines):

● vek385-setup.service - VEK385 board setup
     Active: active (exited)
    Process: ExecStart=/overlay/setup_overlay.sh (code=exited, status=0/SUCCESS)
    Process: ExecStart=/overlay/runtime_env.sh (code=exited, status=0/SUCCESS)

The setup is successful when Active: active (exited) is shown and the ExecStart processes report status=0/SUCCESS.

Important

When sudo privileges are required, use the sudo -i command.

At this point, the board setup is complete. You can proceed to the next section Run Your First Inference to start running models on the board.

For more details, advanced usage, options, error handling, or verification steps, refer to the detailed reference: OSPI and SD Card Boot Flow - Detailed Reference.

Contents