![[Contents]](icons/contents.gif){kind=icon}
![[Index]](icons/index.gif){kind=icon}
![[Top]](icons/top.gif){kind=icon}
![[Prev]](icons/prev.gif){kind=icon}
![[Next]](icons/next.gif){kind=icon}
WindView 2.0 utilizes a dynamic ring buffer (rBuff) structure to support data collection. The new library, rBuffLib, provides a ring buffer structure which grows and shrinks dynamically during operation. The rBuff library introduces a new class of object, allowing rBuffs to be browsed and manipulated like other objects.
The size of each individual buffer and the minimum and maximum number of buffers are configured when the buffer ring is created. The library initially allocates the minimum number plus one additional buffer for immediate addition to the ring if necessary. If these buffers are filled, more buffers are added until the ring reaches the maximum size. If data is read from the rBuff, the unused buffer memory is freed so that it may be used by other processes.
WindView allows you to configure the rBuff which holds the event log as it is captured and stored on the target. How the rBuff is configured affects how logging interacts with the target application and thus the quality of the resulting event log.
The optimum rBuff configuration is dependent on two factors:
The configuration of the rBuff has a significant impact on the frequency with which it is dynamically extended and, consequently, how much of this activity is represented in the log. Optimum values depend on whether you are using deferred or continuous upload mode.
In both deferred and continuous modes, the rBuff's memory requirements are sourced from the system memory partition, the general partition from which all malloc requests are sourced. Therefore it is important to consider the size of the rBuff carefully to ensure that it does not conflict with target application requirements.
The most effective way to use WindView is in deferred upload mode. In this mode the event data remains on the target during collection and can be uploaded to the host once logging is completed. The entire log must be stored on the target, which potentially requires a large ring buffer. If the system partition is exhausted to the granularity of one buffer block or if the specified maximum number of buffers is full, data collection stops. However, triggering can be used to focus the sequence captured, avoiding an unnecessarily large buffer requirement.
In deferred upload mode, users may want all available memory to be used to hold event data. The extendable ring of buffers can share available memory between the customer application and the buffers. In order to collect as much event data as possible within the constraints of the system and application, the user points the rBuff at the system memory partition, sets the maximum size to infinite by specifying 0xffffffff, and recreates the problem. The rBuff starts at the specified minimum size, allowing the application to allocate memory during initialization, and only begins extending the buffer when its preallocated buffer is full.
The limitation of this approach is that the activity necessary to extend the rBuff appears in the log. This makes it more difficult to determine exactly how the system will behave when logging is not active. To avoid the intrusion of buffer allocation on the log, you can pre-allocate the buffer space by setting the minimum number of buffers equal to the maximum number of buffers. If you choose this approach, configure the rBuff with a smaller number of large individual buffers.
In continuous upload mode, the data in the log is uploaded to the host periodically as it is captured. However, the network activity required to upload the data itself generates events that appear in the log. In addition, any activity required to resize the rBuff will be reflected in the log. This results in logs which are larger and more complex than would be required to represent the application activity alone.
In continuous upload mode, the user provides a minimum and maximum number of buffers. When an individual buffer is full, data is written to the next buffer. If there are no more buffers and the current number of buffers is less than the maximum, a new buffer is added. If a buffer is emptied and the current number is greater than the minimum, the empty buffer is removed. This implementation is flexible and dynamic. The logged data can fill all the memory available if necessary and if the maximum number of buffers specified is that large, but the memory is not reserved for logging if it is not needed.
The size of the individual buffers is used to determine when to start transferring the event data to the host. A smaller individual buffer size initiates upload sooner and more often. As there are variations in the rate at which events are generated on the target and at which the network and host can achieve upload, the rBuff may dynamically resize to accommodate the events stored on the target. Using a small individual size maximizes the possibility of a suitable area of memory being available to extend the rBuff.
On occasion you will notice that, although data is being uploaded to the host, the rBuff is still growing. This happens when the number of events generated by the upload process is greater than the number of events being uploaded. This is most likely to occur when you have specified AIL level logging and instrumented semLib because the upload implementation generates many semaphore events.
The ability to specify the minimum number of buffers to be retained avoids buffer thrashing, where the ring is repeatedly extended and shortened as the amount of data in the buffer crosses a particular threshold. Note that there is nothing special about the set of buffers that is originally allocated. As the ring of buffers is filled and then emptied, the initial set is just as likely to be freed as those that are subsequently allocated to meet demand. In a balanced system, the rBuff is not constantly resized; the ring of buffers remain at the original size and allows steady upload of event data.
For these reasons, when using continuous upload mode, configure the rBuff with a larger number of small sized individual buffers and adjust the minimum number of buffers if necessary to prevent thrashing.
In post-mortem mode, WindView automatically configures the number and size of buffers in the ring. The only configuration step you must take is to place your buffer in an area of memory that is not overwritten when VxWorks reboots (see Post-Mortem Mode).
The rBuff is managed by the task tWvRBuffMgr. The default priority of this task is 100. This priority is usually appropriate, particularly when you use either deferred upload mode or post-mortem mode. In some environments when you use continuous upload mode, tWvRBuffMgr is not high enough priority to be able to expand the number of buffers before they fill. If you find that the rBuff is overflowing in continuous mode, use wvRBuffMgrPrioritySet( ) to give tWvRBuffMgr a higher priority.
If you are using a target configuration with sufficient memory resource to dedicate a proportion to WindView, then the ring of buffers may be configured such that it has its individual buffers pre-allocated. This is achieved by configuring the minimum number of buffers in the ring equal to the maximum number of buffers.
If you are using a target with limited memory resource, then the ring buffer dynamic resizing facility should be used. This is done by allocating a low minimum number of buffers with a greater maximum number of buffers. In deferred mode, only those buffers required above the minimum, and for which space is available at the time of request, will be allocated. In continuous mode, the buffer will only be extended above the minimum when necessary to hold the upload backlog, and those extra buffers will be freed when not in use. Note, however, that when using a dynamically resizing buffer configuration, the ring buffer will not give up buffers it is holding to satisfy a request for memory made by another part of the system. Therefore, care should be taken when specifying the maximum ring buffer size.
When using post-mortem mode, the ring buffer is automatically configured to make appropriate use of the available memory dedicated to this purpose.
The precise ring buffer configuration used is dependent upon many factors such as relative host and target performance, network bandwidth, the rate at which the target application generates events, and the upload method used. Therefore it is advisable to experiment with the ring buffer and upload configuration if any of these factors is altered to find a configuration which best suits the development system.