wvlib.html

Vxworks API操作系统和驱动程序设计API。压缩的HTML文件

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS wvEventInst
    (
    int mode                  /* instrumentation mode */
    )
</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine instruments VxWorks Event activity.
<p>
If <i>mode</i> is <b>INSTRUMENT_ON</b>, instrumentation for VxWorks events is turned on;
if it is any other value (including <b>INSTRUMENT_OFF</b>), instrumentation for
VxWorks Events is turned off.
<p>
This routine has effect only if <b>INCLUDE_WINDVIEW</b> is defined in
<b>configAll.h</b> and event logging has been enabled for system objects.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
OK or ERROR.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./wvLib.html#top">wvLib</a></b>

<hr>
<a name="wvEvent"></a>
<p align=right>
<a href="rtnIndex.htm"><i>OS Libraries :  Routines</i></a></p>

</blockquote><h1>wvEvent(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong>wvEvent(&nbsp;)</strong> - log a user-defined event (WindView)</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS wvEvent
    (
    event_t usrEventId,       /* event */
    char *  buffer,           /* buffer */
    size_t  bufSize           /* buffer size */
    )
</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine logs a user event.  Event logging must have been started with
<b>wvEvtLogEnable(&nbsp;)</b> or from the WindView GUI to use this routine.  
The <i>usrEventId</i> should be in the
range 0-25535.  A buffer of data can be associated with the event;
<i>buffer</i> is a pointer to the start of the data block, and <i>bufSize</i> is its
length in bytes.  The size of the event buffer configured with
<b>wvInstInit(&nbsp;)</b> should be adjusted when logging large user events.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
OK, or ERROR if the event can not be logged.
<p>
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./wvLib.html#top">wvLib</a></b>, <b><a href="./dbgLib.html#top">dbgLib</a></b>, <b><a href="./dbgLib.html#e">e</a>(&nbsp;)</b>
<p>


<hr>
<a name="wvUploadStart"></a>
<p align=right>
<a href="rtnIndex.htm"><i>OS Libraries :  Routines</i></a></p>

</blockquote><h1>wvUploadStart(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong>wvUploadStart(&nbsp;)</strong> - start upload of events to the host (WindView)</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>WV_UPLOADTASK_ID wvUploadStart
    (
    BUFFER_ID bufId,             /* event data buffer ID */
    UPLOAD_ID pathId,            /* upload path to host */
    BOOL      uploadContinuously /* upload continuously if true */
    )
</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
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 <i>uploadContinuously</i> 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 <b>tWVUpload</b>.  The buffer to upload is 
identified by <i>bufId</i>, and the upload path to use is identified by <i>pathId</i>.
<p>
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.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
A valid <b>WV_UPLOADTASK_ID</b> 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.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./wvLib.html#top">wvLib</a></b>

<hr>
<a name="wvUploadStop"></a>
<p align=right>
<a href="rtnIndex.htm"><i>OS Libraries :  Routines</i></a></p>

</blockquote><h1>wvUploadStop(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong>wvUploadStop(&nbsp;)</strong> - stop upload of events to host (WindView)</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS wvUploadStop
    (
    WV_UPLOADTASK_ID upTaskId
    )
</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
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.
<p>
This task blocks until the buffer is emptied, and then frees memory
associated with <i>upTaskId</i>.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
OK if the upload task terminates successfully, 
or ERROR either if <i>upTaskId</i> is invalid or if the upload task terminates
with an ERROR.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./wvLib.html#top">wvLib</a></b>

<hr>
<a name="wvUploadTaskConfig"></a>
<p align=right>
<a href="rtnIndex.htm"><i>OS Libraries :  Routines</i></a></p>

</blockquote><h1>wvUploadTaskConfig(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong>wvUploadTaskConfig(&nbsp;)</strong> - set priority and stacksize of <b>tWVUpload</b> task (WindView)</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>void wvUploadTaskConfig
    (
    int stackSize,            /* the new stack size for tWVUpload */
    int priority              /* the new priority for tWVUpload */
    )
</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine sets the stack size and priority of future instances of 
the event-data upload task, created by calling <b><a href="./wvLib.html#wvUploadStart">wvUploadStart</a>(&nbsp;)</b>.  The default
stack size for this task is 5000 bytes, and the default priority is 150.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
N/A
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./wvLib.html#top">wvLib</a></b>

<hr>
<a name="wvLogHeaderCreate"></a>
<p align=right>
<a href="rtnIndex.htm"><i>OS Libraries :  Routines</i></a></p>

</blockquote><h1>wvLogHeaderCreate(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong>wvLogHeaderCreate(&nbsp;)</strong> - create the event-log header (WindView)</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>WV_LOG_HEADER_ID wvLogHeaderCreate
    (
    PART_ID memPart           /* partition where header should be stored */
    )
</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine creates the header of <b>EVENT_CONFIG</b>, <b>EVENT_BUFFER</b>, and <b>EVENT_BEGIN</b>
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.
<p>
This routine should be called after <b><a href="./wvLib.html#wvEvtLogInit">wvEvtLogInit</a>(&nbsp;)</b> 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.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
A valid <b>WV_LOG_HEADER_ID</b>, or NULL if memory can not be allocated.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./wvLib.html#top">wvLib</a></b>

<hr>
<a name="wvLogHeaderUpload"></a>
<p align=right>
<a href="rtnIndex.htm"><i>OS Libraries :  Routines</i></a></p>

</blockquote><h1>wvLogHeaderUpload(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong>wvLogHeaderUpload(&nbsp;)</strong> - transfer the log header to the host (WindView)</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS wvLogHeaderUpload
    (
    WV_LOG_HEADER_ID pHeader, /* pointer to the header */
    UPLOAD_ID        pathId   /* path by which to upload to host */
    )
</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This functions transfers the log header events (<b>EVENT_BEGIN</b>, <b>EVENT_CONFIG</b>,
<b>EVENT_BUFFER</b>) to the host.  These events were saved to a local buffer
with the call to <b><a href="./wvLib.html#wvLogHeaderCreate">wvLogHeaderCreate</a>(&nbsp;)</b>.  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.
<p>
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.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
OK, or ERROR if there is trouble with the upload path.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./wvLib.html#top">wvLib</a></b>

<hr>
<a name="wvEvtBufferGet"></a>
<p align=right>
<a href="rtnIndex.htm"><i>OS Libraries :  Routines</i></a></p>

</blockquote><h1>wvEvtBufferGet(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong>wvEvtBufferGet(&nbsp;)</strong> - return the ID of the WindView event buffer (WindView)</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>BUFFER_ID wvEvtBufferGet (void)</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
</blockquote><h4>RETURNS</h4><blockquote><p>
The event buffer ID if one exists, otherwise NULL.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./wvLib.html#top">wvLib</a></b>

<hr>
<a name="wvTaskNamesPreserve"></a>
<p align=right>
<a href="rtnIndex.htm"><i>OS Libraries :  Routines</i></a></p>

</blockquote><h1>wvTaskNamesPreserve(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong>wvTaskNamesPreserve(&nbsp;)</strong> - preserve an extra copy of task name events (WindView)</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>TASKBUF_ID wvTaskNamesPreserve
    (
    PART_ID memPart,          /* memory where preserved names are stored */
    int     size              /* must be a power of 2 */
    )
</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine initializes the data structures and instrumentation necessary
to allow WindView to store an extra copy of each <b>EVENT_TASKNAME</b> event,
which is necessary for post-mortem analysis.  This routine should be called
after <b><a href="./wvLib.html#wvEvtLogInit">wvEvtLogInit</a>(&nbsp;)</b> has been called, and before event logging is started.
<p>
If this routine is called before event logging is started, all
<b>EVENT_TASKNAME</b> 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.
<p>
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.
<p>
The buffer size must be a power of two.
<p>
This routine sets the event class <b>WV_CLASS_TASKNAMES_PRESERVE</b>, which can
be turned off by calling <b><a href="./wvLib.html#wvEvtClassClear">wvEvtClassClear</a>(&nbsp;)</b> or <b><a href="./wvLib.html#wvEvtClassSet">wvEvtClassSet</a>(&nbsp;)</b>.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
A valid <b>TASKBUF_ID</b> to be used for later uploading, or NULL if 
not enough memory exists to create the task buffer.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./wvLib.html#top">wvLib</a></b>

<hr>
<a name="wvTaskNamesUpload"></a>
<p align=right>
<a href="rtnIndex.htm"><i>OS Libraries :  Routines</i></a></p>

</blockquote><h1>wvTaskNamesUpload(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong>wvTaskNamesUpload(&nbsp;)</strong> - upload preserved task name events (WindView)</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS wvTaskNamesUpload
    (
    TASKBUF_ID taskBufId,     /* taskname event buffer to upload */
    UPLOAD_ID  pathId         /* upload path id */
    )
</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine uploads task name events, saved after calling 
<b><a href="./wvLib.html#wvTaskNamesPreserve">wvTaskNamesPreserve</a>(&nbsp;)</b>, 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.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
OK, or ERROR if the upload path or task name buffer is invalid.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./wvLib.html#top">wvLib</a></b>

</body>
</html>