The Tornado distribution includes several VxWorks system images for each target shipped. (See 4.4.4 Selecting the VxWorks Image Type.) The system image is a binary module that can be booted and run on a target system. The system image consists of all desired system object modules linked together into a single non-relocatable object module with no unresolved external references.

In most cases, you will find the supplied system image entirely adequate for initial development. However, later in the cycle you may want to configure the operating system to reflect your application requirements.

This chapter describes in detail the manual cross-development procedures used to create and run VxWorks systems and applications as well as how to configure the system by directly editing configuration files.

The following topics are included:

• Building, loading, running, and unloading VxWorks applications manually.

• Using VxWorks configuration files and configuration options and parameters.

• Creating common alternative configurations of VxWorks.

• Rebuilding VxWorks system images, bootable applications, and ROM images using manual methods.

There are two approaches to system configuration in Tornado 2.2:

You can use the project facility for configuring and building, with or without a command-line or automated build. If this is your choice, you do not need any of the information in this chapter. See 4. Projects.

The remainder of this chapter summarizes the steps and issues involved in this choice.

In the Tornado development environment, application modules for the target system are created and maintained on a separate development host. First, the source code, generally in C or C++, is edited and compiled to produce a relocatable object module. Application modules use VxWorks facilities by virtue of including header files that define operating system interfaces and data structures. The resulting object modules can then be loaded and dynamically linked into a running VxWorks system over the network.

The procedure for configuring a customized VxWorks image is described in 5.3 Configuring VxWorks. In the interim, you can use the default images shipped with Tornado.

The following sections describe in detail the procedures for carrying out cross-development manually (without using the project facility).

Many application modules make use of VxWorks operating system facilities or utility libraries. This usually requires that the source module refer to VxWorks header files. The following sections discuss the use of VxWorks header files.

VxWorks header files supply ANSI C function prototype declarations for all global VxWorks routines. The ANSI C prototypes are conditionally compiled; to use them, the preprocessor constant __STDC__ must be defined. ANSI C compilers define this constant by default. VxWorks provides all header files specified by the ANSI X3.159-1989 standard.

VxWorks system header files are in the directory installDir\target\h and its subdirectories.

The header file vxWorks.h contains many basic definitions and types that are used extensively by other VxWorks modules. Many other VxWorks header files require these definitions. Thus, this file must be included first by every application module that uses VxWorks facilities. Include vxWorks.h with the following line:

#include "vxWorks.h"

Application modules can include other VxWorks header files as needed to access VxWorks facilities. For example, an application module that uses the VxWorks linked-list subroutine library must include the lstLib.h file with the following line:

#include "lstLib.h"

The API reference entry for each library lists all header files necessary to use that library.

All ANSI-specified header files are included in VxWorks. Those that are compiler-independent or more VxWorks-specific are provided in installDir\target\h while a few that are compiler-dependent (for example stddef.h and stdarg.h) are provided by the compiler installation. Each toolchain knows how to find its own internal headers; no special compile flags are needed.

Each Wind River compiler has its own C++ libraries and C++ headers (such as iostream and new). The C++ headers are located in the compiler installation directory rather than in installDir\target\h. No special flags are required to enable the compilers to find these headers.

By default, the compiler searches for header files first in the directory of the source module and then in its internal subdirectories. In general, installDir\target\h should always be searched before the compilers' other internal subdirectories; to ensure this, always use the following flag for compiling under VxWorks:

-I %WIND_BASE%\target\h

Some header files are located in subdirectories. To refer to header files in these subdirectories, be sure to specify the subdirectory name in the include statement, so that the files can be located with a single -I specifier. For example:

#include "vxWorks.h" 
#include "sys\stat.h"

Some VxWorks facilities make use of other, lower-level VxWorks facilities. For example, the tty management facility uses the ring buffer subroutine library. The tty header file tyLib.h uses definitions that are supplied by the ring buffer header file rngLib.h.

It would be inconvenient to require you to be aware of such include-file interdependencies and ordering. Instead, all VxWorks header files explicitly include all prerequisite header files. Thus, tyLib.h itself contains an include of rngLib.h. (The one exception is the basic VxWorks header file vxWorks.h, which all other header files assume is already included.)

Generally, explicit inclusion of prerequisite header files can pose a problem: a header file could get included more than once and generate fatal compilation errors (because the C preprocessor regards duplicate definitions as potential sources of conflict). However, all VxWorks header files contain conditional compilation statements and definitions that ensure that their text is included only once, no matter how many times they are specified by include statements. Thus, an application module can include just those header files it needs directly, without regard to interdependencies or ordering, and no conflicts arise.

Internal header files are, for the most part, not intended for use by applications. The following subdirectories are exceptions, and are sometimes required by application programs:

• installDir\target\h\net, which is used by network drivers for specific network controllers.

• installDir\target\h\rpc, which is used by applications using the remote procedure call library.

• installDir\target\h\sys, which is used by applications using standard POSIX functions.

Some elements of VxWorks are internal details that may change and so should not be referenced in your application. The only supported uses of a module's facilities are through the public definitions in the header file, and through the module's subroutine interfaces. Your adherence ensures that your application code is not affected by internal changes in the implementation of a VxWorks module.

Some header files mark internal details using HIDDEN comments:

/* HIDDEN */ 
... 
/* END HIDDEN */

Internal details are also hidden with private header files: files that are stored in the directory installDir\target\h\private. The naming conventions for these files parallel those in installDir\target\h with the library name followed by P.h. For example, the private header file for semLib is installDir\target\h\private\semLibP.h.

Tornado includes a full-featured C and C++ compiler and associated tools, collectively called the GNU ToolKit. Extensive documentation for this set of tools is available in the GNU ToolKit User's Guide. This section provides some general orientation about the source of these tools, and describes how the tools are integrated into the Tornado development environment.

GNU ("GNU's Not UNIX!") is a project of the Free Software Foundation started by Richard Stallman and others to promote free software. To the FSF, free software is software whose source code can be copied, modified, and redistributed without restriction. GNU software is not in the public domain; it is protected by copyright and subject to the terms of the GNU General Public License, a legal document designed to ensure that the software remains free--for example, by prohibiting proprietary modifications and concomitant restrictions on its use. The General Public License can be found in the file COPYING that accompanies the source code for the GNU tools, and in the section titled Free Software at the back of the GNU ToolKit User's Guide.

It is important to be aware that the terms under which the GNU tools are distributed do not apply to the software you create with them. In fact, the General Public License makes no requirements of you as a software developer at all, as long as you do not modify or redistribute the tools themselves. On the other hand, it gives you the right to do both of these things, provided you comply with its terms and conditions. It also permits you to make unrestricted copies for your own use.

The Wind River GNU distribution consists of the GNU ToolKit, which contains GNU tools modified and configured for use with your VxWorks target architecture. The source code for these tools is available upon request.

The GNU cross-development tools in Tornado have names that clearly indicate the target architecture. This allows you to install and use tools for more than one architecture, and to avoid confusion with corresponding host native tools. A suffix identifying the target architecture is appended to each tool name. For example, the cross-compiler for the PowerPC processor family is called ccppc, and the assembler asppc. The suffixes used are shown in Table 5-1. Note that the GNU ToolKit User's Guide refers to these tools by their generic names (without a suffix).

Tornado supports multiple target architectures. To accommodate this support, several VxWorks header files contain conditional compilation directives based on the definition of the variable CPU. When using these header files, the variable CPU must be defined in one of the following places:

• the source modules

• the header files

• the compilation command line

To define CPU in the source modules or header files, add the following line:

#define CPU cputype

To define CPU on the compilation command line, add the following flag:

-DCPU=cputype

The constants shown in Table 5-2 are supported values for cputype.

With makefiles, the CPU definition can be added to the definition of the flags passed to the compiler (usually CFLAGS).

In the source code, the file vxWorks.h must be included before any other files with dependencies on the CPU flag.

As well as specifying the CPU value, you must usually run the compiler with one or more option flags to generate object code optimally for the particular architecture variant. These option flags usually begin with -m; see Compiling C Modules With the GNU Compiler.

The following is an example command to compile an application module for a VxWorks PowerPC 604 system:

c:\> ccppc -mcpu=604 -mstrict-align -I %WIND_BASE%\target\h \ 
-DCPU=PPC603 -DTOOL_FAMILY=gnu -DTOOL=gnu -c applic.c

This compiles the module applic.c into an object file applic.o.

Below we give summary descriptions of the target-independent flags used in the example. Flags that are specific to a particular target architecture are described in the relevant architecture supplement. For more information on any of these flags, see the GNU ToolKit User's Guide.

Generate debugging information.

Compile only to produce a relocatable object file. The result is an object module with the suffix .o, in this case, applic.o.

Required; defines the CPU type.

Optional; defines the compilation toolkit used to compile VxWorks. If not entered, it is derived from -DTOOL=.

Required; specifies the compilation toolkit and the tool environment. For more information, see the GNU ToolKit User's Guide.

Include VxWorks header files. (See 5.2.1 Using VxWorks Header Files.)

Use library calls even for common library subroutines such as memcpy. Used by VxWorks for historical reasons. There is no need for application code to use this flag.

Turn on all warnings. This flag is optional.

Reject non-ANSI-compliant code. This flag is optional.

Perform basic optimizations.

Perform most supported optimizations (except those involving a space-speed trade-off).

The GNU compiler drivers can be used to compile both C and C++ source files. C++ source files are recognized by their extension (typically .cc, .cpp, or .C). For complete information on using C++, including a detailed discussion of compiling C++ modules, see the VxWorks Programmer's Guide: C++ Development.

For more information about the Diab tools, see the Diab C/C++ Compiler User's Guide. The Diab tools are the only tools available for ColdFire. Diab tools are available as an optional product for the ARM/StrongARM/XScale, MIPS, PowerPC, and SuperH architectures.

The Diab C/C++ compiler suites are high performance programming tools. In addition to the benefits of state-of-the-art optimization, they reduce time spent creating reliable code because the compilers and other tools include many built-in, customizable, checking features which help detect problems earlier.

The compilers are particularly helpful in speeding up or reducing the size of existing programs developed with other tools.

With over 250 command-line options and special pragmas, and a powerful linker command language for arranging code and data in memory, the Diab C/C++ compiler suites can be customized to meet the needs of any embedded systems project. A number of options are specifically designed to be compatible with other tools to ease porting of existing code.

If you are using the Diab tools, you need to be sure that two settings are in place:

• Be sure that installDir\host\diab\WIN32\bin is in your path.

• Be sure that the environment variable DIABLIB is set to installDir\host\diab.

There is a batch file called torVars.bat in installDir\host\x86-win32\bin that will set DIABLIB for you.

The Diab cross-development tools in Tornado are always called by the same names: dcc, dld, and so forth. The architecture-specific version of the tool is specified by the -t option in the command line or makefile. For Tornado 2.2, the -t option always includes the architecture family and the VxWorks specifier, for example:

-tPPC403FS:vxworks55 

When you install Diab in the Tornado tree, the defaults are set correctly for the architecture you installed. You can use the command dcc -Xshow-target to display the value and dctrl -t to change it.

You may need to change the architecture family and its characteristics (for example, PPC403FS). Detailed information is available in the Diab C/C++ Compiler User's Guide: Selecting a Target and Its Components.

Tornado supports multiple target architectures. To accommodate this, several VxWorks header files contain conditional compilation directives based on the definition of the variable CPU. When using these header files, the variable CPU must be defined in one of the following places:

• the source modules

• the header files

• the compilation command line

To define CPU in the source modules or header files, add the following line:

#define CPU cputype

To define CPU on the compilation command line, add the following flag:

-DCPU=cputype

The constants shown in Table 5-2 are supported values for cputype.

With makefiles, the CPU definition can be added to the definition of the flags passed to the compiler (usually CFLAGS).

In the source code, the file vxWorks.h must be included before any other files with dependencies on the CPU flag.

As well as specifying the CPU value, you must usually run the compiler with one or more option flags to generate object code optimally for the particular architecture variant. For detailed information, see Diab C/C++ Compiler User's Guide: Selecting a Target and Its Components.

The following is an example command to compile an application module for a VxWorks PowerPC 604 system:

c:\> dcc -g -tPPC403FS:vxworks55 -Xmismatch-warning=2 \ 
-ew1554,1551,1552, 1086,1047,1547 -Xclib-optim-off -Xansi \ 
-Xstrings-in-text=0 -Wa,-Xsemi-is-newline-ei1516,1643,1604 \ 
-Xlocal-data-area-static-only -W:c++:,-Xexceptions -Xsize-opt \ 
-Wall -I%WIND_BASE%\target\h -DCPU=PPC604 -DTOOL=diab -c applic.c

This compiles the module applic.c into an object file applic.o.

Below we give summary descriptions of the target independent flags used in the example. Flags that are specific to a particular target architecture are described in the relevant architecture supplement. For more information on any of these flags see the Diab C/C++ Compiler User's Guide.

Generate debugging information.

Specifies the processor family and the compilation environment. See Cross-Development Commands.

Control the compilation process when behavior other than the default is needed. Most -X options can be set either by name (-Xname) or by number (-Xn). Options control such behaviors as debugging, optimization, and syntax.

For each message number in the comma-separated list, change the severity level of the message to warning.

Pass argument to the assembler.

For each message number in the comma-separated list, change the severity level of the message to information (equivalent to ignore).

Pass the argument -Xexception to the C++ compiler.

Specifies the architecture family.

Required; defines the CPU type.

Optional; defines the compilation toolkit used to compile VxWorks. If not entered, it is derived from -DTOOL=.

Required; specifies the tool and tool environment. For more information, see the Diab C/C++ Compiler User's Guide.

Include VxWorks header files. (See 5.2.1 Using VxWorks Header Files)

The Diab compiler uses dcc to invoke the C compiler and dplus to invoke the C++ compiler. For complete information on using C++, including a detailed discussion of compiling C++ modules see the VxWorks Programmer's Guide: C++ Development and the Diab C/C++ Compiler User's Guide.

After you compile an application module, you can load it directly into the target with the Tornado dynamic loader (through the shell or through the debugger).

In general, application modules do not need to be prelinked before being downloaded to the target. The exception is when several application modules cross reference each other. In this case, the modules should be linked to form a single downloadable module. When using C++, this prelinking should be done before the munch step (see the VxWorks Programmer's Guide: C++ Development).

The following example is a command to link several application modules, using the GNU linker for the PowerPC family of processors.

c:\> ldppc -o applic.o -r applic1.o applic2.o applic3.o

Similarly, the following example is a command to link several application modules, using the Diab linker for the PowerPC family of processors.

c:\> dld -o applic.o -r applic1.o applic2.o applic3.o

This creates the object module applic.o from the object modules applic1.o, applic2.o, and applic3.o. The -r option is required, because the object-module output must be left in relocatable form so that it can be downloaded and linked to the target VxWorks image.

Any VxWorks facilities called by the application modules are reported by the linker as unresolved externals. These are resolved by the Tornado loader when the module is loaded into VxWorks memory.

After application object modules are compiled (and possibly linked by the host ldarch command), they can be dynamically loaded into a running VxWorks system by invoking the Tornado module loader. You can do this either from the Tornado shell using the built-in command ld( ), or from the debugger using the Debug menu or the load command.

The following is a typical load command from the Tornado shell:

-> ld <applic.o

This relocates the code from the host file applic.o, linking to previously loaded modules, and loads the object module into the target's memory. Once an application module is loaded into target memory, any subroutine in the module can be invoked directly from the shell, spawned as a task, connected to an interrupt, and so on.

When a module is loaded, it is assigned a module ID and a group number. Both the module ID and the group number are used to reference the module. The module ID is returned by ld( ) as well as by the target-resident loader routines. When symbols are added to the symbol table, the associated module is identified by the group number (a small integer). (Due to limitations on the size of the symbol table, the module ID is inappropriate for this purpose.) All symbols with the same group number are from the same module. When a module is unloaded, the group number is used to identify and remove all the module's symbols from the symbol table.

Whenever you load a particular object module more than once, using the target server (from either the shell or the debugger), the older version is unloaded automatically. You can also unload a module explicitly; both the Tornado shell and the target-resident VxWorks libraries include an unloader. To remove a module from the shell, use the shell routine unld( ); see the reference entry for windsh.

For information about the target-resident version of the unloader (which also requires the target-resident symbol table and loader), see the VxWorks Programmer's Guide: Target Tools and the VxWorks reference entry for unldLib.

After a module has been unloaded, any calls to routines in that module fail with unpredictable results. Take care to avoid unloading any modules that are required by other modules. One solution is to link interdependent files using the static linker ldarch as described in 5.2.4 Static Linking (Optional), so that they can only be loaded and unloaded as a unit.

The configuration of VxWorks is determined by the configuration header files installDir\target\config\all\configAll.h and installDir\target\config\bspname\config.h. These files are used by the usrConfig.c, bootConfig.c, and bootInit.c modules as they run the initialization routines distributed in the directory installDir\target\src\config to configure VxWorks.

The VxWorks distribution includes the configuration files for the default development configuration. You can create your own versions of these files to better suit your particular configurations; this process is described in the following subsections. In addition, if you need multiple configurations, environment variables can be set so you can move easily between them.

Including optional components in your VxWorks image can significantly increase the image size. VxWorks BSP Developer's Guide you receive a warning from vxsize when building VxWorks, or if the size of your image becomes greater than that supported by the current setting of RAM_HIGH_ADRS, be sure to see Scaling Down VxWorks and 5.6 Creating Bootable Applications for information on how to resolve the problem.

The directory installDir\target\config\bspname contains the Board Support Package (BSP), which consists of files for the particular hardware used to run VxWorks, such as a VME board with serial lines, timers, and other devices. The files include: Makefile, sysLib.c, sysALib.s, romInit.s, bspname.h, and config.h.

Wind River-supplied BSPs conform to a standard, introduced with BSP Version 1.1. The standard is fully described in the VxWorks BSP Developer's Guide.

The file sysLib.c provides the board-level interface on which VxWorks and application code can be built in a hardware-independent manner. The functions addressed in this file include:

• Initialization functions

• initialize the hardware to a known state

• identify the system

• initialize drivers, such as SCSI or custom drivers

• Memory/address space functions

• get the on-board memory size

• make on-board memory accessible to the external bus (optional)

• map local and bus address spaces

• enable/disable cache memory

• set/get nonvolatile RAM (NVRAM)

• define the board's memory map (optional)

• virtual-to-physical memory map declarations for processors with MMUs

• Bus interrupt functions

• enable/disable bus interrupt levels

• generate bus interrupts

• Clock/timer functions

• enable/disable timer interrupts

• set the periodic rate of the timer

• Mailbox/location monitor functions (optional)

• enable mailbox/location monitor interrupts

The sysLib library does not support every feature of every board. Some boards may have additional features, others may have fewer, others still may have the same features with a different interface. For example, some boards provide some sysLib functions by means of hardware switches, jumpers, or PALs, instead of by software-controllable registers.

The configuration modules usrConfig.c and bootConfig.c in installDir\target\config\all are responsible for invoking this library's routines at the appropriate time. Device drivers can use some of the memory mapping routines and bus functions.

For boards with MMU support, the data structure sysPhysMemDesc defines the virtual-to-physical memory map. This table is typically defined in sysLib.c, although some BSPs place it in a separate file, memDesc.c. It is declared as an array of the data structure PHYS_MEM_DESC. No two entries in this descriptor can overlap; each entry must be a unique memory space.

The sysPhysMemDesc array should reflect your system configuration, and you may encounter a number of reasons for changing the MMU memory map, for example: the need to change the size of local memory or the size of the VME master access space, or because the address of the VME master access space has been moved. For information on virtual memory mapping, as well as an example of how to modify sysPhysMemDesc, see VxWorks Programmer's Guide: Virtual Memory Interface.

The file config.h specifies which VxWorks facilities are included in your system image. The file bspname.h specifies BSP-specific capabilities.

The following files initialize the BSP:

• The file romInit.s contains assembly-level initialization routines.

• The file sysALib.s contains initialization and system-specific assembly-level routines.

The file target.nr in the installDir\target\config\bspname directory is the source of the online reference entry for target-specific information. (You can also view the HTML version of this document from the Tornado IDE: Help>Manuals Contents>BSP Reference>bspname.) The target.nr file describes the supported board variations, the relevant jumpering, and supported devices. It also includes an ASCII representation of the board layout with an indication of board jumpers (if applicable) and the location of the ROM sockets.

You can use Tornado environment variables to build variations of system configurations. In general, your Tornado environment consists of three parts: the host code (Tornado), the target code, and the configuration files discussed in this section. On Windows hosts, the IDE automatically locates Tornado code in the following locations:

Host code:	installDir\host\hosttype\bin or %WIND_BASE%\host\x86-win32\bin
Target code:	installDir\target or TGT_DIR = %WIND_BASE%\target
Configuration code:	installDir\target\config\all or CONFIG_ALL = %TGT_DIR%\config\all

To use different versions of usrConfig.c, bootConfig.c, and bootInit.c, store them in a different directory and change the value of CONFIG_ALL. To use different target code, point to the alternate directory by changing the value of TGT_DIR.

You can change the value of CONFIG_ALL by changing it either in your makefile or on the command line. The value of TGT_DIR must be changed on the command line.

You can control VxWorks's configuration by including or excluding definitions in the global configuration header file configAll.h and in the target-specific configuration header file config.h. This section describes these files.

The configAll.h header file, in the directory installDir\target\config\all, contains default definitions that apply to all targets, unless they are redefined in the target-specific header file config.h. The following options and parameters are defined in configAll.h:

• kernel configuration parameters

• I/O system parameters

• NFS parameters

• selection of optional software modules

• selection of optional device controllers

• cache modes

• maximum number of different shared memory objects

• device controller I/O addresses, interrupt vectors, and interrupt levels

• miscellaneous addresses and constants

The BSP-specific header file, config.h, is located in the directory installDir\target\config\bspname. This file contains definitions that apply only to the specific target, and can also redefine default definitions in configAll.h that are inappropriate for the particular target. For example, if a target cannot access a device controller at the default I/O address defined in configAll.h because of addressing limitations, the address can be redefined in config.h.

The config.h header file includes definitions for the following parameters:

• default boot parameter string for boot ROMs

• interrupt vectors for system clock and parity errors

• device controller I/O addresses, interrupt vectors, and interrupt levels

• shared memory network parameters

• miscellaneous memory addresses and constants

VxWorks ships with optional features and device drivers that can be included in, or omitted from, the target system. These are controlled by macros in the project facility or the configuration header files that cause conditional compilation in the installDir\target\config\all\usrConfig.c module.

The distributed versions of the configuration header files configAll.h and config.h include all the available software options and several network device drivers. If you are not using the project facility (see 4. Projects), you define a macro by moving it from the EXCLUDED FACILITIES section of the header file to the INCLUDED SOFTWARE FACILITIES section.¹ For example, to include the ANSI C assert library, make sure the macro INCLUDE_ANSI_ASSERT is defined; to include the Network File System (NFS) facility, make sure INCLUDE_NFS is defined. Modification or exclusion of particular facilities is discussed in detail in 5.3.5 Alternative VxWorks Configurations.

Use of the VxWorks configuration header files to configure your VxWorks system should meet all of your development requirements. Users should not resort to changing the Wind River-supplied usrConfig.c, or any other module in the directory installDir\target\config\all. If, however, an extreme situation requires such a change, we recommend you copy all the files in installDir\target\config\all to another directory, and add a CONFIG_ALL macro to your makefile to point the make system to the location of the modified files. For example, add the following to your makefile after the first group of include statements:

The discussion of the usrConfig module in 5.3.4 The Configuration Module: usrConfig.c outlined the default configuration for a development environment. In this configuration, the VxWorks system image contains all of the VxWorks modules that are necessary to allow you to interact with the system through the Tornado host tools.

However, as you approach a final production version of your application, you may want to change the VxWorks configuration in one or more of the following ways:

• Change the configuration of the target agent.

• Decrease the size of VxWorks.

• Run VxWorks from ROM.

The following sections discuss the latter two alternatives to the typical development configuration. For a discussion on reconfiguring the target agent, see 4. Projects.

In a production configuration, it is often desirable to remove some of the VxWorks facilities to reduce the memory requirements of the system, to reduce boot time, or for security purposes.

Optional VxWorks facilities can be omitted by commenting out or using #undef to undefine their corresponding control constants in the header files configAll.h or config.h. For example, logging facilities can be omitted by undefining INCLUDE_LOGGING, and signalling facilities can be omitted by undefining INCLUDE_SIGNALS.

VxWorks is designed to make it easy to exclude facilities you do not need. However, not every BSP is organized in this way. If you wish to minimize the size of your system, be sure to examine your BSP code and eliminate references to facilities you do not need. Even though you exclude them, if your code refers to them, your exclusion will be overridden.

You can put VxWorks or a VxWorks-based application into ROM; this is discussed in 5.6.3 Creating a VxWorks System in ROM. For an example of a ROM-based VxWorks application, see the VxWorks boot ROM program. The file installDir\target\config\all\bootConfig.c is the configuration module for the boot ROM, replacing the file usrConfig.c provided for the default VxWorks development system.

In such ROM configurations, the text and data segments of the boot or VxWorks image are first copied into the system RAM, then the boot procedure or VxWorks executes in RAM. On some systems where memory is a scarce resource, it is possible to save space by copying only the data segment to RAM. The text segment remains in ROM and executes from that address space, and thus is termed ROM resident. The memory that was to be occupied by the text segment in RAM is now available for an application (up to 300 KB for a standalone VxWorks system). Note that ROM-resident VxWorks is not supported on all boards; see the reference entry for your target if you are not sure that your board supports this configuration.

The drawback of a ROM-resident text segment is the limited data widths and lower memory access time of the EPROM, which causes ROM-resident text to execute more slowly than if it was in RAM. This can sometimes be alleviated by using faster EPROM devices or by reconfiguring the standalone system to exclude unnecessary system features.

Aside from program text not being copied to RAM, the ROM-resident versions of the VxWorks boot ROMs and the standalone VxWorks system are identical to the conventional versions. A ROM-resident image is built with an uncompressed version of either the boot ROM or standalone VxWorks system image. VxWorks target makefiles include entries for building these images; see Table 5-4.    

Because of the size of the system image, 512 KB of EPROM is recommended for the ROM-resident version of the standalone VxWorks system. More space is probably required if applications are linked with the standalone VxWorks system. For a ROM-resident version of the boot ROM, 256 KB of EPROM is recommended. If you use ROMs of a size other than the default, modify the value of ROM_SIZE in the target makefile and config.h.

A separate make target, vxWorks.res_rom_nosym, has been created to provide a ROM-resident image without the symbol table. This is intended to be a standard ROM image for use with the Tornado environment where the symbol table resides on the host system. Being ROM-resident, the debug agent and VxWorks are ready almost immediately after power-up or restart.

The data segment of a ROM-resident standalone VxWorks system is loaded at RAM_LOW_ADRS (defined in the makefile) to minimize fragmentation. The data segment of ROM-resident boot ROMs is loaded at RAM_HIGH_ADRS, so that loading VxWorks does not overwrite the resident boot ROMs. For a CPU board with limited memory (under 1 MB of RAM), make sure that RAM_HIGH_ADRS is less than LOCAL_MEM_SIZE by a margin sufficient to accommodate the data segment. Note that RAM_HIGH_ADRS is defined in both the makefile and config.h. These definitions must agree.

Figure 5-1 shows the memory layout for ROM-resident boot and VxWorks images. The lower portion of the diagram shows the layout for ROM; the upper portion shows the layout for RAM. LOCAL_MEM_LOCAL_ADRS is the starting address of RAM. For the boot image, the data segment gets copied into RAM above RAM_HIGH_ADRS (after space for bss is reserved). For the VxWorks image, the data segment gets copied into RAM above RAM_LOW_ADRS (after space for bss is reserved). Note that for both images the text segment remains in ROM.

You can redefine the VxWorks configuration in two ways: interactively, as described 4. Projects, or by editing VxWorks configuration files as described in 5.3 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 application images

• Downloadable VxWorks images

• ROM-based VxWorks images

Boot ROM images come in three 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, while "standalone" is an image that uses the target 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 include:

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

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 the GNU Make User's Guide for a detailed description of GNU make and of how to write makefiles.

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 12.4.3 Customizing the Build Menu.

To rebuild VxWorks from the Windows command prompt (or from a batch file), change to the config directory for the desired target and invoke make as follows:

C:\> cd installDir\target\config\bspname 
C:\installDir\target\config\bspname> make

make compiles and links modules as necessary, based on the directives in the target directory's makefile.

The directory installDir\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 A. 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\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:

c:\> make CPU=cputype TOOL=tool

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 12.4.3 Customizing the Build Menu.

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.

c:\> cd %WIND_BASE%\target\src\usr 
c:\installDir\target\src\usr> copy usrLib.c usrLib.c.orig 
c:\installDir\target\src\usr> copy develDir\usrLib.c usrLib.c 
c:\installDir\target\src\usr> make CPU=PPC860 
... 
c:\installDir\target\src\usr> cd %WIND_BASE%\target\config\epc4 
c:\installDir\target\config\epc4> make 
...

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

VxWorks operating system modules are distributed in the form of archive libraries. One set of archives is provided for each target architecture. These archives are located under installDir/target/lib. For more details about the archive directory structure, see the Tornado Migration Guide: Binary Compatibility.

These modules are combined with the configuration module usrConfig.o by the ccarch command on the host. (The file usrConfig.c is described in 5.3.4 The Configuration Module: usrConfig.c.) The following are example commands for building and linking a VxWorks system using the GNU compiler for PowerPC.

For a partial image (partially linked):

ccppc -r -nostdlib -Wl,-X -o vxWorks.tmp sysALib.o sysLib.o \ 
miiLib.obj  usrConfig.o version.o -Wl,--start-group \ 
-L\vobs\wpwr\target\lib\ppc\PPC604\gnu \ 
-L\vobs\wpwr\target\lib\ppc\PPC604\common -lcplus -lgnucplus \ 
-lvxcom -lvxdcom -larch -lcommoncc -ldcc -ldrv -lgcc -lnet -los \ 
-lrpc -lsecurity -ltffs -lusb -lvxfusion -lvxmp -lvxvmi -lwdb  \ 
-lwind -lwindview \vobs\wpwr\target\lib\libPPC604gnuvx.a -Wl,--end-group

For the final image (fully linked):

ldppc -X -N -e _sysInit -Ttext 00100000 -o vxWorks dataSegPad.o \ 
vxWorks.tmp ctdt.o -T \vobs\wpwr\target\h\tool\gnu\ldscripts\link.RAM

The meanings of the flags in these commands are as follows:

Generate relocatable output.

Do not use the standard system libraries.

Pass option as an option to the linker.

Eliminate some compiler-generated symbols from the symbol table.

Name the output object module vxWorks.

The specified archives are searched repeatedly until no new undefined references are created. archives should be a list of archive files. They may be either explicit file names, or -l options.

List of all the archive files added to the list of files to link. ld searches its path-list for occurrences of libarch.a for every archive specified.

List of all the paths that ld will search for archive libraries. The directories are searched in the order in which they are specified on the command line. All -L options apply to all -l options, regardless of the order in which the options appear.

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 5.3.4 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.

A VxWorks 5.4.x archive, included for backward compatibility. VxWorks is completely specified by the libraries indicated by -l and -L. This library might be used by optional or third-party products.

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 5.6 Creating Bootable Applications for more detail on linking application modules in a bootable system.

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 the makefile that creates this file executes the command:

xsym < vxWorks > vxWorks.sym

The file vxWorks.sym is downloaded to the target to build the target symbol table when INCLUDE_NET_SYM_TBL is included.

Makefiles for VxWorks applications are easy to create by exploiting the makefiles and make include files shipped with VxWorks BSPs. This section discusses how the VxWorks BSP makefiles are structured. For more information, see B. Makefile Details. An example of how to utilize this structure for application makefiles is in 5.5.2 Using Makefile Include Files for Application Modules.

A set of supporting files in installDir\target\h\make makes it possible for each BSP or application makefile to be terse, specifying only the essential parameters that are unique to the object being built.

Example 5-1 shows the makefile from the installDir\target\config\mbx860 directory; the makefile for any other BSP is similar. Two variables are defined at the start of the makefile: CPU, to specify the target architecture; and TOOL to identify what compilation tools to use. Based on the values of these variables and on the environment variables defined as part of your Tornado configuration, the makefile selects the appropriate set of definitions from installDir\target\h\make. After the standard definitions, several variables define properties specific to this BSP. Finally, the standard rules for building a BSP on your host are included.

The variables defined in the make include files provide convenient defaults for most situations, and allow individual makefiles to specify only the definitions that are unique to each. This section describes the make variables most often used to specify properties of BSPs or applications. The following lists are not intended to be comprehensive; see the make include files for the complete set.

The variables grouped in this section are useful for either BSP makefiles or application-module makefiles. They specify aspects of how to invoke the compiler.

The complete set of option flags for any invocation of the C compiler. This variable gathers the options specified in CC_COMPILER, CC_WARNINGS, CC_OPTIM, CC_INCLUDE, CC_DEFINES, and ADDED_CFLAGS.

The complete set of option flags for any invocation of the C++ compiler. This variable gathers together the options specified in C++_COMPILER, C++_WARNINGS, CC_OPTIM, CC_INCLUDE, CC_DEFINES, and ADDED_C++FLAGS.

Option flags specific to compiling the C language. Default: -ansi -nostdinc.

Option flags specific to compiling the C++ language. Default: -ansi -nostdinc.

Option flags to select the level of warning messages from the compiler, when compiling C programs. Two predefined sets of warnings are available: CC_WARNINGS_ALL (the compiler's most comprehensive collection of warnings) and CC_WARNINGS_NONE (no warning flags). Default: CC_WARNINGS_ALL.

Option flags to select the level of warning messages from the compiler, when compiling C++ programs. The same two sets of flags are available as for C programs. Default: CC_WARNINGS_NONE.

Optimization flags. Three sets of flags are predefined for each architecture: CC_OPTIM_DRIVER (optimization level appropriate to a device driver), CC_OPTIM_TARGET (optimization level for BSPs), and CC_OPTIM_NORMAL (optimization level for application modules). Default: CC_OPTIM_TARGET.

Standard set of header-file directories. To add application-specific header-file paths, specify them in EXTRA_INCLUDE.

Definitions of preprocessor constants. This variable is predefined to propagate the makefile variable CPU to the preprocessor, to include any constants required for particular target architectures, and to include the value of the makefile variable EXTRA_DEFINE. To add application-specific constants, specify them in EXTRA_DEFINE.

The variables included in this section specify properties of a particular BSP, and are thus recorded in each BSP makefile. They are not normally used in application-module makefiles.

Name of the BSP (used for dependency lists and name of documentation reference entry). The value matches the bspname directory name.

Address of the ROM entry point. Also defined in config.h; the two definitions must match.

Number of bytes available in the ROM. Also defined in config.h; the two definitions must match.

RAM address where the boot ROM data segment is loaded. Must be a high enough value to ensure loading VxWorks does not overwrite part of the ROM program. Also defined in config.h; the two definitions must match. See 5.6 Creating Bootable Applications for more discussion.

Beginning address to use for the VxWorks run-time in RAM.

GNU objcopy flags. These vary by architecture; for more information, see the GNU ToolKit User's Guide.

Linker options for the static link of VxWorks and boot ROMs.

Additional static-link option flags specific to boot ROM images.

The variables listed in this section make it easy to control what facilities are statically linked into your run-time system. You can specify values for these variables either from the make command line, or from your own makefiles (when you take advantage of the predefined VxWorks make include files).

Location of a directory containing the architecture-independent BSP configuration files. Set this variable if you maintain several versions of these files for different purposes. Default: installDir\target\config\all.

Linker options to include additional archive libraries (you must specify the complete option, including the -L for each library). These libraries appear in the link command before the standard VxWorks libraries.

Names of application modules to include in the static link to produce a VxWorks run-time. See 5.6 Creating Bootable Applications.

Names of application modules to include in the static link to produce a VxWorks boot image but not in a normal VxWorks image.

Do not define a value for this variable in makefiles. This variable is reserved for adding modules to a static link from the make command line. Its value is used in the same way as MACH_EXTRA, to include additional modules in the link. Reserving a separate variable for use from the command line avoids the danger of overriding any object modules that are already listed in MACH_EXTRA.

Preprocessor options to define any additional header-file directories required for your application (specify the complete option, including -I).

Definitions for application-specific preprocessor constants (you must specify the complete option, including the -D).

Application-specific compiler options for C programs.

Application-specific compiler options for C++ programs.

You can exploit the VxWorks makefile structure to put together your own application makefiles quickly and tersely. If you build your application directly in a BSP directory (or in a copy of one), you can use the makefile in that BSP, by specifying variable definitions (Variables for Customizing the Run-Time) that include the components of your application.

You can also take advantage of the Tornado makefile structure if you develop application modules in separate directories. Example 5-2 illustrates the general scheme. Include the makefile headers that specify variables, and list the object modules you want built as dependencies of a target. This simple scheme is usually sufficient, because the Tornado makefile variables are carefully designed to fit into the default rules that make knows about.²

As you approach a final version of your application, you will probably want to add modules to the bootable system image, and include startup of your application with the system initialization routines. In this way, you can create a bootable application, which is completely initialized and functional after booting, without requiring any interaction with the host-resident development tools.

Linking the application with VxWorks is a two-step process. You must include the application initialization code in config.h, and you must modify the makefile to link the application statically with VxWorks.

To include the application code in config.h, you must:

• #define INCLUDE_USER_APPL (change #undef to #define)

• Modify the code fragment that defines USER_APPL_INIT. A template is provided; modify it as necessary to start your application:

#define USER_APPL_INIT \ 
    { \ 
    IMPORT int myAppInit(); \ 
    taskSpawn ("myApp", 30, 0, 5120, \ 
                mpAppInit, 0x1, 0x2, 0x3, 0,0,0,0,0,0,0); \ 
    } 

To include your application modules in the bootable system image, add the names of the application object modules (with the .o suffix) to MACH_EXTRA in the makefile. For example, to link the module myMod.o, add a line like the following:

MACH_EXTRA = myMod.o

Building the system image with the application linked in is the final part of this step. In the target directory, execute the following command:

c:\> make vxWorks

Application size is usually an important consideration in bootable applications. Generally, VxWorks boot ROM code is copied to a start address in RAM above the constant RAM_HIGH_ADRS, and the ROM in turn copies the downloaded system image starting at RAM_LOW_ADRS. The values of these constants are architecture dependent, but in any case the system image must not exceed the space between the two. Otherwise the system image overwrites the boot ROM code while downloading, thus killing the booting process.

To help avoid this, the last command executed when you make a new VxWorks image is vxsize, which shows the size of the new executable image and how much space (if any) is left in the area below the space used for ROM code:

vxsize 386 -v 00100000  00020000  vxWorks 
vxWorks: 612328(t) + 69456(d) + 34736(b) = 716520 (235720 bytes left)

If your new image is too large, vxsize issues a warning. In this case, you can reprogram the boot ROMs to copy the ROM code to a sufficiently high memory address by increasing the value of RAM_HIGH_ADRS in config.h and in your BSP's makefile (both values must agree). Then rebuild the boot ROMs by executing the following command:

c:\> make bootrom.hex

The binary image size of typical boot ROM code is 128KB or less. This small size is achieved through compression; see Boot ROM Compression. The compressed boot image begins execution with a single uncompressed routine, which uncompresses the remaining boot code to RAM. To avoid uncompressing and thus initialize the system a bit faster, you can build a larger, uncompressed boot ROM image by specifying the make target bootrom_uncmp.hex.

It is sometimes useful to create a VxWorks system that includes a copy of its own symbol table. The procedure for building such a system is somewhat different from the procedure described in 5.6.1 Linking Bootable Applications. No change is necessary to usrConfig.c. A different make target, vxWorks.st, specifies the standalone form of VxWorks:

c:\> make vxWorks.st

The rules for building vxWorks.st create a module usrConfig_st.o, which is the usrConfig.c module compiled with the STANDALONE flag defined. The STANDALONE flag causes the usrConfig.c module to be compiled with the built-in system symbol table, the target-resident shell, and associated interactive routines.

The STANDALONE flag also suppresses the initialization of the network. If you want to include network initialization, define STANDALONE_NET in either of the header files installDir\target\config\bspname\config.h or installDir\target\config\all\configAll.h.³

VxWorks is linked as described previously, except that the first pass through the loader does not specify the final load address; thus the output from this stage is still relocatable. The makeSymTbl tool is invoked on the loader output; it constructs a data structure containing all the symbols in VxWorks. This structure is then compiled and linked with VxWorks itself to produce the final bootable VxWorks object module.

To include your own application in the system image, add the object modules to the definition of MACH_EXTRA and follow the procedures discussed in 5.6.1 Linking Bootable Applications.

Because vxWorks.st has a built-in symbol table, there are some minor differences in how it treats VxWorks symbols, in contrast with the host symbol table used by Tornado tools through the target server. First, VxWorks symbol table entries cannot be deleted from the vxWorks.st symbol table. Second, no local (static) VxWorks symbols are present in vxWorks.st.

To put VxWorks or a VxWorks-based application into ROM, you must enter the object files on the loader command line in an order that lists the module romInit.o before sysALib.o. Also specify the entry point option -e _romInit. The romInit( ) routine initializes the stack pointer to point directly below the text segment. It then calls bootInit( ), which clears memory and copies the vxWorks text and data segments to the proper location in RAM. Control is then passed to usrInit( ).

A good example of a ROM-based VxWorks application is the VxWorks boot ROM program itself. The file installDir\target\config\all\bootConfig.c is the configuration module for the boot ROM, replacing the file usrConfig.c provided for the default VxWorks development system. The makefiles in the target-specific directories contain directives for building the boot ROMs, including conversion to a file format suitable for downloading to a PROM programmer. Thus, you can generate the ROM image with the following make command:

c:\> make bootrom.hex

Tornado makefiles also define a ROMable VxWorks run-time system suitable for use with Tornado tools as the target vxWorks.res_rom_nosym. To generate this image in a form suitable for writing ROMs, run the following command:

c:\> make vxWorks.res_rom_nosym.hex

VxWorks target makefiles also include the entry vxWorks.st_rom for creating a ROMable version of the standalone system described in 5.6.2 Creating a Standalone VxWorks System with a Built-in Symbol Table. The image vxWorks.st_rom differs from vxWorks.st in two respects: (1) romInit code is loaded as discussed above, and (2) the portion of the system image that is not essential for booting is compressed by approximately 40 percent using the VxWorks compress tool (see Boot ROM Compression).

To build the form of this target that is suitable for writing into a ROM (most often, this form uses the Motorola S-record format), enter:

c:\> make vxWorks.st_rom.hex

When adding application modules to a ROMable system, size is again an important consideration. Keep in mind that by using the compress tool, a configuration that normally requires a 256-KB ROM may well fit into a 128-KB ROM. Be sure that ROM_SIZE (in both config.h and the makefile) reflects the capacity of the ROMs used.

In some cases, you may wish to change and customize your BSP using the techniques described in this chapter, and then build the VxWorks image for use by application developers using the project facility. This is the one case where you can "mix" the two methods of configuration. Using one of these make targets creates a project based on the BSP you have created with all your customizations. This project can serve as a base for further development.