This chapter describes how to use the default configuration to collect and analyze data about your VxWorks target and your application and how to interpret the data presented in the WindView view graph. You can do this using the integrated WindView and the integrated simulator that are included in Tornado 2.2 without any additional installation or configuration. The integrated WindView is a full-featured version of WindView for the integrated simulator. This chapter also describes how to install the WindView optional product on a Tornado host system. The optional product allows you to collect data from a target other than a simulator and to use networking with WindView.

For information on WindView host and target requirements, see the Tornado Release Notes. For information on how to set up the entire Tornado cross-development environment, see the Tornado User's Guide: Getting Started.

The order of this chapter follows the sequence required to use the integrated WindView to collect data from your target and view it; to install the WindView optional product and configure your target server and your VxWorks BSP to work with WindView; and, finally, to remove the WindView libraries from your production VxWorks before testing and shipping. However, if you wish to start by seeing what kind of output WindView generates, you can skip from 2.4.1 Installing WindView to 2.3 An Overview of WindView. Once you install WindView, you have access to several event logs that are shipped with the product. You can load and examine them without completing your rebuild of VxWorks to support WindView.

This section describes launching WindView; both the integrated and optional products with the default settings use the same process. For information on installing the optional product, see 2.4 WindView Optional Product.

There are slight differences between the launch process and the work environment for Windows and UNIX. In a Windows application, all subwindows, dialog boxes, and other elements reside in a master window. Thus WindView for Windows resides in the main Tornado window. In a UNIX application, each task or function exists in a separate window. When you launch WindView for UNIX, a main WindView control window opens, within which all WindView subwindows and dialog boxes appear. Throughout this manual the main Tornado window on Windows hosts and the main WindView window on UNIX hosts is called the main window and the menus at the top of this window will be called the main Tools menu, the main Help menu, and so on (see Figure 2-1).   

From this step on, the Windows and UNIX versions of WindView look the same except for stylistic differences in the windows. In either environment, WindView displays a Collection Configuration dialog box similar to Figure 2-3.

The default specifies that the Base Events are collected at the Context Switch event-logging level, in other words, only events that cause context switches are logged. This is the lowest level of collection and is usually referred to as CSE level logging; for more information on what data is logged for the different levels, see 3.2 Selecting a Logging Level. A list of libraries called Additional Instrumentation appears, but it is grayed out in the default configuration. For a discussion of collecting data from additional instrumented libraries, see 3.3 Instrumented Objects.

The Reset button resets all the WindView settings to the defaults. The first time you run WindView, click Reset to assure that you are using the default settings.

Pressing the Properties button brings up the Upload Configuration dialog box. This dialog box allows you to configure the collection buffers and the upload path. After you familiarize yourself with the defaults described below, accept them by clicking OK. Also accept the defaults in the Collection Configuration dialog box with OK.   

Follow the instructions in Tornado Getting Started to start a simulator and target server. If you have changed the target server defaults, see Configuring the Target Server for TSFS. (TSFS is required for the integrated simulator.) Once you have a target and a target server, you must launch WindView. To launch WindView, use either the button on the toolbar or WindView>Launch from the main Tools menu. The WindView launch button is a toggle button which, when depressed, indicates that the WindView Control window is running. Pressing the button when the Control window is open closes the window; pressing the button again re-opens it. Once you have opened the WindView Control window (see Figure 2-4), you can start WindView data collection. Click the button on the Control window.   

While WindView is running, click the button; the Current Content and Peak Content fields in the lower half of the Control window are updated. To obtain a regular update of the log status while event collection continues, press the button; it causes the information fields to be updated every 20 seconds.

While a regular update is useful, each query to the target from WindView generates additional events. Thus a regular update increases the amount of intrusion caused by WindView on the log data you collect.

To stop WindView, click the button on the Control window. (Don't worry about not having enough data. Even an idling target generates significant events.)

The default configuration uploads the data directly into a view graph. Click the button on the Control window. A new view graph opens containing your log data. The log file looks similar to Figure 2-5.    

To save the log file, use the Save menu item on the main File menu. The Save As dialog box appears, allowing you to save your log file in any location. Select a path and enter a file name. The file is automatically saved with a .wvr extension to indicate a WindView log.

In WindView, an event is any action undertaken by a task or an ISR that can affect the state of the real-time system. WindView displays detailed information for each event (such as the action that occurred, the context in which the action occurred, and the object associated with the action). In addition, WindView tags certain events with either high-resolution timestamps or event sequence numbers.

The interactions of the tasks, objects, and interrupts in a real-time system result in context switches. When a context switch occurs, execution switches from one thread to another. At the default logging level, the CSE level, WindView shows only the context switches. You can configure WindView to show all task state transitions so that, for example, when a task goes from pended to active state, that event is logged and displayed. This is called task state transition event-logging level or TST level. Or you can configure WindView to show details of selected objects in instrumented libraries, also called additional instrumentation event-logging level or AIL level. Instrumented objects include semaphore gives and takes, message queue sends and receives, timer expirations, and signals, as well as task and memory activities.

The heart of WindView is the view graph. The view graph presents the event data you collect in a graphical format that allows you to see the interaction of the various contexts in your system over time. If you have already followed the steps in 2.2 Running WindView and collected your own event log, you will have a view graph similar to Figure 2-6.

If you skipped to this section to familiarize yourself with the view graph before preparing to collect your own data, your WindView installation includes several sample files of data that you can view immediately. Even if you have your own log to look at, you may also want to open a sample log to compare a large, complex log with the simple log you generated. Figure 2-7 shows the view graph that appears if you open installDir/host/src/windview/apilib/vxColor.wvr using Open from the main File menu.

First, compare Figure 2-6 or your graph generated with the WindView default settings to Figure 2-7 or your display of vxColor.wvr. Notice that Figure 2-6 is quite simple, showing only some plain vertical bars and a few icons corresponding to interrupts near the top of the graph. On the other hand, Figure 2-7 is much more complex. It includes many more tasks, many connections between tasks, and many event icons. Your basic event log was generated using CSE logging level. vxColor.wvr was collected using AIL logging level with tasks, semaphores, message queues, and watchdogs instrumented. For information about logging levels, see 3.2 Selecting a Logging Level. For information about additional instrumented libraries, see 3.3 Instrumented Objects.    

Try clicking on the various zoom buttons on the WindView toolbar, Zoom In ( ), Zoom Out ( ), and Zoom 100% ( ). Note that when you use to display the entire log on the view graph, the icons overlay each other and can't be distinguished. Click and drag over a dense portion of the view graph and then click . Your view immediately zooms in on the area you indicated. You may need to do this several times to clearly distinguish the icons.

The following paragraphs provide an overview of the view graph shown in Figure 2-7. The features of the WindView display are discussed in detail in 5. Data Display.

The view graph is a window into the event data. In most cases, it does not show the entire event log; instead, it shows a time interval. The title of each view-graph window indicates where the events displayed come from: either the name of a file (an event log) or the name of a target server. The file name appears in the upper left-hand corner of the view graph: vxColor.wvr. If you have not yet saved a view graph, the name of the target server appears instead of the file name.

The timeline displays the time in seconds, or the sequence numbers, since event logging began.

On the left side of the view graph, the interrupt levels used in this event log are listed in order, with the highest-level interrupt at the top.

After the interrupt levels, tasks are listed with the highest priority task first, based on initial priority. Even if the priority of a particular task changes (due to a taskPrioritySet( ) or priority inheritance, for example), its vertical position does not change.

The last thread of execution shown represents the kernel idle loop.

The status bar for each WindView view graph provides information about the time interval currently displayed in that view graph unless a specific context is selected. For a time interval, as shown in Figure 2-7, the status bar displays the lower and upper bounds and the duration of the interval. To see the status bar when a specific event is selected, see Figure 2-6.

Various icons indicate what type of event occurred at a given time.

These are horizontal lines that show the state of each task at a given time.

An analysis pack is available to calculate the amount of memory usage (if you have collected memory data). Click the button to display the Analysis dialog box. Select the contexts you want to include in the analysis and click Perform. You can display the memory data in graph form below the main view graph by using the split box (see the upper right corner of Figure 2-7) to divide the view graph horizontally. (The analog graph is shown in Figure 5-12).

When you start WindView, a new task, tWvRBuffMgr, is created on the target. This task continues to run during your Tornado session, whether you stop WindView or not. Because you are likely to start and stop WindView often during the development process, tWvRBuffMgr is not deleted each time. This avoids the overhead of deletion and of recreation when you next use WindView. tWvRBuffMgr remains idle when you are not performing WindView logging.

The WindView optional product is an extension to the Tornado cross-development environment. You must have Tornado installed in order to install WindView. If you are installing Tornado for the first time when you install WindView, you will only have to run SETUP once. If you already have Tornado 2.2 installed, run SETUP with your WindView installation key to install WindView. For detailed information on running SETUP, see Tornado Getting Started.

When you install WindView, the default configuration does almost everything necessary for you to begin collecting and analyzing data immediately. The only other step you need to take, in addition to installing WindView, is to reconfigure and build VxWorks to include the WindView libraries. When you start your target and start WindView, WindView collects data on how your real-time system is running and uploads it to your development host.

For information on configuring WindView libraries into VxWorks, see Tornado User's Guide: Projects. The configuration macro for WindView is INCLUDE_WINDVIEW.¹

When you install and run WindView, the instrumented kernel tags certain events with either high-resolution timestamps or with sequence numbers; for background information, see 7.5 Timestamping. To determine whether your BSP includes a timestamp driver, see the BSP documentation. The configuration macro for the timestamp driver is INCLUDE_TIMESTAMP.

The drivers are in the directory installDir/target/src/drv/timer; the corresponding header files are in installDir/target/h/drv/timer.

On supported targets with limited hardware resources, the system clock, the auxiliary clock, or both may be taken over by WindView when the timestamp driver is enabled. In this case, these clocks are not available for system or application use. For example, the Motorola MVME147 timestamp driver uses the auxiliary clock; thus, that clock is not available for other uses.

If you are using a board that does not have a timestamp driver or if you do not enable the driver with INCLUDE_TIMESTAMP, the BSP is compiled with the sequential event display driver rather than the timestamp driver.

In order to upload your data from the target to the host, you must provide an upload path. The following options are available:

INCLUDE_WVUPLOAD_FILE	upload to a file (includes TSFS files)
INCLUDE_WVUPLOAD_SOCK	upload through a socket
INCLUDE_WVUPLOAD_TSFSSOCK	upload through a TSFS socket
INCLUDE_WVUPLOAD_ALL	include all available upload paths

If no upload path is selected, but INCLUDE_WINDVIEW is selected, then INCLUDE_WVUPLOAD_FILE and INCLUDE_WVUPLOAD_TSFSSOCK are defined automatically.

To upload WindView data to a file, you must have a file system defined. To upload to the WindView view graph, you must define a socket facility. The easiest way to include these facilities is to configure the Target Server File System (TSFS), which supports upload to both files and sockets. For detailed information on TSFS, see the VxWorks Programmer's Guide: Local File Systems.

To configure TSFS into your system for use with either upload option, the following options are available:

INCLUDE_WDB_TSFS	include the TSFS file system
INCLUDE_WDB	include the WDB target agent

There is no automatic dependency checking between INCLUDE_WDB_TSFS and INCLUDE_WDB, but WDB must be included for TSFS to work. The WDB agent is included in the default VxWorks configuration (see the project facility), but you should confirm that you have not changed that default.

If you plan to use WindView to analyze causes of target failure, see Post-Mortem Mode for additional configuration information.

In order to use the triggering function, you must select the configuration macro INCLUDE_TRIGGERING.

Triggering is not required for WindView, but it can be useful in collecting precisely the data you need and no more.

After all products have been installed and configured, remake the vxWorks image as described in Tornado User's Guide: Projects and reboot your target with the new image.

Note that the VxWorks boot ROM does not need to be rebuilt unless you are using a VxWorks standalone ROM or unless you are configuring VxWorks and WindView for post-mortem analysis using a reserved memory partition.

The default WindView configuration uses the Target Server File System, TSFS. For more information, see the VxWorks Programmer's Guide: Local File Systems. In order to use TSFS, you need to give the target server certain information.

• Confirm that the read/write option is Read/Write.

The default is Read/Write; you may decide that when you are not running WindView, you will set the TSFS option for your target server to read only. (For a discussion of security issues around write options, see the VxWorks Programmer's Guide: Local File Systems).

• Enter the root path.

Type the path to where you want your log file saved in the Target Server File System root box. For example:

/usr/windview/logfiles 

• Confirm that the read/write option is Read/Write.

The default is Read/Write; you may decide that when you are not running WindView, you will set the TSFS option for your target server to read only. (For a discussion of security issues around write options, see the VxWorks Programmer's Guide: Local File Systems).

Select Launch. Then select the name of your target server in the drop-down combo box in the main tool bar (Windows) or in the Target list in the Tornado Launcher window (UNIX).

During the development phase of your project, the WindView libraries are included in VxWorks. Once your application is complete and debugged, you will want to remove these libraries before testing and shipping your final product.

To do this, remove INCLUDE_WINDVIEW from your configuration and rebuild VxWorks. This should have no impact on your application behavior, but of course you will want to test after the removal.