wvlib.c

VXWORKS源代码

/* wvLib.c - event logging control library (WindView) */

/* Copyright 1994-2001 Wind River Systems, Inc. */


/*
modification history
--------------------
02x,26oct01,tcr  fix problem with half-word alignment in wvLogHeaderCreate()
02w,24oct01,tcr  Fix comment string for Diab compiler
02v,18oct01,tcr  move to VxWorks 5.5, add VxWorks Events
02u,03mar99,dgp  update to reference project facility instead of config.h
02t,31aug98,cth  FCS man page edit
02s,28aug98,dgp  FCS man page edit, change order of sections
02r,18aug98,cjtc event buffer full handled more gracefully (SPR 22133)
02q,06aug98,cth  added retry to upload path write on EWOULDBLOCK, updated docs
02p,16jul98,cjtc wvUploadStop returns status of upload task (SPR 21461)
02o,09jul98,cjtc fix problems with task name preservation (SPR 21350)
02n,26may98,dgp  final doc editing for WV 2.0
02m,14may98,cth  added lib man page, other doc changes
02l,13may98,cth  added continued upload if thresh bytes still in buffer, 
		 added ints locked on buffer access, added wvUploadTaskConfig
02k,07may98,dgp  clean up man pages for WV 2.0 beta release
02j,20apr98,cth  added wvLogHeaderCreate/Upload, changed wvEvtLogInit, cleanup
		 removed separate cont/defer upload priorities
02i,17apr98,cth  reworked event-log header uploading and storage, cleaned up,
		 added status to wvUpTaskId
02h,15apr98,cth  added tnHashTbl functions for post-mortem taskname preserving,
		 added wvTaskNameBufAdd, wvTaskNamesPreserve, wvTaskNamesUpload
02g,17feb98,pr   added memLib support for object instrumentation
02f,27jan98,cth  removed evtLogHeaderCreate, changed wvLibInit/2, added
		 wvEvtLogInit, changed upTask priority to 150, doc changes
02e,23jan98,pr   modified WV macros, deleted trgCheck binding.
02d,18dec97,cth  updated includes, removed tmp references, wvOn/Off, and
		 rBuffErrorHandler
02c,14dec97,pr   deleted some windview 1.0 variables.
02b,16nov97,cth  reworked for wv2.0
02a,26aug97,pr   modified evtLog functions initialization and added trgCheck.
            cth  added wvEvtLogDisable in the event of a buffer overflow.
01z,18aug97,pr   added temporary function pointer initializer for 
		 CTX level.
01y,11aug97,nps  fixed typo causing compilation problem.
01x,29jul97,nps  added ring buffer support.
01w,24jun97,pr   replaced evtLogTIsOn with evtInstMode
		 Added return (ERROR) for default case in wvEvtLogEnable
01v,09aug96,pr   deleted obj instrumentation functions from wvEvtLogEnable
01u,07aug96,pr   Added object instrumentation functions to wvEvtLog[Enable
                 ,Disable] for SPR #6998.
01t,11jul96,pr   added ifdef for PPC function evtLogT1_noTS
01s,08jul96,pr   added evtLogT1_noTS
01r,03feb95,rhp  doc tweaks from last printed version of man pages
01q,01feb95,rhp  lib man page: add SEE ALSO ref to User's Guide
01p,15sep94rdc   wvEvent insures logging is enabled to minimize overhead
		 when logging is turned off.
01o,20oct94,rdc  increased evtTask stack size.
01n,14apr94,smb  Changes made to wvObjInst to treat task objects and other
		 system object instrumentation differently.
01m,05apr94,smb  documentation modifications.
01l,30mar94,smb  fixed event buffer overflow race.
01k,07mar94,smb  changed prototypes for OSE functionality
		 removed PASSIVE_MODE
		 documentation modifications
01j,22feb94,smb  changed typedef EVENT_TYPE to event_t (SPR #3064)
01i,15feb94,smb  renamed collection modes for wvInstInit SPR #3049
		 parameter checking SPR #3050
		 added scratch-pad reset.
01h,01feb94,smb  fixed return values for wvEvtLog[Enable,Disable] SPR #2994 
		 object are not instrumented until specified SPR #2985
01g,24jan94,smb  added INT_RESTRICT to wvEvtLogEnable and wvEvtLogDisable
		 initialised function pointer for portable kernel
01f,19jan94,smb  documentation changes
		 wvEvtLog changes to wvEvtLogEnable and wvEvtLogDisable
		 tEvtTask() is no longer spawned in POST_MODE
		 added wvEvtLogStop(), wvOn() and wvOff routines
01e,18jan94,maf  tEvtTask() no longer calls connectionClose() upon event
		   buffer overflow (part of fix for SPR #2800).
		 tEvtTask() now uploads last buffer upon event buffer
		   overflow (SPR #2888).
01d,13jan94,c_s  adjusted documentation for wvEvent () and removed NOMANUAL.
                   (SPR #2870).	 
01c,04jan94,c_s  wvInstInit doesn't attempt to free user-supplied memory 
		   (SPR #2750).
01b,15dec93,smb  documentation additions
		 allows wvEvtLog() to be called multiple times.
01a,10dec93,smb  created
*/

/*
DESCRIPTION
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.

EVENT BUFFERS AND UPLOAD PATHS
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:
.CS
    int wvUploadMaxAttempts   /@ number of attempts to try writing @/
    int wvUploadRetryBackoff  /@ delay between tries (in ticks - 60/sec) @/
.CE

INITIALIZATION
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.

DETERMINING WHICH EVENTS ARE COLLECTED
There are three classes of events that can be collected.  They are:

.CS
    WV_CLASS_1              /@ Events causing context switches @/
    WV_CLASS_2	            /@ Events causing task-state transitions @/
    WV_CLASS_3	            /@ Events from object and system libraries @/
.CE

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:
.iP 
Using wvObjInst() allows individual objects (for example, 'sem1') to be 
instrumented.
.iP
Using wvSigInst() allows signals to be instrumented.
.iP
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.  
.LP

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.

CONTROLLING EVENT LOGGING
Once the class of events has been specified, event logging can be started
with wvEvtLogStart() and stopped with wvEvtLogStop().

CREATING AN EVENT LOG
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.

.SS "Deferred Upload"
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.

.CS
    /@ 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 @/
.CE

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.

.SS "Continuous Upload"
When uploading event data as it is still being logged to the event buffer
(continuous upload), simply rearrange the above calls:

.CS
    /@ 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 @/
.CE


.SS "Post-Mortem Event Collection"
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>.

.CS
    /@ 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 @/
.CE

INCLUDE FILES: wvLib.h eventP.h

SEE ALSO: rBuffLib, wvFileUploadPathLib, wvSockUploadPathLib,
wvTsfsUploadPathLib,
.I WindView User's Guide

INTERNAL
All buffer accesses are made with interrupts locked.

Event logging is started by setting the evtAction variable, which is done
by the WV_ACTION_SET macro.  This global variable acts as a guard around
all event points.  When the first byte of this 16-bit word is TRUE, the
windview event point will then check the global wvEvtClass to dertermine
if this event point belongs to any of the classes being logged.  The
second half of evtAction is used in the same way for triggering.  The
event points that should respond when evtAction's triggering half is TRUE
are determined by the trgEvtClass variable.

In the most common case, when neither windview nor triggering is being
used within the kernel, having two levels of variables (evtAction is the
first level, wvEvtClass and trgEvtClass are the second) reduces the work
at each event point to the testing of a single variable, evtAction.