📄 wvlib.html
字号:
<html><head><!-- /vobs/wpwr/docs/vxworks/ref/wvLib.html - generated by refgen from wvLib.c --> <title> wvLib </title></head><body bgcolor="#FFFFFF"> <hr><a name="top"></a><p align=right><a href="libIndex.htm"><i>VxWorks API Reference : OS Libraries</i></a></p></blockquote><h1>wvLib</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>wvLib</strong> - event logging control library (WindView) </p></blockquote><h4>ROUTINES</h4><blockquote><p><p><b><a href="./wvLib.html#wvLibInit">wvLibInit</a>( )</b> - initialize <b><a href="./wvLib.html#top">wvLib</a></b> - first step (WindView)<br><b><a href="./wvLib.html#wvLibInit2">wvLibInit2</a>( )</b> - initialize <b><a href="./wvLib.html#top">wvLib</a></b> - final step (WindView)<br><b><a href="./wvLib.html#wvEvtLogInit">wvEvtLogInit</a>( )</b> - initialize an event log (WindView)<br><b><a href="./wvLib.html#wvEvtLogStart">wvEvtLogStart</a>( )</b> - start logging events to the buffer (WindView)<br><b><a href="./wvLib.html#wvEvtLogStop">wvEvtLogStop</a>( )</b> - stop logging events to the buffer (WindView)<br><b><a href="./wvLib.html#wvEvtClassSet">wvEvtClassSet</a>( )</b> - set the class of events to log (WindView)<br><b><a href="./wvLib.html#wvEvtClassGet">wvEvtClassGet</a>( )</b> - get the current set of classes being logged (WindView)<br><b><a href="./wvLib.html#wvEvtClassClear">wvEvtClassClear</a>( )</b> - clear the specified class of events from those being logged (WindView)<br><b><a href="./wvLib.html#wvEvtClassClearAll">wvEvtClassClearAll</a>( )</b> - clear all classes of events from those logged (WindView)<br><b><a href="./wvLib.html#wvObjInstModeSet">wvObjInstModeSet</a>( )</b> - set object instrumentation on/off (WindView)<br><b><a href="./wvLib.html#wvObjInst">wvObjInst</a>( )</b> - instrument objects (WindView)<br><b><a href="./wvLib.html#wvSigInst">wvSigInst</a>( )</b> - instrument signals (WindView)<br><b><a href="./wvLib.html#wvEventInst">wvEventInst</a>( )</b> - instrument VxWorks Events (WindView)<br><b><a href="./wvLib.html#wvEvent">wvEvent</a>( )</b> - log a user-defined event (WindView)<br><b><a href="./wvLib.html#wvUploadStart">wvUploadStart</a>( )</b> - start upload of events to the host (WindView)<br><b><a href="./wvLib.html#wvUploadStop">wvUploadStop</a>( )</b> - stop upload of events to host (WindView)<br><b><a href="./wvLib.html#wvUploadTaskConfig">wvUploadTaskConfig</a>( )</b> - set priority and stacksize of <b>tWVUpload</b> task (WindView)<br><b><a href="./wvLib.html#wvLogHeaderCreate">wvLogHeaderCreate</a>( )</b> - create the event-log header (WindView)<br><b><a href="./wvLib.html#wvLogHeaderUpload">wvLogHeaderUpload</a>( )</b> - transfer the log header to the host (WindView)<br><b><a href="./wvLib.html#wvEvtBufferGet">wvEvtBufferGet</a>( )</b> - return the ID of the WindView event buffer (WindView)<br><b><a href="./wvLib.html#wvTaskNamesPreserve">wvTaskNamesPreserve</a>( )</b> - preserve an extra copy of task name events (WindView)<br><b><a href="./wvLib.html#wvTaskNamesUpload">wvTaskNamesUpload</a>( )</b> - upload preserved task name events (WindView)<br><p></blockquote><h4>DESCRIPTION</h4><blockquote><p>This 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.<p>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. <p>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).<p>Each of these three methods is explained in more detail in CREATING AN EVENT LOG.<p></blockquote><h4>EVENT BUFFERS AND UPLOAD PATHS</h4><blockquote><p>Many of the routines in <b><a href="./wvLib.html#top">wvLib</a></b> 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 <b><a href="./wvLib.html#top">wvLib</a></b> with the appropriate information for access. <p>The event buffering mechanism used by <b><a href="./wvLib.html#top">wvLib</a></b> is provided by <b><a href="./rBuffLib.html#top">rBuffLib</a></b>.The upload paths available for use with <b><a href="./wvLib.html#top">wvLib</a></b> are provided by<b><a href="./wvFileUploadPathLib.html#top">wvFileUploadPathLib</a></b>, <b><a href="./wvTsfsUploadPathLib.html#top">wvTsfsUploadPathLib</a></b> and <b><a href="./wvSockUploadPathLib.html#top">wvSockUploadPathLib</a></b>.<p>The upload mechanism backs off and retries writing to the upload pathif an error occurs during the write attempt with the errno <b>EAGAIN</b> or <b>EWOULDBLOCK</b>. Two global variables are used to set the amount of time toback off and the number of retries. The variables are:<pre> int wvUploadMaxAttempts /* number of attempts to try writing */ int wvUploadRetryBackoff /* delay between tries (in ticks - 60/sec) */</pre></blockquote><h4>INITIALIZATION</h4><blockquote><p>This library is initialized in two steps. The first step, done by calling<b><a href="./wvLib.html#wvLibInit">wvLibInit</a>( )</b>, associates event logging routines to system objects. This isdone when the kernel is initialized. The second step, done by calling<b><a href="./wvLib.html#wvLibInit2">wvLibInit2</a>( )</b>, associates all other event logging routines with theappropriate event points. Initialization is done automatically when<b>INCLUDE_WINDVIEW</b> is defined.<p>Before event logging can be started, and each time a new event buffer isused to store logged events, <b><a href="./wvLib.html#wvEvtLogInit">wvEvtLogInit</a>( )</b> must be called to bind theevent logging routines to a specific buffer.<p></blockquote><h4>DETERMINING WHICH EVENTS ARE COLLECTED</h4><blockquote><p>There are three classes of events that can be collected. They are:<p><pre> WV_CLASS_1 /* Events causing context switches */ WV_CLASS_2 /* Events causing task-state transitions */ WV_CLASS_3 /* Events from object and system libraries */</pre>The 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:<ul><li></li>Using <b><a href="./wvLib.html#wvObjInst">wvObjInst</a>( )</b> allows individual objects (for example, <b>sem1</b>) to be instrumented.<li></li>Using <b><a href="./wvLib.html#wvSigInst">wvSigInst</a>( )</b> allows signals to be instrumented.<li></li>Using <b><a href="./wvLib.html#wvObjInstModeSet">wvObjInstModeSet</a>( )</b> allows finer control over what type of objects areinstrumented. <b><a href="./wvLib.html#wvObjInstModeSet">wvObjInstModeSet</a>( )</b> allows types of system objects (for example,semaphores, watchdogs) to be instrumented as they are created. </ul><p>Logging 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.<p>To manipulate the class of events being logged, the following routines canbe used: <b><a href="./wvLib.html#wvEvtClassSet">wvEvtClassSet</a>( )</b>, <b><a href="./wvLib.html#wvEvtClassGet">wvEvtClassGet</a>( )</b>, <b><a href="./wvLib.html#wvEvtClassClear">wvEvtClassClear</a>( )</b>, and<b><a href="./wvLib.html#wvEvtClassClearAll">wvEvtClassClearAll</a>( )</b>. To log a user-defined event, <b><a href="./wvLib.html#wvEvent">wvEvent</a>( )</b> can be used. It is also possible to log an event from any point during execution using <b><a href="./dbgLib.html#e">e</a>( )</b>, located in <b><a href="./dbgLib.html#top">dbgLib</a></b>.<p></blockquote><h4>CONTROLLING EVENT LOGGING</h4><blockquote><p>Once the class of events has been specified, event logging can be startedwith <b><a href="./wvLib.html#wvEvtLogStart">wvEvtLogStart</a>( )</b> and stopped with <b><a href="./wvLib.html#wvEvtLogStop">wvEvtLogStop</a>( )</b>.<p></blockquote><h4>CREATING AN EVENT LOG</h4><blockquote><p>An event log consists of a header, a section of task names, and a list ofevents logged after calling <b><a href="./wvLib.html#wvEvtLogStart">wvEvtLogStart</a>( )</b>. As discussed above, there arethree common ways to upload an event log.<p></blockQuote><h4>Deferred Upload</h4><blockQuote>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.<p><pre> /* 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 */</pre>Routines which can be used as they are, or modified to meet the users needs,are located in <b>usrWindview.c</b>. These routines, <b>wvOn( )</b> and <b>wvOff( )</b>, provide away to produce useful event logs without using the host user interface ofWindView.<p></blockQuote><h4>Continuous Upload</h4><blockQuote>When uploading event data as it is still being logged to the event buffer(continuous upload), simply rearrange the above calls:<p><pre> /* 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 */</pre><p></blockQuote><h4>Post-Mortem Event Collection</h4><blockQuote>This library also contains routines that preserve task name informationthroughout event logging in order to produce post-mortem event logs:<b><a href="./wvLib.html#wvTaskNamesPreserve">wvTaskNamesPreserve</a>( )</b> and <b><a href="./wvLib.html#wvTaskNamesUpload">wvTaskNamesUpload</a>( )</b>.<p>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 the<b>EVENT_TASKNAME</b> 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.<p>Note that several of the routines in <b><a href="./wvLib.html#top">wvLib</a></b>, including<b><a href="./wvLib.html#wvTaskNamesPreserve">wvTaskNamesPreserve</a>( )</b>, 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.<p>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 <i>postMortemPartId</i>.<p><pre> /* 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 */</pre></blockquote><h4>INCLUDE FILES</h4><blockquote><p><b>wvLib.h</b> eventP.h<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./rBuffLib.html#top">rBuffLib</a></b>, <b><a href="./wvFileUploadPathLib.html#top">wvFileUploadPathLib</a></b>, <b><a href="./wvSockUploadPathLib.html#top">wvSockUploadPathLib</a></b>,<b><a href="./wvTsfsUploadPathLib.html#top">wvTsfsUploadPathLib</a></b>,<i>WindView User's Guide </i><p><hr>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -