Data Upload

8.2 Data Upload Mode

The upload mode you specify determines when your event data is uploaded to the host:

Deferred upload mode uploads data when you request it. If you have not already stopped logging before requesting upload, WindView stops logging before uploading the data.

Continuous upload mode uploads data automatically and periodically while logging continues.

Post-mortem mode uploads data when you request it. It preserves collected data so you can upload it after a warm reboot of the target.

Deferred upload is the default upload mode. Data is collected first and uploaded after collection is complete. Not uploading data during the period you are examining minimizes the effect of logging on target performance and eliminates events associated with upload from the sample. In most cases, there is too much data to be able to examine it as fast as it is generated, so a real-time analysis is not possible anyway.

WindView 2.0 optimizes deferred upload mode with the following facilities:

The dynamic ring buffer (rBuff) allows maximum flexibility in utilizing available memory for logging (see 7.7 Dynamic Buffer Allocation).

Logging stops when the buffer is completely full so no data is overwritten.

Triggering provides a facility for focusing event collection on sequences of interest (see 6. Triggering).

Continuous Upload Mode

Continuous upload mode uploads data periodically as it is being logged. It allows you to collect more data than you have target memory available to store it, with the penalty of having the upload activity reflected in the log being captured.

Continuous upload mode delivers data to the host whenever the amount of data in the ring buffer passes the upload threshold. If data is being logged faster than it can be uploaded to the host, the ring buffer grows. When the rate of logging slows, the excess buffers are deallocated. If the ring buffer becomes full because it has grown to the maximum size or because the buffer cannot expand fast enough to accommodate peaks in event generation, logging stops.

Upload Threshold

The upload threshold is determined by WindView, and is proportional to the size of the buffers in the ring. The threshold minimizes the intrusion by WindView on the target by minimizing irregularities in the source and sink of the data. Data may be written to the ring buffer in short, intense bursts. When the amount of data in the ring reaches the threshold, the upload task (tWVUpload) is wakened and uploads data until the amount remaining falls below the threshold. The event source may continue to add data to the ring, and if it is added faster than it is uploaded, the ring continues to grow. When data collection stops, the buffers are flushed to upload any remaining data.

NOTE: Normally the default priority of 150 is appropriate for tWVUpload. On rare occasions, the priority may need to be adjusted. If higher-priority tasks execute often enough to prevent tWVUpload from executing, the event buffer cannot be uploaded when it becomes full. In this case, the logging mechanism turns itself off. For more information, see Configuring the Upload Task.

Post-Mortem Mode

Post-mortem analysis is configured to log data that can be used to determine the cause of an application failure. It requires placing the log buffers in a region of memory that is not overwritten when the target reboots.

Post-mortem mode allows you to recover WindView log data after a warm reboot of the target. This is useful for investigating the events leading up to an unrecoverable error on the target. It works by configuring the ring buffer in a region of memory that is preserved, that is, not overwritten during reboot. Shared memory and off-board memory are not overwritten on reboot. Many BSPs do not reinitialize areas of system memory that are not overwritten by the operating system during a warm reboot. If none of these is available, you can partition your system memory to reserve an area for your post-mortem buffer (see Configuring VxWorks to Reserve System Memory for Post-Mortem Mode).

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

The data of interest is typically the data collected just before the failure. For this reason, the ring buffer is set to wrap around if it overflows, overwriting earlier data. Any existing data in an individual buffer is lost as soon as the first byte in that buffer is overwritten. To minimize the amount of data lost in this way, WindView automatically configures a large number of small buffers in the ring buffer for post-mortem mode. The number of buffers in the ring depends on how much memory you assign to post-mortem storage in your buffer configuration.

WindView reserves the first four 32-bit words in the specified range for its own use. It creates a memory partition in the remainder, reserving a buffer in which to store task names and using the remainder for the ring buffer. The task name information is sent to the host with the logged data. This means that task names are retained in addition to task IDs at all times.

When you select Post-Mortem mode on the Control Properties dialog box, the Buffer Configuration portion of the dialog box changes. (See Figure 8-1.) Use this dialog box to specify the lower and upper addresses of the range where you want your post-mortem buffer stored. For example, suppose you have 0x4000000 bytes of system memory starting at address 0x0000000. If your target does not reinitialize memory on a warm reboot, you could enter 0x3f80000 in the sysMemTop box and 0x3ffffff in the sysPhysMemTop box to configure a 512K buffer. Or suppose you have 0x4000000 bytes of system memory plus an equal amount of shared memory assigned to the addresses 0x4000000-0x7ffffff. If you wished to use all the shared memory for your post-mortem buffer, you would enter 0x4000000 in the sysMemTop box and 0x7ffffff in the sysPhysMemTop box.

Figure 8-1: Post-Mortem Buffer Configuration

If your target does reinitialize the entire system partition during a warm reboot, and you have no other source of memory for your post-mortem buffer, you must reconfigure VxWorks to reserve a portion of the system memory so that it is not overwritten on reboot. This procedure is described in Configuring VxWorks to Reserve System Memory for Post-Mortem Mode.

WARNING: If you reconfigure your system to reserve a system memory partition for your post-mortem buffer, you must rebuild your VxWorks image, rebuild your boot ROM, reboot your target, and reset the WindView configuration by clicking Reset in the Collection Configuration dialog box to pick up these changes. The lower and upper address of the preserved area now appear in the Control Properties dialog box. Note that they are preset to correspond to 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 some BSPs return a preset, minimum value for onboard memory.

Configuring VxWorks to Reserve System Memory for Post-Mortem Mode

NOTE: The information in this section applies only to WRS-style BSPs. Although third-party BSP developers are encouraged to follow WRS conventions, it is not a requirement. Thus, memory size configuration mechanisms described here may differ for non-WRS BSPs. Consult the BSP vendor for more information. If you wish to adapt your BSP to follow WRS conventions, see Wind Technical Note #41: Reserving User Memory.

All Wind River Systems BSPs include a macro, USER_RESERVED_MEM, configurable if INCLUDE_MEMORY_CONFIG is selected. Set this macro to the size in bytes of the area you wish to reserve for the post-mortem buffer.

The memory reserved with this macro is immediately after the top of memory used by VxWorks; thus, you can use the return value of sysMemTop( ) to point to the reserved block of memory. All Wind River Systems BSPs include a routine called sysPhysMemTop( ) in sysLib.c whose result is the top of all local memory, as opposed to the top of memory used by VxWorks. Thus to reserve 512K of memory for your post-mortem log, change USER_RESERVED_MEM to (0x80000) on the INCLUDE_MEMORY_CONFIG Params tab or make the following change in config.h:

#define USER_RESERVED_MEM   (0x80000)     /* number of reserved bytes */

Rebuilding the Boot ROM After Reserving System Memory

Note that the VxWorks boot ROM must be rebuilt when you use this method of configuring for post-mortem mode. To make sure that the boot process does not clear the memory you reserve for the event buffer, you must rebuild the boot ROM (as well as the VxWorks system image) with the changes to memory allocation described in the previous section.

For instructions on rebuilding VxWorks and on rebuilding boot ROMs, see the Tornado User's Guide: Projects. After you rebuild the boot ROM and system image, verify that the target still runs as expected, that the reserved area of local memory is not used by the system image, and that the reserved area of local memory is not cleared during a reboot.

Configuring the Upload Task

The upload task, tWVUpload, uploads the contents of the event buffer to the host.

In deferred analysis and post-mortem modes, the task is spawned when upload is requested, empties the ring buffer, and exits. In continuous mode, the task is spawned when data collection is requested but before it starts, and it runs until logging is stopped, waiting for more data to be written to the buffers.

The default settings for tWVUpload are usually appropriate, but if necessary, you can configure the priority and stack size of tWVUpload by calling wvUploadTaskConfig( ).

wvUploadTaskConfig 
    ( 
    int stackSize,       /* the new stack size for tWVUpload */ 
    int priority         /* the new priority for tWVUpload */ 
    )

The default value of stackSize is 5000 bytes; the default of priority is 150.

If any higher-priority tasks execute often enough to prevent tWVUpload from executing, the event buffer cannot be uploaded. In the case of continuous mode, the logging mechanism turns itself off. In the case of deferred and post-mortem modes, the task will time out before upload occurs. If you see these symptoms, try increasing the priority level of tWVUpload.