The Tornado browser conveniently monitors the state of your target. The main browser window summarizes active system and application tasks, memory consumption, and a summary of the current target memory map. Using the browser, you can also examine:

• detailed task information

• semaphores

• message queues

• memory partitions

• watchdog timers

• stack usage by all tasks on the target

• target CPU usage by task

• object-module structure and symbols

• interrupt vectors

These displays are snapshots. They can be updated interactively, or the browser can be configured to automatically update its displays at a specified interval. When any displayed information changes, in any browser display, the browser highlights the affected line.

There are two ways to start a Tornado browser:

• From the Tornado Launch toolbar, click the button. This launches a browser for the currently selected target server (see Tornado Launch Toolbar).

• From the Tools menu, click on Browser. The dialog box shown in Figure 9-1 appears, to allow you to select a target server from the Targets drop-down list.

The top of the browser window, shown in Figure 9-2, allows you to request particular browser displays and to control other browser functionality.

Clicking this drop-down list box displays the list of specialized browser displays you can choose from. Each specialized display is described in a section of this chapter.

You can choose among the following browser displays:

Target Information	See 9.5 Target-Information Window.
Tasks	See 9.6 Task-List Window.
Memory Usage	See 9.7 Memory-Usage Window.
Object Information	See 9.8 Object-Information Windows.
Stack Check	See 9.11 The Stack-Check Window.
Module Information	See 9.9 The Module-Information Window.
Spy Chart	See 9.10 The Spy Window.
Vector Table	See 9.12 The Vector Table Window. This selection is available only on supported architectures.

Buttons to give you fresh snapshots of your target, and to adjust browser parameters. 9.4 Browser Buttons describes each button.

Below the controls, most of the browser window is devoted to a display of the selected target information. The default Target Information window provides a summary of the target hardware and software on the current target.

When you choose a particular browser display, the contents of the data area are replaced in the currently active browser window. You can have as many browser windows open as necessary to monitor different aspects of the target system simultaneously.

The button bar at the top right of each browser window provides the following controls:

Immediate-update button. Use this button to update all browser displays immediately. You can use this button for an immediate update even if a periodic update is running.

Periodic-update button. This button is a toggle: press it to request or cancel regular updates of all browser displays (the time period between updates is one of the parameters controlled by the button, described below).

Parameter adjustment button. Press this button to adjust the parameters that govern the browser's behavior. Figure 9-3 shows the Browser Configuration dialog box, displayed when you click this button.

Figure 9-3:   Browser Configuration Dialog Box

The Browser Configuration dialog box contains the following controls:

To select alphabetic sorting order for symbols displayed by the browser, check this box; otherwise, the browser uses numeric order.

To select differential mode for the spy window, check this box; otherwise the browser uses cumulative mode (see 9.10 The Spy Window).

Specify how often to update browser windows (when periodic updates are running).

Specify how many times per second to gather data for the spy window.

To open a new window when you double-click on an object ID (for example, a task ID) in the browser, leave this box un-checked. To discard the data area of the current window in that situation, replacing it with data for the object you clicked on, check this box.

The Target Information window (Figure 9-4) displays the following summary information about the selected target:

A unique string identifying the target server, which matches the selected entry in the target list. Servers are shown as target@serverhost, where target is an identifier (frequently the network name) for the target device itself, and serverhost is the network name of the host where the target server is running.

The target-server version number.

This field indicates whether a target is reserved (see the User field) or unreserved. Anyone may connect to an unreserved target.¹

The name and version number of the operating system running on the target.

The name and version number of the agent program running on the target.

A string identifying the CPU architecture (and possibly other related information, such as whether this is a real target or a simulated one).

The name and version number of the Board Support Package linked into the run-time.

The total number of bytes of RAM available on this target.

The physical connection mechanism to the target.

The sign-on name of the developer who launched this target server, or of the user who reserved it most recently.

A timestamp showing when this target server was launched.

The last time this target server received any transaction request.

A list of all the tools currently attached to this target server. The list includes all Tornado tools attached to this target by any user on the network, not just your own tools.

Figure 9-5 shows two examples of the task list produced by clicking Tasks in the browser window selector.

The tasks in this window are organized into two lists:

Summary information on all operating-system tasks running on the target.

Summary information on all application tasks running on the target.

Each task list is marked with a small (minus sign) icon.You can double-click on this icon to hide data that is not of current interest; the browser changes the marker to a small (plus sign) to indicate that hidden data is available. To reveal the contents of a hidden task list, click the plus-sign icon. (This convention for controlling the display of hierarchical information is used in many parts of Tornado.)

The task-summary display (for either system or application tasks) includes the task ID, the task name (if known), and the task state.

You can display detailed information on any of these tasks by clicking on the summary line for that task; see 9.8.1 The Task Browser.

Figure 9-6 shows an example of the window produced by clicking Memory Usage in the browser window selector.

The Memory Usage window has the following areas:

• Memory-Consumption Graphs

The two bar graphs in this area show what proportions of target memory are currently in use.

The upper bar shows the state of the memory pool managed by the target agent.² This represents target memory consumed by Tornado tools, for example with dynamically linked modules or for variables defined from the shell.

The lower bar shows the memory consumed by all tasks in the target system, including both application (user) tasks and system tasks.

The agent-memory pool is separate from the memory controlled by VxWorks'. If the target server wants to allocate more memory than is available in the agent-memory pool, it transfers memory from the VxWorks memory pool to the agent-memory pool and then allocates it from the agent-memory pool.

In both bars, the numeric label inside the bar measures the memory currently in use. The numbers below the right edge of each graph indicate the total memory size available in each pool. All memory-size numbers are byte counts in decimal.

• Loaded-Module List

This area lists each object file currently loaded on your target. This includes the VxWorks image and all dynamically linked object modules.

Clicking Object Information in the browser window selector brings up a window where you can request a specialized display for VxWorks system objects (Figure 9-7). Type or paste either the name or the ID of a system object in the text box next to the Show button. Then click Show (or press ENTER) to display information about that particular object. As a convenient shorthand, we refer to the browser's object-information windows as object browsers: task browsers, semaphore browsers, and so on.

Another way to bring up an object-information window is to click on the name of an object in the module browser (9.9 The Module-Information Window). If the object is a recognized system object, the data area for it is displayed just as if you had copied the name to the Show box.

For example, Figure 9-7 shows the Show box filled in with a request to display an object called graphSem.

To see more detailed information about a particular task, click on any task's summary line in a browser Tasks window (or enter the task name or task ID in the Show box of an Object Information browser window). The browser displays a window for that task, similar to Figure 9-8.

At the top of the task browser you can see global task attributes, and information about stack allocation and usage. The last major region shows the hardware registers for this task; their precise organization and contents depends on your target architecture. As usual, a scrollbar is displayed if more room is needed.

Notice the (minus sign) icons; the lines they mark categorize the task information. As in other parts of Tornado that display hierarchical data, you can hide categories by clicking on any icon, or expose hidden categories by clicking on any (plus sign) icon.

Figure 9-9 shows another task browser running on the same target, but with most of the hardware registers hidden.

To inspect a semaphore, enter either its name or its semaphore ID in the Show box of a browser window with Object Information selected. A specialized semaphore browser appears, similar to the one shown in Figure 9-10. The semaphore browser displays both information about the semaphore itself (under the heading Attributes), and the complete queue of tasks blocked on that semaphore, under the heading Blocked Tasks.

Figure 9-10 shows a binary semaphore with several blocked tasks in its queue. As in other browser windows, you can click on the levels of the display to control detail. To start a browser for any queued task, click on the task name or ID; both are displayed for each task.

POSIX semaphores have a somewhat different collection of attributes, and the browser display for a POSIX semaphore reflects those differences. Similarly, the semaphore browser adapts to shared-memory semaphores.

To inspect a message queue, enter its name or message-queue ID in the Show box of a browser window with Object Information selected. A message-queue browser like the one in Figure 9-11 is displayed.

In addition to displaying the attributes of the message queue, the message-queue browser shows three queues:

• Receivers Blocked shows all tasks waiting for messages from the message queue.

• Senders Blocked shows all tasks waiting for space to become available to place a message on the message queue.

• Messages Queued shows the address and length of each message currently on the message queue.

Shared-memory message queues have a very similar display format (differing only in the title bar). Just as for semaphores, the message-queue browser also has a version for POSIX message queues.

The memory-partition browser comes up when you enter a memory partition ID (or the name of a variable containing one) in the Show box of a browser window with Object Information selected, as do all specialized browser windows. Figure 9-12 shows the VxWorks system memory partition, memSysPartId.

By default the memory-partition browser displays the following:

• The total size of the partition.

• The number of blocks currently allocated, and their total size in bytes.

• The number of blocks currently free, and their total size in bytes.

• The totals allocated since booting the target system (headed Cumulative).

• The size and address of each block currently on the free list.

As with other object browsers, you can control the level of detail visible by clicking on the (minus sign) or (plus sign) icons beside each heading.

When the Tornado browser recognizes a watchdog-timer ID (or a variable containing one) in the Show box of a browser window with Object Information selected, it displays a window like those shown in Figure 9-13.

Before you start a timer, the display resembles the one on the left of Figure 9-13; only the state field is particularly meaningful. However, after the timer starts counting, you can see the number of ticks remaining, the address of the routine to be executed when the timer expires, and the address of the routine's parameter.

VxWorks kernel objects are implemented as related classes: collections of objects with similar properties. Each class has an identifier in the run-time; the symbol names for these identifiers end with the string ClassId, making them easy to recognize. When you enter a class identifier in the Show box of a browser window with Object Information selected, the browser displays overall information about the objects in that class.

For example, Figure 9-14 shows the display for semClassId (the semaphore class).

You can get a list of the class identifiers in your run-time system by executing the following in a shell window:

-> lkup "ClassId" 

To inspect the memory map of any currently loaded module, click on the line that lists that module in the loaded-module list (described in 9.7 Memory-Usage Window).

The browser opens a module-information window resembling Figure 9-16 for the selected object module.

The module-information window displays information in the following categories:

Overall characteristics of the object module: its name, the loader flags used when the module was downloaded, the object-module format (OMF), and the group number. (The group number identifies all of the symbols from a single module.)

For each segment (section) of the object module: the segment type (text, bss, or data), starting address, and size in bytes.

The bulk of the object-module browser display is occupied by a listing of symbols and their addresses. Symbols are displayed in either alphabetical or numerical order, depending on what browser state is in effect when you request a module browser.

Each symbol's display occupies one line. The symbol display includes the symbol's address in hexadecimal, a letter representing the symbol type (Table 9-1), and the symbol name (in its internal representation--C++ symbols are displayed "mangled," and all compiled-language symbols begin with an underbar).

Symbol displays are grouped by category. There is one category for the symbols in each section, plus a category headed Other_Symbols that contains uninitialized globals and unrecognized symbols.

For symbols that represent system objects, clicking on the symbol name brings up the corresponding object browser; see 9.8 Object-Information Windows.

Clicking Spy Chart in the browser window selector produces a display similar to Figure 9-17. This window reports on CPU utilization for each task on your target, as a percentage of CPU cycles. Besides tasks, the spy window always includes the following additional categories for CPU-cycle usage: time spent in the kernel, time spent in interrupt handlers, and idle time. These additional categories appear below all task data; you may need to use the scrollbar to see them.

Spy data is reported in one of two modes (selected with the Browser Configuration dialog box shown in Figure 9-3). When the Differential check box is off in the Browser Parameters dialog box (see 9.4 Browser Buttons), the spy window is in cumulative mode: it shows total CPU usage since you first display the spy window. Spy reports in differential mode reflect only the CPU usage since the last update.

The spy window uses the facilities of the VxWorks target software in spyLib (which is automatically downloaded to the target when you request a spy window, if it is not already present there). For related information, see the reference entries for spyLib.

Clicking Stack Check in the browser window selector produces a window similar to Figure 9-18. The stack-check window summarizes the current and maximum stack usage for each task currently running.

The display for each task presents three values:

• The stack size allocated for each task, shown as a number of bytes beneath the bar representing that task.

• The maximum stack space used so far by each task is indicated graphically by the shaded portion of each task's bar.

• The portion of the stack currently in use, shown as a number of bytes, displayed within the bar graph for each task.

To inspect the interrupt/exception vector table, click Vector Table in the browser window selector. (This facility is available for all target architectures except the Windows simulator, PowerPC, and ARM.) The display is similar to Figure 9-19.

Vectors are numbered from 0 to X (X = number of interrupt/exception vectors). The connected routines or addresses are displayed, or if no routine is connected the following key words are be displayed:

standard exception handler

default trap (Sparc)

uninitialized interrupt vector

corrupted interrupt vector

If you set a new vector from WindSh and then update the browser, the new vector is highlighted.

If your communications link to the target is slow (a serial line, for example), use the browser judiciously. The traffic back and forth to the target grows with the number of objects displayed, and with the update frequency. On slow links, this traffic may seriously slow down overall Tornado performance. If you experience this problem, try displaying fewer objects, updating browser displays on request instead of periodically, or setting updates to a longer interval.

Many problem conditions in target applications become much clearer with the browser's visual feedback on the state of tasks and critical objects in the target. The examples in this section illustrate some of the possibilities.

The memory-consumption bar graphs in the Memory Usage window makes memory leaks easy to notice. If the allocated portion of memory grows continually, you have a problem. The memory-consumption graph in Figure 9-20 indicates a memory leak in an application that has run long enough to exhaust memory almost completely.

A more subtle memory-management problem occurs when small blocks of memory that are not freed for long periods are allocated interleaved with moderate-sized blocks of memory that are freed more frequently: memory can become fragmented, because the calls to free( ) for the large blocks cannot coalesce the free memory back into a single large available-memory pool. This problem is easily observed by examining the affected memory partition (in many applications this is the VxWorks system memory partition, memSysPartId) with the browser. Figure 9-21 shows an example of a growing free-list with many small blocks, characteristic of memory fragmentation.

When a task exceeds its stack size, the resulting problem is often hard to trace, because the initial symptom may be in some other task altogether. The browser's stack-check window is useful when faced with behavior that is hard to explain: if the problem is a stack overflow, you can spot it immediately (Figure 9-22).

Browser displays are most useful when they complement each other. For example, suppose you notice in a task-list window (as in Figure 9-23) that a task uHi, expected to be high priority, is blocked while two other tasks are ready to run.

An immediate thing to check is whether the three tasks really have the expected priority relationship (in this example, the names are chosen to suggest the intended priorities: uHi is supposed to have highest priority, uMed medium priority, and uLow the lowest). You can check this immediately by clicking on each task's summary line, thus bringing up the windows shown in Figure 9-24.

Unfortunately, that turns out to be the wrong explanation; the priorities (shown for each task under Attributes) are indeed as expected. Examining the CPU allocations with the spy window (Figure 9-25) reveals that the observed situation is ongoing; uMed is monopolizing the target CPU. It should certainly execute by preference to the low-priority uLow, but why is uHi not getting to run?

At this point examining the code (not shown) may seem worthwhile. Doing so, you notice that uMed uses no shared resources, but uHi and uLow synchronize their work with a semaphore. Could that be the problem?

Examining the semaphore with the browser (Figure 9-26) confirms this suspicion: uHi is blocking on the semaphore, which uLow cannot release because uMed has preempted it.

Having diagnosed the problem as a classic priority inversion, the fix is straightforward. As described in VxWorks Programmer's Guide: Basic OS, you can revise the application to synchronize uLow and uHi with a mutual-exclusion semaphore created with the SEM_INVERSION_SAFE option.

When the browser begins executing, it first checks for a file called .wind\browser.tcl in two places: first under c:\tornado, and then in the directory specified by the HOME environment variable (if that environment variable is defined). In each of these directories, if a browser.tcl file is found, its contents are sourced as Tcl code; this gives you an opportunity to customize the browser.