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.

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

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.

To start Tornado, use the launch command:

% launch &

If Tornado is unable to connect to a Tornado registry, you are prompted to start one.

The Tornado Launcher window appears:

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:

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

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.

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.

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.

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.

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

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.

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.

The build output window displays any errors and warnings (in this case there are none):

Press RETURN to close the build output window.

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

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:

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.

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:

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.

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:

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.

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.

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

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.

Open the source in your editor by double-clicking on cobble.c in the workspace Files view.²

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.

At the debugger command line enter:

attach taskNumber

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

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.

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:

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.

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.

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.

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.

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:

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!

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.