VxWorks on Altera Cyclone V: SD/MMC and QSPI Boot Guide

VxWorks on Altera Cyclone V: SD/MMC and QSPI Boot Guide

Booting VxWorks on an FPGA-based system-on-chip requires coordination between the processor’s built-in boot mechanism, board-specific initialization code, the operating-system bootloader, and the final VxWorks image.

On Altera Cyclone V and Arria V SoC development boards, this process uses a hardware BootROM, an Altera preloader, and a VxWorks bootrom. Depending on the target configuration, the preloader and operating-system image can be stored on an SD/MMC card or programmed into QSPI Flash.

This guide explains how to combine a VxWorks 6.9 bootrom built with Wind River’s alt_soc_gen5 Board Support Package (BSP) with an Altera SoC preloader. It covers image preparation, preloader configuration, bootrom generation, SD/MMC boot, QSPI programming, and runtime boot parameters.

The examples are based on the legacy development environment used by the original implementation, including VxWorks 6.9.3.2, Wind River Workbench 3.3.4, Altera SoC EDS 14.0, and Quartus Programmer 14.0.

Scope: This guide focuses on assembling and booting the system using an existing preloader configuration and a VxWorks bootrom. It does not cover the complete process of designing an FPGA, generating a new preloader from scratch, or developing a new VxWorks BSP.

For background on platform initialization and board support, see the VxWorks BSP Development Handbook and the VxWorks 6.9 development environment overview.

🧩 Hardware and Software Requirements

#

Before building a bootable image, prepare the target hardware, development tools, and appropriate board-specific files.

Hardware

#

The reference configuration uses:

• An Altera Cyclone V or Arria V SoC development board.
• An SD/MMC card for removable-media boot or as an intermediate programming medium for QSPI.
• A serial connection for monitoring boot output.
• A USB Blaster connection if programming QSPI directly with the Quartus programmer.
• A host computer for building images and transferring files.

Software

#

The original test environment included:

These versions are retained for compatibility with the original procedure. They are not recommendations for a new development environment. Newer toolchains, BSP revisions, and board revisions may use different configuration files and boot-image formats.

For Windows-based development, the original procedure uses Win32 Disk Imager to write a raw image to an SD card. On Linux, dd can perform the same task, but the destination device must be identified carefully because writing to the wrong device can destroy existing data.

The package described in this guide includes or assumes access to prebuilt images for both development-board families, preloader binaries for SD/MMC and QSPI, a Windows build of mkimage, and a make_sdimage.sh script for creating SD/MMC images on Linux.

🚀 Understanding the Altera SoC Boot Architecture

#

The Altera SoC boot sequence contains several distinct stages. Understanding the difference between the silicon BootROM and the VxWorks bootrom is essential.

The hardware BootROM is built into the processor and cannot be replaced. The VxWorks bootrom is a software bootloader generated using the Wind River development environment.

A simplified boot sequence is:

Power-On / Reset
       |
       v
+---------------------------+
| Hardware BootROM          |
| Built into the SoC        |
+-------------+-------------+
              |
              v
+---------------------------+
| Altera Preloader          |
| Clock, RAM, Pin Setup     |
| Optional FPGA Programming |
+-------------+-------------+
              |
              v
+---------------------------+
| VxWorks BootROM           |
| Loads VxWorks Image       |
+-------------+-------------+
              |
              v
+---------------------------+
| VxWorks Kernel and Apps   |
+---------------------------+

Hardware BootROM

#

At power-on, the SoC’s built-in BootROM selects the configured boot source and loads the initial boot image into on-chip memory.

The BootROM then transfers execution to the preloader.

This is a hardware-defined stage and is separate from the bootrom generated using VxWorks tools.

Altera Preloader

#

The preloader performs the initialization needed before a larger software image can execute.

Its responsibilities typically include configuring clocks, initializing external RAM, setting up pin multiplexing, and loading the next boot stage.

Depending on the preloader configuration, it can also program the FPGA fabric from an image stored on the boot medium.

The preloader must match the board’s hardware configuration. A preloader built for a development kit is not necessarily suitable for a custom board, even when both use the same SoC.

VxWorks BootROM

#

After initialization, the preloader loads the VxWorks bootrom into external RAM and transfers control to it.

The VxWorks bootrom then loads the final VxWorks image from the configured storage device or network source and transfers control to the operating system.

This separation allows the preloader to focus on low-level board initialization while the VxWorks bootrom handles operating-system image loading and boot parameters.

⚙️ Building the VxWorks BootROM

#

The VxWorks bootrom must be built for the target BSP and wrapped in the image header expected by the Altera preloader.

There are two approaches: using the BSP’s command-line build target or building a bootrom image through a VxWorks Image Project (VIP).

Command-Line BootROM

#

Open a VxWorks 6.9 Development Shell from Workbench and navigate to the alt_soc_gen5 BSP directory.

cd vxworks_6.9/target/config/alt_soc_gen5
make bootrom.bin

The resulting bootrom.bin must be wrapped with mkimage before the preloader can load it.

For the command-line bootrom described in the original implementation, the image is loaded at an address that differs from its eventual decompression destination. The reference load address is 0x08000040.

Example:

mkimage.exe -A arm -T firmware -C none -O vxworks \
  -a 0x08000040 -e 0 \
  -n "vxWorks bootloader for SoC FPGA" \
  -d bootrom.bin bootloader.bin

This produces bootloader.bin, which can be placed on the SD/MMC FAT partition or programmed into QSPI according to the selected boot method.

The load address must match the bootrom’s actual requirements. Do not assume that 0x08000040 is appropriate for every custom image or BSP revision.

BootROM from a VxWorks Image Project

#

The alternative is to create a VxWorks Image Project using the boot application profile.

The reference procedure is:

1. Create a VIP with the PROFILE_BOOTAPP profile.
2. Select the default_rom build specification.
3. Build the vxworks.bin target.
4. Locate vxWorks_rom.bin in the project’s default_rom output directory.
5. Determine the image’s starting address and wrap the binary using mkimage.

Use the appropriate target-toolchain inspection utility to determine the image’s entry or load address. In the original procedure, the command is shown as:

objdump -f vxWorks_rom.bin

The reference address for this build method was 0x3f000000.

That value is specific to the tested image, not a universal VxWorks address. Use the address reported for the binary you actually build.

Both bootrom-generation methods require the correct Altera image header before the resulting binary can be consumed by the preloader.

🧰 Configuring the Altera Preloader

#

The preloader and VxWorks bootrom have different responsibilities and build requirements.

The preloader is typically generated from the FPGA and HPS configuration using Altera SoC EDS tools. The VxWorks bootrom is generated with the Wind River toolchain and then wrapped with the appropriate image header.

The original implementation used SoC EDS 14.0 and included prebuilt preloader binaries for the Cyclone V and Arria V development boards.

For custom hardware, the preloader should be regenerated using the board’s actual pin assignments, clock configuration, memory setup, and FPGA design.

SD/MMC Preloader Configuration

#

In the reference implementation, the SD/MMC preloader was modified to load the VxWorks bootrom from the FAT partition instead of assuming that the next-stage image was U-Boot in the raw partition.

The main settings in uboot-socfpga/board/altera/socfpga/build.h were:

/* Enable FAT partition support for SD/MMC boot. */
#define CONFIG_PRELOADER_FAT_SUPPORT (1)

/* FAT partition containing the boot image. */
#define CONFIG_PRELOADER_FAT_BOOT_PARTITION (1)

/* File loaded by the preloader. */
#define CONFIG_PRELOADER_FAT_LOAD_PAYLOAD_NAME "bootloader.bin"

The preloader was also configured to support FPGA programming from an image stored on the selected boot device.

In uboot-socfpga/include/configs/socfpga_common.h:

/* Enable FPGA programming support in SPL. */
#define CONFIG_SPL_FPGA_LOAD

Together, these changes allow the preloader to load bootloader.bin from the SD/MMC FAT partition and program the FPGA when the corresponding configuration and image are present.

QSPI Preloader Configuration

#

For QSPI boot, the preloader must load the VxWorks bootrom from QSPI and locate the FPGA image at the configured QSPI address.

The reference settings in uboot-socfpga/board/altera/socfpga/build.h were:

#define CONFIG_PRELOADER_BOOT_FROM_QSPI  (1)
#define CONFIG_PRELOADER_BOOT_FROM_SDMMC (0)
#define CONFIG_PRELOADER_BOOT_FROM_RAM   (0)

The configuration in uboot-socfpga/include/configs/socfpga_common.h included:

/* Enable FPGA programming support in SPL. */
#define CONFIG_SPL_FPGA_LOAD

/* QSPI address containing the FPGA image. */
#define CONFIG_SPL_FPGA_QSPI_ADDR (0x800000)

Only one boot mode should be selected at a time. The QSPI preloader must also agree with the image locations used when programming Flash.

💾 Booting VxWorks from SD/MMC

#

SD/MMC is a practical first target because it allows the board to be brought up without permanently programming QSPI. It can also serve as an intermediate mechanism for programming QSPI with U-Boot.

The basic workflow is to boot a known-good SD/MMC image, verify serial output, build and wrap the VxWorks bootrom, and replace the placeholder bootloader file.

Step 1: Configure the Board for SD/MMC Boot

#

For the reference Cyclone V SoC development board, the documented BootSEL settings are:

These physical descriptions depend on how the board is oriented. Confirm them against the user guide for your exact board revision before applying power.

Also consult the board’s factory-default switch and jumper settings in the Cyclone V SoC Development Kit User Guide.

Step 2: Create the SD/MMC Card

#

Use the prebuilt image that matches the target board:

Extract the appropriate image and write it to the SD/MMC card using Win32 Disk Imager or an equivalent raw-image tool.

Caution: Raw-image tools overwrite the target device. Verify the selected drive or device path before writing.

Step 3: Verify the Initial Boot

#

Connect the board’s serial interface to the host computer and configure a terminal for 115200 baud.

Apply power and monitor the output.

The prebuilt image initially uses U-Boot as a placeholder for the VxWorks bootrom. Seeing the preloader output followed by the U-Boot prompt confirms that the board can boot from the prepared SD/MMC image.

Step 4: Build and Wrap the VxWorks BootROM

#

Build the bootrom using the alt_soc_gen5 BSP, following one of the methods described earlier.

Then run mkimage to produce the file expected by the preloader. For the command-line bootrom, the reference output is:

mkimage.exe -A arm -T firmware -C none -O vxworks \
  -a 0x08000040 -e 0 \
  -n "vxWorks bootloader for SoC FPGA" \
  -d bootrom.bin bootloader.bin

For other bootrom images, substitute the appropriate load address.

Step 5: Replace the Placeholder Bootloader

#

Power off the board and remove the SD/MMC card. Insert it into the host computer and copy the new bootloader.bin onto its FAT partition, replacing the placeholder bootloader file.

Eject the card safely and reinstall it in the board.

Step 6: Boot VxWorks

#

Apply power while monitoring the serial output.

The expected sequence is:

1. The SoC hardware BootROM starts the preloader.
2. The preloader initializes the board.
3. The preloader loads the VxWorks bootrom from the FAT partition.
4. The VxWorks bootrom displays its prompt or continues using its configured boot parameters.
5. The VxWorks image loads and starts.

If the sequence stops, inspect the serial output to identify the failing stage before changing the boot configuration.

🔌 Booting from QSPI Using an SD/MMC Card

#

The SD/MMC card can also be used to program QSPI, avoiding the need for the Quartus programmer during this procedure.

The board first boots from SD/MMC into U-Boot. U-Boot then writes the preloader, VxWorks bootrom, and FPGA image into their assigned QSPI locations.

Step 1: Prepare the Required Files

#

Prepare the following files:

Use the board-specific QSPI preloader:

qspi/cv/preloader-mkpimage.bin  # Cyclone V
qspi/av/preloader-mkpimage.bin  # Arria V

Rename the wrapped VxWorks bootrom to vxworksqspi.bin to distinguish it from the SD/MMC bootloader.

The FPGA bitstream is normally supplied as fpga.rbf. Convert it into the form expected by the QSPI preloader:

mkimage -A arm -T firmware -C none -O u-boot \
  -a 0 -e 0 -n "FPGA" -d fpga.rbf fpga.img

Copy these files to the FAT partition of the SD/MMC card.

Step 2: Program the QSPI Preloader

#

Insert the SD/MMC card into the development board and boot to the U-Boot prompt.

Load the preloader into temporary RAM and program it into QSPI:

fatload mmc 0:1 0x2000000 preloader-mkpimage.bin
sf probe
sf erase 0x0 0x40000
sf write 0x2000000 0x0 $filesize

Here, 0x2000000 is the temporary RAM address used by the example, while 0x0 is the start of the QSPI region occupied by the preloader.

Use a RAM address that is valid and not already occupied by another image or reserved memory area.

Step 3: Program the VxWorks BootROM

#

Load the wrapped bootrom:

fatload mmc 0:1 0x2000000 vxworksqspi.bin
printenv filesize

The erase operation must cover the required Flash erase units, rounded up to the next 64KB boundary in the reference procedure.

For example, if the file size is 0x5a360, the rounded erase size is 0x60000.

Use the appropriate size for the actual file:

sf probe
sf erase 0x60000 0x60000
sf write 0x2000000 0x60000 $filesize

The example places the bootrom at QSPI offset 0x60000. The erase-size argument must be calculated from the actual image size and the Flash device’s erase requirements.

Step 4: Program the FPGA Image

#

Load the wrapped FPGA image into RAM:

fatload mmc 0:1 0x2000000 fpga.img
printenv filesize

Then erase the required Flash region and write the FPGA image at offset 0x800000:

sf probe
sf erase 0x800000 0x60000
sf write 0x2000000 0x800000 $filesize

The 0x60000 value is only an example based on the file size used in the original instructions. Calculate an appropriate erase size for the actual image and Flash geometry before running these commands.

The FPGA image offset 0x800000 must match CONFIG_SPL_FPGA_QSPI_ADDR in the preloader configuration.

Step 5: Switch the Board to QSPI Boot

#

Power off the board and remove the SD/MMC card if you want to verify that the boot process no longer depends on removable media.

For the reference Cyclone V board, the documented QSPI BootSEL settings are:

Check the board-specific manual before changing boot switches.

Power on the board and monitor the serial port at 115200 baud. The preloader should start, followed by the VxWorks bootrom.

🖥️ Programming QSPI Directly with the Quartus Programmer

#

QSPI can also be programmed without an SD/MMC card by using Altera’s quartus_hps utility and a USB Blaster connection.

This method requires the same three prepared files:

• preloader-mkpimage.bin
• vxworksqspi.bin
• fpga.img

Step 1: Connect the USB Blaster

#

Connect the host computer to the board’s USB Blaster interface and start the appropriate Altera SoC EDS command shell.

In the historical Windows environment, the shell was launched from the Altera SoC EDS installation menu. It sets environment variables such as:

QUARTUS_ROOTDIR='C:\altera\14.0\qprogrammer'
SOCEDS_DEST_ROOT=C:/altera/14.0/embedded

Power on the board and run:

jtagconfig

Identify the USB Blaster cable number reported by the tool. In the following commands, <cable> represents that identifier.

Step 2: Program the Preloader

#

quartus_hps -c <cable> -o P -a 0 -s 0x40000 preloader-mkpimage.bin

This writes the preloader at QSPI offset 0x0.

Step 3: Program the VxWorks BootROM

#

quartus_hps -c <cable> -o P -a 0x60000 vxworksqspi.bin

The 0x60000 offset must agree with the preloader configuration that identifies the next boot image.

Step 4: Program the FPGA Image

#

quartus_hps -c <cable> -o P -a 0x800000 fpga.img

The FPGA image is written at offset 0x800000, matching the configured QSPI FPGA-image location.

Step 5: Perform a Full Power Cycle

#

After programming the files, remove power from the board for approximately ten seconds before restarting it.

The original procedure notes that a CRC error may occur if the board is not fully powered down after programming. If an error appears, remove power, wait, and retry before assuming the image itself is invalid.

Monitor the serial output at 115200 baud to confirm that the preloader and VxWorks bootrom start correctly.

🧭 Configuring the VxWorks Boot Parameters

#

After the VxWorks bootrom starts, its boot prompt can be used to inspect and change the boot configuration.

In the reference environment:

• p displays the current boot settings.
• c changes boot parameters.
• M changes the MAC address associated with the emac1 interface.

The available commands and device names depend on the BSP configuration.

The following sections describe three boot options from the original alt_soc_gen5 environment: loading the VxWorks image over FTP, loading it from the SD/MMC FAT partition, and using DHCP before retrieving the image over FTP.

Booting the Image over Ethernet and FTP

#

Ethernet boot is useful during development because the VxWorks image can remain on the host instead of being copied to removable storage after every build.

The reference parameters are:

These values are examples from the original development setup. Replace the IP addresses, paths, and credentials with those appropriate for the actual network.

For Ethernet boot, the target address and host address must be reachable from each other, and the host must provide the configured image through the supported boot protocol.

Booting the Image from the SD/MMC FAT Partition

#

To load the VxWorks image directly from the card’s FAT partition, the bootrom configuration must include the appropriate storage and filesystem components.

The original config.h additions are:

#define DRV_STORAGE_ALT_SOC_GEN5_DW_MSHC
#define INCLUDE_BOOT_FILESYSTEMS
#define INCLUDE_DOSFS

Rebuild the bootrom, wrap it with mkimage, and copy the bootloader and VxWorks image to the SD/MMC FAT partition.

The reference boot parameters are:

The other setting can be used to enable Ethernet even though the VxWorks image itself is being loaded from the SD/MMC card. This can be useful when Ethernet is needed after startup for debugging or application communication.

This configuration is separate from the DHCP-and-FTP boot method described next.

Booting with DHCP and FTP

#

The BSP can also be configured to obtain an IP address through DHCP before retrieving the VxWorks image over FTP.

The original configuration uses the following options:

#define INCLUDE_BOOT_DHCPC
#define INCLUDE_IPDHCPC
#define DHCPC_OPTION_MAX_MESSAGE_SIZE "576"
#define DHCPC_TTL "1"
#define DHCPC_FLAGS_BIT_BROADCAST "0"
#define DHCPC_IF_INFORMATION_ONLY_LIST ""
#define INCLUDE_IPNET_IFCONFIG_1
#define IFCONFIG_1 \
    "ifname","devname driver","inet dhcp","gateway dhcp","inet6 3ffe:1:2:3::4/64"

These settings are specific to the original VxWorks 6.9 configuration and should be checked against the exact BSP and networking components being used.

After adding the configuration, rebuild the bootrom, wrap it with mkimage, and copy the resulting bootloader file and VxWorks image to the appropriate storage location.

The reference boot parameters for DHCP and FTP are:

Use either the SD/MMC filesystem boot configuration or the DHCP/FTP configuration as appropriate for the bootrom build. The original instructions treat these as alternative configurations rather than options to combine blindly.

📦 Understanding the Prebuilt Image Package

#

The package described by the original implementation contains board-specific preloader and FPGA assets for both Cyclone V and Arria V.

The ghrd_fpga directory contains FPGA images for the Golden Hardware Reference Design:

ghrd_fpga/
├── cv/
│   └── fpga.rbf
└── av/
    └── fpga.rbf

The cv directory refers to Cyclone V, while av refers to Arria V.

The QSPI and SD/MMC directories contain board-specific preloader files. Typical contents include:

The preloader and FPGA images are board-specific. Do not interchange Cyclone V and Arria V files simply because the bootloader procedure is similar.

Creating an SD/MMC Image on Linux

#

The original package includes make_sdimage.sh to assemble the necessary components into a raw image.

An example command from the original environment is:

./make_sdimage.sh \
  -p preloader-mkpimage.bin \
  -b u-boot.img \
  -k bootloader.bin,u-boot.img,fpga.rbf,readme.txt \
  -o cv_140_fat_sdmmc.img \
  -g 512M

The correct input files and script options depend on the package version. Review the script before running it, particularly when preparing a new image for a custom board.

The original SD/MMC image contains a raw partition for the preloader and a FAT partition containing files such as bootloader.bin and fpga.rbf. The preloader configuration determines which file is loaded and whether FPGA programming occurs during startup.

🧪 Troubleshooting Common Boot Problems

#

A multi-stage boot process provides several points where startup can fail. Diagnose each stage independently rather than changing the bootloader, memory map, and boot parameters simultaneously.

No Serial Output

#

Check the serial connection, terminal baud rate, board power, and boot-switch positions first.

The reference procedure uses 115200 baud. Confirm that the serial interface is connected to the correct port and that the board’s boot mode matches the prepared image.

Preloader Starts but VxWorks BootROM Does Not

#

Check:

• Whether the preloader matches the board.
• Whether the expected boot image is present.
• Whether the FAT partition and file name match the preloader configuration.
• Whether the image has been wrapped with the required header.
• Whether the load address is appropriate for the bootrom binary.
• Whether the SDRAM configuration is correct.

VxWorks BootROM Starts but the Kernel Does Not

#

Inspect the boot parameters and verify that the image path is valid.

For FTP boot, check host and target addressing, routing, and image availability. For SD/MMC boot, confirm that the filesystem components are included in the bootrom and that the boot path points to the correct partition and file.

QSPI Boot Fails After Programming

#

Verify that:

• The correct preloader was programmed.
• The bootrom was written at the configured address.
• The FPGA image was written at the expected offset.
• The erase sizes align with the Flash device’s requirements.
• The QSPI boot switches are correct.
• The board received a complete power cycle after programming.

For custom boards, also verify the QSPI device geometry and the preloader’s configured image addresses.

🔗 Related VxWorks Resources

#

For further background and related implementation workflows, consult:

• VxWorks BSP Development Handbook — BSP responsibilities, startup code, memory initialization, interrupts, and device support.
• VxWorks 7 BSP Development Guide — A broader overview of BSP architecture and platform customization in VxWorks 7. Its APIs and workflow differ from the VxWorks 6.9 examples in this article.
• VxWorks 6.9 on Zynq-7000: BSP Setup and Boot Guide — A related SoC boot workflow involving a preloader, a VxWorks boot image, removable storage, and Ethernet boot.
• Managing VxWorks Projects from the Command Line — Background on command-line project management and repeatable builds.

For board-specific FPGA configuration, consult the matching Cyclone V or Arria V SoC Development Kit documentation and the SoC EDS documentation corresponding to the toolchain being used.

✅ Conclusion

#

Booting VxWorks on Altera Cyclone V and Arria V SoC platforms requires several software layers to work together: the silicon BootROM, the Altera preloader, the VxWorks bootrom, and the final VxWorks image.

The main workflow is:

1. Configure or select the appropriate board-specific preloader.
2. Build the VxWorks bootrom using the alt_soc_gen5 BSP.
3. Wrap the bootrom with the header required by the preloader.
4. Prepare an SD/MMC image or program the necessary images into QSPI.
5. Configure the board’s boot switches and boot parameters.
6. Verify each startup stage through serial output.
7. Validate storage, networking, and application initialization after VxWorks starts.

SD/MMC boot is useful for initial bring-up and development. QSPI boot provides a non-removable startup configuration and can be programmed through U-Boot or the Quartus programmer.

The central engineering lesson is that the boot image, preloader configuration, memory map, and board-specific hardware settings must agree. Once those interfaces are configured and tested systematically, the same multi-stage process provides a repeatable foundation for running VxWorks on Cyclone V and Arria V SoC development platforms.