Documentation Guide

Documentation for Tornado falls into the following general categories:

Release Information.  

The Tornado Release Notes describe changes in the current release, and supported platforms. The files README.TXT and README.HTML at the root of the CD-ROM, contain last-minute information about the current Tornado release. In addition, the Release Bulletin at URL http://www.wrs.com/corporate/support/prodbullet/T2.0 contains several text files that contain pertinent information. PROBLEMS.TXT lists known problems for this release and FIXED.TXT lists problems fixed since the last release.

Tornado Host-Tool Documentation.  

These manuals focus principally on the interactive cross-development tools in Tornado. The Tornado Getting Started Guide provides instructions on installing Tornado, and a tutorial introduction. The Tornado User's Guide (this manual) describes the Tornado development tools and how they are used with the target system. The Tornado API Guide and the Tornado API Reference describe the interfaces available to extend this development environment.

VxWorks Target-OS Documentation.  

These manuals describe the VxWorks operating system and associated run-time facilities. The VxWorks Programmer's Guide is a comprehensive introduction to VxWorks, with the exception of networking, which is covered separately in the VxWorks Network Programmer's Guide. The VxWorks Reference Manual contains reference entries for all VxWorks modules and subroutines.

Online Documentation.  

All Tornado manuals are available online in HTML format, including Board Support Package (BSP)¹ setup information for VxWorks on that target.

Free Software Foundation Documentation.  

These supporting manuals are redistributed by Wind River Systems to provide auxiliary reference information on the compiler, debugger, and associated utilities supplied with Tornado. The GNU ToolKit User's Guide contains detailed information about the compiler, and its supporting tools. GNU Make describes makefiles and make usage. Debugging with GDB describes the command-line interface to the Tornado debugger.

Tornado Release Notes

The Tornado Release Notes is a brief document primarily meant for developers who are already using Tornado and VxWorks. It contains the latest list of supported hosts and targets, as well as information on compatibility with older releases and an outline of new features.

Readme File

The README.TXT file, found at http://www.wrs.com/corporate/support/prodbullet/T2.0, contains information about the current Tornado release that was developed after the Tornado Release Notes were completed.

Problem Lists

http://www.wrs.com/corporate/support/prodbullet/T2.0 contains two files of problem lists, FIXED.TXT and PROBLEMS.TXT. Both are plain text files located at the root directory of the CD-ROM.

FIXED.TXT

For each WRS product on the CD-ROM, describes the problems fixed since that product's previous release.

PROBLEMS.TXT

Describes all known problems with WRS products on the CD-ROM at the time of release.

Tornado Getting Started Guide

The Tornado Getting Started Guide provides instructions on installing Tornado (and other products), as well as a tutorial introduction to Tornado.

Tornado User's Guide

This manual, the Tornado User's Guide, is the central document for the Tornado IDE. It includes:

• A global overview of Tornado and its capabilities.

• Instructions on how to configure your environment and set up communications with a target system.

• Chapters on the Tornado development environment and its major interactive features-- the launcher, project facility, shell, browser, and the debugger.

• Appendices on Tornado directories and files, the use of Tcl (Tool Command Language) in Tornado, and reference information for host tools.

• Tcl-customization sections. Many chapters in the Tornado User's Guide contain suggestions about how to customize the Tornado tools using Tcl. These discussions are segregated into separate sections so that readers unfamiliar with Tcl can skip them. Titles for these sections always begin with "Tcl:" to indicate the special focus.

Tornado API Programmer's Guide

The Tornado API Programmer's Guide is for developers who wish to extend the Tornado development environment. It discusses the Tornado architecture from the perspective of software application program interfaces (APIs) and protocols, and describes how to extend and modify the Tornado tools and integrate them with custom software. It contains descriptive information about the run-time target agent; on its host-system counterpart, the target server; and on the WTX protocol used by the Tornado tools to communicate with the target server.

Tornado API Reference

The Tornado API Reference is the reference companion to the Tornado API Programmer's Guide. It is available online only (in HTML format).

VxWorks Programmer's Guide

The VxWorks Programmer's Guide describes the VxWorks operating system and associated run-time facilities. The Programmer's Guide is the best starting point to learn about VxWorks from a problem-solving perspective, because it is organized by the function of VxWorks components. It includes the following topics:

• Basic OS: the fundamentals of the VxWorks kernel and run-time environment.

• I/O System: the VxWorks I/O system and the device drivers that underlie it.

• Local File Systems: VxWorks file systems, including a DOS-compatible file system, the "raw" file system, and the RT-11 file system.

• Optional Products: VxWorks optional products VxMP (shared memory objects), VxVMI (virtual memory interface), and the Wind Foundation Classes (C++ libraries).

• Configuration and build: how to configure VxWorks for your application by editing configuration files and how to build it from the command line. (The Tornado User's Guide: Projects discusses the automated features provided by the project facility GUI.

• Architecture Appendices: special considerations for each supported target-CPU architecture.

VxWorks Network Programmer's Guide

The VxWorks Network Programmer's Guide describes the networking facilities available with VxWorks. It includes the following topics:

• Configuring the network stack.

• Booting over the network.

• Using the MUX interface.

• Upgrading 4.3 BSD drivers.

• Appendices: Libraries and subroutine references.

VxWorks Reference Manual

The VxWorks Reference Manual consists of reference entries divided into the following sections:

Libraries (1).  

Reference descriptions of all VxWorks libraries that apply to all targets. Each entry lists the routines found in a given library, including a one-line synopsis of each, along with a general description of their use. This section also contains entries for the serial, Ethernet, and SCSI drivers available with VxWorks Board Support Packages (BSPs).

Subroutines (2).  

Reference descriptions for each of the subroutines found in the libraries in Libraries (1).

Online Manuals

The Tornado software suite includes a hypertext collection of all Tornado and VxWorks manuals (in HTML format). You can open the online manuals from the Help>Manuals contents menu. A search tool is available from the Help>Manuals index menu option.

Board Support Package (BSP) Documentation

The online manuals contain reference entries for the libraries and subroutines specific to each BSP. These entries include a target information entry, which covers such topics as: what drivers the board uses; how the board should be jumpered for use with VxWorks; the board layout, indicating the location of board jumpers (if applicable) and ROM sockets; and any other board-specific considerations. See Help>Manuals contents>BSP Reference (wind/docs/BSP_Reference.html).

Check with your sales representative for a current list of supported BSPs.

Context-Sensitive Help

Help buttons in every Tornado dialog box (and the Help menu in the menu bar) provide information on the Tornado component you are currently executing.

These manuals are Free Software Foundation (FSF) manuals formatted and edited by Cygnus Support. They have been further edited to remove information that is not relevant to Wind River Systems' products, and assembled into a the three volumes, by Wind River Systems.

GNU ToolKit User's Guide

The Gnu ToolKit User's Guide is a convenient collection of the manuals for the GNU C and C++ compiler and its supporting tools: the C preprocessor, assembler, static linker and binary utilities.

GNU Make

The Free Software Foundation's manual for the make utility.

Debugging with GDB

The Free Software Foundation's manual for the command-line interface to the GNU debugger GDB, which is the foundation of the Tornado graphical debugger, CrossWind.

Cross-References

In the Tornado guides, cross-references to a reference entry or to a manual entry for a specified tool or module refer to an entry in the VxWorks Reference Manual (for target libraries or subroutines), to the reference appendix in the Tornado User's Guide (for host tools), or to their corresponding online versions.

Other cross-references between books take the form Book Title: Chapter Name.

Path Names

In general, this manual refers to Tornado directories and files with relative path names starting at the directory wind. However, nothing in Tornado assumes or requires this particular path name. Use the path name chosen on your system for Tornado installation.

Screen Displays

The screen displays in this book are for illustrative purposes. They may not correspond exactly to the Tornado environment you see on your computer, because both Tornado and the UNIX environment in which it runs can be customized. Tornado is also designed to permit easy integration with added tools.

Tcl

The Tornado tools make extensive use of Tcl, which allows a great degree of customization. However, it is not necessary to know Tcl in order to use the tools. Section titles in this manual that begin with Tcl: are of interest only to readers who may want to use Tcl to change some aspect of the tool's behavior, and can safely be skipped by other readers. See B. Tcl.

Typographical Conventions

Tornado manuals use the font conventions in the following table for special elements. Subroutine names always include parentheses, as in printf( ). Combinations of keys that must be pressed simultaneously are shown with a + linking the keys. For example, CTRL+C means to press the key labeled CTRL and the key labeled C.

Term		Example
files, path names		/etc/hosts
libraries, drivers		memLib.c
UNIX shell tools		xsym
Tcl procedures		wtxMemRead
subroutines		semTake( )
VxWorks boot commands		p
code display		main ();
keyboard input display		wtxregd -V
output display		value = 0
user-supplied values		name
constants		INCLUDE_NFS
keywords		struct
named key on keyboard		RETURN
key combinations		CTRL+C
lower-case acronyms		fd
GUI titles and commands		Help
series of GUI options to be selected		Tools>Target Server>Configure

1:  A BSP is a component of VxWorks that is specific to a given target.