VxWorks Reference Manual : Libraries
wvLib - event logging control library (WindView)
wvLibInit( ) - initialize wvLib - first step (WindView)
wvLibInit2( ) - initialize wvLib - final step (WindView)
wvEvtLogInit( ) - initialize an event log (WindView)
wvEvtLogStart( ) - start logging events to the buffer (WindView)
wvEvtLogStop( ) - stop logging events to the buffer (WindView)
wvEvtClassSet( ) - set the class of events to log (WindView)
wvEvtClassGet( ) - get the current set of classes being logged (WindView)
wvEvtClassClear( ) - clear the specified class of events from those being logged (WindView)
wvEvtClassClearAll( ) - clear all classes of events from those logged (WindView)
wvObjInstModeSet( ) - set object instrumentation on/off (WindView)
wvObjInst( ) - instrument objects (WindView)
wvSigInst( ) - instrument signals (WindView)
wvEvent( ) - log a user-defined event (WindView)
wvUploadStart( ) - start upload of events to the host (WindView)
wvUploadStop( ) - stop upload of events to host (WindView)
wvUploadTaskConfig( ) - set priority and stacksize of tWVUpload task (WindView)
wvLogHeaderCreate( ) - create the event-log header (WindView)
wvLogHeaderUpload( ) - transfer the log header to the host (WindView)
wvEvtBufferGet( ) - return the ID of the WindView event buffer (WindView)
wvTaskNamesPreserve( ) - preserve an extra copy of task name events (WindView)
wvTaskNamesUpload( ) - upload preserved task name events (WindView)
This library contains routines that control event collection and upload of event data from the target to various destinations. The routines define the interface for the target component of WindView. When event data has been collected, the routines in this library are used to produce event logs that can be understood by the WindView host tools.
An event log is made up of a header, followed by the task names of each task present in the system when the log is started, followed by a string of events produced by the various event points throughout the kernel and associated libraries. In general, this information is gathered and stored temporarily on the target, and later uploaded to the host in the proper order to form an event log. The routines in this file can be used to create logs in various ways, depending on which routines are called, and in which order the routines are called.
There are three methods for uploading event logs. The first is to defer upload of event data until after logging has been stopped in order to eliminate events associated with upload activity from the event log. The second is to continuously upload event data as it is gathered. This allows the collection of very large event logs, that may contain more events than the target event buffer can store at one time. The third is to defer upload of the data until after a target reboot. This method allows event data to continuously overwrite earlier data in the event buffer, creating a log of the events leading to a target failure (a post-mortem event log).
Each of these three methods is explained in more detail in CREATING AN EVENT LOG.
Many of the routines in wvLib require access to the buffer used to store event data (the event buffer) and to the communication paths from the target to the host (the upload paths). Both the buffer and the path are referenced with IDs that provide wvLib with the appropriate information for access.
The event buffering mechanism used by wvLib is provided by rBuffLib. The upload paths available for use with wvLib are provided by wvFileUploadPathLib, wvTsfsUploadPathLib and wvSockUploadPathLib.
The upload mechanism backs off and retries writing to the upload path if an error occurs during the write attempt with the errno EAGAIN or EWOULDBLOCK. Two global variables are used to set the amount of time to back off and the number of retries. The variables are:
int wvUploadMaxAttempts /* number of attempts to try writing */ int wvUploadRetryBackoff /* delay between tries (in ticks - 60/sec) */
This library is initialized in two steps. The first step, done by calling wvLibInit( ), associates event logging routines to system objects. This is done when the kernel is initialized. The second step, done by calling wvLibInit2( ), associates all other event logging routines with the appropriate event points. Initialization is done automatically when INCLUDE_WINDVIEW is defined.
Before event logging can be started, and each time a new event buffer is used to store logged events, wvEvtLogInit( ) must be called to bind the event logging routines to a specific buffer.
There are three classes of events that can be collected. They are:
WV_CLASS_1 /* Events causing context switches */ WV_CLASS_2 /* Events causing task-state transitions */ WV_CLASS_3 /* Events from object and system libraries */The second class includes all of the events contained within the first class, plus additional events causing task-state transitions but not causing context switches. The third class contains all of the second, and allows logging of events within system libraries. It can also be limited to specific objects or groups of objects:
- Using wvObjInst( ) allows individual objects (for example, sem1) to be instrumented.
- Using wvSigInst( ) allows signals to be instrumented.
- Using wvObjInstModeSet( ) allows finer control over what type of objects are instrumented. wvObjInstModeSet( ) allows types of system objects (for example, semaphores, watchdogs) to be instrumented as they are created.
Logging events in Class 3 generates the most data, which may be helpful during analysis of the log. It is also the most intrusive on the system, and may affect timing and performance. Class 2 is more intrusive than Class 1. In general, it is best to use the lowest class that still provides the required level of detail.
To manipulate the class of events being logged, the following routines can be used: wvEvtClassSet( ), wvEvtClassGet( ), wvEvtClassClear( ), and wvEvtClassClearAll( ). To log a user-defined event, wvEvent( ) can be used. It is also possible to log an event from any point during execution using e( ), located in dbgLib.
Once the class of events has been specified, event logging can be started with wvEvtLogStart( ) and stopped with wvEvtLogStop( ).
An event log consists of a header, a section of task names, and a list of events logged after calling wvEvtLogStart( ). As discussed above, there are three common ways to upload an event log.
When creating an event log by uploading the event data after event logging has been stopped (deferred upload), the following series of calls can be used to start and stop the collection. In this example the memory allocated to store the log header is in the system partition. The event buffer should be allocated from the system memory partition as well. Error checking has been eliminated to simplify the example.
/* 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" BUFFER_ID bufId; UPLOAD_ID pathId; WV_UPLOAD_TASK_ID upTaskId; WV_LOG_HEADER_ID hdrId; /* @ To prepare the event log and start logging: */ /* Create event buffer in memSysPart, yielding bufId. */ wvEvtLogInit (bufId); hdrId = wvLogHeaderCreate (memSysPartId); wvEvtClassSet (WV_CLASS_1); /* set to log class 1 events */ wvEvtLogStart (); /* @ To stop logging and complete the event log. */ wvEvtLogStop (); /* Create an uplaod path using wvFileUploadPathLib, yielding pathId. */ wvLogHeaderUpload (hdrId, pathId); upTaskId = wvUploadStart (bufId, pathId, TRUE); wvUploadStop (upTaskId); /* Close the upload path and destroy the event buffer */Routines which can be used as they are, or modified to meet the users needs, are located in usrWindview.c. These routines, wvOn( ) and wvOff( ), provide a way to produce useful event logs without using the host user interface of WindView.
When uploading event data as it is still being logged to the event buffer (continuous upload), simply rearrange the above calls:
/* Includes and declarations. */ /* @ To prepare the event log and start logging: */ /* Create event buffer in memSysPart, yielding bufId. */ /* Create an uplaod path, yielding pathId. */ wvEvtLogInit (bufId); upTaskId = wvUploadStart (bufId, pathId, TRUE); hdrId = wvLogHeaderCreate (memSysPartId); wvLogHeaderUpload (hdrId, pathId); wvEvtClassSet (WV_CLASS_1); /* set to log class 1 events */ wvEvtLogStart (); /* @ To stop logging and complete the event log: */ wvEvtLogStop (); wvUploadStop (upTaskId); /* Close the upload path and destroy the event buffer */
This library also contains routines that preserve task name information throughout event logging in order to produce post-mortem event logs: wvTaskNamesPreserve( ) and wvTaskNamesUpload( ).Post-mortem event logs typically contain events leading up to a target failure. The memory containing the information to be stored in the log must not be zeroed when the system reboots. The event buffer is set up to allow event data to be logged to it continuously, overwriting the data collected earlier. When event logging is stopped, either by a system failure or at the request of the user, the event buffer may not contain the first events logged due to the overwriting. As tasks are created the EVENT_TASKNAME that is used by the WindView host tools to associate a task ID with a task name can be overwritten, while other events pertaining to that task ID may still be present in the event buffer. In order to assure that the WindView host tools can assign a task name to a context, a copy of all task name events can be preserved outside the event buffer and uploaded separately from the event buffer.
Note that several of the routines in wvLib, including wvTaskNamesPreserve( ), take a memory partition ID as an argument. This allows memory to be allocated from a user-specified partition. For post-mortem data collection, the memory partition should be within memory that is not zeroed upon system reboot. The event buffer, preserved task names, and log header should be stored in this partition.
Generating a post-mortem event log is similar to generating a deferred upload log. Typically event logging is stopped due to a system failure, but it may be stopped in any way. To retrieve the log header, task name buffer, and event buffer after a target reboot, these IDs must be remembered or stored along with the collected information in the non-zeroed memory. Also, the event buffer should be set to allow continuous logging by overwriting earlier event data. The following produces a post-mortem log. The non-zeroed memory partition has the ID postMortemPartId.
/* Includes, as in the examples above. */ 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 event buffer in non-zeroed memory, allowing overwrite, @ yielding bufId. */ wvEvtLogInit (bufId); taskBufId = wvTaskNamesPreserve (postMortemPartId, 32); hdrId = wvLogHeaderCreate (postMortemPartId); wvEvtClassSet (WV_CLASS_1); /* set to log class 1 events */ wvEvtLogStart (); /* @ 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. */ /* Create an uplaod path, yielding pathId. */ wvLogHeaderUpload (hdrId, pathId); upTaskId = wvUploadStart (bufId, pathId, TRUE); wvUploadStop (upTaskId); wvTaskNamesUpload (taskBufId, pathId); /* Close the upload path and destroy the event buffer */
wvLib.h eventP.h
rBuffLib, wvFileUploadPathLib, wvSockUploadPathLib, wvTsfsUploadPathLib, WindView User's Guide
wvLibInit( ) - initialize wvLib - first step (WindView)
void wvLibInit (void)
This routine starts initializing wvLib. Its actions should be performed before object creation, so it is called from usrKernelInit( ) in usrKernel.c.
N/A
wvLibInit2( ) - initialize wvLib - final step (WindView)
void wvLibInit2 (void)
This routine is called after wvLibInit( ) to complete the initialization of wvLib. It should be called before starting any event logging.
N/A
wvEvtLogInit( ) - initialize an event log (WindView)
void wvEvtLogInit ( BUFFER_ID evtBufId /* event-buffer id */ )
This routine initializes event logging by associating a particular event buffer with the logging functions. It must be called before event logging is turned on.
N/A
wvEvtLogStart( ) - start logging events to the buffer (WindView)
void wvEvtLogStart (void)
This routine starts event logging. It also resets the timestamp mechanism so that it can be called more than once without stopping event logging.
N/A
wvEvtLogStop( ) - stop logging events to the buffer (WindView)
void wvEvtLogStop (void)
This routine turns off all event logging, including event-logging of objects and signals specifically requested by the user. In addition, it disables the timestamp facility.
N/A
wvEvtClassSet( ) - set the class of events to log (WindView)
void wvEvtClassSet ( UINT32 classDescription /* description of evt classes to set */ )
This routine sets the class of events which are logged when event logging is started. classDescription can take the following values:
WV_CLASS_1 /* Events causing context switches */ WV_CLASS_2 /* Events causing task-state transitions */ WV_CLASS_3 /* Events from object and system libraries */See wvLib for more information about these classes, particularly Class 3.
N/A
wvLib, wvObjInst( ), wvObjInstModeSet( ), wvSigInst( )
wvEvtClassGet( ) - get the current set of classes being logged (WindView)
UINT32 wvEvtClassGet (void)
This routine returns the set of classes currently being logged.
The class description.
wvEvtClassClear( ) - clear the specified class of events from those being logged (WindView)
void wvEvtClassClear ( UINT32 classDescription /* description of evt classes to clear */ )
This routine clears the class or classes described by classDescription from the set of classes currently being logged.
N/A
wvEvtClassClearAll( ) - clear all classes of events from those logged (WindView)
void wvEvtClassClearAll (void)
This routine clears all classes of events so that no classes are logged if event logging is started.
N/A
wvObjInstModeSet( ) - set object instrumentation on/off (WindView)
STATUS wvObjInstModeSet ( int mode /* object instrumentation on/off */ )
This routine causes objects to be created either instrumented or not depending on the value of mode, which can be INSTRUMENT_ON or INSTRUMENT_OFF. All objects created after wvObjInstModeSet( ) is called with INSTRUMENT_ON and before it is called with INSTRUMENT_OFF are created as instrumented objects.
Use wvObjInst( ) if you want to enable instrumentation for a specific object or set of objects. Use wvSigInst( ) if you want to enable instrumentation for all signal activity.
This routine has effect only if INCLUDE_WINDVIEW is defined in configAll.h.
The previous value of mode or ERROR.
wvLib, wvObjInst( ), wvSigInst( )
wvObjInst( ) - instrument objects (WindView)
STATUS wvObjInst ( int objType, /* object type */ void * objId, /* object ID or NULL for all objects */ int mode /* instrumentation mode */ )
This routine instruments a specified object or set of objects and has effect when system objects have been enabled for event logging.
objType can be set to one of the following: OBJ_TASK (tasks), OBJ_SEM (semaphores), OBJ_MSG (message queues), or OBJ_WD (watchdogs). objId specifies the identifier of the particular object to be instrumented. If objId is NULL, then all objects of objType have instrumentation turned on or off depending on the value of mode.
If mode is INSTRUMENT_ON, instrumentation is turned on; if it is any other value (including INSTRUMENT_OFF) then instrumentation is turned off for objId.
Call wvObjInstModeSet( ) with INSTRUMENT_ON if you want to enable instrumentation for all objects created after a certain place in your code. Use wvSigInst( ) if you want to enable instrumentation for all signal activity.
This routine has effect only if INCLUDE_WINDVIEW is defined in configAll.h.
OK or ERROR.
wvLib, wvSigInst( ), wvObjInstModeSet( )
wvSigInst( ) - instrument signals (WindView)
STATUS wvSigInst ( int mode /* instrumentation mode */ )
This routine instruments all signal activity.
If mode is INSTRUMENT_ON, instrumentation for signals is turned on; if it is any other value (including INSTRUMENT_OFF), instrumentation for signals is turned off.
This routine has effect only if INCLUDE_WINDVIEW is defined in configAll.h and event logging has been enabled for system objects.
OK or ERROR.
wvEvent( ) - log a user-defined event (WindView)
STATUS wvEvent ( event_t usrEventId, /* event */ char * buffer, /* buffer */ size_t bufSize /* buffer size */ )
This routine logs a user event. Event logging must have been started with wvEvtLogEnable( ) or from the WindView GUI to use this routine. The usrEventId should be in the range 0-25535. A buffer of data can be associated with the event; buffer is a pointer to the start of the data block, and bufSize is its length in bytes. The size of the event buffer configured with wvInstInit( ) should be adjusted when logging large user events.
OK, or ERROR if the event can not be logged.
wvUploadStart( ) - start upload of events to the host (WindView)
WV_UPLOADTASK_ID wvUploadStart ( BUFFER_ID bufId, /* event data buffer ID */ UPLOAD_ID pathId, /* upload path to host */ BOOL uploadContinuously /* upload continuously if true */ )
This routine starts uploading events from the event buffer to the host. Events can be uploaded either continuously or in one pass until the buffer is emptied. If uploadContinuously is set to TRUE, the task uploading events pends until more data arrives in the buffer. If FALSE, the buffer is flushed without waiting, but this routine returns immediately with an ID that can be used to kill the upload task. Upload is done by spawning the task tWVUpload. The buffer to upload is identified by bufId, and the upload path to use is identified by pathId.
This routine blocks if no event data is in the buffer, so it should be called before event logging is started to ensure the buffer does not overflow.
A valid WV_UPLOADTASK_ID if started for continuous upload, a non-NULL value if started for one-pass upload, and NULL if the task can not be spawned or memory for the descriptor can not be allocated.
wvUploadStop( ) - stop upload of events to host (WindView)
STATUS wvUploadStop ( WV_UPLOADTASK_ID upTaskId )
This routine stops continuous upload of events to the host. It does this by making a request to the upload task to terminate after it has emptied the buffer. For this reason it is important to make sure data is no longer being logged to the buffer before calling this routine.
This task blocks until the buffer is emptied, and then frees memory associated with upTaskId.
OK if the upload task terminates successfully, or ERROR either if upTaskId is invalid or if the upload task terminates with an ERROR.
wvUploadTaskConfig( ) - set priority and stacksize of tWVUpload task (WindView)
void wvUploadTaskConfig ( int stackSize, /* the new stack size for tWVUpload */ int priority /* the new priority for tWVUpload */ )
This routine sets the stack size and priority of future instances of the event-data upload task, created by calling wvUploadStart( ). The default stack size for this task is 5000 bytes, and the default priority is 150.
N/A
wvLogHeaderCreate( ) - create the event-log header (WindView)
WV_LOG_HEADER_ID wvLogHeaderCreate ( PART_ID memPart /* partition where header should be stored */ )
This routine creates the header of EVENT_CONFIG, EVENT_BUFFER, and EVENT_BEGIN events that is required at the beginning of every event log. These events are stored in a packed array allocated from the specified memory partition. In addition to this separate header, this routine also logs all tasks active in the system to the event buffer for uploading along with the other events.
This routine should be called after wvEvtLogInit( ) is called. If uploading events continuously to the host, this routine should be called after the upload task is started. This ensures that the upload task is included in the snapshot of active tasks. If upload will occur after event logging has stopped (deferred upload), this routine can be called any time before event logging is turned on.
A valid WV_LOG_HEADER_ID, or NULL if memory can not be allocated.
wvLogHeaderUpload( ) - transfer the log header to the host (WindView)
STATUS wvLogHeaderUpload ( WV_LOG_HEADER_ID pHeader, /* pointer to the header */ UPLOAD_ID pathId /* path by which to upload to host */ )
This functions transfers the log header events (EVENT_BEGIN, EVENT_CONFIG, EVENT_BUFFER) to the host. These events were saved to a local buffer with the call to wvLogHeaderCreate( ). This routine should be called before any events or tasknames are uploaded to the host. The events in the header buffer must be the first things the parser sees.
If continuously uploading events, it is best to start the uploader, and then call this routine. If deferring upload until after event logging is stopped, this should be called before the uploader is started.
OK, or ERROR if there is trouble with the upload path.
wvEvtBufferGet( ) - return the ID of the WindView event buffer (WindView)
BUFFER_ID wvEvtBufferGet (void)
The event buffer ID if one exists, otherwise NULL.
wvTaskNamesPreserve( ) - preserve an extra copy of task name events (WindView)
TASKBUF_ID wvTaskNamesPreserve ( PART_ID memPart, /* memory where preserved names are stored */ int size /* must be a power of 2 */ )
This routine initializes the data structures and instrumentation necessary to allow WindView to store an extra copy of each EVENT_TASKNAME event, which is necessary for post-mortem analysis. This routine should be called after wvEvtLogInit( ) has been called, and before event logging is started.
If this routine is called before event logging is started, all EVENT_TASKNAME events that are produced by VxWorks are logged into the standard event buffer, and a copy of each is logged automatically to the task name buffer created by this routine. All tasks running when this routine is called are also added to the buffer. The events in this buffer can be uploaded after the other events have been uploaded, to provide the task names for any events in the log which no longer have a corresponding task name event due to wrapping of data in the buffers. Because there may be two copies of some of the task name events after the buffer data wraps around, the resultant log may have two task name events for the same task. This is not a problem for the parser.
Occasionally the task ID of a task is reused, and in this case, only the last instance of the task name event with a particular task ID is maintained.
The buffer size must be a power of two.
This routine sets the event class WV_CLASS_TASKNAMES_PRESERVE, which can be turned off by calling wvEvtClassClear( ) or wvEvtClassSet( ).
A valid TASKBUF_ID to be used for later uploading, or NULL if not enough memory exists to create the task buffer.
wvTaskNamesUpload( ) - upload preserved task name events (WindView)
STATUS wvTaskNamesUpload ( TASKBUF_ID taskBufId, /* taskname event buffer to upload */ UPLOAD_ID pathId /* upload path id */ )
This routine uploads task name events, saved after calling wvTaskNamesPreserve( ), to the host by the specified upload path. There is no particular order to the events uploaded. All the events contained in the buffer are uploaded in one pass. After all have been uploaded, the buffer used to store the events is destroyed.
OK, or ERROR if the upload path or task name buffer is invalid.