Boot VxWorks from a SCSI Disk with Tornado 2.2

Table of Contents

Boot VxWorks from a SCSI Disk with Tornado 2.2

Booting VxWorks directly from a SCSI hard disk can eliminate the need to download the kernel from a development host during every startup. This is particularly useful for legacy embedded platforms where the target board contains a dedicated SCSI controller and local disk.

This guide describes how to configure VxWorks 5.5, Tornado 2.2, and BSP 02248 to boot a standalone VxWorks kernel from a SCSI hard disk on VMPC6-series boards. It also covers SCSI and dosFs configuration, boot ROM updates, standalone kernel generation, disk formatting, boot parameters, and a two-board configuration using the Backplane Shared Memory (SM) network.

Legacy-environment note: The commands, memory addresses, firmware prompts, BSP symbols, and device names in this guide are specific to the historical VxWorks 5.5/Tornado 2.2 and VMPC BSP environment. Validate them against your exact hardware and BSP revision before modifying boot ROM or flash contents.

🧰 Test Environment and Hardware
#

The original configuration uses the following environment:

Component	Configuration
Development host	Solaris or Windows NT 4
Development environment	Tornado 2.2
RTOS	VxWorks 5.5
BSP	BSP ID `02248`
Target boards	VMPC6a / VMPC6c / VMPC6d
Storage	9 GB Quantum Fireball SCSI disk
Filesystem	`dosFs`
Network	Ethernet and, for multi-board setups, Shared Memory

The procedure assumes that the target BSP already supports the corresponding VMPC hardware and that the required SCSI controller and boot ROM facilities are available.

🔧 Configure the BSP for SCSI Boot Support
#

SCSI boot support requires changes to the BSP configuration and boot code. The main files involved are:

/target/config/<BSP>/
    config.h
    bootConfig.c
    sysScsi.c

A patch to the SCSI driver library may also be required.

Update `config.h`
#

Enable the networking, symbol-table, shell, SCSI, and dosFs facilities required by the development and boot configuration.

For the original BSP setup, the relevant definitions are:

/* Symbol table management */
#define INCLUDE_NET_SYM_TBL
#define INCLUDE_NETWORK
#define INCLUDE_NET_INIT
#define INCLUDE_STAT_SYM_TBL
#define INCLUDE_SYM_TBL
#define INCLUDE_SYM_TBL_INIT

/* Traces */
#define INCLUDE_SHOW_ROUTINES
#define INCLUDE_NET_SHOW
#define INCLUDE_SYM_TBL_SHOW

/* Target Shell */
#define INCLUDE_SHELL
#define INCLUDE_LOADER

/* SCSI support */
#define INCLUDE_SCSI
#define INCLUDE_SCSI_BOOT
#define SYS_SCSI_CONFIG

/* dosFs support */
#define INCLUDE_DOSFS
#define INCLUDE_DOSFS_MAIN
#define INCLUDE_DISK_UTIL

INCLUDE_SCSI_BOOT is important because the target boot ROM must contain the functionality required to load the kernel from a SCSI device.

SYS_SCSI_CONFIG causes the BSP to invoke the custom sysScsiConfig() routine described below.

Modify `bootConfig.c`
#

The BSP’s scsiLoad routine must initialize the SCSI block device and make it available through dosFs.

In the section around the comment:

/* now support booting from partitions on SCSI devices */

ensure that the appropriate PARTITION_MANAGEMENT_USED conditional structure is present.

Before the section responsible for loading the boot file, add the required dosFs initialization path:

#else

scsiShow(pSysScsiCtrl);

if (dosFsDevInit("/sd0/", (CBIO_DEV_ID)pScsiBlkBootDev, 0) == NULL)
{
    printErr("dosFsDevInit failed.\n");
    return (ERROR);
}

printErr("done.\n");

#endif

The important point is that the SCSI block device must be registered with dosFs before the boot loader attempts to access /sd0/vxWorks.st.

Add `sysScsiConfig()` to `sysScsi.c`
#

Add a custom SCSI configuration routine to the BSP’s sysScsi.c:

#ifdef SYS_SCSI_CONFIG

#include "dosFsLib.h"

SCSI_PHYS_DEV *pSpd20;
BLK_DEV       *pSbd0;

/*******************************************************************************
* sysScsiConfig - Example SCSI device setup routine
*******************************************************************************/
STATUS sysScsiConfig(void)
{
    /* Configure a SCSI hard disk at busId = 0, LUN = 0 */
    if ((pSpd20 = scsiPhysDevCreate(
            pSysScsiCtrl,
            0,
            0,
            0,
            NONE,
            0,
            0,
            0)) == (SCSI_PHYS_DEV *)NULL)
    {
        printErr(
            "usrScsiConfig: scsiPhysDevCreate failed.\n",
            0, 0, 0, 0, 0, 0);

        return (ERROR);
    }
    else
    {
        /* Create block device and initialize dosFs */
        if ((pSbd0 = scsiBlkDevCreate(pSpd20, 0, 0)) == NULL)
        {
            return (ERROR);
        }

        if (dosFsDevInit("/sd0/", pSbd0, NULL) == NULL)
        {
            return (ERROR);
        }
    }

    return (OK);
}

#endif /* SYS_SCSI_CONFIG */

This example assumes the SCSI disk is configured at:

SCSI bus ID = 0
LUN         = 0

The resulting block device is exposed through:

/sd0/

The exact device configuration should be adjusted if the target hardware uses a different SCSI ID or LUN.

Apply the `ncrLib.a` Patch
#

For BSP 02248 under Tornado 2.2, apply patch:

bsp02248-T2.2-3

The patch addresses issue CRP 2713 in ncrLib.a.

Because this is a legacy BSP-specific correction, verify that the patch matches the exact BSP and Tornado version before applying it to a production build environment.

💾 Build and Flash the Boot ROM
#

After configuring SCSI boot support, rebuild the boot ROM and install the new image into the target board’s flash.

Enable Boot ROM Programming Mode
#

Place the jumper on:

LK2

on the VMPC board before performing the firmware update.

Build `bootrom.bin`
#

From the BSP directory, clean the previous build and generate the boot ROM image:

make clean
make bootrom.bin

The resulting bootrom.bin contains the boot-time SCSI functionality required to locate and load the VxWorks kernel.

Transfer the Boot ROM Image
#

Use the VMPCBug firmware’s TFTP functionality from the COMMAND> prompt.

For example:

COMMAND> tftpget 192.54.144.173:?,192.54.144.189;t d:/tornado2.2/.../bootrom.bin

In this example:

Host   = 192.54.144.173
Target = 192.54.144.189

The host and target must be reachable over the same network path, and the TFTP server must be configured to provide the image.

Write the Image to Flash
#

After downloading the image, enter the firmware’s I/O programming interface:

COMMAND> iop
(R)ead / (W)rite / (F)ormat / rewin(D) [R]? w
Controller LUN = c ? 4
Device LUN = 0 ? 1
Memory address = 10000 ? 20000
Sector number = 0 ? 0
Number of sector = 1 ? 400

The exact flash-controller parameters are hardware-specific. Confirm them against the VMPC board documentation before writing flash.

🏗️ Rebuild the VxWorks Kernel
#

After updating the boot ROM, rebuild the standard VxWorks kernel:

make clean
make vxWorks

The kernel can then be loaded manually from the firmware prompt using the configured entry address:

COMMAND> go ffe00000

This step verifies that the newly built kernel and boot ROM can execute correctly before moving to disk-based standalone boot.

📦 Build a Standalone VxWorks Kernel
#

To boot the kernel directly from the SCSI disk, create a standalone image containing the necessary symbol information and networking configuration.

Modify config.h:

#define INCLUDE_STANDALONE_SYM_TBL
#define STANDALONE_NET
#undef INCLUDE_NET_SYM_TBL

Then rebuild:

make clean
make vxWorks.st

The resulting:

vxWorks.st

is the standalone kernel image intended for storage on the SCSI filesystem.

The distinction between vxWorks and vxWorks.st matters here: the standalone image is designed to operate without depending on the normal host-side symbol-table and boot-download workflow.

💽 Detect and Initialize the SCSI Disk
#

Once VxWorks is running, verify that the SCSI controller detects the disk.

Inspect SCSI Devices
#

Run:

-> scsiShow

A device may appear similar to:

ID LUN VendorID ProductID Rev. Type Blocks BlkSize pScsiPhysDev
-- --- -------- ---------------- ---- ---- -------- -------
0  0   QUANTUM  FIREBALL SE2.1S PJ0A 0    4201304  512

The important information includes:

SCSI ID.
LUN.
Vendor.
Product.
Number of blocks.
Block size.
Physical-device pointer.

Create the SCSI Block Device
#

Retrieve the physical SCSI device:

-> pDisk = scsiPhysDevIdGet(pSysScsiCtrl, 0, 0)

Create the corresponding block device:

-> pBlockDev = scsiBlkDevCreate(pDisk, 0x2000, 0x0)

Then initialize the dosFs filesystem:

-> pdosVolDescript = dosFsMkfs("/sd0/", pBlockDev)

The resulting filesystem is accessible through:

/sd0/

Verify the Filesystem
#

List available devices:

-> devs

If required, perform additional disk formatting:

-> DiskFormat("/sd0/")

Formatting is destructive. Do not execute disk-formatting commands on a disk containing data that must be preserved.

📤 Copy `vxWorks.st` to the SCSI Disk
#

Once /sd0/ has been initialized, copy the standalone kernel image from the development host:

-> copy "HOST:/Tornado2.2ppc/target/config/vmpc6c/vxWorks.st", "/sd0/vxWorks.st"

Then verify the file:

-> cd "/sd0/"
-> ls

The directory should contain:

vxWorks.st

At this point, the SCSI disk contains the standalone VxWorks kernel in the location expected by the boot configuration.

Compatibility note: The original procedure specifies SCSI-2-compliant disks with the standard VxWorks drivers. Modern SCSI hardware may not behave identically with this legacy driver stack.

🚀 Configure VxWorks to Boot from SCSI
#

At the VxWorks boot prompt, use the c command to configure the boot parameters:

[VxWorks Boot]: c

A configuration for the primary VMPC board can look like:

boot device          : scsi=0,0
processor number     : 0
host name            : HOST
file name            : /sd0/vxWorks.st
inet on ethernet (e) : 192.54.144.189
host inet (h)        : 192.54.144.173
user (u)             : support
flags (f)            : 0x8
other (o)            : dec

The critical parameters are:

boot device : scsi=0,0
file name  : /sd0/vxWorks.st

These tell the boot loader to use SCSI ID 0, LUN 0, and load the kernel from the dosFs path /sd0/vxWorks.st.

After saving the configuration and rebooting, the updated boot ROM should initialize the SCSI subsystem, attach the disk, mount the filesystem, and load the standalone kernel.

🔗 Boot a Second Board Through Shared Memory
#

A second VMPC board can use the first board’s SCSI disk indirectly through the VxWorks Backplane Shared Memory (SM) network.

In this configuration:

                    SCSI Disk
                        |
                        v
                  +-----------+
                  |   VMPC1   |
                  | SCSI Host |
                  +-----------+
                        |
                 Shared Memory
                        |
                        v
                  +-----------+
                  |   VMPC2   |
                  | Secondary |
                  +-----------+

VMPC1 directly accesses the SCSI disk and can provide services that allow VMPC2 to access resources over the backplane.

Configure the Standalone Kernel
#

For the standalone image used in this configuration, update config.h:

#define INCLUDE_STANDALONE_SYM_TBL
#define STANDALONE_NET
#undef INCLUDE_NET_SYM_TBL
#define INCLUDE_SM_SHOW
#define INCLUDE_FTP_SERVER

Rebuild the standalone image:

make clean
make vxWorks.st

Copy the resulting image to the SCSI disk attached to VMPC1.

🖥️ Configure VMPC1
#

VMPC1 is the primary board and directly owns the SCSI disk.

Example boot parameters:

boot device          : scsi=0,0
processor number     : 0
host name            : pcfbo
file name            : /sd0/vxWorks.st
inet on ethernet (e) : 192.93.161.148:ffffff00
inet on backplane (b): 93.0.0.1:0xffffff00
host inet (h)        : 192.93.161.133
user (u)             : support
ftp password (pw)    : support
flags (f)            : 0x8
other (o)            : dec

VMPC1 boots the kernel directly from:

/sd0/vxWorks.st

and provides the backplane network endpoint:

93.0.0.1

🖥️ Configure VMPC2
#

VMPC2 boots through Shared Memory:

boot device          : sm=0xc4004100
processor number     : 1
host name            : vx
file name            : /sd0/vxWorks.st
inet on backplane (b): 93.0.0.2
host inet (h)        : 93.0.0.1
user (u)             : support
ftp password (pw)    : support
flags (f)            : 0x8
target name (tn)     : vxworks0

Here, VMPC2 uses:

sm=0xc4004100

as the Shared Memory boot device and communicates with VMPC1 through the backplane network.

The exact shared-memory address is hardware- and BSP-specific and should not be copied to an unrelated VMPC configuration without verification.

📁 Keep `/sd0/` Available to VMPC2
#

Booting VMPC2 through VMPC1 does not automatically mean that VMPC2 has persistent filesystem access to the SCSI disk.

If VMPC2 must continue accessing /sd0/ after boot, VMPC1 can provide the filesystem through NFS.

Enable the NFS server on VMPC1:

#define INCLUDE_NFS_SERVER

Then export the SCSI filesystem using nfsExport.

VMPC2 can subsequently mount the exported filesystem using nfsMount.

Conceptually:

VMPC1
+-----------------------+
| SCSI Disk             |
| /sd0/                 |
+-----------+-----------+
            |
            | NFS
            |
            v
+-----------------------+
| VMPC2                  |
| nfsMount(...)          |
+-----------------------+

This approach separates boot transport from filesystem access: VMPC2 can boot through the Shared Memory network while VMPC1 provides access to the locally attached SCSI filesystem.

🔍 Troubleshooting the SCSI Boot Sequence
#

A SCSI boot failure can occur at several different stages. Isolating the failing layer makes troubleshooting considerably easier.

The disk does not appear in `scsiShow`
#

Check:

SCSI cabling.
SCSI termination.
Device ID configuration.
LUN configuration.
Controller initialization.
Disk compatibility.
BSP SCSI support.
ncrLib.a patch level.

If the device is not detected by the SCSI subsystem, filesystem configuration is not yet relevant.

The SCSI disk is detected but `/sd0/` cannot be initialized
#

Check:

scsiBlkDevCreate() result.
dosFsMkfs() or dosFsDevInit() result.
Block size and device parameters.
Filesystem compatibility.
Disk formatting.

For example:

-> pDisk = scsiPhysDevIdGet(pSysScsiCtrl, 0, 0)
-> pBlockDev = scsiBlkDevCreate(pDisk, 0x2000, 0x0)

Each step should be validated before proceeding to the next.

`/sd0/` works but `vxWorks.st` cannot be loaded
#

Verify:

-> cd "/sd0/"
-> ls

and confirm that:

vxWorks.st

exists.

Also verify the boot parameter:

file name : /sd0/vxWorks.st

The filesystem path must match the actual filename and mount point.

The kernel loads but the target does not boot correctly
#

Verify that the standalone image was built with the appropriate configuration:

#define INCLUDE_STANDALONE_SYM_TBL
#define STANDALONE_NET
#undef INCLUDE_NET_SYM_TBL

Also check that the image was rebuilt after modifying config.h:

make clean
make vxWorks.st

Stale object files can otherwise make it appear that configuration changes have no effect.

⚠️ Important Legacy-System Considerations
#

This procedure targets a very specific software and hardware stack:

Tornado 2.2
VxWorks 5.5
BSP 02248
VMPC6-series hardware
Legacy SCSI controller

Several details should therefore be treated as BSP-specific rather than universal VxWorks instructions.

In particular:

go ffe00000 depends on the target’s memory map and boot ROM.
scsi=0,0 assumes SCSI ID 0 and LUN 0.
/sd0/ depends on the configured block device.
0xc4004100 is specific to the Shared Memory configuration.
Flash programming parameters depend on the VMPC hardware.
Network addresses must match the actual deployment.
Legacy dosFs, SCSI, and BSP interfaces may differ from later VxWorks releases.

Before adapting the procedure to another board or BSP, verify the BSP source, boot ROM implementation, memory map, SCSI controller, and VxWorks version.

🧩 Complete Boot Flow
#

The entire SCSI boot process can be summarized as:

1. Configure BSP
       |
       v
2. Enable SCSI + dosFs + SCSI boot
       |
       v
3. Patch ncrLib.a if required
       |
       v
4. Build bootrom.bin
       |
       v
5. Flash updated boot ROM
       |
       v
6. Build vxWorks.st
       |
       v
7. Detect SCSI disk
       |
       v
8. Create SCSI block device
       |
       v
9. Initialize /sd0/
       |
       v
10. Copy vxWorks.st to /sd0/
       |
       v
11. Configure boot device = scsi=0,0
       |
       v
12. Reboot
       |
       v
13. Boot ROM initializes SCSI
       |
       v
14. VxWorks loads /sd0/vxWorks.st

For a two-board configuration, the flow extends to:

VMPC1
  |
  | Boots vxWorks.st from local SCSI disk
  |
  +---- Shared Memory ----> VMPC2
  |
  +---- NFS (optional) ---> VMPC2 filesystem access

📌 Key Takeaways
#

Booting VxWorks from a local SCSI disk requires coordination between the BSP, boot ROM, SCSI driver, block-device layer, dosFs, and standalone kernel configuration.

The critical components are:

Enable INCLUDE_SCSI and INCLUDE_SCSI_BOOT.
Configure SYS_SCSI_CONFIG and implement sysScsiConfig().
Register the SCSI block device with dosFs.
Apply the appropriate BSP-specific ncrLib.a correction.
Rebuild and flash the SCSI-capable boot ROM.
Build vxWorks.st as a standalone kernel.
Format and mount the SCSI disk as /sd0/.
Copy vxWorks.st to /sd0/.
Configure scsi=0,0 and /sd0/vxWorks.st as the boot source.
For multi-board systems, use Shared Memory for secondary-board booting and NFS when continued filesystem access is required.

The key architectural idea is that SCSI boot is not simply a boot-parameter change. The boot ROM must understand the SCSI device, the BSP must initialize the controller and block device, dosFs must expose the disk as a filesystem, and the standalone kernel must be built in a form suitable for local boot.

Once these layers are correctly configured, the VMPC target can boot VxWorks directly from its SCSI disk without requiring the development host to provide the kernel image at every startup.

VxWorks vs. Windows CE: Real-Time Embedded OS Comparison

17 August 2006·1588 words·8 mins

VxWorks Windows CE RTOS Embedded Systems Real-Time OS Hard Real-Time Industrial Automation Embedded Linux

WindML Window Mechanism in VxWorks: GUI Design Guide

3 May 2006·557 words·3 mins

VxWorks WindML GUI Embedded Systems RTOS Window System HMI Software Design

VxWorks 6.0 Beta: A Milestone in Embedded Software Development

4 October 2004·736 words·4 mins

VxWorks Wind River Embedded Systems RTOS Workbench Software Development Real-Time Operating System Embedded Software

🧰 Test Environment and Hardware #

🔧 Configure the BSP for SCSI Boot Support #

Update config.h #

Modify bootConfig.c #

Add sysScsiConfig() to sysScsi.c #

Apply the ncrLib.a Patch #

💾 Build and Flash the Boot ROM #

Enable Boot ROM Programming Mode #

Build bootrom.bin #

Transfer the Boot ROM Image #

Write the Image to Flash #

🏗️ Rebuild the VxWorks Kernel #

📦 Build a Standalone VxWorks Kernel #

💽 Detect and Initialize the SCSI Disk #

Inspect SCSI Devices #

Create the SCSI Block Device #

Verify the Filesystem #

📤 Copy vxWorks.st to the SCSI Disk #

🚀 Configure VxWorks to Boot from SCSI #

🔗 Boot a Second Board Through Shared Memory #

Configure the Standalone Kernel #

🖥️ Configure VMPC1 #

🖥️ Configure VMPC2 #

📁 Keep /sd0/ Available to VMPC2 #

🔍 Troubleshooting the SCSI Boot Sequence #

The disk does not appear in scsiShow #

The SCSI disk is detected but /sd0/ cannot be initialized #

/sd0/ works but vxWorks.st cannot be loaded #

The kernel loads but the target does not boot correctly #

⚠️ Important Legacy-System Considerations #

🧩 Complete Boot Flow #

📌 Key Takeaways #

Related