3 Configuring Data Collection

3.1 Introduction

The WindView defaults are set to allow you to start using WindView to generate useful data immediately. If you experimented with VxWorks as described in 2. Getting Started, you saw how quickly large volumes of event data can be generated. When you are solving a problem with a real-time system, you do not want to dig through large quantities of irrelevant data to find the precise information you need. At the same time, once you know approximately where the problem is, you may need more detailed data from that region of the program. This chapter shows you how to modify the defaults in the Collection Configuration dialog box to log exactly the information necessary to solve your problem most efficiently.

3.2 Selecting a Logging Level

The level of logging you specify determines how much data is collected and how much impact WindView has on your application. The three options are:

Context Switch Event-Logging Level (CSE Level)

Task State Transition Event-Logging Level (TST Level)

Additional Instrumentation Event-Logging Level (AIL Level)

The relationship between these levels is shown in Figure 3-1. CSE level collects the smallest amount of data and is the least intrusive. TST level collects all the data collected at CSE level plus additional data about task state transitions. AIL level collects all the data collected at TST level plus additional data about selected objects. At AIL level, you can choose to collect data about only some or all of the possible objects, depending on your needs.

Figure 3-1: WindView Logging Levels

To select a logging level, open the Collection Configuration dialog box by clicking the button on the Control window toolbar. The Collection Configuration dialog box is shown in Figure 3-2. Select the desired level from the Base Events drop-down combo box.

Figure 3-2: Collection Configuration Dialog Box

Context Switch Logging Level (CSE Level)

In real-time systems, the term current context usually refers to the current task and the information needed to restore the task's state, such as the state of the processor registers, operating system control information, and the stack. For WindView, the meaning of current context is extended to include any thread of execution: a task, an ISR, or the kernel's idle loop. A context switch, then, refers to a change in the current context, which can occur when one task preempts another, a task delays itself or pends on a resource, or a task is interrupted by an ISR. To view a sample event log collected with CSE level logging, select Open in the main File menu and open installDir/host/src/windview/samples/switch.wvr. Figure 3-3 shows this event log.

Figure 3-3: Event Log Collected with CSE Level Logging

When you select Context Switch on the Collection Configuration dialog box (see Figure 3-2), WindView collects data about the current context and where it is switched. It also records every entry and exit of an ISR, every program error that results in an exception that is handled by a default exception handler, periods of task preemption locking, and periods of priority inheritance. Because CSE level logging is the least intrusive, it can be useful for fine-tuning an otherwise debugged system. For example, you might use it to see that all timing deadlines are being met, or that all tasks get to run.

Task State Transition Logging Level (TST Level)

The term task state transition refers to the process of a task exiting from one state and entering into another. For example, if a task issues a call to semTake( ) and the semaphore is not available, it makes a transition from the executing state to the pended state. If it calls taskDelay( ), it makes a transition from the delayed state to the ready state when the number of ticks specified in the call expire. All context switches involve task state transitions, but a given task state transition may or may not result in a context switch, depending on the states of other tasks in the system when the task in question makes a state transition. View a sample event log collected at TST logging level by selecting Open in the main File menu to installDir/host/src/windview/samples/state.wvr. Figure 3-4 shows a portion of this event log.

Figure 3-4: Event Log Collected with TST Level Logging

When you select Task State Transition on the Collection Configuration dialog box, WindView collects data about task state transitions and the events that cause them. However, when you specify TST level logging WindView does not collect information on events that do not result in task state transitions. For example, if no tasks are pended on a particular semaphore, a semGive( ) of that semaphore does not result in any task state transitions; thus, the semGive event icon is not logged.

Additional Instrumentation Logging Level (AIL Level)

AIL level logging works a little differently from CSE and TST levels. At AIL level, WindView gathers all the information included at the other two levels, as well as additional information about instrumented libraries that you choose to log. When you ask WindView to log an instrumented library, it logs all operations on library objects, including creations, gives or sends, takes or receives, and deletions. Events are generated for these operations whether or not they result in task state transitions, context switches, or neither; for example, a semTake( ) of a semaphore that is available would be logged at AIL level, even though it would not change the state of the calling task. To view a sample event log collected at AIL logging level, open installDir/host/src/windview/samples/object.wvr by selecting Open in the main File menu. Figure 3-5 shows this event log.

When you specify AIL level logging, you can collect data for many kinds of objects in your real-time system. By default, the main kernel AIL libraries are selected when you select AIL level: taskLib, semLib, msgQLib, wdLib, and eventLib, which are checked in the default setting shown in Figure 3-2. For information on changing the selected libraries, see 3.3 Instrumented Objects.

Figure 3-5 shows the same scenario as Figure 3-4. The only difference is that Additional Instrumentation was selected on the Collection Configuration dialog box, causing the default libraries to be logged. You can see that in addition to the information shown in Figure 3-4, tNetTask gives and take several semaphores( and ), only one of which results in a task state transition or a context switch.

Figure 3-5: Event Log Collected with AIL Level Logging

3.3 Instrumented Objects

Once you have selected Additional Instrumentation, you must decide which objects to log. The kernel objects that can be selected for logging from the Collection Configuration dialog box are tasks, semaphores, watchdog timers, message queues, VxWorks events, and signals. Memory objects and network objects can also be selected. Select the libraries containing the objects you want to log by checking the box in front of the library name.

Tasks (taskLib)

Semaphores (semLib)

Message queues (msgQLib)

Watchdog timers (wdLib)

VxWorks events (eventLib)

Memory allocs/frees (memLib)

Signals (sigLib)

Network activity (netLib)

NOTE: By default, only the kernel libraries taskLib, semLib, wdLib, msgQLib, and eventLib are selected.

The Selection Screen

Once you have selected Additional Instrumentation, you must decide which objects to log. The kernel objects that can be selected for logging from the Collection Configuration dialog box are tasks, semaphores, watchdog timers, message queues, and signals. Memory objects can also be selected. Select the libraries containing the objects you want to log by checking the box in front of the library name.

Figure 3-6: WindView Collection Configuration: Additional Instrumentation

For all kernel objects except signals, you can enable instrumentation for a particular object, such as task t1, within your application code. You can also enable instrumentation for whole libraries programmatically if you wish. For information on how to specify data collection for AIL level logging in your code, see 7.2 Instrumenting Objects Programmatically.

The Memory Library

When you select memLib, WindView logs the following events:

Memory allocations of all types (calloc( ), malloc( ), and so on)

Memory frees

Memory partition creations

Memory reallocations

Additions to memory pools

For detailed information about what parameters are logged for each event, which routines call them, and so on, see the Event Dictionary in the online WindView User's Reference.

Memory Analysis Pack

The view graph shows you when memory events occur, but the most interesting thing about your application's use of memory is how much is allocated at any time. WindView provides an analysis pack to calculate and display this information. To run it, display your log in the view graph and click . Select Memory Usage in the Analysis dialog box. To display the results of the calculation, click Export to Graph; the view graph displays the memUsage analog graph. (See Figure 3-7.)

Figure 3-7: Output for memLib Analysis Pack

Memory Example

To see how WindView can find memory leaks, compile and load this example:

void func1 (int loopcnt) 
    { 
    int i; 
 
    for (i = 0; i < loopcnt; i++) 
        { 
        char *p1 = (char *)malloc (1023); 
        char *p2 = (char *)malloc (1017); 
        free ((void *)p1); 
 
        /* note: p2 points at an unreturned piece of system memory.  */ 
        } 
    exit (0); 
    }

Start WindView in additional instrumentation logging level with memLib selected. Run func1 from the shell with a parameter of 5. When func1 returns, stop WindView and display the view graph. Select the Memory Usage analysis pack, click Select All to calculate memory usage for all tasks, select Perform, and click Export to Graph to display the analog graph. The analog graph allows you to quickly identify when func1 was running, and to see that not all the memory it allocated was returned to the system memory pool. (See Figure 3-7.)

Networking Library

Select netLib to log core and auxiliary networking events. Windview presents the Network Instrumentation Configuration dialog, shown in Figure 3-8. Because there are so many networking events compared to other categories of events, they are divided into eight categories based on priority. This gives you more precise control in pinpointing events you want to log. To log only the highest priority networking events, select the EMERGENCY priority level. To log events of all priorities, select VERBOSE.

In practice, while there are many types of networking events that can occur, logging at VERBOSE priority level can still produce readable logs. If a log is unreadable because it is cluttered with too many networking events, you can change the priority level in this dialog. You can also filter the data for display after collection is complete. See "Filtering for Data of Interest" on page 57.for more information.

Figure 3-8: Network Instrumentation Configuration Dialog

3.4 Starting and Stopping Data Collection

As you add more instrumentation, you increase the number of logged events. If there is a lot of activity on your target, starting and stopping WindView manually from the control window can generate unnecessarily large logs and make your problem-solving more difficult. There are three ways to control WindView:

Use the and buttons on the Control window. This is the most straightforward but least precise method.

Use triggering. This is a powerful tool for focusing your data collection and simplifying your problem solving. Triggering allows you to specify events and conditions that can cause WindView logging to start and stop. For more information see 6. Triggering.

Use the WindView API; issue WindView commands from WindSh or include them in your application code. This method can be very precise but is more difficult to use than triggering.

There are two approaches to using the API. The most straightforward is to use wvOn( ) and wvOff( ), located in target/src/config/usrWindview.c. These routines start a typical instance of event logging and upload. These routines are not used by WindView itself, so they can be modified to suit individual requirements.

The second approach is to use the routines in wvLib and wvNetLib. These routines give much finer control than wvOn( ) and wvOff( ) over the configuration of how events are logged. Detailed information and examples are available in the reference entries; you can examine the source code in target/config/comps/src/usrWindview.c to see how they are used. They are more complex to use than wvOn( ) and wvOff( ), since the order in which they are invoked is critical

All WindView routines are discussed in the online reference pages.