Boot VxWorks 7 with U-Boot: DTB, mkimage, XIP and Build Guide

Boot VxWorks 7 with U-Boot: DTB, mkimage, XIP and Build Guide

Integrating VxWorks 7 with U-Boot requires careful coordination between the bootloader, VxWorks image format, Device Tree Blob (DTB) handling, target memory layout, and early CPU initialization.

VxWorks 7 uses the Flattened Device Tree (FDT) model to separate hardware description from the kernel image. U-Boot can therefore boot VxWorks using either a standalone DTB or an embedded DTB, with important differences in how boot arguments, image generation, and execution commands are handled.

This guide covers the complete workflow for ARM and PowerPC targets, including mkimage header generation, compressed images, Execute-In-Place (XIP) Flash configurations, and Wind River project builds.

🧩 VxWorks 7 and U-Boot DTB Architecture

#

VxWorks 7 uses FDT/DTB files compliant with the ePAPR specification to describe board hardware. In a U-Boot deployment, the DTB can either remain as a separate boot artifact or be incorporated directly into the VxWorks image.

Standalone DTB vs. Embedded DTB

#

The standalone DTB model is generally more flexible during board bring-up because U-Boot can load and modify the DTB independently from the kernel image.

The embedded DTB model simplifies deployment by producing a self-contained image, but it removes the ability to dynamically override the DTB’s boot arguments through the U-Boot environment.

🛠️ Building a U-Boot-Compatible VxWorks Image

#

U-Boot can consume VxWorks kernel binaries wrapped with its image header. The typical workflow is to convert the VxWorks ELF output into a raw binary and then encapsulate it with mkimage.

Convert ELF to Raw Binary

#

The default VxWorks build produces an ELF image. Use the appropriate target cross-toolchain objcopy to generate a raw binary.

# ARM
objcopyarm -O binary vxWorks vxWorks.bin

# PowerPC
objcopyppc -O binary vxWorks vxWorks.bin

The resulting vxWorks.bin contains the binary payload without the ELF container metadata.

Add the U-Boot Image Header

#

Use mkimage to generate the U-Boot-compatible image. The load address and entry point must match the target board’s VxWorks memory configuration, such as RAM_LOW_ADRS.

# ARM
mkimage -A arm -O vxworks -T kernel -C none \
  -a 0x80100000 -e 0x80100000 \
  -n vxworks -d vxWorks.bin vxWorks.uboot

# PowerPC
mkimage -A ppc -O vxworks -T kernel -C none \
  -a 0x00100000 -e 0x00100000 \
  -n vxworks -d vxWorks.bin vxWorks.uboot

The generated image contains the VxWorks payload together with the U-Boot metadata required by bootm.

Compressing the Kernel

#

For network boot or storage-constrained deployments, the raw VxWorks image can be compressed before being wrapped.

gzip --best vxWorks.bin

mkimage -A ppc -O vxworks -T kernel -C gzip \
  -a 0x00100000 -e 0x00100000 \
  -n vxworks -d vxWorks.bin.gz vxWorks.uboot

With -C gzip, U-Boot knows that the payload requires decompression during the bootm process.

⚡ Execute-In-Place from NOR Flash

#

VxWorks 7 can also execute directly from non-volatile NOR Flash rather than copying the entire kernel into RAM.

Two common approaches are available:

1. Use go with an image containing an embedded DTB.
2. Use bootm with a U-Boot header reserved in the early VxWorks image layout.

XIP Using the go Command

#

With an embedded DTB, the VxWorks image can be placed at its Flash execution address and started directly:

U-Boot# go 0x<flash_addr>

This approach jumps directly to the image’s execution address rather than invoking the normal U-Boot image-loading and decompression flow.

XIP Using bootm

#

When bootm is required for an XIP image, the U-Boot header occupies the beginning of the image. VxWorks early initialization must therefore reserve space for it.

For example, sysALib.s can reserve 64 bytes:

FUNC_LABEL(_sysInit)
FUNC_BEGIN(sysInit)

#ifdef UBOOT_XIP
    .fill 16, 4, 0xff    /* 16 x 4 bytes = 64-byte U-Boot header */
#endif

The corresponding image can then be generated with the XIP option:

mkimage -x -A arm -O vxworks -T kernel -C none \
  -a 0x80100000 -e 0x80100000 \
  -n vxworks -d vxWorks.bin vxWorks.uboot

The image can subsequently be started from the U-Boot console:

U-Boot# bootm 0x80100000

The exact address must match the board’s Flash mapping and VxWorks startup configuration.

🔧 Building VxWorks Images with Wind River CLI

#

Wind River project tooling can generate images appropriate for either standalone or embedded DTB deployment.

First add the required components:

prj vip component add INCLUDE_STANDALONE_DTB
prj vip component add INCLUDE_STANDALONE_SYM_TBL

For a standalone DTB image:

prj build -target uVxWorks

For an embedded DTB binary:

prj build -target vxWorks.bin

The choice of target should match the intended U-Boot boot protocol. A standalone DTB deployment requires U-Boot to provide the DTB address separately, while an embedded configuration packages the hardware description with the VxWorks image.

🌐 Configuring U-Boot Networking

#

For network-based deployment, configure the Ethernet and TFTP parameters in the U-Boot environment:

U-Boot# setenv ethaddr 00:04:9f:ef:01:01
U-Boot# setenv ipaddr 192.168.10.5
U-Boot# setenv serverip 192.168.10.2
U-Boot# setenv netmask 255.255.255.0
U-Boot# setenv gatewayip 192.168.10.1
U-Boot# saveenv

These parameters allow U-Boot to retrieve VxWorks images from a TFTP server before transferring control to the kernel.

🚀 U-Boot Boot Protocols

#

Standalone DTB with bootm

#

Load the VxWorks image and DTB into separate RAM regions:

U-Boot# tftp 0x80300000 uVxWorks
U-Boot# tftp 0x80e00000 your-board.dtb

If the VxWorks configuration supports U-Boot-provided boot arguments, the environment can be configured before boot:

U-Boot# setenv bootargs "cpsw(0,0)host:vxWorks h=192.168.10.2 e=192.168.10.5:ffffff00 g=192.168.10.1 u=vxworks pw=vxworks f=0x0"

Start VxWorks and pass the DTB address as the third bootm argument:

U-Boot# bootm 0x80300000 - 0x80e00000

The resulting boot sequence separates the kernel and hardware description, allowing the DTB to be updated independently.

Embedded DTB with go

#

For an image containing the DTB internally:

U-Boot# tftp 0x80300000 vxWorks.bin
U-Boot# go 0x80300000

Because the DTB is already embedded, U-Boot does not provide a separate DTB address. Likewise, boot arguments configured through the U-Boot environment cannot be used to dynamically replace the embedded boot configuration.

📋 Deployment Model Comparison

#

The standalone DTB + bootm approach is generally preferable during board development because the kernel and hardware description can be updated independently.

For fixed production configurations where the image and hardware description are tightly coupled, an embedded DTB can simplify deployment and reduce the number of boot artifacts.

🧠 Key Implementation Considerations

#

The most important integration points are the image format, memory addresses, DTB placement, and boot command.

The U-Boot load and entry addresses passed to mkimage must correspond to the VxWorks board configuration. Incorrect address selection can result in immediate boot failures or execution from an invalid memory region.

DTB handling is equally important. With a standalone DTB, U-Boot can pass a dynamically loaded hardware description to VxWorks and potentially modify /chosen information. With an embedded DTB, that flexibility is intentionally removed.

For XIP deployments, the Flash execution address and early startup layout must also account for the U-Boot header when bootm is used. Reserving the header space in the VxWorks assembly startup path prevents the bootloader metadata from overwriting critical initialization code or vector data.

In practice, the cleanest architecture is to select the DTB strategy first, align the VxWorks build target with that strategy, verify the target memory map, and only then generate the final U-Boot image with mkimage.