OSPI and SD Card Boot Flow (Windows)

OSPI and SD Card Boot Flow (Windows)#

This section introduces the boot flow that uses OSPI and an SD card with native Windows deployment scripts that handle the bring-up steps end-to-end. These PowerShell scripts match the Linux experience but run directly on Windows – only PowerShell and Vivado Lab. The scripts have been verified with a Windows laptop connected directly to the VEK385 board through a JTAG cable (no network on the target).

Prerequisites#

Before proceeding, complete the board setup in Board Setup, including physical connections (power, USB-UART, 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 in the following sections.

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/
  windows/                               # Windows scripts and documentation
    docs/                                # Documentation directory
    vek385-flash-ospi.ps1                # OSPI flash automation (PowerShell script)
    vek385-flash-sdcard.ps1              # SD card flash automation (PowerShell script)
  linux/                                 # Linux scripts and documentation (see the Linux boot flow)

Ensure your host machine has the following installed:

Windows 11 (PowerShell 5.1+ is built-in)
Vivado Lab Edition 2026.1 (provides XSDB, hw_server, and the bundled Python used for image decompression)

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. Run PowerShell as Administrator so the scripts can access the JTAG interface and the SD card raw disk device. No additional software is required – no WSL2, no bmap-tools, and no third-party tools.

Note

If PowerShell blocks script execution, run this once in your session before running the scripts:

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

Note

Place the scripts and boot images in a path that does not contain whitespace, and avoid directories that are synchronized by OneDrive. Paths with spaces or active OneDrive backup can cause the scripts to fail. For example, use C:\vek385\ rather than a folder under C:\Users\<username>\OneDrive\.

Prepare Boot Images Directory#

Prepare the boot images directory as described in Prepare Boot Images Directory of the Linux boot flow. On Windows, use a path without whitespace (for example, C:\vek385\boot_images\). The UFS images (rootfs.wic.ufs.*) are not required for the Windows OSPI + SD card flow.

Hardware Configuration#

Configure the board hardware as described in Hardware Configuration of the Linux boot flow.

Boot Flow Overview#

The boot flow includes the same three main sections described in Boot Flow Overview of the Linux boot flow. On Windows, the equivalent PowerShell scripts are used: vek385-flash-ospi.ps1 (Section 1, OSPI Programming) and vek385-flash-sdcard.ps1 (Section 2, SD Card Setup).

Note

Because Windows cannot write to ext4 filesystems, the SD card script stages the overlay files on the FAT32 boot partition. On first boot, the on-target setup_overlay.sh (baked into the rootfs through the vek385-board-setup Yocto recipe) migrates them from FAT32 to the ext4 rootfs, so the board auto-configures on boot and no manual script copy is needed.

Note

Both scripts support the -Help flag for full usage details, and the -DryRun flag to validate paths and settings without touching hardware.

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 documentation under windows/docs/.

Step 1: Flash OSPI

Set board to JTAG boot mode (0000 = all ON)
Close any serial terminals (PuTTY, Tera Term) before running – the script needs exclusive serial port access
Open PowerShell as Administrator and run:

cd C:\vek385\ospi_sd_flash\windows

# (Optional) Dry run: validate the environment, arguments, and image paths without writing to OSPI flash
.\vek385-flash-ospi.ps1 `
  -VivadoDir "C:\AMDDesignTools\2026.1\Vivado_Lab" `
  -BootImages "C:\vek385\boot_images" `
  -DryRun

# Actual run: program the OSPI flash with the boot images
.\vek385-flash-ospi.ps1 `
  -VivadoDir "C:\AMDDesignTools\2026.1\Vivado_Lab" `
  -BootImages "C:\vek385\boot_images"

Note

The OSPI image is auto-detected by matching *ospi*.bin in the boot images directory. To flash a specific image, pass -OspiImage "<filename>". The serial port is auto-detected; override it with -SerialPort COM<n> if needed.

Note

For early bring-up testing before a dedicated OSPI image is available, you can flash BOOT.bin as the OSPI image by passing -OspiImage "BOOT.bin". This is a test-only override; for normal deployment, use the *ospi*.bin image (auto-detected) and keep BOOT.bin as the separate bootloader.

Example output of the OSPI flash dry run:

  [INFO]  Auto-detected OSPI image: edf-ospi-versal-2ve-2vm-vek385-revb-multidomain.bin
  [INFO]  OSPI image size: 0x10000000 [256.0 MB]
  [INFO]  Auto-detected VEK385 console (FT4232H port B): COM7
  [INFO]  Auto-detected serial port: COM7

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

  Vivado:       C:\AMDDesignTools\2026.1\Vivado_Lab
  Boot images:  C:\Users\Foo\work_downloads\vitis_ai\6.3\gen2\release\vai6.3_vek385_RevB_ai_ref_design_boot_images
  BOOT.bin:     BOOT.bin
  OSPI image:   edf-ospi-versal-2ve-2vm-vek385-revb-multidomain.bin
  Image size:   0x10000000 [256.0 MB]
  Serial port:  COM7
  XSDB port:    3121
  Log file:     C:\Users\Foo\work_downloads\vitis_ai\6.3\gen2\release\Vitis-AI\versal_2ve\tools\ospi_sd_flash\windows\vek385-flash-ospi_20261001_172741.log
  Mode:         DRY RUN (no hardware operations)

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

  Re-run without -DryRun to flash.

Example output after the OSPI flash completes successfully:

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

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

  Next steps:
    1. Power OFF the board
    2. Set SW1 DIP switch to OSPI mode (0001 = ON, ON, ON, OFF)
    3. Power ON the board

  Then run vek385-flash-sdcard.ps1 to prepare the SD card.

Note

The flashing process might take several minutes depending on image size. An inline spinner shows elapsed time during erase and programming. On the first run, click Allow access if Windows Firewall prompts for hw_server.

Step 2: Flash SD Card

Insert the SD card (minimum 32 GB) into your Windows host machine, then open PowerShell as Administrator and run the following commands:

cd C:\vek385\ospi_sd_flash\windows

# (Optional) Dry run: validate the SD card device and image paths without writing to the SD card
.\vek385-flash-sdcard.ps1 `
  -VivadoDir "C:\AMDDesignTools\2026.1\Vivado_Lab" `
  -BootImages "C:\vek385\boot_images" `
  -DryRun

# Actual run: flash the boot images to the SD card
.\vek385-flash-sdcard.ps1 `
  -VivadoDir "C:\AMDDesignTools\2026.1\Vivado_Lab" `
  -BootImages "C:\vek385\boot_images"

Note

The SD card device is auto-detected. If multiple removable disks are present, confirm the target when prompted, or pass -SdDisk <n> to select the disk number explicitly. The .wic.xz image is decompressed using the Python interpreter bundled with Vivado Lab (via -VivadoDir), so no separate Python installation is needed.

Example output of the SD card flash dry run:

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

  Boot images:   C:\vek385\boot_images
  Rootfs image:  rootfs.wic.xz
  SD device:     \\.\PhysicalDrive2 (Disk 2)
  Device size:   59.6 GB
  Device model:  Generic MassStorageClass USB Device
  USB version:   3.0
  Log file:      .\vek385-flash-sdcard_<timestamp>.log
  Mode:          DRY RUN (no hardware operations)

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

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

Example output after the SD card flash completes successfully:

========================================================================
  Finalizing SD card
========================================================================
  [INFO]  Syncing writes...
  [INFO]  SD card ready for removal.

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

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

  Next steps:
    1. Remove the SD card and insert it into the VEK385 board
    2. Ensure SW1 DIP is set to OSPI mode (0001 = ON, ON, ON, OFF)
    3. Power on the board
    4. On first boot, overlay files will be migrated from FAT32 to rootfs automatically

Note

Windows can only see the FAT32 boot partition; the ext4 storage and rootfs partitions are invisible to Windows. This is expected – the overlay files are staged on FAT32 and migrated to the ext4 rootfs automatically on first boot.

Step 3: Boot the Board

Insert SD card
Set board to OSPI mode (0001 = ON, ON, ON, OFF)
Open a serial console (for example, Tera Term on the detected COM port) with 115200 baud rate
Power ON the board

Log in with the username amd-edf (you can choose the password). After logging in, verify that the automatic board setup (overlay, runtime environment, and UFS configuration) completed successfully:

sudo systemctl status vek385-setup.service

Expected output (simplified key lines):

● vek385-setup.service - VEK385 board setup (overlay, runtime, UFS)
     Active: active (exited)
    Process: ExecStart=/overlay/setup_overlay.sh (code=exited, status=0/SUCCESS)
    Process: ExecStart=/usr/sbin/ldconfig (code=exited, status=0/SUCCESS)
    Process: ExecStart=/etc/ufs_config/configure_ufs.sh (code=exited, status=0/SUCCESS)

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

Sample verification output of the board setup service on a board flashed with the Windows OSPI/SD card scripts:

../../_images/vek385-outputs-windows.png

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.

OSPI and SD Card Boot Flow (Windows)

Contents

OSPI and SD Card Boot Flow (Windows)#

Prerequisites#

Install Required Tools#

Prepare Boot Images Directory#

Hardware Configuration#

Boot Flow Overview#

Quick Reference: Essential Boot Steps#