![[Contents]](icons/contents.gif){kind=icon}
![[Index]](icons/index.gif){kind=icon}
![[Prev]](icons/prev.gif){kind=icon}
![[Next]](icons/next.gif){kind=icon}
In WindView, the upload mode and the upload path are separately configurable and separately tunable to make optimal use of target memory and the communication bandwidth.
Configuring the upload mode allows you to specify whether data is uploaded when you request it, automatically during event collection, or after an application failure. This allows you to balance the amount of data you expect to collect with the amount of intrusion caused by data upload.
In addition to these alternative upload modes, the upload path can be specified in a variety of configurations. The default path is through the target server, like other Tornado tools. This is done using a new feature called TSFS (see the VxWorks Programmer's Guide: Local File Systems). TSFS can be used to send data to the WindView view graph for immediate analysis, to a file, or to the Event Receive tool. If network facilities are included on the target, data can be sent directly to the host using a TCP/IP socket or NFS can be used to write data directly to a file. Additional target resources and additional configuration effort are required for the TCP/IP and NFS paths, or to configure another destination, such as Event Receive, for either a TSFS or a TCP/IP socket.
Deferred upload is the default 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 examine it as fast as it is generated, so a real-time analysis is not possible anyway.
WindView optimizes deferred upload mode with the following facilities:
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.
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 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).
|
|
|||||||||||||||||||
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 Upload Configuration 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.
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.
When Windview is connected to a target configured in this way, it is possible to configure the post-mortem memory region easily.
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 */
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.
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.
WindView supports two separate paths for uploading data from the target to the host: a path through the target server, and a path directly to the host. The path through the target server is supported by TSFS and allows you to send your event data to either a file (any file the target can open) or a TSFS socket (usually the view graph). For more information on TSFS, see the VxWorks Programmer's Guide: Local File Systems. The path directly to the host is supported by the target network facilities. You can send your event data to any file the target can open, or to a target-native TCP/IP socket (if you have the optional WindView product installed). (See Figure 8-2.)
In order to use TSFS to upload WindView data to either a file or the view graph, the target server must be started with TSFS enabled and set to -RW. A typical target server command line, which is displayed in the Configure Target Servers dialog box, is as follows:
tgtsvr.exe 150.50.50.50 -n t50-150 -c E:\wpwr\target\config\mv177\vxWorks
-V -R C:\Products\WindView\eventLogs -RW
In this example, the root is C:\Products\WindView\eventLogs and -RW is specified. This means that event logs will be saved in the root directory, which will appear in the configuration screen as /tgtsvr. Specifying -RW allows you to write event logs to the file. For more information, see the VxWorks Programmer's Guide: Local File Systems.
The only configuration steps required to use the target server path to a file are described in File via TSFS. The target server must have a TSFS root specified, which must be read/write. The root must be a path visible to the target server. If the machine running the target server is different from the one running WindView, you may make the root reference a mapped network drive.
The default hostname for TSFS sockets is your WindView host and the default port is 6164. You can change the hostname or use the host IP number to send the event log to another host; hostname is resolved by the target server on the host. Each time you open a view graph using New>WindView Log on the main File menu, the port increments by 1; you must be sure that the port specified in the Upload Configuration dialog box matches the port the view graph is using. The Event Receive tool uses port 6164 by default; if you want Event Receive to use a different port, you must change it both here and in the Event Receive configuration (see 8.4 The Event Receive Tool).
One alternative to the target server path is provided by TCP/IP network sockets. To use this facility, you must have a host-target Ethernet connection, including all the networking modules on the target. You must also open a socket on the host capable of accepting the socket connection from the target. You can do this either by opening a view graph using New>WindView Log on the main File menu or by starting Event Receive.
The default hostname is your WindView host and the default port is 6164. You can chose to use a different hostname or a host IP number to direct your data to a different host. Remember that the target must resolve hostname and it can only recognize hosts whose names have been added with routeAdd( ).
The Event Receive tool uses the default event port number, 6164. However, each time you open another new view graph, the port number it uses increments. Open your view graph and then replace the default in the configuration window with the actual port number shown at the top of the view graph.
Also, be aware that TCP/IP sockets are managed by the VxWorks task tNetTask. This task has a default priority of 50. If application-task priorities interfere with the scheduling of tNetTask, you must raise its priority with taskPrioritySet( ) in order to upload your WindView data.
This upload path sends your event data to any file your target can open. Usually you would have the Network File System installed on your target, as well as the TCP/IP network stack. For information about configuring NFS on your target, see the Network Programmer's Guide: File Access Applications. You must mount a file system on the target and specify the appropriate path in the configuration window for the file you wish to access.
This tool allows you to upload event logs to the host using a socket, and save them immediately in a file without configuring either TSFS or NFS on the target. This same functionality offered by Event Receive is also available in TSFS; nevertheless, Event Receive is maintained in WindView for your convenience. You might choose to use Event Receive in the following circumstances:
|
|
|||||||||||||||||||
Start event logging by pressing the
button, then start the target application.
By default, the collected raw event log is saved to the host file eventLog.wvr. You can change this name by starting Event Receive with the -o flag; note that if you do not specify the .wvr suffix, Event Receive adds this suffix to the file.
When you stop logging by pressing
, the host-target connection is closed and the Event Receive process exits. You can now import this event log into the WindView view graph using Open from the main Tools menu.
When Event Receive executes, its main window is the Event Data Receiver dialog box (Figure 8-8). Normally, this window opens when you start Event Receive, indicating that it is ready to receive target connections. However, if the socket where Event Receive expects to receive target connections is not available, the Setup dialog box opens first; see The Event Receive Setup Dialog Box for more information.
When the Event Data Receiver dialog box first opens, the list of event-log files is blank, and the two target information fields are not filled in; Event Receive fills in this information automatically when a target connects to it and begins transmitting data. If Event Receive has accepted connections from multiple targets simultaneously, the target-information fields reflect the most recent connection, unless one of the log files in the list is selected. To see the target name and IP address for any connection, select the corresponding log file from the list.
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
The Status column in the list of log files indicates the state of the connection to the target for that particular event log. The Status column shows the following states:
Because Event Receive is a passive receiver of event data, normally the data stream ends only when you stop data collection by clicking the Stop button in the Control window or when the target application calls wvOff( ) if it was started with wvOn( ) (see usrWindview.c). However, you can also stop data collection interactively for the currently selected log file, by clicking the Stop button in the Event Data Receiver dialog box.
You can use the Remove button to stop displaying information for the currently selected log file in the Event Data Receiver dialog box, after the connection is shown with status DONE. (Removing a log file from this list does not delete the log file.)
Start event logging with the Start button in the Control window or with wvOn( ), then start the target application. Close the host-target connection by clicking the Stop button in the Control window or by invoking wvOff( ) on the target.
By default, Event Receive saves event data to log files named after the target, and it accepts connections over TCP port 6164. You can change these and other related parameters by clicking the Setup button, which displays the dialog box shown in Figure 8-9.
The event port number is the host TCP/IP port over which either WindView or Event Receive listens for event data from the upload task, tWVUpload. WindView negotiates with tWVUpload on the selected target for an event port number, starting at TCP port 6164.
By contrast, Event Receive listens passively for connections from any target on the network, but on a particular port. The default event port number for Event Receive is also 6164; if your target uses a different event port, you must specify the port number explicitly in the Port Number field of the Event Receive Setup dialog box. To specify the port number on the target, use the Upload Configuration dialog box.
The remaining controls in the Event Receive Setup dialog box allow you to control where and how to save log files for incoming event data.
The Event Receive application is designed to run for extended periods, collecting multiple event logs. It can collect event logs either simultaneously (from different targets), or serially (whether from one target or from many). To distinguish multiple log files from one another, Event Receive names its log files using the following pattern:
