Tornado

2.2
G E T T I N G S TA RT E D G U I D E

UNIX VERSION
Copyright  2002 Wind River Systems, Inc.
ALL RIGHTS RESERVED. No part of this publication may be copied in any form, by photocopy,
microfilm, retrieval system, or by any other means now known or hereafter invented without the prior
written permission of Wind River Systems, Inc.
AutoCode, Embedded Internet, Epilogue, ESp, FastJ, IxWorks, MATRIXX, pRISM, pRISM+, pSOS,
RouterWare, Tornado, VxWorks, wind, WindNavigator, Wind River Systems, WinRouter, and Xmath are
registered trademarks or service marks of Wind River Systems, Inc.
Attaché Plus, BetterState, Doctor Design, Embedded Desktop, Emissary, Envoy, How Smart Things Think,
HTMLWorks, MotorWorks, OSEKWorks, Personal JWorks, pSOS+, pSOSim, pSOSystem, SingleStep,
SNiFF+, VxDCOM, VxFusion, VxMP, VxSim, VxVMI, Wind Foundation Classes, WindC++, WindManage,
WindNet, Wind River, WindSurf, and WindView are trademarks or service marks of Wind River Systems,
Inc. This is a partial list. For a complete list of Wind River trademarks and service marks, see the following
URL:
http://www.windriver.com/corporate/html/trademark.html
Use of the above marks without the express written permission of Wind River Systems, Inc. is prohibited.
All other trademarks mentioned herein are the property of their respective owners.

Corporate Headquarters
Wind River Systems, Inc.
500 Wind River Way
Alameda, CA 94501-1153
U.S.A.

toll free (U.S.): 800/545-WIND

telephone: 510/748-4100
facsimile: 510/749-2010

For additional contact information, please visit the Wind River URL:
http://www.windriver.com
For information on how to contact Customer Support, please visit the following URL:
http://www.windriver.com/support

Tornado Getting Started Guide UNIX Version, 2.2

31 Jul 02
Part #: DOC-14209-2D-01
 Contents

Documentation Guide .............................................................................................. vii

Introduction ........................................................................................ vii
Release and Migration Information ................................................ vii
Tornado IDE and Tools ...................................................................... viii
VxWorks Operating System ............................................................. ix
GNU Compiler and Tools ................................................................. xi
Diab C/C++ Compiler and Tools .................................................... xii
Online Documentation ...................................................................... xii
Documentation Conventions ........................................................... xiii

1 Overview ................................................................................................................... 1

1.1 Introduction ...................................................................................................... 1

1.2 Terminology and Conventions ....................................................................... 2

2 Installing Tornado .................................................................................................... 3

2.1 Introduction ...................................................................................................... 3

2.2 Before You Start ................................................................................................ 4

Licensing ............................................................................................. 4
Installing with Previous Versions of Tornado ................................ 5
Obtaining the Installation Keys ....................................................... 5

iii
 Tornado 2.2
Getting Started Guide

2.3 Product Installation Procedure ...................................................................... 5

2.3.1 Preliminary Installation Steps .......................................................... 5
2.3.2 Installing Tornado ............................................................................. 7
2.3.3 Obtaining a Tornado License ........................................................... 11
Obtaining a Floating License ........................................................... 12
Obtaining a Node-Locked License .................................................. 15

2.4 Uninstalling Tornado 2.2 ................................................................................. 20

2.5 Administering License Management ............................................................ 21

2.5.1 Installing and Configuring a License Server ................................. 21
Automatic License File Installation ................................................. 23
Manual License File Installation ...................................................... 25
2.5.2 Managing Licenses ............................................................................ 28
Summary of Floating License Management .................................. 28
Starting and Stopping the License Server ...................................... 29

3 Tornado Tutorial ........................................................................................................ 31

3.1 Introduction ...................................................................................................... 31

3.2 Set Tornado Environment Variables .............................................................. 32

3.3 Start Tornado .................................................................................................... 33

3.4 Create a Project ................................................................................................. 34

3.5 Add the Sample Source File to the Project ................................................... 40

3.6 Build the Project ............................................................................................... 43

3.7 Start the VxWorks Target Simulator .............................................................. 46

3.8 Download the Project to the VxWorks Target Simulator ........................... 50

3.9 Run the Application from the Tornado Shell ............................................... 51

3.10 Examine Target Memory Consumption ....................................................... 53

iv
 Contents

3.11 Examine Task Activity ..................................................................................... 55

3.12 Fix Task Priorities and Find the Next Bug .................................................... 59

3.13 Fix the Last Bug and Take it for a Spin .......................................................... 63

3.14 What Next? ........................................................................................................ 68

v
Tornado 2.2
Getting Started Guide

vi
 Documentation Guide

Introduction

Documentation for Tornado falls into the following general categories:

■ release and migration information
■ Tornado IDE and tools
■ VxWorks operating system
■ GNU compiler and tools
■ Diab compiler and tools
Each of these categories is described in this chapter. Online documentation and
documentation conventions are also discussed.

Release and Migration Information

Tornado Release Notes

The Tornado Release Notes contain the latest list of supported hosts and targets, as
well as information on compatibility with older releases, an outline of new
features, and any caveats concerning the current release.

Tornado Migration Guide

The Tornado Migration Guide contains information designed to help VxWorks

developers in moving from Tornado 2.2.x and VxWorks 5.4.x to Tornado 2.2 and
VxWorks 5.5.

vii
 Tornado 2.2
Getting Started Guide

GNU Toolchain Release Notes

The GNU Toolchain Release Notes contain information about changes made to the
GNU toolchain since the Tornado 2.0 release.

Diab Release Notes

The Diab C/C++ Release Notes contain information about changes made to the Diab
compiler suite since the Diab 4.4 release.

Tornado Web Page

A Tornado 2.2/VxWorks 5.5 product information Web page is available at:

http://www.windriver.com/corporate/support/prodbullet/T2.2/

Tornado IDE and Tools

Tornado Getting Started Guide

The Tornado Getting Started Guide (this manual) provides instructions on installing
Tornado and other Tornado products, as well as tutorial introductions to both the
Tornado tools and VxWorks.

Tornado User’s Guide

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.
■ The Tornado development environment and its major interactive features—
simulator, editor, project facility, target server management, shell, browser,
and debugger.
■ Command-line tools for project creation and debugging.
■ COM and DCOM.
■ Customizing Tornado.
■ Tornado directories and files, the use of Tcl (Tool Command Language) in
Tornado, and reference information for host tools.
■ Wind River coding conventions.

viii
 Documentation Guide

Tornado API Programmer’s Guide

The Tornado API Programmer’s Guide is for developers who wish to extend the
Tornado development environment. It contains descriptive information about:
■ The run-time agent.
■ Its host-system counterpart, the target server.
■ The WDB protocol that supports the target agent and target server.
■ The WTX C and Tcl protocols used by the Tornado tools to communicate with
the target server.
■ Client Component Architecture (CCA), which is the new architecture of the
Tornado IDE.

Tornado API Reference

The Tornado API Reference is the reference companion to the Tornado API
Programmer’s Guide.

Tornado Reference

The Tornado Reference describes the host tools and utilities.

Tornado SETUP Developer’s Guide

The Tornado SETUP Developer’s Guide provides instructions for creating an

installation image that can install products on top of Tornado.

WindView User’s Guide

The WindView User’s Guide describes the features and use of the WindView
software logic analyzer, which is integrated with the Tornado IDE. The companion
WindView User’s Reference, describes WindView and networking events.

VxWorks Operating System

VxWorks Programmer’s Guide

The VxWorks Programmer’s Guide describes the VxWorks operating system and
associated run-time facilities. This guide is the best starting point for learning
about VxWorks from a problem-solving perspective because it is organized by the
function of VxWorks components. It includes the following topics:
■ The fundamentals of the VxWorks kernel and run-time environment.

ix
 Tornado 2.2
Getting Started Guide

■ The I/O system and the device drivers that underlie it.
■ Local file systems, including the DOS-compatible file system and the CD-ROM
file system.
■ POSIX standard interfaces, which are real-time extensions to the VxWorks
kernel facilities.
■ Target tools, which include the target-resident shell, loader, and symbol tables;
as well as VxWorks show routines.
■ C++ development, with guidelines for creating VxWorks applications in C++
and configuring VxWorks to support them.
■ TrueFFs, a flash memory interface, which provides a block device interface to
a wide variety of flash-memory devices.
■ Configuring and writing COM and DCOM applications for VxWorks.
■ VxMP, which provides shared-memory objects dedicated to high-speed
synchronization and communication between tasks running on separate
CPUs.
■ VxFusion, a lightweight, media-independent mechanism, based on VxWorks
message queues, for developing distributed applications.
■ VxVMI, a virtual memory interface, which provides write protection and an
architecture-dependent interface to the CPU’s MMU.

VxWorks Architecture Supplements

The VxWorks architecture supplements provide additional information specific to

target architectures.1

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.
■ Network configuration protocols.
■ Dynamic routing protocols.
■ Networking APIs.
■ Booting over the network.

1. For example, VxWorks for PowerPC Architecture Supplement.

x
 Documentation Guide

■ Creating a new data link layer driver or network service.

NOTE: If you have installed Tornado with the default networking component, the
networking guide is titled VxWorks Network Programmer's Guide. If you have
installed an optional networking product, the title is slightly different.

VxWorks API References

The VxWorks OS Libraries API Reference and the VxWorks Drivers API Reference
include 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.
In addition to HTML and print formats, the API references are available in
UNIX-style man pages. For details on using man with VxWorks documentation,
see Man Pages, p.xii.

VxWorks BSP Reference

The VxWorks BSP Reference consists of reference descriptions for BSP-specific

libraries and routines for all installed BSPs. This section also contains entries for
the serial, Ethernet, and SCSI drivers available with VxWorks Board Support
Packages (BSPs).

VxWorks Errno Code List

The VxWorks Errno Code List provides a description of VxWorks errno codes, by
number, by routine name, and alphabetically.

VxWorks BSP Developer’s Guide

The VxWorks BSP Developer’s Guide provides instructions on creating,

documenting, and testing new BSPs, components, and projects.

GNU Compiler and Tools

The GNU ToolKit User’s Guide is a convenient collection of manuals for the GNU C
and C++ compiler and its supporting tools: the C preprocessor, assembler, static
linker, and binary utilities. Specific versions are provided for each architecture
family. The GNU Make User’s Guide is the Free Software Foundation’s (FSF) manual
for the make utility. The GDB User’s Guide is the FSF manual for the command-line
interface to the GNU debugger GDB, which is the foundation for the Tornado
graphical debugger, CrossWind.

xi
 Tornado 2.2
Getting Started Guide

NOTE: The FSF develops software under UNIX, and examples in their manuals
reflect this. Nevertheless, the GNU tools operate reliably under Windows.

Diab C/C++ Compiler and Tools

The Diab C/C++ Compiler Guide describes the tools in the Diab C/C++ Optimizing
Compiler Suites, including the compilers, assembler, linker, and utilities. The Diab
suite is provided as the standard compiler for ColdFire, and is available for other
architectures as an optional product.

Online Documentation

Online Manuals

Tornado includes a collection of all Tornado and VxWorks manuals in HTML

format. You can open the online manuals from the Help>Manuals Contents menu in
the Tornado IDE or at installDir/docs/books.html. An index and full-text search are
available.

Online Help

Help buttons in every Tornado dialog box and the Help menu on the menu bar
provide information on the Tornado component you are currently executing. In
addition, from the shell, you can hot-key to the reference entry for the VxWorks
routine you have entered.

Man Pages

UNIX-style man pages for API reference entries are available for Solaris hosts. The
most convenient way to access these pages is to create an alias for man -M such as
vxman:
alias vxman 'man -M installDir/man'

You can then display entries, such as the one for printf( ), from a shell prompt as
follows:
% vman printf

xii
 Documentation Guide

PDF Documents

PDF versions of most books in the standard Tornado documentation set, as well as
the Diab compiler guides, are provided in installDir/SETUP/DOCS. They are also
available in the DOCS directory at the base of the Tornado core product CD.

Documentation Conventions

Cross-References

In the Tornado guides, cross-references to a reference entry for a specified tool or

module refer to an entry in the online VxWorks API Reference (for target libraries or
subroutines) or to the Tornado API Reference(for host tools).
Cross-references between books take the form Book Title: Chapter Name, and are not
linked in the HTML version.

Pathnames

In general, all manuals refer to Tornado directories and files with pathnames
starting at the installation directory installDir. Use the pathname chosen on your
system for Tornado installation. Your working directory is referred to as projDir.

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.

Command-Line Examples

Tornado allows you to execute most functions either from within the IDE or from
the command line. The command syntax is usually the same for Windows and
UNIX command lines. For this reason these documents use the following default
format for command lines:
% prjCreate

When a particular command syntax applies to UNIX only, this is stated. When a
command syntax applies to Windows only, or when the Windows version differs
from the UNIX version, the Windows format is as follows:
c:\> winFooRun param

xiii
 Tornado 2.2
Getting Started Guide

Typographical Conventions

Tornado manuals use the font conventions in the following table for special
elements. C 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+F3 means to simultaneously press the key
labeled CTRL and the key labeled F3.

Table 0-1 Typographical Conventions

Term Example

files, pathnames installDir/host

libraries, drivers memLib.c

Command-prompt tools dir

Tcl procedures wtxMemRead

C subroutines semTake( )

VxWorks boot commands p

code display main ();

keyboard input display [vxKernel] -> wtxregd -V

output display value = 0

user-supplied values name

components INCLUDE_NFS

keywords struct

named key on keyboard RETURN

key combinations ALT+SHIFT+F5

lower-case acronyms fd

GUI titles and commands Help

GUI menu path Tools>Target Server>Configure

references to other manuals VxWorks Programmer’s Guide: Basic OS

xiv
 1
Overview

1.1 Introduction
Thank you for purchasing Tornado!
Tornado 2.2 provides a greater level of accessibility for users unfamiliar with
Tornado, and increased productivity for experienced developers. Key features of
this release are:
■ the integrated version of the VxWorks target simulator (VxSim) introduced in
Tornado 2.0
■ the integrated version of the WindView logic analyzer for the target simulator
introduced in Tornado 2.0
■ an improved project facility
■ a new debugger engine
The target simulator allows you to experience Tornado — as well as begin
developing hardware-independent modules — without target hardware. The
integrated version of WindView provides dynamic visualization of application
behavior on the simulator. The new project facility provides automated graphical
features for managing project files, configuring VxWorks, and building
applications. The new debugger GUI is easier to use and provides more direct
access to debug information.
This guide describes how to install Tornado and other compatible products. It also
provides a simple tutorial that demonstrates the use of the project facility, the
integrated versions of the target simulator and WindView, and the Tornado
debugger. The tutorial is designed to provide new users with an accessible
introduction to the key features of Tornado and their use in application

1
 Tornado 2.2
Getting Started Guide

development. It is also intended to provide experienced Tornado users with an

introduction to major innovations in the development environment.

NOTE: The integrated target simulator (VxSim-Lite) runs as a single instance per
user, without networking support. Optional products such as SNMP and other
network products are not available for this version. The full-scale version of the
simulator, VxSim, is available as an optional product. It supports multiple-instance
use, networking, and other optional products.

The integrated version of WindView is designed solely for use with the VxWorks
target simulator. WindView is available as an optional product for all supported
target architectures.

1.2 Terminology and Conventions

The following terms are used in this document:
host
A computer on which the Tornado development tools run.
target
A processor board that runs VxWorks (Tornado’s real-time operating system)
and applications developed with Tornado.
target server
A service that runs on the host and manages communications between host
tools (such as the Tornado shell, debugger, and browser), and the target system
itself. One target server is required for each target.
Tornado registry
A Tornado service that keeps track of, and provides access to, target servers.
One registry may serve a network, or registries may run on each Tornado host.
The following conventions are used in this document:
■ The root installation directory is identified as installDir in this document, but
the environment variable WIND_BASE must be set to the root installation
directory for Tornado to work.
■ A series of items to be selected from the GUI is denoted by A>B>C. The
elements A, B, and C may be menu items, buttons, or tabs.

2
 2
Installing Tornado

2.1 Introduction
This chapter provides step-by-step instructions for installing Tornado 2.2 and
obtaining a license. It also tells a system administrator how to set up a floating
license server and how to manage the server. This information is also available as
online help for SETUP.
For a floating license installation, license server software must be installed and
running on a host on your network before Tornado can run. A system administrator
should install the license server software on a host designated for that purpose,
using the same SETUP program that installs Tornado. System administrators
installing the floating license server should refer to 2.5.1 Installing and Configuring
a License Server, p.21 for step-by-step instructions.
If you are going to use a node-locked license, you will do the required
configuration when you obtain the license as the final step of installation.
Installing Tornado 2.2 involves:
(1) Setting up your Solaris workstation with the correct patches.
(2) Locating the installation keys. You will be installing from the Tornado core CD
and from a BSP CD. Each has its own key.
(3) Selecting a user account to use for installation.
(4) Running the SETUP program. SETUP can be used to install either Tornado 2.2
or the floating license server. The program requires an installation key and
some other information about your host.

3
 Tornado 2.2
Getting Started Guide

(5) Configuring Tornado to obtain a license, which may include some manual
steps after the SETUP program completes. An optional authorization code may
also be required for some installations.

NOTE: The installation instructions in this section also apply to any

Tornado-compatible Wind River product that you have purchased separately.
Optional products should be installed in the same directory tree as the version of
Tornado for which they have been released.

2.2 Before You Start

If you are a system administrator installing license management on a server, go to
2.5.1 Installing and Configuring a License Server, p.21.
If you are installing Tornado 2.2 on your own machine, be sure you are installing
on a supported host that meets minimum system requirements for both hardware
and software, including patch levels. See the Tornado Release Notes for information
about minimum system requirements and about using Tornado 2.2 in combination
with other Wind River products.

Licensing

Tornado 2.2 and some optional components require a license. If you are installing
on a host with access to the Internet, the setup and installation program obtains the
license for you; but before you start SETUP you should know:
■ Whether the software you are installing requires a license. (Tornado 2.2
requires a license; some optional components do not.)
■ If a license is required, what kind to use: floating or node-locked. (Refer to your
purchase order.)
■ If you will use a floating license, whether a floating license server is installed
on a host in your network.
■ If your system is running in 32-bit mode. (Tornado 2.2 runs only in 32-bit
mode.)

4
 2
Installing Tornado

If you do not know the answers to these questions, check with your system
administrator.
2

Installing with Previous Versions of Tornado

If you plan to install Tornado 2.2 on a host that has another version of Tornado
installed, see the Tornado Release Notes for information about correctly installing
alongside your current version. You can never install a new Tornado in an existing
Tornado tree.

NOTE: If you plan to install Tornado 2.2 on a system that has the Beta version
already installed, you must first uninstall the Beta version.

Obtaining the Installation Keys

If you have purchased Tornado, your installation keys are printed on the
Installation Keys sheet in the Getting Started portfolio that includes the Tornado 2.2
CD-ROM and this guide.
If you cannot find the installation keys, contact Wind River by e-mail at
[email protected]. Please include your sales order number if you have
purchased Tornado.
You can also call 800/545–WIND (800/545–9463) if you are in North America and
ask for Key Administration. In other locations, contact the nearest Wind River
office.

2.3 Product Installation Procedure

2.3.1 Preliminary Installation Steps

Step 1: Start the SETUP Program

Insert one of the Tornado 2.2 CD-ROMs in the drive. Install the Core CD first,
followed by the BSP/driver CD.

5
 Tornado 2.2
Getting Started Guide

The SETUP program has online help that provides detailed information about the
installation and license configuration process. Click on the Help button to access
help from any dialog where the button is enabled (starting with the User
Registration page).

Each SETUP dialog box also has a Cancel button, which you can use to exit from the
installation program. To continue to the next box, click the Next button. To return
to the previous box to review or change information you have entered, click the
Back button (which is grayed-out if it cannot be used).

Run SETUP manually from the command prompt. The Welcome dialog box
appears. To continue, click Next.

Step 2: Review the Readme Information

The README.TXT window appears next. When you have finished reviewing the
information contained in the window, click Next.

Step 3: Review the License Agreement

Read the license agreement. If you agree with its conditions, click I Accept and Next
to proceed with installation.

Step 4: Enter User Information and Installation Key

In the User Registration dialog, enter the primary user name, your company name,
and the installation key.

NOTE: Enter the key exactly as it appears on the Installation Keys sheet. The key
is case sensitive, and all characters must be entered, including non-alphanumeric
characters.

If you have already installed other products from the same CD-ROM, you can
select the installation key from the drop-down list. Otherwise, copy it from the
Installation Keys sheet.

NOTE: The two CD-ROMs associated with Tornado 2.2 require different keys. Both
are on the Installation Keys sheet.

To continue, click Next.

6
 2
Installing Tornado

Step 5: Choose the Type of Installation

In the Installation Options dialog, choose one of the following:
2
■ Full Installation. Choose this option to install a complete version of Tornado 2.2
for an end user on the local host. Click Next to continue. (This is the option most
users will use.)
■
License Management Server Installation. This option installs and configures a
floating license server on the local host. The floating license server manages a
pool of licenses for use by installations on other hosts in a network. System
administrators installing a floating license server should select this option and
click Next to continue. See 2.5.1 Installing and Configuring a License Server, p.21,
then follow the steps listed there.

NOTE: A license server must be installed and available on a network before

Tornado 2.2 can be configured to use floating licenses. Before you install Tornado
and attempt to configure it to use a floating license, you should ensure a license
server has been installed.

To continue, click Next.

Step 6: Enter the Project Information

The license number and number of seats is shown on the Tornado Installation Keys
form that shipped with your product. Enter this information and click Next.

2.3.2 Installing Tornado

Step 7: Specify the Installation Directory

Tornado 2.2 and its related products are designed to be installed in a single
directory tree. Specify the base directory for that tree in the Select Directory dialog
box, for example, /usr/bob/tornado2.2.

! WARNING: Do not install Tornado 2.2 in the same directory as any prior
installation of Tornado, or in the same directory as versions of Tornado for other
target operating systems (such as Tornado for I2O). Unpredictable behavior may
result. For more information about installing Tornado 2.2 alongside existing
installations of Tornado, refer to the Tornado 2.2 Release Notes.

7
 Tornado 2.2
Getting Started Guide

You can use the Browse button to display a file browser for locating and choosing
the installation directory. If the directory you specify does not exist, you will be
prompted to create it.
To continue, click Next.

Step 8: Review the Product List for Installation

All of the products you ordered are marked as selected in the Select Products dialog
box by a check in the box to the left of the product name. Each item in the list
represents a single product. To include or omit a product, click the checkbox next
to the product name.

The line at the bottom indicates how many components comprise the selected
product. If you highlight a product by clicking on it, the line at the bottom displays
how many components within that product are selected. For example, in the Select
Products dialog box, if Tornado Tools: Solaris x ppc is highlighted, the dialog shows 3
out of 5 components are selected. To see a list of the individual components for a
product, click the Details button. See Selecting Parts, p.9 for more information.

8
 2
Installing Tornado

A Tornado 2.2 installation requires the following minimum components:

■ Tornado tools for the host system 2
■ target processor and family
■ driver objects and headers for the selected target (These are on your second,
BSP/driver CD-ROM.)
By default, these components are chosen for installation. This ensures that the
necessary base product is installed, and that other products will install successfully
later. This is especially important when:
■ Your installation key covers more than one product, or multiple run-time
components such as TrueFFS or individual BSPs, and you choose to install
them separately.
■ You have more than one installation key covering different products.
■ You have separate CD-ROMs containing add-on products.
Click Next to continue.
If there is not enough space for the selected products, SETUP warns you and gives
you the option of going back to specify a directory on a larger disk or partition. You
can also go back and omit some products. Click Go Back to return to the Select
Directory dialog box, or No to continue. If you click No and continue, you will be
prompted later to free up disk space.

NOTE: Some components rely on other components. If you select one component
without also selecting others it relies on, the SETUP program warns you and may
require you to go back and change your selections before continuing to the next step.

Click Next to continue.

■ Selecting Parts

If a product has more than one part, clicking Details opens the Select Parts
dialog, which displays all the parts in a list. You can modify the default
selection of parts using this list. Check or uncheck the boxes to the left of the
names.

9
 Tornado 2.2
Getting Started Guide

This dialog also displays the approximate amount of disk space required for
the selected parts.

Click OK to accept any changes you make to the list of parts, or Cancel to ignore
any changes.

Step 9: Set File Permissions

Specify the file system permissions for the installation. When SETUP copies the
files from the CD-ROM to the host system, it assigns these permissions to the files
and directories it creates.

NOTE: These permissions do not apply to files and directories Tornado 2.2 creates
after it is installed. The umask of the user running Tornado 2.2 determines the
permissions assigned to them.

Click Next to continue.

Step 10: Remote Tornado Registry

If the Tornado registry will be installed on another machine, change localhost to
the name of the remote host and click Next.

10
 2
Installing Tornado

Step 11: Backward Compatibility

If you are going to use Tornado 1.0.1 and Tornado 2.2 tools in the same
2
development environment, you must select yes in the Backward Compatibility dialog
box. See the Tornado Release Notes for information about mixed-release
development environments and portmapper usage.

Step 12: SETUP Installs Files

SETUP begins to copy files from the CD-ROM. As installation progresses, the
program displays information about the product as well as the names of the files
being installed. The process may take several minutes.
When SETUP has finished copying files, a dialog confirms installation of the
products you selected for Tornado 2.2. You still need to install one or more BSPs
from the second installation CD-ROM you received; but first, complete license
manager installation. Click OK to close the dialog.
Next, SETUP configures Tornado 2.2 to reserve a license.

2.3.3 Obtaining a Tornado License

If the product you have installed (such as Tornado 2.2) requires a license, the
SETUP program presents additional dialogs to select the type of license and to
obtain one for use.

11
 Tornado 2.2
Getting Started Guide

Step 13: Choosing a Licensing Method

Tornado 2.2 obtains a license using one of two methods. In the License Management
Configuration dialog, you choose the method for your installation to use. If you are
unsure of which one to use, ask your system administrator or refer to your
purchase order.
Configure a Floating License
Choose this method to reserve a license from a pool of shared licenses every
time you run Tornado 2.2. When you exit Tornado 2.2, the license is released
for other installations to use.

NOTE: A license server must be installed and available on your network before
Tornado 2.2 can be configured to use floating licenses. Before you install
Tornado 2.2 and attempt to configure it to use a floating license, you should first
ensure that a license server has been installed. See 2.5.1 Installing and Configuring a
License Server, p.21 for more information.

Configure a Node-Locked License

Choose this method to obtain a license and reserve it for use only on this
computer. Laptop computers that are often disconnected from the local
network (and therefore cannot connect to a floating license server) should use
this method. The license is contained in a file stored in the local installation,
and the installation uses it exclusively thereafter.
Recapture license previously configured for this machine
If a node-locked license for Tornado 2.2 was previously reserved for the host,
and you want to configure the present installation to reuse that license, then
check the box.
Choose an option and click Next to continue
To proceed with the floating license option for typical end users, see Obtaining a
Floating License, p.12. Otherwise, see Obtaining a Node-Locked License, p.15.

Obtaining a Floating License

This section describes the steps to configure Tornado 2.2 to obtain a floating license
from a license server on your network. For instructions on obtaining a node-locked
license, see Obtaining a Node-Locked License, p.15.

12
 2
Installing Tornado

NOTE: A license server must be installed and available on your network before
Tornado 2.2 can be configured to use floating licenses. Before you install 2
Tornado 2.2 and attempt to configure it to use a floating license, you should first
ensure that a license server has been installed. See 2.5.1 Installing and Configuring a
License Server, p.21 for more information.

1. Query the License Database

SETUP can automatically retrieve information from Wind River about the
licenses you have purchased. In the Database Query Permission dialog, you give
permission for SETUP to contact Wind River for this purpose. Your computer
must have an active connection to the Internet to complete this step.
Yes, contact Wind River web site
Select this option to retrieve the information automatically, then click Next.
SETUP transfers only the information necessary to configure a license for
Tornado 2.2, and no other data from your computer. See 2.Select License
Server(s), p.13 to continue.
No, do not contact the Wind River web site
If you select this option, the installation of Tornado 2.2 is complete but it has
not obtained a license. If you do not obtain your license now, there are two
ways to initiate license configuration later:
■ Start SETUP with the -L option.
■ Start Tornado. When you run any Tornado 2.2 tool that is under license
management, SETUP starts and steps you through obtaining a license.
Click Next to continue.

NOTE: In the Finish dialog that appears when you choose not to contact the Wind
River web site, SETUP displays information about manually configuring
Tornado 2.2 to use a floating license. Make a note of the instructions, then click Exit.

2. Select License Server(s)

The User License Management Configuration dialog displays the license servers
available on your network, from which Tornado 2.2 can request a floating
license.

13
Tornado 2.2
Getting Started Guide

Click one or more server names listed in Available Server(s). To add them to the
list of Selected Server(s) click on the button. Click on the button to
move them back. Use the Up and Down buttons to prioritize the selected
servers. Tornado 2.2 sends its request for a license to the server at the top of the
list first.

To see more information about an individual server and the licenses available
on it, click to highlight the server; then click the Details button while the server
name is highlighted.
No Servers Available
If no entries appear under Available Server(s), this means SETUP cannot
locate any license servers. Possible reasons for this and their solutions are:
– No license server is installed on an accessible host in your network; contact
your system administrator to have one installed.
– The license server is installed on an accessible host but is not active;
contact your system administrator to activate it.
– The host is not connected to the network; troubleshoot the connection. If
the machine is normally not connected to the network (for example, a
laptop), consider assigning a node-locked license. See Obtaining a
Node-Locked License, p.15.
Click Next to continue.

14
 2
Installing Tornado

3. Confirm License Servers

In the License Management Registration dialog you can review your choice of 2
license servers. Click Next to accept the choice, or Back to modify it. When you
click Next, SETUP displays the Finish dialog.
There is one more step to complete before you are done. See 4.Set Environment
Variables, p.26.

Obtaining a Node-Locked License

A node-locked license is a license reserved exclusively for a single Tornado 2.2

installation. The license is contained in a file stored locally during setup and
Tornado 2.2 uses it exclusively thereafter. This section describes the steps to follow
to reserve a node-locked license and to obtain the license file.

Choose a Method for Requesting the License File

In the License Management Installation Options dialog, select a method for SETUP to
contact Wind River and request the license file.

Automatic License Installation

Recommended because it is the quickest and easiest method, and when you
exit the SETUP program the license file is installed. This method requires an

15
 Tornado 2.2
Getting Started Guide

active Internet connection. See Automatic License Installation, p.16, if you

choose this method.
Manual License Installation
Choose one of the manual options (e-mail, phone, or fax) if the host is not
connected to the Internet, or if you are located behind a firewall or a proxy
server that prevents automatic installation from completing. When you
request a license file using one of these methods, the file is sent to you through
e-mail and you must install it manually. Click Next and see 3.Select Node-Locked
Licenses to Configure or Reload, p.17 to continue.
If the host has no Internet access and cannot send e-mail, a final option for
obtaining a license file is to visit the Wind River Web site using another computer
that does have network access. Visit http://www.windriver.com/ali and follow the
instructions there. Once you have the file, copy it to a diskette and transfer it to the
install host, as described in 3.Install the License File Manually, p.20.

Automatic License Installation

This section describes the steps to follow when requesting a node-locked license
using the Automatic License Installation option.
1. Query the License Database
In order to obtain the license file, SETUP automatically retrieves information
from Wind River about the licenses you have purchased. In the Database Query
Permission dialog, you give permission for SETUP to contact Wind River for
this purpose. Your computer must have an active connection to the Internet to
complete this step.
Yes, contact Wind River web site
Select this option to retrieve the information automatically. Before you click
Next, review the information that will be transferred. SETUP transfers only the
information necessary to configure a license, and no other data from your
computer.
You may wish to use your disk serial number as your host ID instead of using
your MAC address (the default). This option is recommended if you have a
laptop with multiple NIC cards and you switch between the cards. For more
information, see http://www.windriver.com/corporate/support/license.html.
Click Next to continue.
No, do not contact the Wind River Web Site

If you select this option, SETUP displays instructions for manually installing a
license file (see 3.Install the License File Manually, p.20). If you wish, you can

16
 2
Installing Tornado

return to the previous dialog, where you can choose one of the manual
methods of requesting the license file instead. See Choose a Method for
Requesting the License File, p.15. 2

2. Provide Contact Information/User Authorization

In the Contact Information/User Authorization dialog, enter contact information for
the person who coordinates license configuration and management at your
site. SETUP includes this information in the request for a license file.

staff

510-555-0000

[email protected]

Authorization Code
Your purchase agreement for Tornado 2.2 may have included a request for an
authorization code, used to restrict access to licenses. If so, this dialog is
labeled User Authorization and it includes a field for the code. You can find the
code on the Installation Keys sheet. You must enter the code before you can
request or reserve any licenses.
Click Next to continue.
3. Select Node-Locked Licenses to Configure or Reload
If you are requesting new licenses, the Node Locked License Configuration dialog
displays the number of licenses still available out of the total purchased.

17
 Tornado 2.2
Getting Started Guide

Select the licenses you want to reserve by checking the boxes next to the
product name. Each node-locked license you reserve in this dialog reduces the
number of licenses available for other Tornado 2.2 installations.

If you are reloading a license that was previously assigned to this host, the
Reload Existing License dialog appears instead. This dialog displays
information about the license(s) to be restored. You can review this
information, but you cannot alter it.
When you have selected new licenses to reserve, or reviewed the licenses to be
restored, click Next to continue and proceed with 4.Review License Management
Summary, p.20.

Manual License Installation

This section describes the steps to follow when requesting a node-locked license
using one of the manual methods.
1. Select Products to License
The Email License Configuration dialog or the Phone/Fax License Configuration
dialog appears, depending on the manual method you have chosen. The
following image shows the Phone/Fax dialog, but the contents of the two
dialogs are the same for both methods. The dialog displays the products you
have installed and for which you can request a node-locked license. Select the

18
 2
Installing Tornado

licenses you want to reserve by checking the appropriate boxes next to the
product names.
2

Click Next to continue.

2. Request the License
Next, you must provide information gathered by SETUP to Wind River. After
Wind River has the information, you will receive the license file through
e-mail.
■ Request the License File by E-mail
To use this method, the host must have network access to a mail server.
(a) SETUP inserts all the necessary information into an e-mail message that
you can preview in the Email License dialog. When you have viewed the
message, click Next to continue.
(b) In the Mail Confirmation dialog, enter the e-mail address where you want the
license file to be sent. Select a mail protocol and enter the name of the mail
server to use.
(c) Click Send in the Mail Confirmation dialog. The request is sent from the
current host to [email protected].
(d) See 3.Install the License File Manually, p.20.
■ Request the License File by Phone

19
 Tornado 2.2
Getting Started Guide

(a) SETUP copies all the necessary information into a file that you can preview
in the Contact Wind River dialog and print for your reference.
(b) Call Wind River at the number listed on the dialog and give the
information to the license representative.
(c) Click on Finish to exit the SETUP program.
(d) See 3.Install the License File Manually, p.20.
3. Install the License File Manually
When you receive the license file WRSLicense.lic, do not alter its contents or
change the file name. Copy it to the directory installDir/.wind/license, where
installDir is the directory in which Tornado 2.2 is installed.
4. Review License Management Summary
The Summary dialog shows the license(s) or server(s) you have configured for
this installation. If the information is correct, click Next to accept the results. To
go back and change the configuration, click on Back or Cancel.
One final step is necessary for certain installations. On a UNIX host, you need
to set some host environment variables. See 4.Set Environment Variables, p.26.
Then, you are done installing Tornado 2.2 and configuring a license for it.
For an introductory tutorial on Tornado 2.2 usage, see 3. Tornado Tutorial.

2.4 Uninstalling Tornado 2.2

! WARNING: Before uninstalling Tornado 2.2, make copies of any Tornado files you
have modified. Uninstalling Tornado removes all files that were part of the original
distribution list.

To remove Tornado 2.2, first stop the Tornado registry by killing the wtxregd
process. Then type the following commands at the system prompt:
% cd installDir/setup
% UNINST installDir

The installDir directory is where Tornado 2.2 was installed.

If you plan to re-install Tornado 2.2 after uninstalling, remove the installDir/.wind
directory.

20
 2
Installing Tornado

2.5 Administering License Management

2
2.5.1 Installing and Configuring a License Server

This section describes the steps for installing and configuring a license server using
SETUP. If your site will use floating licenses, at least one license server must be in
place before Tornado 2.2 floating seats and licensed optional products can be used.
The license server manages a pool of floating licenses for use by Tornado 2.2
installations on other hosts on a shared network.
This section is relevant for system administrators who want to install the network
license server, and not for typical end users of Tornado 2.2. It is not part of standard
product installation, but must be completed before any licensed products can be
used with floating licenses.

NOTE: A license server must be installed and available on a network before

Tornado 2.2 can be used with the floating license option. Before users install
Tornado 2.2 and attempt to obtain a floating license, ensure that a license server is
installed.

Step 1: Run SETUP

The initial steps required for installing a license server are the same as 2.3 Product
Installation Procedure, p.5. Follow Step 1 through Step 6 first. When the Installation
Options dialog appears, select License Management Service Installation and click Next.

NOTE: To install only license management daemons and utilities files, you can
invoke SETUP with the -F or /F option. If you use -F or /F, SETUP takes you directly
to Step 2.

Step 2: Choose a Directory for License Management Utilities

SETUP asks you to confirm that this is the correct host on which to install the
license manager software before proceeding. If it is not, exit the program now.
Choose a local directory for the license management files. Click Next to continue.
If you wish to reinstall your existing license file without adding licenses or making
any other changes, check the box.

Step 3: Select Installation Method

The license manager requires a license file installed locally on the server machine.
The file is generated upon request by Wind River. In the License Management

21
Tornado 2.2
Getting Started Guide

Installation Options dialog, select a method for contacting Wind River to request the
license file.

Automatic License Installation

Recommended because it is the quickest and easiest method if you have an
active connection to the Internet. When you exit the SETUP program, the
license file is installed. If you choose this method, click Next and see Automatic
License File Installation, p.23.
Email option or the Phone or Fax option
Choose one of these manual options, if the host is not connected to the Internet
or if you are located behind a firewall. When you request a license file using
one of these methods, the file is sent to you through e-mail and you must
install it manually. Click Next and see 3.Install the WRSLicense.lic File Manually,
p.26 to continue.
If the host has no network access and cannot send e-mail, you can visit the Wind
River Web site using another computer that does have network access. Visit
http://www.windriver.com/ali and follow the instructions there. Once you have
the file, copy it to a medium such as a diskette and transfer it to the install host, as
described in 3.Install the WRSLicense.lic File Manually, p.26.

22
 2
Installing Tornado

Automatic License File Installation

This section describes the steps to follow when requesting a license file using the 2
Automatic License Installation option.

1. Query the License Database

SETUP can automatically retrieve information from Wind River about the
licenses you have purchased. If your computer has an active connection to the
Internet, you can give permission for SETUP to contact Wind River for this
purpose.
Yes, contact Wind River web site
Select this option to retrieve the information automatically, then click Next.
SETUP transfers only the information necessary to configure a license, and no
other data, from your computer. Click Next to continue.
No, do not contact the Wind River Web Site
If you select this option, SETUP returns to the previous dialog, where you can
choose one of the manual methods of requesting the license file instead.
2. Provide Contact Information/User Authorization
In the Contact Information/User Authorization dialog, enter contact information for
the person who coordinates license configuration and management at your
site. SETUP includes this information in the request for a license file.
Authorization Code
Your purchase agreement may have included a request for an Authorization
Code: a number used to restrict access to licenses. If so, this dialog is labeled
User Authorization and it includes a field for the code. You can find the code in
the Installation Keys sheet. You must enter the code before you can request or
reserve any licenses. Click Next to continue.
3. Choose a License Server Port
The license server receives requests for floating licenses on a dedicated port.
Use the License Server Port dialog to select the port the server will use. You can
accept the default of 27000, or choose an unused one numbered 1024 or higher.
Click Next to continue.
4. Specify Floating Licenses to Manage
The Floating License Configuration dialog lists the products for which you have
purchased licenses, the number of licenses (if any) that the current host is
managing, and how many licenses are available to claim. Enter the number of

23
 Tornado 2.2
Getting Started Guide

licenses for each product that you want the server to manage in its pool of
licenses.

If you are increasing the number of licenses for the server, then the numbers
you enter will reserve additional licenses.
In either case, the number that remains for other servers to claim is reduced
accordingly.

! WARNING: If you install more floating seats than appear on your purchase order,
Wind River will contact you to reconcile the difference. Please review your
purchase order before installing, to be sure that you install only as many licenses
as you have purchased or wish to purchase.

When you have made your selection, click Next to continue. The Summary:
Floating License dialog shows the total number of licenses you have configured
for the license server to manage. To accept the configuration, click OK. To go
back and change the configuration, click Cancel.
You need to set system variables manually for UNIX hosts. See 4.Set
Environment Variables, p.26 to continue.

24
 2
Installing Tornado

Manual License File Installation

This section describes the steps to follow when requesting the license file using one 2
of the manual methods.
1. Select Products to License

The Email License Configuration dialog or the Phone/Fax License Configuration

dialog appears, depending on the manual method you have chosen. The image
shows the e-mail dialog, but the contents of the dialogs are the same for both
methods. The dialog displays the products for which you can request a license
file. Indicate the number of licenses you want to reserve in the fields next to the
product names.
2. Manually Send the Request for a License File
To complete your request for the license file manually, you must provide the
following information in your request. SETUP collects the information in an
appropriate format for you to send to Wind River:
(a) host ID of the machine to be the license server
(b) host Name—the name of the license server host
(c) your customer license number
(d) number of licenses to be served for each licensed Wind River product (for
example, five licenses for Tornado 2.2 and three for WindView).
(e) contact information (name, address, phone, e-mail address).

25
 Tornado 2.2
Getting Started Guide

NOTE: The host ID is a number that the license manager software uses to uniquely
identify the host machine. SETUP determines this number for you automatically,
but you can also find it manually by issuing the command lmutil lmhostid from a
host command line in the installDir/SETUP/SUN4/SOLARIS2 directory.

■ Request the License File by E-mail

(a) All the necessary information is put in an e-mail message. You can
preview the message in the Email License dialog. Click Next to continue.
(b) In the Mail Confirmation dialog enter the e-mail address where you want the
license file to be sent. Select a mail protocol and the ID of the mail server
used by the host.
(c) Click Send. The request is sent from the current host to
[email protected], and an automated system receives it.
■ Request the License File by Phone
(a) All the necessary information is copied to a file. You can preview the file
in the Contact Wind River dialog and print it for your reference.
(b) When you call Wind River at the number listed on the dialog, have the
information available to provide to the representative.
(c) Click on Finish to exit the SETUP program.
3. Install the WRSLicense.lic File Manually
When you receive the license file WRSLicense.lic, do not alter its contents in
any way or change the file name. Copy it to the directory
installLic/.wind/license. The installLic directory is where license management
software is installed.

! CAUTION: In most cases you should not alter the file contents or its filename. If
you do wish to rename the license file, relocate the file to a path other than
installLic/.wind/license, or combine the contents of the license file with other
license files, please consult the user documentation from Globetrotter at
http://www.globetrotter.com.

4. Set Environment Variables

After you have copied the license file to its location, you must set host
environment variables. The Finish dialog displays instructions for the
remaining configuration steps you must complete manually. Those steps are
described here.
■ Floating License

26
 2
Installing Tornado

For Tornado 2.2 to use a floating license, the value of the environment variable
LM_LICENSE_FILE must contain information about the floating license
server(s) it uses. If LM_LICENSE_FILE already exists, then the information 2
should be appended to its current value.
When the SETUP program completes installation of Tornado 2.2, the Finish
dialog displays commands that you can use to set the variable to the
appropriate value. These commands are also saved in the file lmEnvVar.txt in
the installation directory.
Depending on the command shell you use, the command uses one of the
following formats. Add the appropriate format to your startup script in, for
example, .cshrc.
For csh:
setenv LM_LICENSE_FILE port@server

For bash, sh, or ksh:

LM_LICENSE_FILE=port@server
export LM_LICENSE_FILE

In these examples, server is the name of the license server host, and port is the
port number for the license server host. The port number is set by the system
administrator.

NOTE: After you have updated your startup script, remember to source it again,
or start a new session for the variable to take effect.

■ License Server or Node-Locked License

A license server installation and a node-locked license installation of
Tornado 2.2 both use the file WRSLicense.lic. The instructions for assigning
system variables are the same for either type of installation.
The value of the environment variable LM_LICENSE_FILE must be set to the
location of the WRSLicense.lic file. If LM_LICENSE_FILE already exists, then
the information should be appended to the current value of the variable.
When the SETUP program completes the Tornado 2.2 installation, the Finish
dialog displays commands that you can use to set the variable to the
appropriate value. These commands are also saved in the file lmEnvVar.txt in
the installation directory.

27
 Tornado 2.2
Getting Started Guide

Depending on your command shell, add the appropriate command to your

startup script in, for example, .cshrc. The default location of the file is
installDir/.wind/license.
For csh:
setenv LM_LICENSE_FILE installDir/.wind/license/WRSLicense.lic

For bash, sh, or ksh:

LM_LICENSE_FILE=installDir/.wind/license/WRSLicense.lic
export LM_LICENSE_FILE

NOTE: After you have updated your startup script, remember to source it again,
or start a new session for the variable to take effect.

2.5.2 Managing Licenses

This section is intended for license administrators to get started using the license
management software for Tornado 2.2.
Tornado 2.2 uses the FLEXlm license management system by Globetrotter
Software. For detailed information about FLEXlm, including downloadable user
documentation, visit http://www.globetrotter.com.

Summary of Floating License Management

The following is a summary of floating license management for Tornado 2.2:

■ The license manager software runs on one or more hosts designated as floating
license servers on your shared network.
■ FLEXlm requires a license file installed on each server machine. This file is
obtained from Wind River during installation of the license server.
■ When a Tornado 2.2 installation on your shared network needs a floating
license to run, it requests the license from a floating license server.
■ The floating license server must be started in order to serve licenses to
Tornado 2.2 installations.

28
 2
Installing Tornado

Starting and Stopping the License Server

To make the floating licenses available to Tornado 2.2 installations on the shared 2
network, the license manager must be started on the server.
To start up the license manager, do the following steps manually or add them to a
system startup script so that the server is started automatically when the system is
rebooted:
1. Change directory to the location where the license utilities are installed:
% cd installLic/host/sun4-solaris2/bin

2. Issue the startup command:

% lmgrd -c installLic/.wind/license/WRSLicense.lic -l
installLic/.wind/license/lmgrd.log [-x lmdown]

In the above example, the optional switch -l directs output to a log file,
lmgrd.log. The optional parameter -x lmdown prevents the shutdown of the
license manager by the lmdown utility.
To stop a license manager process, do the following:
1. If you did not use -x lmdown, issue the shut down command:
% lmutil lmdown -c installLic/.wind/license/WRSLicense.lic

2. If you did use -x lmdown, determine the process ID (pid) of the license
manager process:
% ps | grep lmgrd

3. Kill the process:

% kill pid

29
Tornado 2.2
Getting Started Guide

30
 3
Tornado Tutorial

3.1 Introduction
This tutorial is designed to introduce you to key features of Tornado using the
integrated VxWorks target simulator. It does not require any target hardware or
special configuration of your host system. It is not a programming tutorial; the
sample program was written to exercise Tornado in illustrative ways.
While simply reading the tutorial may be edifying, we encourage you to perform
the steps described in this chapter so that you can experience Tornado first hand.
In the course of the tutorial, you will:
■ Use the project facility to create a workspace and project for a sample program.
■ Build the program from the project facility GUI.
■ Download the program to the VxWorks target simulator on your host system.
■ Use the Tornado shell to run the sample program.
■ Use the browser to observe memory usage on the target simulator.
■ Use the WindView software logic analyzer to graphically display the execution
flow of the sample program and to identify a problem with task prioritization.
■ Use the debugger to identify a runtime application error.
Naturally, you will have several opportunities to modify the program to correct its
runtime behavior, rebuild it, download it, and run it again.

31
 Tornado 2.2
Getting Started Guide

The tutorial assumes minimal knowledge of multi-threaded programming in C,

and basic UNIX usage.
You might approach the tutorial with the following scenario in mind:
A colleague has abruptly announced that he is going on vacation, and the VP of
Engineering has handed you the delinquent’s portion of The Project. You are alarmed.
His code is typically cryptic, poorly documented, and full of run-time mischief. The
thought of reading his source gives you a headache. And the target hardware seems to
have gone on vacation with him. You decide to use Tornado’s target simulator and
analytical tools to see how the code behaves...

NOTE: This tutorial is intended for use with the integrated VxWorks target
simulator. The results may differ if used otherwise (with target hardware, for
example).

3.2 Set Tornado Environment Variables

Before you run Tornado, you need to set several environment variables. You can
do so most easily by changing directory to installDir/host/sun4-solaris2/bin,
and then sourcing torVars.csh or torVars.sh—depending on the shell you use. If
you use another shell, these scripts contain all the information you need to set the
appropriate variables.

32
 3
Tornado Tutorial

3.3 Start Tornado

To start Tornado, use the launch command:
3
% launch &

If Tornado is unable to connect to a Tornado registry, you are prompted to start one.
The Tornado Launcher window appears:

33
 Tornado 2.2
Getting Started Guide

3.4 Create a Project

Use the Project button to display the Tornado Project window:

By default, the Tornado Project window and the Create Project dialog box open at the
same time:

34
 3
Tornado Tutorial

Select the option for a downloadable application:

Click OK to continue.
The Tornado application wizard appears. This wizard guides you through the
steps of creating a new project. In the first step, the wizard prompts you for:
■ A name for the project.
■ The full path and name of the directory you want to use for the project files.
■ An optional description of the project.
■ The name and location of the workspace file, which contains information
about the workspace, including which projects belong to it.
A project consists of the source code files, build settings, and binaries that are used
to create an application.
A workspace is simply a grouping of one or more projects, which provides a useful
means of working with related material, sharing code between projects, and
associating related applications. Once a project and workspace have been created,
a workspace window displays information about the projects that it contains.
You can accept the wizard’s defaults for the project and workspace, but it is
preferable to set them up outside of the Tornado installation tree. (If you do so, you
won’t have to untangle your work from the Tornado tree when you upgrade
Tornado.)

35
Tornado 2.2
Getting Started Guide

In the wizard dialog displayed below:

■ The project name is gizmo.
■ The project directory is /folk/erics/projects/gizmo.
■ The project description is lightning gizmo.
■ The path and file name for the workspace are
/folk/erics/projects/lightning.wsp.

NOTE: The directory path for the workspace must exist—or at least match the path
(or an initial segment thereof) defined in the project Location field—for the wizard
to complete project creation.

Click Next to continue.

36
 3
Tornado Tutorial

In the second wizard dialog, you identify the toolchain with which the
downloadable application will be built.
A toolchain is a set of cross-development tools used to build applications for a
specific target processor (preprocessor, compiler, assembler, and linker). 3

The default toolchain names for target simulators take the form SIMhostOsgnu (for
example, SIMSPARCSOLARISgnu).
Select A toolchain and the option for the target simulator from the drop-down list,
as illustrated in the following:

Click Next to continue.

37
Tornado 2.2
Getting Started Guide

The final wizard dialog confirms your selections:

Click Finish to continue.

38
 3
Tornado Tutorial

The Workspace window appears. The workspace window title includes the name
of the workspace, and the window itself includes a folder for the project:

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 to display an object’s context menu.

39
 Tornado 2.2
Getting Started Guide

3.5 Add the Sample Source File to the Project

The sample program for this tutorial is cobble.c. It is a simple multi-tasking
application that simulates a data collection system that retrieves data from an
external source (for example, a device that generates interrupts as data comes in).
The four cobble tasks are:
■ tCosmos, which simulates an interrupt service routine (ISR) and generates
new data.
■ tSchlep, which collects the data.
■ tCrunch, which performs calculations on the data to obtain a result value.
■ tMonitor, which monitors the results and prints a warning message if they are
outside of the safety range.
The cobble program also includes the progStart( ) and progStop( ) routines. Later
in the tutorial, you will use these routines to start and stop the program.
Before you add the sample program to the project, copy it from the Tornado
installation tree to another location, such as the project directory you have set up
with the Tornado project wizard.
The sample file cobble.c is located in installDir/target/src/demo/start (where
installDir is your base installation directory for Tornado).
In the examples provided thus far in the tutorial, /folk/erics/projects has been used
as the base directory for our project work, and subsequent examples are based on
cobble.c being copied to that directory.

40
 3
Tornado Tutorial

After you have copied cobble.c to another location, add it to the project. Select Add
Files from the context menu in the Files view of the workspace:

Then use the file browser that appears to select cobble.c.

41
Tornado 2.2
Getting Started Guide

Open the Object Modules folder in the Files view to display the names of the object
files that are built from the project:

The Tornado project facility automatically creates the file projectName.out as a

single, partially linked module when a project is built. It comprises all of the
individual object modules in a downloadable application project, and provides for
downloading them all to the target simultaneously.

42
 3
Tornado Tutorial

3.6 Build the Project

To review the default build settings defined when you created the project, select
the Builds tab on the Workspace window, open the gizmo Builds folder, and 3
double-click on the default build name SIMSPARCSOLARISgnu.
The properties sheet for the build appears, which you can use to review makefile
rules and macros, as well as the compiler, assembler, and linker options used for
the build.
When you display the C/C++ compiler page, you will note that the Include debug info
checkbox is selected by default. This selection ensures that optimization is turned
off when the project is compiled with debug information:

Close the property sheet by clicking on the Cancel button.

43
Tornado 2.2
Getting Started Guide

Build the project by selecting Build 'gizmo.out' from the context menu:

The option Build 'projectName.out' builds all project modules as a single, partially
linked module that is optimal for downloading to a target.
Before Tornado builds the project, the Dependencies dialog box warns you that
makefile dependencies have not been calculated for cobble.c:

Click OK to continue.

44
 3
Tornado Tutorial

Tornado calculates makefile dependencies and proceeds with building the project.
If any external dependencies are found, they are automatically included in the
project and listed in the External Dependencies folder in the Files view of the
workspace. 3
The build output window displays any errors and warnings (in this case there are
none):

Press RETURN to close the build output window.

45
 Tornado 2.2
Getting Started Guide

3.7 Start the VxWorks Target Simulator

To start the VxWorks target simulator, first click on the VxSim button in the Tornado
Launcher window:

NOTE: Only one instance of the integrated VxWorks target simulator can be run at
a time. To stop the simulator, close the simulator window.

46
 3
Tornado Tutorial

The Launch VxSim dialog box appears:

Leave Standard simulator selected, and click Confirm to continue. The target
simulator window and the Create Target Server dialog box open.
The simulator window displays information about the operating system and the
target:

47
Tornado 2.2
Getting Started Guide

Click Launch in the Create Target Server dialog to start a target server with the
default configuration for the simulator (including wdbpipe in the Backend List field):

A target server manages all communication between Tornado host tools, such as
the debugger, and the target. The convention for target server names is
targetName@hostName. In this example, the name of the target is vxsim0 (the default
for the integrated simulator), and the name of the host system is duna.

48
 3
Tornado Tutorial

When the target server is launched, the target server name, as well as information
about the target and host-target communications method are displayed in the
Tornado Launcher:
3

NOTE: If you are using a Tornado registry with which other target servers have
been registered, they will be listed in the Targets box as well. Select the target server
for your simulator.

49
 Tornado 2.2
Getting Started Guide

3.8 Download the Project to the VxWorks Target Simulator

To download the project to the simulator, first select the target server name for the
simulator from the drop-down list in the workspace window. Then select the Files
view of the workspace, select the project folder name with the right mouse button,
and select the Download 'gizmo.out' option from the context menu:

50
 3
Tornado Tutorial

3.9 Run the Application from the Tornado Shell

Before you run an application, it is often useful to configure and start the Tornado
debugger, so that the debugger can respond to any program exception. 3
The Tornado debugger (also known as CrossWind) combines the best features of
graphical and command-line debugging interfaces. The most common debugging
activities, such as setting breakpoints and controlling program execution, are
available through convenient point-and-click interfaces. Similarly, program
listings and data-inspection windows provide an immediate visual context for the
crucial portions of your application.
To start the debugger, click on the CrossWind button in the Tornado Launcher
window:

51
Tornado 2.2
Getting Started Guide

The CrossWind window appears:

The Tornado shell (also known as WindSh) is a C-language command interpreter

that allows you to invoke any routine from the shell command line that has been
downloaded to the target. The shell also includes its own set of commands for
managing tasks, accessing system information, debugging, and so on.

52
 3
Tornado Tutorial

You can run the program from the shell command line. To start a shell, click the
WindSh button in the Tornado Launcher window:

When the shell window opens, run the program by entering the name of the main
routine, progStart, at the command line:

3.10 Examine Target Memory Consumption

The Tornado browser is a system-object viewer that is a graphical companion to the
Tornado shell. The browser provides display facilities to monitor the state of the
target system, including summaries of active tasks, memory allocation, and so on.

53
Tornado 2.2
Getting Started Guide

To start the browser, click the Browser button in the Tornado Launcher window:

When the browser appears, click the periodic refresh button . This updates the
display every few seconds; notice cobble.c has a voracious appetite for memory:

Stop the browser with the File>Quit menu option.

54
 3
Tornado Tutorial

3.11 Examine Task Activity

WindView is the Tornado logic analyzer for real-time applications. It is a dynamic
visualization tool that provides information about context switches, and the events 3
that lead to them, as well as information about instrumented objects such as
semaphores, message queues, and watchdog timers.
Start WindView by clicking on the WindView button in the Tornado Launcher
window:

The main WindView window appears:

Click the WindView button in the WindView window to display the WindView
Control window and the WindView Collection Configuration dialog box.

55
Tornado 2.2
Getting Started Guide

Select Additional Instrumentation from the drop-down list in the dialog box and click
OK:

To begin data collection, click the GO button in the WindView Control window.

NOTE: Except where otherwise specified, the default configuration of WindView

is used for this exercise. If WindView settings have been changed during another
session, the behavior may vary from the description below.

56
 3
Tornado Tutorial

Wait a few seconds, and then click the update button in the WindView Control
window to update the status of data collection:

When the Buffers value listed under Current Content reaches at least two, click the
Stop button to end data collection.
Before you upload the WindView data from the simulator target to the host, stop
the sample program by entering progStop at the shell command line.
Then use the upload button to upload the data.
A view graph is displayed while the data is uploaded.

57
 Tornado 2.2
Getting Started Guide

When the data upload is complete, maximize the view graph window control and
adjust the size of the main WindView window. The data display should look
something like the following: 1

You can use the zoom buttons on the WindView toolbar to enlarge or
decrease the scope of the display, and scroll bar at the bottom of the view graph to
display the rest of the data. (The zoom 100% button displays all of the data at
once.) The flag-shaped icons indicate semaphore gives and takes. The horizontal
lines indicate task states (executing, pending, ready, and so on). For information
about the meaning of the WindView icons, select Help>Legend.
Note that tCrunch, the task that processes data—and removes nodes from a linked
list—never runs.
Exit WindView with the menu option File>Exit, and click No in response to the
dialog that prompts you to save the data with: Save changes to hostName?

1. The color of the view graph display can be changed with Tools>Options in the main Wind-
View window.

58
 3
Tornado Tutorial

3.12 Fix Task Priorities and Find the Next Bug

Open the source in your editor by double-clicking on cobble.c in the workspace
Files view.2 3
Then find the progStart( ) routine, where you’ll discover that tCrunch is assigned
a lower priority than tMonitor, which never allows it to run. As a consequence,
data is never processed, and nodes are never deleted from the linked list.
Edit the source file to reverse the priorities between the two tasks:
■ Change the 240 argument in the taskSpawn( ) call for tCrunch to 230.
■ Change the 230 argument in the taskSpawn( ) call for tMonitor to 240.
Then save the file.
Use the context menu in the Files view of the workspace, select the
ReBuild All (gizmo.out) option to rebuild the project. When it is done, close the build
output window.
Then download the project to the target with the Download 'gizmo.out' option from
the context menu.

NOTE: Do not forget to download the new gizmo.out to the target! And if you have
stopped the debugger, restart it by clicking on the CrossWind button in the Tornado
Launcher window.

This time, start the program from the debugger with the command run progStart.

2. Tornado tools refer to the EDITOR environment variable to determine what program to
run. The default is vi, if EDITOR is not defined.

59
Tornado 2.2
Getting Started Guide

Both the simulator and shell windows soon announce an exception, and the
number of the task in which it occurred:

In the debugger Information dialog, click OK:

60
 3
Tornado Tutorial

At the debugger command line enter the following:

attach taskNumber
where taskNumber is the number of the task in which the error occurred (in this 3
example, it is 0x37c2f0):

61
Tornado 2.2
Getting Started Guide

The debugger displays cobble.c source code, and a context pointer marking the
position in the crunch( ) routine where the error was generated:

Before you proceed, detach the debugger and reboot the target simulator:
■ At the debugger command line, enter detach taskNumber.
■ In the shell window, press RETURN to display the prompt, and enter reboot.

62
 3
Tornado Tutorial

If you use the i command in the shell window after you have rebooted the
simulator, you see that only VxWorks system tasks are now running:

3.13 Fix the Last Bug and Take it for a Spin

Open the cobble.c file in your editor by double-clicking on the file name in the Files
view of the workspace window. Fix the source of the exception error in the
crunch( ) routine by using the commented code immediately below it—or
something more interesting. Save the file.
Then use the context menu in the Files view of the workspace to select the
ReBuild All (gizmo.out) option. When the build is done, close the Build Output window.

Download the application to the target with the Download 'gizmo.out' option from
the context menu.
Reattach the debugger to the target by selecting Targets>Connect Target Servers
from the CrossWind debugger menu. The Connect dialog box appears.

63
Tornado 2.2
Getting Started Guide

Select the name of the target server for the simulator from the list in the dialog and
click Connect:

Start the program again from the Tornado shell with the command progStart.

64
 3
Tornado Tutorial

Start WindView by clicking on the WindView button in the Tornado Launcher

window:

Click the WindView button in the WindView window to display the WindView
Control window and the WindView Collection Configuration dialog box.

Select Additional Instrumentation from the drop-down list in the dialog box; click OK.
Then click the GO button in the WindView Control window to begin data
collection.
Wait a few seconds, and then click the update button in the WindView Control
window to update the status of data collection.
When the Buffers value listed under Current Content reaches at least two, click the
Stop button to end data collection.
Then use the upload button to upload the data.
A view graph is displayed while the data is uploaded, and a message box
announces completion of the upload. Click OK to continue.

65
Tornado 2.2
Getting Started Guide

Maximize the view graph window, adjust the window size, and scroll through the
WindView data. You should find that all tasks, including tCrunch, are running in
an orderly manner, and the view graph data should look like this:

Remember that you can use the zoom buttons on the WindView toolbar to
enlarge or decrease the size of the scope of the display.

66
 3
Tornado Tutorial

You can check memory consumption once again with the browser by clicking the
the Browser button in the Tornado Launcher window:

When the browser appears, click the browser’s periodic update button . Every
few seconds the display will be updated.
You’ll note that memory consumption fluctuates modestly within a constant
range:

67
 Tornado 2.2
Getting Started Guide

Moreover, output in the simulator window indicates that the program is humming
along nicely, providing you with information about when it’s hot and when it’s
not:

Stop the program by entering progStop at the shell command line.

Bye! Tschuess! Adieu!

3.14 What Next?

For detailed information about using features of Tornado such as the project
facility, shell, browser, and debugger, see the Tornado User’s Guide. The guide also
provides information about setting up your Tornado development environment
with target hardware.
For information about VxWorks itself, see the VxWorks Programmer’s Guide, the
WindNet TCP/IP Programmer’s Guide, and the VxWorks API Reference.
The Tornado documentation set is available online in HTML format from the main
Tornado launcher menu Help>Manuals contents, or directly from the top level
HTML file installDir\docs\books.html.

68