Chapter

13
Reconfiguring
VxWorks

Tornado Training Workshop Copyright Wind River Systems 13-1

Wind River Systems

Production Issues
VxWorks Start-Up
 Overview
After development is completed, you may need to:
Exclude unneeded VxWorks facilities.
Link application code into VxWorks.
Extend VxWorkss start-up code to spawn
application tasks.
Final application may be:
Linked with VxWorks and put into ROM or flash.
Downloaded from host over a network.
Loaded from a local disk.

Tornado Training Workshop Copyright Wind River Systems 13-2

Wind River Systems

See the Programmers Guide for more information on booting off of a

local disk.
 1. Scaling VxWorks
The Project Facility may be used to configure all
VxWorks images (downloadable, ROMable, ROM
resident) except for boot ROM images.
Boot ROM images must be configured by editing the
config.h file for the BSP involved. VxWorks must be
rebuilt using the Tornado 1.0.1 mechanism (make in the
BSP directory).
When the new VxWorks image is built and booted, it
will initialize the facilities selected.

Tornado Training Workshop Copyright Wind River Systems 13-3

Wind River Systems
 Autoscaling VxWorks
The project facility contains an Auto Scale feature which
scales VxWorks based on user application code.
Access via Project => Auto Scale... or context menu Auto
Scale... item on Workspace Builds tab.

First locates VxWorks components required by your

BSP or application; then looks for included components
which might not be needed by your application.
Auto Scale can only detect direct references to VxWorks
modules by your application. Indirect references
through pointers are not detected, so Auto Scale may
suggest a module is unneeded when it really is needed.
Provides an easy, quick start scaling VxWorks.
Tornado Training Workshop Copyright Wind River Systems 13-4
Wind River Systems

As an example of the limitations of Auto Scale, suppose you have a

small application which writes to STD_OUT. Does this mean that Auto
Scale will realize that the target serial console is needed? No. Standard
output may be redirected to any file descriptor, not necessarily the
target console. When it is redirected to a serial device, the serial drivers
routines are called indirectly through pointers. So Auto Scale cannot
detect the dependency (if in fact there is one). It will be able to detect
that the I/O system is required.
 2. Application Start-up Code
The file usrAppInit.c is provided containing a stub
routine usrAppInit() in every bootable project.
void usrAppInit (void)
{
#ifdef USER_APPL_INIT
USER_APPL_INIT; /* for backwards compatibility */
#endif

/* add application specific code here */

}

If application components > application initialization is

included, then usrAppInit() will be called at startup
after VxWorks components have been initialized.
Edit usrAppInit () to include code starting your
application. Often a single taskSpawn() suffices.

Tornado Training Workshop Copyright Wind River Systems 13-5

Wind River Systems

usrAppInit() executes at the end of usrRoot(), the function executed by

the first VxWorks task, tUsrRoot. If you do much work within
usrAppInit(), you may need to redefine ROOT_STACK_SIZE parameter,
which is the stack size for tUsrRoot.
The Macro USER_APPL_INIT is provided for backwards compatibility
only. This macro would be defined in a BSPs config.h file as a C block
or statement which started the user application.
 3. Linking An Application with
VxWorks
Several approaches:
Add application source code to the bootable
VxWorks project and build together.
Build application object modules in separate
projects, and list these modules in the
EXTRA_MODULES makefile macro in the VxWorks
project build spec. The modules will be linked with
the VxWorks image when it is built.
Build archive(s) containing application modules.
Add archive(s) to LIBS makefile macro in VxWorks
build spec. VxWorks / usrAppInit() code will be
linked against these libraries.
Combined approaches are possible.

Tornado Training Workshop Copyright Wind River Systems 13-6

Wind River Systems

Link unmunched files (xx.o, not xx.out) from your downloadable

projects with VxWorks. A munching step is performed near the end of
the VxWorks build. You may use a custom rule to link together the
objects in the project without munching.
 4. VxWorks Build Targets
The Project Facility can build the following VxWorks
images in a bootable project:
vxWorks
vxWorks_rom
vxWorks_romCompress
vxWorks_romResident
These are listed in the drop-down list in the drop-down
list on the Rules tab of the projects build spec Properties
dialog.
The rule selected in the drop down list is the default
rule which is built in a Build Project or Re-Build All.

Tornado Training Workshop Copyright Wind River Systems 13-7

Wind River Systems
 ROMable Images
ROMable images contain bootstrap code which copies
VxWorks from ROM to RAM, decompressing if
necessary.
The bootstrap code is target/config/comps/src/
romStart.c, which is shared by all ROMable and ROM
resident projects.
vxWorks_rom contains an uncompressed, and
vxWorks_romCompress a compressed, VxWorks
image, built using the vxWorks rule.
S-record hex format images are automatically built as
vxWorks_rom.hex or vxWorks_romCompress.hex.

Tornado Training Workshop Copyright Wind River Systems 13-8

Wind River Systems

If using large capacity ROMs, may need to modify the constant

ROM_SIZE in both:
wind/target/config/target/config.h
wind/target/config/target/Makefile
Make will fail if the object is larger than ROM_SIZE.
VxWorks also provides ROM-resident images, which execute in ROM
and only copy the data segment into RAM.
 Compressed ROMable Startup
LMLA +
Unused ROM USER_RESERVED_MEM LOCAL_MEM_SIZE

Compressed 0
3.
VxWorks

bootstrap data
1. bootstrap data
RTA bootstrap text RAM_HIGH_ADRS
STACK_SAVE
RBA

RTA = ROM_TEXT_ADRS Decompressed

RBA = ROM_BASE_ADRS VxWorks 0 2. Zero RAM

RAM_LOW_ADRS

RESERVED
LOCAL_MEM_LOCAL_ADRS LMLA

Tornado Training Workshop Copyright Wind River Systems 13-9

Wind River Systems

The vxWorks_romCompress images bootstrap code romStart() runs

after early hardware initialization code from the BSP. The stack used by
romStart() is the region of size STACK_SAVE just below RAM_HIGH_ADRS.
romStart() does the following:
Copies the portion of the data segment for the bootstrap program
which does not contain the compressed VxWorks binary image into
RAM at RAM_HIGH_ADRS.
On a cold reboot, zeroes out memory from LOCAL_MEM_LOCAL_ADRS
+ RESERVED to RAM_HIGH_ADRS - STACK_SAVE, and from the end of
the bss segment for the bootstrap code up to
LOCAL_MEM_LOCAL_ADRS + LOCAL_MEM_SIZE - USER_RESERVED_MEM.
Decompresses the compressed VxWorks image from its location in
ROM to start at RAM_LOW_ADRS in RAM.
Jumps to the entry point of the decompressed VxWorks image at
RAM_LOW_ADRS. The bootstrap data and stack space may now be
overwritten.
 ROM Resident Image
vxWorks_romResident is a ROM resident image.
It executes out of ROM.
This image contains start-up code which copies only the
VxWorks data segment into RAM at RAM_LOW_ADRS. It
clears RAM in a cold reboot.
This image starts faster and uses less RAM than the
other ROMable images, but executes more slowly.
An S-record hex image is produced automatically in
vxWorks_romResident.hex.

Tornado Training Workshop Copyright Wind River Systems 13-10

Wind River Systems
 Downloadable Image
The vxWorks image does not contain within it the
bootstrap code to copy itself out of ROM into RAM.
It requires a separate boot program to:
obtain the image from a local storage device or from
across the network; and
load it into RAM at RAM_LOW_ADRS to execute.
The standard VxWorks boot program which does this is
a specialized VxWorks application, coming in several
variants: bootrom, bootrom_uncmp, and bootrom_res.
The boot program may not currently be built with the
project facility. It must instead be configured and built
using the traditional BSP mechanism.

Tornado Training Workshop Copyright Wind River Systems 13-11

Wind River Systems
 Standard bootrom Program, A
LMLA +
Unused ROM USER_RESERVED_MEM LOCAL_MEM_SIZE

Compressed 3.
Boot Program
Decompressed
bootstrap data Boot Program 0 2. Zero RAM

RTA bootstrap text RAM_HIGH_ADRS

RBA
1.
bootstrap data
RTA = ROM_TEXT_ADRS
RBA = ROM_BASE_ADRS bootstrap text
RAM_LOW_ADRS
STACK_SAVE

RESERVED
LOCAL_MEM_LOCAL_ADRS LMLA

Tornado Training Workshop Copyright Wind River Systems 13-12

Wind River Systems

The above slide refers to the standard compressed boot program image
bootrom. Other boot images are provided: bootrom_uncmp is an
uncompressed bootrom image, while bootrom_res is ROM-resident.
The bootstrap portion of the standard bootrom program copies itself
and its data into RAM at RAM_LOW_ADRS, zeroes some other RAM on a
cold reboot, and then decompresses the primary boot program from
ROM into RAM at RAM_HIGH_ADRS. After doing so, it jumps to the
entry point of the decompressed boot program. At this point the
bootstrap portion in RAM is no longer needed.
RAM_LOW_ADRS and RAM_HIGH_ADRS are defined in
wind/target/config/bspName/Makefile and in
wind/target/config/bspName/config.h.
 Standard bootrom Program, B
LMLA +
USER_RESERVED_MEM LOCAL_MEM_SIZE
Local Storage

Decompressed
Boot Program

RAM_HIGH_ADRS
FREE_RAM_ADRS
Downloaded

VxWorks Image

RAM_LOW_ADRS
Initial Stack
Network

RESERVED
LOCAL_MEM_LOCAL_ADRS LMLA

Tornado Training Workshop Copyright Wind River Systems 13-13

Wind River Systems

The boot program obtains boot parameters from nonvolatile RAM, from
the user, from a service such as DHCP or BOOTP, or from the default
boot line.
It then downloads VxWorks from the network or from some local
storage device such as a disk. The downloaded image is loaded into
RAM at RAM_LOW_ADRS; the top of the image is called FREE_RAM_ADRS.
After downloading VxWorks, the boot program jumps to the sysInit()
entry point (located at RAM_LOW_ADRS) of the downloaded image.
From this point, the boot program code and data may be overwritten.
 Rebuilding Boot ROMs
If system image is large, downloading will overwrite
the booting code, which may fail while printing:
Loading... 400316 + 28744 + 23852
Need to increase RAM_HIGH_ADRS in:
wind/target/config/bspName/config.h
wind/target/config/bspName/Makefile
The Project facility configuration for the bootable
VxWorks project.
New ROMs are also required to boot from a local disk,
or other boot devices not configured by default into the
boot program.

Tornado Training Workshop Copyright Wind River Systems 13-14

Wind River Systems

The last line of a vxWorks build displays the sizes of the text, data, and
bss sections of the built image, and shows also how much margin
remains between the end of the bss and RAM_HIGH_ADRS. So you dont
have to wait for the download to fail to know that it will do so!
You may also use the project facility or your compiler Toolkits sizeArch
command to determine the size of your VxWorks images and other
modules.
The maximum size of a downloadable system image for your
architecture is RAM_HIGH_ADRS - RAM_LOW_ADRS.
 Traditional VxWorks Configuration
The traditional VxWorks configuration mechanism is
required for configuring boot ROMs and still available
for other builds.
Edit target/config/bspName/config.h to configure
VxWorks.
Define the INCLUDE_xxx macro for a component to
include it.
Define the values of other parameter macros.
Many defaults are defined in target/config/all/
configAll.h, and may need to be redefined.
Build VxWorks or boot ROM using Makefile in BSP
directory, e.g. make bootrom.

Tornado Training Workshop Copyright Wind River Systems 13-15

Wind River Systems

It is recommended that one keep a pristine copy of ones BSP with its
original configuration. One may copy a BSP to a folder with a different
name under target/config/, and make changes in that.
Most changes made to a BSPs configuration by editing config.h only
affect builds done in the project facility when one creates a new
bootable project from the BSP after reconfiguring it; the new project
would be created starting with the new BSP configuration.
Normal use of the project facility will not modify a BSP. Of course, if
you edit the BSP files sysLib.c, sysALib.s, or romInit.s which are
referenced by the project, you are modifying these files in the BSP, and
the modifications will be seen in any project based on the BSP.
The Build => Build Boot ROM... menu item allows one to do a traditional
build of a boot ROM target from the Windows GUI.
 Redundant Address Parameters
The following macros are defined in: 1. The bootable
project build spec; 2. bspName/config.h; and 3. bspName/
Makefile.
RAM_LOW_ADRS
RAM_HIGH_ADRS

They should be kept consistent in all three locations.

Also, the following should be kept consistent in a BSPs
config.h and Makefile:
ROM_TEXT_ADRS
ROM_SIZE

Tornado Training Workshop Copyright Wind River Systems 13-16

Wind River Systems

In the BSP makefile and (for RAM_HIGH_ADRS and RAM_LOW_ADRS) in a

bootable project build spec, these macros are written as hex values
without a leading 0x. In config.h, the values are C constant
expressions, i.e. they are written with 0x.
 ROM-based VxWorks Start-up
1. _romInit in config/bspName/romInit.s
Minimal initialization: mask interrupts, disable

caches, set initial stack, initialize DRAM access.

2. romStart( ) in romStart.c or bootInit.c
Copy text/data segment(s) to RAM, clear other

RAM. Decompress if necessary.

3. usrInit( ) in prjConfig.c or bootConfig.c
Do pre-kernel hardware & software initialization;

start kernel by calling kernelInit( ).

4. usrRoot( ) in prjConfig.c or bootConfig.c
Initialize facilities configured into VxWorks; start

boot program or user application

5. Boot program or user application.

Tornado Training Workshop Copyright Wind River Systems 13-17

Wind River Systems

prjConfig.c is generated by the project facility in each bootable project

directory. It calls functions defined in configlettes, small source files
which contain the initialization code for each VxWorks component. The
configlettes are located under target/config/comps/src.
bootInit.c and bootConfig.c are located in target/config/all/.
The VxWorks boot program is an example of a ROM-based application.
 Downloaded VxWorks Start-up
1. Boot program loads VxWorks over network, from local
disk, etc.. Call:
2. _sysInit in config/bspName/sysALib.s
Similar to _romInit: mask interrupts, disable caches,

set initial stack pointer. Then call:

3. usrInit( ) in prjConfig.c
4. usrRoot( ) in prjConfig.c
5. User application.

Tornado Training Workshop Copyright Wind River Systems 13-18

Wind River Systems
 Summary
1. Scale VxWorks using the project facility. Auto Scale may
be helpful.
2. Define application start-up code by editing the stub
usrAppInit() in usrAppInit.c in the project directory.
3. Link you application with VxWorks by including its
files, or specifying its object modules or libraries in the
EXTRA_MODULES or LIBS macros.

4. Rebuild ROMable (compressed or uncompressed),

ROM resident, or downloadable VxWorks images in
the project facility.
When required,
5. Rebuild boot ROMs in the BSP using the traditional
build mechanism.
Tornado Training Workshop Copyright Wind River Systems 13-19
Wind River Systems