You can redefine the VxWorks configuration in two ways: interactively, as described in this manual in the Tornado User's Guide: Projects, or by editing VxWorks configuration files as described in 8.5 Configuring VxWorks. In either case, after you alter the configuration, VxWorks must be rebuilt to incorporate the changes. This includes recompiling certain modules and re-linking the system image. This section explains the procedures for rebuilding the VxWorks system image using manual techniques.

There are three types of VxWorks images.

Boot ROM images come in 3 flavors: compressed, uncompressed, and ROM-resident.

bootrom	normal compressed boot ROM
bootrom_uncmp	uncompressed boot ROM
bootrom_res	ROM-resident boot ROM

Downloaded VxWorks images come in two basic varieties, Tornado and standalone. (Here "Tornado" is a Vxworks image that uses the host-based tools and symbol table.)

vxWorks	basic Tornado	uses host shell and symbol table
vxWorks.st	standalone image	has target shell and symbol table

ROMmed VxWorks images:

vxWorks_rom	Tornado in ROM (uncompressed)
vxWorks.st_rom	vxWorks.st in ROM (compressed)
vxWorks.res_rom	vxWorks.st ROM-resident
vxWorks.res_rom_nosym	Tornado, ROM-resident

Note that there are variations in available targets for the x86 architecture. See D. Intel x86 for details.

VxWorks uses the GNU make facility to recompile and relink modules. A file called Makefile in each VxWorks target directory contains the directives for rebuilding VxWorks for that target. See GNU ToolKit User's Guide: GNU Make for a detailed description of GNU make and of how to write makefiles.

With a UNIX host, you can use either the GNU version of make included with Tornado or the version included with your UNIX system. If you choose that version, see your host system's reference for make for information about the version of make supplied in that system.

To rebuild VxWorks on a UNIX host, first change to the VxWorks target directory for the desired target, and invoke make as follows:

% cd ${WIND_BASE}/target/config/bspname 
% make

If you choose to use manual techniques on Windows hosts, you must use the command line for building individual application modules. You can use either the command line or the project facility in Tornado 1.0.1 compatibility mode to rebuild BSPs. For information on how to implement Tornado 1.0.1 compatibility mode, see the Tornado User's Guide: Customization.

The directory installDir/target/target/src/usr contains the source code for certain portions of VxWorks that you may wish to customize. For example, usrLib.c is a popular place to add target-resident routines that provide application-specific development aids. For a summary of other files in this directory, see the Tornado User's Guide: Directories and Files.

If you modify one of these files, an extra step is necessary before rebuilding your VxWorks image: you must replace the modified object code in the appropriate VxWorks archive. The Makefile in installDir/target/target/src/usr automates the details; however, because this directory is not specific to a single architecture, you must specify the value of the CPU variable on the make command line:

% make CPU=cputype 

If you do this frequently on a Windows host, you can record the CPU definition in the Build Target field of a custom command in the Project menu; see Tornado User's Guide: Customization.

This step recompiles all modified files in the directory, and replaces the corresponding object code in the appropriate architecture-dependent directory. After that, the next time you rebuild VxWorks, the resulting system image includes your modified code.

The following example illustrates replacing usrLib with a modified version, rebuilding the archives, and then rebuilding the VxWorks system image. For the sake of conciseness, the make output is not shown. The example assumes the epc4 (I80386) BSP; replace the BSP directory name and CPU value as appropriate for your environment. (On a Windows host, use copy instead of the UNIX cp.)

% cd ${WIND_BASE}/target/src/usr 
% cp usrLib.c usrLib.c.orig 
% cp develDir/usrLib.c usrLib.c 
% make CPU=I80386 
...

 
% cd ${WIND_BASE}/target/config/epc4 
% make 
...

The commands to link a VxWorks system image are somewhat complicated. Fortunately, it is not necessary to understand those commands in detail because the Makefile in each VxWorks target directory includes the necessary commands. However, for completeness, this section gives an explanation of the flags and parameters used to link VxWorks.

VxWorks operating system modules are distributed in the form of an archive library for each target architecture. The library is installDir/target/lib/libcpugnuvx.a.

These modules are combined with the configuration module usrConfig.o by the ldarch command on the host. (usrConfig.c is described in 8.5.3 The Configuration Module: usrConfig.c.) The following is an example command for linking a VxWorks system using the GNU linker for the MC680x0:

ld68k -o vxWorks -X -N -Ttext 1000 -e _sysInit sysALib.o sysLib.o \ 
usrConfig.o version.o /tornado/target/lib/libcpugnuvx.a

The meanings of the flags in this command are as follows:

name the output object module vxWorks.

eliminate some compiler-generated symbols from the symbol table.

do not configure the output object module for a virtual-memory system.

specify the relocation address as a hexadecimal constant; in this example, 1000 hexadecimal. This is the address where the system must be loaded in the target, and is also the address where execution starts. Some target systems have limitations on where this relocation address can be.

define the entry point to vxWorks. sysInit( ) is the first routine in sysALib.o, which is the first module loaded by ldarch.

modules that contain CPU-dependent initialization and support routines. The module sysALib.o must be the first module specified in the ldarch command.

the configuration module (described in detail in 8.5.3 The Configuration Module: usrConfig.c). If you have several different system configurations, you may maintain several different configuration modules, either in installDir/target or in your own directory.

a module that defines the creation date and version number of this vxWorks object module. It is created by compiling the output of makeVersion, an auxiliary tool in the installDir/host/host-os/bin directory.

the archive library that contains all the VxWorks modules.

You can link additional object modules (with .o suffix) into the run-time VxWorks system by naming them on the ldarch command line. An easy way to do this is to use the variable MACH_EXTRA in the BSP makefiles. Define this variable and list the object modules to be linked with VxWorks. Note that during development, application object modules are generally not linked with the system (unless they are needed by the usrConfig module), because it is more convenient to load them incrementally from the host, after booting VxWorks. See 8.9 Creating Bootable Applications for more detail on linking application modules in a bootable system.

i960 systems require additional Intel libraries, which are listed in the makefiles for i960 BSPs.

The Tornado target server uses the VxWorks symbol table on the host system, both for dynamic linking and for symbolic debugging. The symbol table file is created by the supplied tool xsym. Processing an object module with xsym creates a new object module that contains all the symbols of the original file, but with no code or data. The line in Makefile that creates this file executes the command as follows:

xsym < vxWorks > vxWorks.sym

The file vxWorks.sym is the symbol table that the target server loads when it begins executing.