/* 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 compiler02v,18oct01,tcr  move to VxWorks 5.5, add VxWorks Events02u,03mar99,dgp  update to reference project facility instead of config.h02t,31aug98,cth  FCS man page edit02s,28aug98,dgp  FCS man page edit, change order of sections02r,18aug98,cjtc event buffer full handled more gracefully (SPR 22133)02q,06aug98,cth  added retry to upload path write on EWOULDBLOCK, updated docs02p,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.002m,14may98,cth  added lib man page, other doc changes02l,13may98,cth  added continued upload if thresh bytes still in buffer, 		 added ints locked on buffer access, added wvUploadTaskConfig02k,07may98,dgp  clean up man pages for WV 2.0 beta release02j,20apr98,cth  added wvLogHeaderCreate/Upload, changed wvEvtLogInit, cleanup		 removed separate cont/defer upload priorities02i,17apr98,cth  reworked event-log header uploading and storage, cleaned up,		 added status to wvUpTaskId02h,15apr98,cth  added tnHashTbl functions for post-mortem taskname preserving,		 added wvTaskNameBufAdd, wvTaskNamesPreserve, wvTaskNamesUpload02g,17feb98,pr   added memLib support for object instrumentation02f,27jan98,cth  removed evtLogHeaderCreate, changed wvLibInit/2, added		 wvEvtLogInit, changed upTask priority to 150, doc changes02e,23jan98,pr   modified WV macros, deleted trgCheck binding.02d,18dec97,cth  updated includes, removed tmp references, wvOn/Off, and		 rBuffErrorHandler02c,14dec97,pr   deleted some windview 1.0 variables.02b,16nov97,cth  reworked for wv2.002a,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 wvEvtLogEnable01v,09aug96,pr   deleted obj instrumentation functions from wvEvtLogEnable01u,07aug96,pr   Added object instrumentation functions to wvEvtLog[Enable                 ,Disable] for SPR #6998.01t,11jul96,pr   added ifdef for PPC function evtLogT1_noTS01s,08jul96,pr   added evtLogT1_noTS01r,03feb95,rhp  doc tweaks from last printed version of man pages01q,01feb95,rhp  lib man page: add SEE ALSO ref to User's Guide01p,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 modifications01j,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 #298501g,24jan94,smb  added INT_RESTRICT to wvEvtLogEnable and wvEvtLogDisable		 initialised function pointer for portable kernel01f,19jan94,smb  documentation changes		 wvEvtLog changes to wvEvtLogEnable and wvEvtLogDisable		 tEvtTask() is no longer spawned in POST_MODE		 added wvEvtLogStop(), wvOn() and wvOff routines01e,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*//*DESCRIPTIONThis library contains routines that control event collection and upload ofevent data from the target to various destinations.  The routines definethe interface for the target component of WindView.  When event data hasbeen collected, the routines in this library are used to produce eventlogs that can be understood by the WindView host tools.An event log is made up of a header, followed by the task names of eachtask present in the system when the log is started, followed by a string ofevents produced by the various event points throughout the kernel andassociated libraries.  In general, this information is gathered and storedtemporarily on the target, and later uploaded to the host in the properorder to form an event log.  The routines in this file can be used tocreate logs in various ways, depending on which routines are called, and inwhich order the routines are called.  There are three methods for uploading event logs.  The first is to deferupload of event data until after logging has been stopped in order toeliminate events associated with upload activity from the event log.  Thesecond is to continuously upload event data as it is gathered.  Thisallows the collection of very large event logs, that may contain moreevents than the target event buffer can store at one time.  The third isto defer upload of the data until after a target reboot.  Thismethod allows event data to continuously overwrite earlier data in theevent buffer, creating a log of the events leading to a target failure (apost-mortem event log).Each of these three methods is explained in more detail in CREATING AN EVENT LOG.EVENT BUFFERS AND UPLOAD PATHSMany 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 bywvFileUploadPathLib, wvTsfsUploadPathLib and wvSockUploadPathLib.The upload mechanism backs off and retries writing to the upload pathif an error occurs during the write attempt with the errno 'EAGAIN' or 'EWOULDBLOCK'.  Two global variables are used to set the amount of time toback 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) @/.CEINITIALIZATIONThis library is initialized in two steps.  The first step, done by callingwvLibInit(), associates event logging routines to system objects.  This isdone when the kernel is initialized.  The second step, done by callingwvLibInit2(), associates all other event logging routines with theappropriate event points.  Initialization is done automatically whenINCLUDE_WINDVIEW is defined.Before event logging can be started, and each time a new event buffer isused to store logged events, wvEvtLogInit() must be called to bind theevent logging routines to a specific buffer.DETERMINING WHICH EVENTS ARE COLLECTEDThere 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 @/.CEThe second class includes all of the events contained within the firstclass, plus additional events causing task-state transitions but notcausing context switches.  The third class contains all of the second, andallows logging of events within system libraries.  It can also belimited to specific objects or groups of objects:.iP Using wvObjInst() allows individual objects (for example, 'sem1') to be instrumented..iPUsing wvSigInst() allows signals to be instrumented..iPUsing wvObjInstModeSet() allows finer control over what type of objects areinstrumented.  wvObjInstModeSet() allows types of system objects (for example,semaphores, watchdogs) to be instrumented as they are created.  .LPLogging events in Class 3 generates the most data, which may be helpfulduring analysis of the log.  It is also the most intrusive on the system,and may affect timing and performance.  Class 2 is more intrusive thanClass 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 canbe used:  wvEvtClassSet(), wvEvtClassGet(), wvEvtClassClear(), andwvEvtClassClearAll().  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 LOGGINGOnce the class of events has been specified, event logging can be startedwith wvEvtLogStart() and stopped with wvEvtLogStop().CREATING AN EVENT LOGAn event log consists of a header, a section of task names, and a list ofevents logged after calling wvEvtLogStart().  As discussed above, there arethree common ways to upload an event log..SS "Deferred Upload"When creating an event log by uploading the event data after event logginghas been stopped (deferred upload), the following series of calls can beused to start and stop the collection.  In this example the memoryallocated to store the log header is in the system partition.  The eventbuffer 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 @/.CERoutines 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 away to produce useful event logs without using the host user interface ofWindView..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 informationthroughout event logging in order to produce post-mortem event logs:wvTaskNamesPreserve() and wvTaskNamesUpload().Post-mortem event logs typically contain events leading up to a targetfailure.  The memory containing the information to be stored in the logmust not be zeroed when the system reboots.  The event buffer is set up toallow event data to be logged to it continuously, overwriting the datacollected earlier.  When event logging is stopped, either by a systemfailure or at the request of the user, the event buffer may not containthe first events logged due to the overwriting.  As tasks are created theEVENT_TASKNAME that is used by the WindView host tools to associate a taskID with a task name can be overwritten, while other events pertaining tothat task ID may still be present in the event buffer.  In order to assurethat the WindView host tools can assign a task name to a context, a copyof all task name events can be preserved outside the event buffer anduploaded separately from the event buffer.Note that several of the routines in wvLib, includingwvTaskNamesPreserve(), take a memory partition ID as an argument.  Thisallows memory to be allocated from a user-specified partition.  Forpost-mortem data collection, the memory partition should be within memorythat is not zeroed upon system reboot.  The event buffer, preserved tasknames, and log header should be stored in this partition.Generating a post-mortem event log is similar to generating a deferredupload 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 namebuffer, and event buffer after a target reboot, these IDs must be rememberedor stored along with the collected information in the non-zeroed memory.Also, the event buffer should be set to allow continuous logging byoverwriting 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 @/.CEINCLUDE FILES: wvLib.h eventP.hSEE ALSO: rBuffLib, wvFileUploadPathLib, wvSockUploadPathLib,wvTsfsUploadPathLib,.I WindView User's GuideINTERNALAll buffer accesses are made with interrupts locked.Event logging is started by setting the evtAction variable, which is doneby the WV_ACTION_SET macro.  This global variable acts as a guard aroundall event points.  When the first byte of this 16-bit word is TRUE, thewindview event point will then check the global wvEvtClass to dertermineif this event point belongs to any of the classes being logged.  Thesecond half of evtAction is used in the same way for triggering.  Theevent points that should respond when evtAction's triggering half is TRUEare determined by the trgEvtClass variable.In the most common case, when neither windview nor triggering is beingused within the kernel, having two levels of variables (evtAction is thefirst level, wvEvtClass and trgEvtClass are the second) reduces the workat each event point to the testing of a single variable, evtAction.