U-Boot VxWorks Boot Guide: bootvx, bootm, and bootefi

U-Boot VxWorks Boot Guide: bootvx, bootm, and bootefi

U-Boot provides several mechanisms for loading and transferring control to a VxWorks kernel, with the appropriate method depending on the VxWorks generation, CPU architecture, image format, and firmware interface.

The three primary commands are bootvx, bootm, and bootefi. bootvx primarily serves legacy VxWorks boot flows, bootm provides the modern VxWorks 7 path on PowerPC, ARM, and RISC-V, while bootefi is used to chain-load VxWorks through a UEFI environment on x86 systems.

The boot architecture can be summarized as:

                         U-Boot
                           |
             +-------------+-------------+
             |             |             |
             v             v             v
          bootvx         bootm        bootefi
             |             |             |
             v             v             v
        Legacy ELF      uImage + DTB   UEFI Loader
             |             |             |
             +-------------+-------------+
                           |
                           v
                     VxWorks Kernel

Choosing the correct command is important because the three paths differ in image format, bootline handling, Device Tree processing, and kernel entry conventions.

🧭 Boot Command Compatibility

#

The supported command depends primarily on the target architecture and VxWorks version.

The exact availability and behavior can depend on the U-Boot configuration and the VxWorks BSP.

bootvx

#

bootvx is the traditional VxWorks-oriented boot command.

It is particularly relevant to legacy BSPs where the kernel expects a VxWorks bootline at a predefined memory address.

The basic flow is:

VxWorks ELF
    |
    v
U-Boot bootvx
    |
    +--> Prepare bootline
    |
    +--> Place bootline at bootaddr
    |
    v
Kernel Entry Point

The bootaddr environment variable must correspond to the BSP’s expected BOOT_LINE_ADRS.

bootm

#

bootm is the primary path for modern VxWorks 7 configurations on PowerPC, ARM, and RISC-V.

A typical invocation is:

bootm <kernel_image_addr> - <dtb_address>

The kernel image and Flattened Device Tree are therefore supplied as separate boot objects.

bootefi

#

bootefi uses U-Boot’s EFI loader infrastructure to launch a VxWorks UEFI bootloader.

The flow becomes:

U-Boot
   |
   v
bootefi
   |
   v
VxWorks UEFI Loader
   |
   v
VxWorks Kernel

This approach is especially relevant to x86 and x64 systems where UEFI provides the expected firmware interface.

🌳 VxWorks 7 Device Tree and FDT Handling

#

VxWorks 7 introduced broader use of Flattened Device Trees (FDT) for describing platform hardware.

On PowerPC, ARM, and RISC-V, the DTB can provide information such as:

• Memory regions
• CPU topology
• Interrupt controllers
• Peripheral register addresses
• Device compatibility information
• Bus relationships
• Platform-specific configuration

Since VxWorks SR0640, VxWorks supports standard Linux-compatible Device Trees.

This makes the VxWorks boot flow substantially closer to the Linux-style firmware-to-kernel interface used by modern embedded platforms.

DTB Selection Through bootargs

#

The least significant bit of the relevant flags in bootargs controls the DTB processing mode described by the VxWorks boot flow.

Conceptually:

bootargs flags
      |
      +---- LSB = 1 ---> Standard Linux-compatible DTB processing
      |
      +---- LSB = 0 ---> Legacy bootm execution

This distinction is important when integrating VxWorks with an existing U-Boot environment that was originally designed around Linux-compatible FDT conventions.

🧩 Kernel Entry Point Conventions

#

The kernel entry convention depends on the processor architecture and whether the Linux-compatible boot flow is being used.

PowerPC ePAPR Flow

#

Under the ePAPR-style interface, the kernel receives arguments corresponding to the FDT address and the expected boot protocol values.

Conceptually:

void (*kernel_entry)(
    fdt_addr,
    0,
    0,
    EPAPR_MAGIC,
    boot_IMA,
    0,
    0
);

The exact register-level calling convention should be matched against the VxWorks BSP and boot protocol expected by the kernel image.

ARM Legacy Flow

#

The legacy ARM flow uses the DTB pointer as the primary kernel argument:

void (*kernel_entry)(void *fdt_addr);

ARM and PowerPC Linux-Compatible Flow

#

When the Linux-compatible interface is selected, VxWorks follows the corresponding standard Linux-style kernel entry convention.

This allows U-Boot to reuse much of its existing DTB preparation and boot infrastructure.

RISC-V

#

RISC-V uses a Linux-compatible interface:

void (*kernel_entry)(
    unsigned long hartid,
    void *fdt_addr
);

The first argument identifies the boot hart, while the second points to the Flattened Device Tree.

📝 VxWorks Bootline and bootargs

#

The handling of kernel command-line information differs between bootvx, bootm, and bootefi.

Understanding this difference is essential when migrating an existing VxWorks BSP from a traditional bootloader flow to U-Boot.

bootvx Bootline Handling

#

With bootvx, U-Boot prepares the VxWorks command line in memory before transferring control to the kernel.

The key environment variable is:

bootaddr

It must match the VxWorks BSP’s expected:

BOOT_LINE_ADRS

For example:

bootaddr=0x101200

may be appropriate for a particular x86 BSP configuration.

The address is BSP-specific and should not be copied between platforms without verification.

Explicit bootargs

#

If bootargs is defined, U-Boot can copy the specified bootline directly to bootaddr.

Conceptually:

bootargs
   |
   v
U-Boot
   |
   v
BOOT_LINE_ADRS / bootaddr
   |
   v
VxWorks Kernel

Automatically Constructed Bootline

#

If bootargs is not explicitly configured, U-Boot can construct the bootline using environment variables such as:

bootdev
ipaddr
serverip
gatewayip
hostname

The resulting bootline is then placed at the configured boot address.

🌐 bootm Command-Line Handling

#

The bootm flow uses the Device Tree as the primary hardware and boot-parameter interface.

A typical configuration is:

setenv bootargs "..."
bootm <kernel_addr> - <dtb_addr>

U-Boot can update the DTB’s /chosen node with the appropriate boot arguments before entering the VxWorks kernel.

This differs fundamentally from the legacy bootvx model, where a bootline is explicitly placed at a predefined memory address.

The resulting flow is:

U-Boot Environment
        |
        v
    bootargs
        |
        v
     DTB /chosen
        |
        v
   VxWorks Kernel

🖥️ bootefi and UEFI Configuration

#

With bootefi, command-line and platform initialization are handled through the VxWorks UEFI bootloader.

The general flow is:

U-Boot
  |
  v
UEFI Services
  |
  v
VxWorks UEFI Loader
  |
  +--> Hardware / Memory Information
  |
  +--> Boot Configuration
  |
  v
VxWorks Kernel

This eliminates much of the legacy bootline preparation required by bootvx.

For x86 systems, however, the UEFI and VxWorks BSP configuration must still agree on memory, console, graphics, and firmware interfaces.

⚙️ Serial Console Configuration

#

A common source of apparently failed VxWorks boots is a console baud-rate mismatch.

For example:

U-Boot     -> 115200
VxWorks    -> 9600

The kernel may actually boot correctly while the terminal appears to hang because the serial receiver is using the wrong baud rate.

A practical configuration should therefore ensure:

U-Boot Console Baud
        =
VxWorks BSP Console Baud
        =
Terminal Baud

For x86 VxWorks BSPs, 9600 may be the BSP default while U-Boot commonly defaults to 115200.

The actual values should always be checked against the specific BSP and board configuration.

🖥️ x86 Memory Configuration

#

x86 VxWorks boots require particular attention to the relationship between physical memory and the BSP’s local-memory configuration.

vx_phys_mem_base

#

When using U-Boot to boot VxWorks on x86, the physical memory base can be provided through:

setenv vx_phys_mem_base <physical_address>

The value should correspond to the physical address associated with the BSP’s:

LOCAL_MEM_LOCAL_ADRS

A mismatch can cause the kernel to initialize with an incorrect view of system RAM.

The relationship is:

BSP Configuration
LOCAL_MEM_LOCAL_ADRS
        |
        v
vx_phys_mem_base
        |
        v
U-Boot / VxWorks Memory Mapping

The value must be derived from the actual BSP rather than copied from another x86 platform.

🔧 x86 ACPI and MPTABLE Considerations

#

Some U-Boot configurations do not provide the ACPI information expected by the VxWorks BSP.

In such cases, the kernel may need to be configured for an alternative multiprocessor-table initialization path.

Relevant VxWorks configuration options can include:

INCLUDE_MPTABLE_BOOT_OP
INCLUDE_VIRTUAL_WIRE_MODE

These options can provide the necessary x86 interrupt and processor initialization path when ACPI information is unavailable.

The correct configuration depends on the firmware capabilities exposed by the target platform.

🎨 x86 Graphics and Framebuffer Configuration

#

The boot configuration also differs depending on whether VxWorks is expected to operate in VGA text mode or graphical framebuffer mode.

VGA Text Mode

#

For an 80×25 VGA text console, U-Boot framebuffer mode should be disabled:

CONFIG_FRAMEBUFFER_SET_VESA_MODE

should be disabled in the relevant U-Boot configuration.

The resulting path is:

U-Boot
  |
  v
VGA Text Mode
  |
  v
VxWorks Console

EFI Bitmap Graphics Mode

#

For graphical EFI operation, VESA framebuffer configuration can remain enabled.

Supported 32-bit RGBA framebuffer formats can include:

10F
112
115
118
11B

The exact format should match the framebuffer representation expected by the VxWorks graphics subsystem.

The resulting flow is:

UEFI / U-Boot
      |
      v
VESA Framebuffer
      |
      v
VxWorks Graphics Subsystem

📋 Platform Configuration Checklist

#

Before attempting to boot a VxWorks kernel through U-Boot, validate the following parameters.

🔬 Troubleshooting the Boot Path

#

When a VxWorks kernel fails to start through U-Boot, debugging should proceed from the bootloader interface toward the kernel rather than immediately changing kernel configuration.

A useful diagnostic sequence is:

1. Verify U-Boot command
          |
          v
2. Verify kernel image format
          |
          v
3. Verify kernel load address
          |
          v
4. Verify DTB / bootline handling
          |
          v
5. Verify memory configuration
          |
          v
6. Verify CPU entry convention
          |
          v
7. Verify serial console
          |
          v
8. Verify interrupt / firmware configuration
          |
          v
9. Verify VxWorks BSP initialization

No Console Output

#

If there is no output immediately after the kernel jump, first check:

• Serial baud rate
• Kernel load address
• Kernel entry address
• bootaddr
• DTB address
• Physical memory base
• Console device configuration

A baud mismatch should be ruled out before assuming that the kernel failed to execute.

Kernel Starts but Hardware Is Incorrect

#

If VxWorks starts but devices are missing or malfunctioning, investigate:

• DTB compatibility
• DT /chosen properties
• Peripheral address mappings
• BSP hardware descriptions
• Interrupt configuration
• PCI/PCIe initialization
• ACPI or MPTABLE availability on x86

bootm Versus bootvx

#

When migrating an older VxWorks BSP, one of the most important distinctions is whether the kernel expects a traditional VxWorks bootline or a modern DTB-based interface.

Conceptually:

Legacy BSP
   |
   v
bootvx
   |
   v
BOOT_LINE_ADRS
   |
   v
VxWorks

Modern VxWorks 7 BSP
   |
   v
bootm
   |
   v
Kernel + DTB
   |
   v
VxWorks

Using the wrong model can result in a kernel that executes but cannot correctly discover its hardware or networking configuration.

📊 Boot Method Comparison

#

🏁 Conclusion

#

Loading VxWorks through U-Boot is primarily a matter of matching the boot command, image format, hardware description mechanism, and kernel entry convention to the target BSP.

The three main approaches serve different generations of the VxWorks boot architecture:

                 U-Boot
                    |
        +-----------+-----------+
        |           |           |
        v           v           v
      bootvx      bootm      bootefi
        |           |           |
        v           v           v
    Bootline       DTB         UEFI
        |           |           |
        +-----------+-----------+
                    |
                    v
              VxWorks Kernel

For legacy systems, bootvx remains centered on the VxWorks bootline and BOOT_LINE_ADRS. For VxWorks 7 on PowerPC, ARM, and RISC-V, bootm provides a more modern DTB-based boot interface. On x86 and x64 platforms using UEFI, bootefi shifts responsibility toward the VxWorks UEFI loader.

The most important practical rule is to treat the BSP as the authoritative source for memory addresses, bootline locations, console configuration, and hardware initialization requirements. U-Boot can provide the boot infrastructure, but successful VxWorks startup ultimately depends on those values matching the assumptions encoded in the target BSP.