The Tornado distribution includes a VxWorks system image for each target shipped. 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-relocateable object module with no unresolved external references. In most cases, you will find the supplied system image adequate for initial development. However, later in the cycle you may want to create a custom VxWorks image.

VxWorks is a flexible, scalable operating system with numerous facilities that can be tuned, and included or excluded, depending on the requirements of your application and the stage of the development cycle. For example, various networking and file system components may be required for one application and not another, and the project facility provides a simple means for either including them in, or excluding them from, a VxWorks application. In addition, it may be useful to build VxWorks with various target tools during development (such as the target-resident shell), and then exclude them from the production application.

Once you create a customized VxWorks, you can boot your target with it and then download and run applications. You can also create a bootable application simply by linking your application to VxWorks and adding application startup calls to the VxWorks system initialization routines (see 4.4 Creating a Bootable Application).

All work that you do with the project facility, whether a downloadable application, a customized version of VxWorks, or a bootable application, takes place in the context of a project.

Open a project workspace by clicking the Project button in the Tornado Launch window. If the Create Project or Open Workspace window is open (the default when you first open the Tornado Project window¹ ), click the New tab. Otherwise, click File>New Project. Then choose the selection for a bootable application, and click OK (Figure 4-17)

Figure 4-17:  Create Bootable Application

.

The application wizard appears (Figure 4-18). This wizard is a tool that guides you through the steps of creating a new project.

First, enter the full directory path and name of the directory you want to use for the project (only one project is allowed in a directory), and enter the project name. It is usually most convenient to use the same name for the directory and project, but it is not required.

	NOTE: You may create your projects anywhere on your file system. However, it is preferable to create them outside of the Tornado directory tree to simplify the process of future Tornado upgrades.

You may also enter a description of the project, which will later appear in the property sheet for the project. Finally, identify the workspace in which the project should be created. Click Next to continue.

Figure 4-18:  Application Wizard: Step One for Bootable Application

Then you identify the BSP with which you will build the project. You can do so by referring to an existing project, or by identifying a BSP that you have installed.

	NOTE: If you are creating a customized VxWorks image or a bootable application, the project will be generated faster if you base it on an existing project rather than a BSP. This is because the project facility does not have to regenerate configuration information from BSP configuration files. All Tornado 2.x BSPs include project files for this purpose. Options for BSP projects are available in the drop-down list for existing projects. For example, the mv162 BSP project file is         wind/target/proj/mv162_vx.wpj. Projects can only be created from BSPs installed in the Tornado 2.x directory tree. If you want to use a BSP from an earlier version of Tornado (or any third-party BSP that is compliant with Wind River Systems coding conventions for BSPs), you must install it in the current tree before creating your project.

Basing a project on an existing project means that the new project will reference the same source files as the one on which it was based, but it will start with copies of the original project's VxWorks configuration and build specifications. The build specifications and VxWorks configuration for the new project can be modified without affecting the original project, but changes to any shared source files will be reflected in both.

For example, to create a project for a module that will run on a 486 PC target, select An existing project and then select pc486_vx.wpj from the drop-down list (Figure 4-19). Click Next.

Figure 4-19:  Application Wizard: Step Two for Bootable Application

The wizard confirms your selections (Figure 4-20). Click Finish.

Figure 4-20:  Application Wizard: Step Three for Bootable Application

The Workspace window appears.

The project facility generates, or includes copies of, a variety of files for a VxWorks project. The names of the files that you may need to work with are displayed in the workspace File view (Figure 4-21).

	NOTE: Context menus provide access to all commands that can be used with the objects displayed in, and the pages that make up, the Workspace window (use the right mouse button).

Figure 4-21:  VxWorks Project Files

During typical use of the project facility you do not need to be concerned with these files, except to avoid accidental deletion, to check them in or out of a source management system, or to share your projects or workspaces with others. You will need to edit userAppInit.c, however, when you create a bootable application (see 4.4 Creating a Bootable Application).

The VxWorks project files serve the following purposes:

linkSyms.c

A dynamically generated configuration file that includes code from the VxWorks archive by creating references to the appropriate symbols.

prjConfig.c

A dynamically generated configuration file that contains initialization code for components included in the current configuration of VxWorks.

romInit.s

Contains the entry code for the VxWorks boot ROM.

romStart.c

Contains routines to load VxWorks system image into RAM.

sysALib.s

Contains system startup code, the first code executed after booting (which is the entry point for VxWorks in RAM).

sysLib.c

Contains board-specific routines.

userAppInit.c

Contains a stub for adding user application initialization routines for a bootable application.

The following files are created in the main project directory as well, but are not visible in the workspace:

prjComps.h

Contains the preprocessor definitions (macros) used to include VxWorks components.

Makefile

The makefile used for building an application or VxWorks. Created when the project is built, based on the build specification selected at that time.

prjParams.h

Contains component parameters.

projectName.wpj

Contains information about the project used for generating the project makefile, as well as project source files such as prjConfig.c.

workspaceName.wsp

Contains information about the workspace, including which projects belong to it.

When you build the project, a makefile is dynamically generated in the main project directory, and a subdirectory is created containing the objects produced by the build. The subdirectory is named after the selected build specification. If other build specifications are created and used for other builds, parallel directories are created for their objects.

The Files view can also display the default list of objects that would be built, and the external dependencies that make up the new project, in the Object Modules and External Dependencies folders, respectively.

The VxWorks view of the Workspace displays all VxWorks components available for the target. The names of components that are selected for inclusion appear in bold type. The names of components that are excluded appear in plain type. The names of components that have not been installed appear on italics. Note that the names of folders appear in bold type if any (but not necessarily all) of their components are included. (Figure 4-22.)

Figure 4-22:  VxWorks Components

	NOTE: See the VxWorks Programmer's Guide for detailed information about the use of VxWorks facilities, target-resident tools, and optional components.

You can locate individual components and configuration parameters in the component tree, based on their macro names with the Find Object dialog box. The dialog box can be accessed with the context menu for the VxWorks view (Figure 4-23).

Figure 4-23:  Find Object

	NOTE: The Find Object dialog box is particularly helpful in conjunction with VxWorks documentation, which discusses VxWorks configuration in terms of preprocessor symbols, rather than the descriptive names used in the project facility GUI.

The component tree in the VxWorks view provides descriptive names for components. You can display a component description property sheet, which includes the name of the pre-processor macro for the component, by double-clicking on the component name (Figure 4-24).

Figure 4-24:  VxWorks Component Properties and HTML Reference

To display online reference documentation, double-click on the topic of your choice displayed in the Help Link box of the property sheet. The corresponding HTML reference material is displayed in a Web browser (Figure 4-24).

VxWorks components that are not needed for a project can be excluded, and components that have been excluded can be included again. The context menu provides Include and Exclude options for components you select in the VxWorks view. You can also use the DELETE key to exclude options.

Tornado automatically determines component dependencies each time a component is included or excluded. That is, it determines if a component you want to include is dependent upon other components that have not been included in the project, or if a component that you are deleting is required by other components. When a component is included, any dependent components are automatically included. When a component is excluded, any dependent components are also excluded. In either case, a dialog box provides information about dependencies and the option of cancelling the requested action. For example, if you exclude POSIX clocks, the dialog box informs you that ANSI time component would be excluded (Figure 4-25).

Figure 4-25:  Exclude VxWorks Component

	WARNING: The results of calculating dependencies is not necessarily identical for inclusion and removal. Including a component you previously excluded does not automatically include the components that were dependent on that component, and that were therefore excluded with it. For example, excluding the POSIX clocks component automatically excludes the ANSI time component, which is dependent on it. But if the POSIX clocks component is subsequently included, there are no components required by it, and the ANSI time component is not automatically included (Figure 4-26).

Figure 4-26:  Include VxWorks Component

You can also include folders of components. However, not all components in a folder are necessarily included by default (nor would it always be desirable to do so, as there might be conflicts between components). Tornado offers a choice about what components to include. For example, if you include target shell components, not all of the components are included by default, and you are prompted to accept or modify the default selection (Figure 4-27).

Figure 4-27:  Including a Component Folder

Tornado automatically calculates an estimate of the change in the size of the image resulting from the inclusion or exclusion, as well as the new image size. The Include and Exclude dialog boxes display this information. (Also see Estimating Total Component Size).

Some folders contain component options that are explicitly combinative or mutually exclusive (in the sense of being potentially conflictual). The name of these folders are preceded by a checkbox icon in the folder tree. You can make your selection or change either by opening the folder and performing an include or exclude operation on individual components; or by displaying the property sheet for the folder and making selections with the check boxes on the Components page (Figure 4-27).

Figure 4-28:  Including Conflicting Components

If you include components that potentially conflict, or are missing a required component, Tornado warns you of the conflict by displaying a message box with a warning, and by highlighting the full folder path to the source of the conflict. The property sheet for the folder also displays error information in its Errors page. For example, if you attempt to include both symbol table initialization components a warning is first displayed. Once you acknowledge the warning, the folder names development tool components, symbol table components, select symbol table initialization are highlighted. You can display the property sheet for the folder for a description of the problem and how to correct it. (See Figure 4-29 for all GUI elements.)

Figure 4-29:  Component Conflicts

	WARNING: You can build VxWorks even if there are conflicts between the components you have selected, but you may have linker errors or the run-time results may be unpredictable.

In the VxWorks view, the context menu provides access to component parameters (preprocessor macros). For example, selecting the operating system components folder, then Params for 'operating system components' from the context menu (or double-clicking on the folder name), displays a dialog box that allows you to change the values of the parameters defined for the operating system components (Figure 4-30). Parameters specific to individual components can be accessed similarly.

Figure 4-30:  Component Parameters

To calculate and display the estimated size of the components included in an image, select the project name (in any of the workspace views), then select Properties from the context menu, and select the Size tab in the property sheet that appears (Figure 4-31). Note that this estimate is for the components only, and does not include the BSP or any application code.

Figure 4-31:  Total Component Size

       

The default VxWorks is a RAM-based image. If you want to create something other than the default, double click on the build name in the Builds view to display the property sheet for that build. Then select the Rules tab, use the drop-down list to select the type of VxWorks image that you want to build, and click OK (Figure 4-32).

Figure 4-32:  Build Rules for VxWork Images

The options available for a VxWorks image are:

vxWorks

A RAM-based image, usually loaded into memory by a VxWorks boot ROM. This is the default development image.

vxWorks_rom

A ROM-based image that copies itself to RAM before executing. This image generally has a slower startup time, but a faster execution time than vxWorks_romResident.

vxWorks_romCompress

A compressed ROM image that copies itself to RAM and decompresses before executing. It takes longer to boot than vxWorks_rom but takes up less space than other ROM-based images (nearly half the size). The run-time execution is the same speed as vxWorks_rom.

vxWorks_romResident

A ROM-resident image. Only the data segment is copied to RAM on startup. It has the fastest startup time and uses the smallest amount of RAM. Typically, however, it runs slower than the other ROM images because ROM access is slower.

	NOTE: Project files used only for a ROM-based image can flagged as such, so that they are only used when a ROM-based image is built. See Compiler Options.

VxWorks projects are built in the same manner as downloadable applications. To build a project with the default options, select the name of the project (or any subordinate object in its folder) and then select the Build option from the context menu. The name of the build specification that will be used is displayed in the Build Spec drop-down list at the top of the workspace window.

See 4.2.4 Building a Downloadable Application for more information about a generic build, and 4.5 Working With Build Specifications for information about modifying builds and creating new build configurations.

	NOTE: All source files in a project are built using a single build specification (which includes a specific set of makefile, compiler, and linker options) at a time. If some of your source requires a different build specification from the rest, you can create a project for it in the same workspace, and customize the build specification for those files. One project's build specification can then be modified to link in the output from the other project. See Linker Options.

	WARNING: The default compiler options include -g for debugging information. Using -g with the optimization option -O set to anything but zero may produce unexpected results. See 4.5 Working With Build Specifications for information about modifying builds and creating new build configurations.

For information about booting VxWorks (and bootable applications) see 2.6 Booting VxWorks. VxWorks images for the target simulator can be downloaded and booted with the context-menu Start command.

1:  You can modify the default behavior by un-checking the Show this window on startup box at the bottom of the window.