4 Configuring Data Upload

4.1 Introduction

The Upload Configuration dialog box (see Figure 4-1) allows you to configure all aspects of data upload.This chapter shows you how to change the default settings and explains why you might choose one alternative over another. The following items are configured in the Upload Configuration dialog box:

Buffer configuration: specifies the number and size of buffers included in the dynamic ring buffer.

Upload mode and destination: specifies whether data is uploaded periodically during collection, when you request it after collection stops, or when you request it after a target reboot; also specifies whether data is directed to a file or to a view graph.

Upload path: specifies whether data is uploaded using one of the TSFS options or using network facilities.

To reach the Upload Configuration dialog box, select WindView>Configure from the main Tools menu, or press the button in the Control window. Press the Properties button to display the dialog box shown in Figure 4-1.

Figure 4-1: Upload Configuration Dialog Box

NOTE: The buffer configuration and data upload settings you choose should match the configuration of the WindView components in the VxWorks target system. See the Tornado User's Guide and the online Tornado User's Reference for information on configuring VxWorks components with Tornado.

4.2 Dynamic Ring Buffer

The WindView dynamic ring buffer (rBuff) is designed to provide the most effective use of memory resources during event logging. You set limiting parameters, and WindView automatically expands or shrinks the ring depending on how much data is stored in it at a particular time. For a detailed discussion of how the rBuff works and how to configure buffer parameters, see 7.6 Dynamic Buffer Allocation.

The rBuff is configured in the Buffer Configuration section of the Upload Configuration dialog box.

Figure 4-2: Buffer Configuration

4.2.1 Parameters

This section provides rules of thumb for changing buffer parameters. For a detailed discussion of dynamic buffer allocation with examples, see 7.6 Dynamic Buffer Allocation.

Minimum Buffer Count

The minimum buffer count has a default of two, and this value is usually appropriate. Since the upload threshold for continuous mode is calculated from this value, if you find that your system is thrashing in continuous mode (allocating and deallocating buffers), you may tune it by increasing this value to three, or even to four.

Maximum Buffer Count

The maximum buffer count has a default of ten. For continuous upload mode this should be appropriate unless your system generates occasional very large bursts of data. If it happens that the ring of buffers occasionally fills during one of these bursts, causing logging to stop, you can increase the maximum number of buffers.

For deferred upload mode, you probably want to assign all system memory that is not needed for VxWorks and your applications to the log buffer.You will need to calculate the amount of memory you have remaining taking into account your kernel and application requirements, and set the maximum buffer count to the appropriate value. WindView adds buffers to the ring until the maximum is reached or all memory is exhausted and then stops logging.

Buffer Size

The default buffer size is 32KB. This is usually appropriate for either deferred mode or continuous mode. If you select post-mortem mode, WindView automatically specifies small buffers. (For more information on post-mortem mode, see Post-Mortem Mode.)

4.2.2 Buffer-Full Behavior

In both deferred and continuous modes, when the ring of buffers fills, logging stops and a warning message is generated. This is more likely to happen in deferred mode, where a very large log may consume all available memory. It may also happen in continuous mode if a very large burst of data fills the entire ring of buffers before it can be uploaded. This behavior can not be configured; in other words, you can't tell WindView to keep logging after the ring of buffers is full. To prevent premature termination of logging, adjust the maximum number of buffers or use triggering to limit the amount of data collected.

In post-mortem mode you are collecting data to analyze a system failure. You may have to run your system for an extended period of time before the failure occurs, but when it does, the log data collected just before the failure is probably the most useful. For this reason, in post-mortem mode, WindView continues logging, automatically wrapping around and overwriting the oldest data if the dynamic ring buffer fills.

4.3 Upload Path and Destination

The upload path is the route used to upload your event data from the target to the host. The upload destination is where the data is put when it is uploaded. The options presented in the Upload Path section of the Upload Configuration dialog box (see Figure 4-3) combine a path and a destination.

Figure 4-3: Upload Path and Destination

4.3.1 Alternative Upload Paths

Target Server

WindView, like other Tornado tools, allows you to upload data through the target server. This is done using a new feature called TSFS, which is described in detail in the VxWorks Programmer's Guide: Local File Systems. TSFS uses the VxWorks virtual I/O facility to send data to the host. (For information about the VxWorks VIO facility, see the Tornado API Guide: The WTX Protocol.) TSFS implements the standard I/O commands. In addition, TSFS supports a socket as a special file type. Thus TSFS can upload data either to a file or to the WindView display or another destination.

TSFS uses the same path as your WDB agent to communicate to the target server. Thus you must define INCLUDE_WDB in order to use TSFS. If you configured WDB to use a serial interface, TSFS will use the serial interface. If you configured WDB to use a network connection, TSFS will use the network connection. Note that when you include WindView and do not specify an upload path, the TSFS paths to both files and the WindView display are included (see Upload Path).

NOTE: Remember that you must also configure your target server to support TSFS (see Configuring the Target Server for TSFS).

The advantage of using TSFS is that it does not require extra facilities. If you have chosen to use network facilities for other reasons, TSFS takes advantage of the bandwidth you have already configured to upload WindView data. If you have decided not to configure network facilities, TSFS uses the serial connection.

Network Facilities

The advantage of a network connection over a WDB connection is that it is separate from the WDB messages flowing between your target and the Tornado target server. The disadvantage is that using this path requires that your target contain at least the network stack (TCP/IP) and possibly also the Network File System (NFS). If you plan to configure these facilities anyway, you may choose to use these paths. If you do not need these facilities, and if you need to minimize the size of your VxWorks kernel, you might choose to use TSFS over a serial line.

4.3.2 Alternative Destinations

View Graph

Sending your event data directly to the view graph means you can eliminate the step of opening a file. On the other hand, the parser element within the WindView host tool must process the data before it can be displayed, which may slow the data transfer rate. You can save any event log to a file from the view graph.

File

Sending your event data to a file means that the log is saved on the host before you begin analysis. The data can be written to a file more rapidly than to the view graph because the data is written in its raw format. The parser does not process the data until you open the file to display it in the view graph.

4.3.3 Choosing the Path and Destination

Direct to Graph

When you select Direct to Graph from the Upload Path drop-down combo box, the event log is uploaded directly into the WindView view graph on the host where the target server is located. The only configuration steps you must take to use this path are to include TSFS in your VxWorks image (see 2.4.2 Configuring VxWorks) and to configure the target server to support TSFS (see 2.4.3 Starting a Target Server). When you upload data, a view graph opens and the data streams into it.

NOTE: If you use Direct to Graph with continuous upload mode, you can use the Track incoming events button ( ) to pause the display so that you can look at a particular section without it continually changing. Data continues to stream into the view graph, and when you click the button again, the display updates to show the whole log.

File via TSFS

When you select File via TSFS from the Upload Path drop-down combo box, the default path presented is /tgtsvr/eventLog.wvr. When you upload data, the root you specified in the Target Server Configuration dialog box is substituted for /tgtsvr. Data is written to this file when upload is requested, either by the target (in continuous upload mode) or by you (in deferred upload mode). To view and analyze the data, you must load the log file into WindView using Open from the main File menu. For more information on configuring this path, see TSFS to a File.

Socket via TSFS

When you select Socket via TSFS from the Upload Path drop-down combo box, the default path presented is /tgtsvr/TCP:hostname:6164 where hostname is the name of the machine where the target server is located. Using this default path sends the data to the WindView view graph just like Direct to Graph. However, if you select this option you must open the view graph using New on the main File menu before starting data collection, which is unnecessary with Direct to Graph. The port number indicated on the view graph must match the port number in the Upload Configuration dialog box. In addition, selecting this option allows you to modify the defaults to send the data to an alternate destination, such as a remote machine or Event Receive. Data is uploaded either continuously or when you request it, but when it is uploaded, it streams to the specified destination. For more information on configuring this path, see TSFS Sockets.

Socket via TCP/IP

When you select Socket via TCP/IP from the Upload Path drop-down combo box, the default path presented is hostname/6164. When upload occurs, it goes from the socket on the target to the socket connection on the host which you have configured. You can configure the host socket by opening the view graph using File>New on the main Tools menu or by starting Event Receive. The port number indicated on the view graph or used by Event Receive must match the port number in the Upload Configuration dialog box. Data is uploaded either continuously or when you request it, but when it is uploaded, it streams to the specified destination. For more information on configuring this path, see TCP/IP.

NFS to File

When you select NFS to File from the Upload Path drop-down combo box, the default path presented is /eventLog.wvr. You must configure NFS on your target so it can find this file. Data is uploaded either continuously or when you request it, but when it is uploaded, it is written to this file. To view and analyze the data, you must load the log file into WindView using Open from the main File menu. For more information on configuring this path, see Using NFS.

4.4 Upload Mode

The upload mode is configured using the lower portion of the Upload Path section of the Upload Configuration dialog box shown in Figure 4-4.

Figure 4-4: Upload Mode

Deferred Upload Mode

The WindView default is deferred upload mode. The event data generated by your target is saved in the WindView dynamic ring buffer. At any time after logging is completed, you can upload the data from the buffer to WindView on the host for display, analysis, and storage. The steps of this upload process are described in 2.2.2 Collecting Data.

NOTE: If you request upload before stopping logging, logging stops and upload occurs; you cannot upload the buffer while simultaneously logging more data to it when you are using deferred upload mode.

In most cases deferred upload mode is the preferred method. The only WindView activity that affects the target is data collection; there is no impact from data upload because that activity is deferred until data collection is complete.

Continuous Upload Mode

Sometimes your situation requires that you collect very large amounts of data. For example, early in your analysis it may not be clear where the problem is. You can not use triggers to isolate the events of interest because you don't yet know how to characterize them. In this case, you can use continuous upload mode. This mode is more intrusive and will have more impact on the performance of your target, since the target must periodically stop its normal work to upload data to the host. On the other hand, you can collect more data than you have memory available on the target. Select continuous upload mode by clicking on the Continuous radio button.

Unlike the default deferred upload mode, continuous upload mode transfers data to the host whenever the amount of data stored in the buffers reaches the upload threshold. The upload threshold is calculated based on the buffer parameters you configure and an optimization algorithm. The data may be transferred to a file on the host or streamed to the WindView view graph, but it is transferred to the host when the upload threshold is reached without any action on your part, and logging continues uninterrupted.

Continuous upload mode takes advantage of the dynamic ring buffer to prevent buffer overflow during periods of heavy event generation. If the existing buffers fill, additional buffers are added to the ring. Once data collection slows and the buffers are emptied, excess buffers are deallocated. See 4.2 Dynamic Ring Buffer and 7.6 Dynamic Buffer Allocation.

Post-Mortem Mode

Configuring Post-Mortem Mode Using the GUI

Post-mortem mode applies to the specific case where an application failure is causing the target to reboot. Select post-mortem mode by clicking on the Post-Mortem radio button. When you select post-mortem mode, the Buffer Configuration portion of the dialog box changes as shown in Figure 4-2.

In this mode, WindView event data is logged to the dynamic ring buffer continually, wrapping around to write over the oldest data once all the individual buffers are full. Then, when the failure occurs, up to one full set of buffers worth of event data leading up to the failure will have been captured, providing useful diagnostic information. In addition to preserving the log itself for upload after a target reboot, WindView saves task name information in the reserved memory area. This information is uploaded to the target along with the event log. This means that tasks can be identified symbolically in the event log even though the application is no longer active on the target.

When not in post-mortem mode, the event buffer resides in VxWorks system memory. However, on many targets, the system memory region is reset during the booting sequence that occurs to re-establish the target following an application failure. For this reason, in order to ensure that the event log can be recovered for analysis after the reboot, you must identify a region of preserved memory so that WindView can place your data in a memory region that is not overwritten during reboot.

To use post-mortem mode, follow these steps:

Identify an address range that is not cleared during system reboot and that is not cacheable. Usually this address range is at least 64K, although it may be possible to get by with less if you have very few tasks running. You can use this range to specify a separate memory board. Alternatively, it may be necessary to reconfigure the system as discussed in Post-Mortem Mode. The start and end of your preserved memory area are entered into the Buffer Configuration section of the Upload Configuration dialog box (see Figure 4-5).

Figure 4-5: Post-mortem Buffer Configuration

NOTE: Be sure that the address range you choose for your preserved memory is aligned according to the requirements of your board.

WARNING: If you reconfigure your system memory to reserve a memory partition for your post-mortem buffer, you must rebuild your VxWorks image and your boot ROM, reboot your target, and reset the WindView configuration by clicking Reset in the Collection Configuration dialog box. See Post-Mortem Mode.

Once you have identified a preserved memory region, you can select post-mortem mode by clicking on the Post-Mortem radio button. When you do this, the Buffer Configuration section changes to allow the post-mortem area to be specified. (If you have reset the configuration, the lower and upper address of the preserved area are preset to correspond to the values returned by sysMemTop( ) and sysPhysMemTop( ).

If you have rebuilt the VxWorks image and target boot ROMs, these values automatically represent the post-mortem region you have reserved. However, you can modify these values if you wish to reduce the region used for the event buffer, but you must stay within the reserved values. Entering incorrect values can cause exceptions when WindView tries to use the region.

If you have provided a preserved region by some other means, enter the lower and upper address in the buffer configuration boxes. No checks are performed to confirm that the values entered are actually preserved or that they actually exist.

The region specified is used to hold an rBuff whose configuration is automatically determined by WindView (see Post-Mortem Mode).

After clicking OK, confirm that the level of instrumentation and other parameters are still correctly configured following the configuration reset.

WARNING: The automatic configuration of the post-mortem region following reconfiguration of the boot ROM relies upon the values returned by sysMemTop( ) and sysPhysMemTop( ). Care should be taken to ensure that these values are valid for the specific target board you are using, as boards sharing the same BSP are often supplied with varying amounts of onboard memory.

You are now ready to collect a post-mortem event log. Note that you must still start WindView logging by using either the button or triggering.

Perform those actions necessary to reproduce the sequence resulting in the application failure.

Once the failure has occurred, click on the button in the Control window and wait for the target to reboot. This may require pressing the button on the front panel of the target or some equivalent action. However, do not remove power from the board as doing so clears all memory on most target boards.

After reboot the Control window does not indicate the presence of an event buffer. To upload the post-mortem buffer you must first cause WindView to find it. Do this by opening the Collection Configuration dialog box and clicking Properties followed by OK. A message box appears indicating that a post-mortem event buffer has been found. Click OK and return to the Control window. The post-mortem event log is now represented in the summary and is available for upload in exactly the same manner as other logs.

Subsequent analysis of the log should now reveal those events leading up to the demise of the application.

Configuring Post-Mortem Mode Without the GUI

You can configure post-mortem mode programmatically. The following example shows how to set up the log, collect data, and upload data after a reboot.

/* wvLib and rBuffLib initialized at system start up */  
 
#include "vxWorks.h" 
#include "wvLib.h" 
#include "private/wvBufferP.h" 
#include "private/wvUploadPathP.h" 
#include "private/wvFileUploadPathLibP.h"

In order to retrieve information after a reboot, the log header, task name buffer, and event buffer IDs must be remembered or stored along with the collected information in the non-zeroed memory.

BUFFER_ID           bufId; 
UPLOAD_ID           pathId; 
WV_UPLOAD_TASK_ID   upTaskId; 
WV_LOG_HEADER_ID    hdrId; 
WV_TASKBUF_ID       taskBufId;

To prepare the event log and start logging, create an event buffer in non-zeroed memory, allowing overwrite; this yields the bufId.

wvEvtLogInit (bufId); 
taskBufId = wvTaskNamesPreserve (postMortemPartId, 32); 
hdrId = wvLogHeaderCreate (postMortemPartId); 
wvEvtClassSet (WV_CLASS_1);         /* set to log class 1 events */ 
wvEvtLogStart ();

The system fails and reboots. Note that taskBufId, bufId, and hdrId must be preserved through the reboot so they can be used to upload the data. Creating the upload path yields the pathId.

wvLogHeaderUpload (hdrId, pathId); 
upTaskId = wvUploadStart (bufId, pathId, TRUE); 
wvUploadStop (upTaskId); 
wvTaskNamesUpload (taskBufId, pathId);

Complete the process by closing the upload path and destroying the event buffer.