The WindView event-base API allows controlled access to a WindView event log through a C++ programming interface or a TCL programming interface. The Tcl interface is implemented using the C++ interface. The API is used by the WindView tool itself and is available for use by external applications, which may be written by third parties.

In order to maximize the power of the API, it is written in C++ and exports a number of classes to the client. These classes represent the event base, the event contexts (task contexts, interrupt contexts, and the idle context), and the individual events. These classes are called WVEventBase, WVContext, and WVEvent respectively, and are defined in installDir/host/include/wvapi.h.

There is also a class that acts as a cursor, which points into the event base and can be moved around to search for events of specific kinds, in one context or in any. This class is called WVCoords and is defined in wvapi.h.

In keeping with the latest C++ Standards, these public classes are implemented as containers similar to STL containers. They provide iterator classes which allow searching and extraction of sub-ranges using Standard Library algorithms.

The API ships as a dynamically-linked shared library and functions as a Tcl extension package that can be loaded into tclsh or wish at runtime with the load command.

To instantiate an object representing a complete event log, an object of class WVEventBase is created. Its constructor requires the name of the event-log file, usually ending in a .wvr suffix. If the file cannot be opened, is not in the required format, or some error occurs while building the in-memory data structures, a wv_error exception is thrown.

The WVEventBase class exposes the following useful public member functions:

WVEventBase(Tcl_Interp *pTcl=0); 

takes an optional Tcl interpreter and constructs an empty event base. If no Tcl interpreter is supplied, one is created.

STATUS load(const char *fileName); 

attempts to load an event-log file or files into the event base. The routine returns OK or ERROR and may throw wv_error exceptions if underlying file-system errors occur.

UINT32 size() const; 

returns the number of contexts in the event base.

WVContext operator[](unsigned index) const; 

returns a WVContext object from the index position in the event-base sequence of contexts.

const_iterator begin() const; 

returns a WVEventBase::const_iterator representing the start of the sequence.

const_iterator end() const; 

returns a WVEventBase::const_iterator representing the first position past the end of the sequence.

string name() const; 

returns the name of the event base.

int cpuId() const; 

returns the processor ID of the event base.

string eventName(const WVEvent& ev) const; 

returns the name of the event ev in human-readable format. This name is gathered from the event-description file loaded when the parser is loaded.

WVContext contextFromUniqueId(int uid) const; 

returns a WVContext object that corresponds to the unique ID given as the argument.

WV_TIME startTime() const;  
WV_TIME endTime() const; 

return the first and last timestamps of the events contained within the event base.

This section details the public member functions of the WVContext class, which represents a single context (task, interrupt, or idle) within the instrumented target. Internally, it is composed of a simple reference into the private internal data structures which takes up very little real application memory. Thus, it is safe for the application to build lists or vectors of these objects, for whatever reason.

The class also exposes an iterator type. It represents positions inside the context, viewing the context as a sequence of events and allowing application of STL standard algorithms to perform binary searches and other functions.

The public member functions of the WVContext class are:

UINT32 size() const; 

returns the size of the context when viewed as a sequence of events, in other words, the number of events in the sequence.

int uniqueId() const; 

returns a unique integer which distinguishes this context from all others within the same event base, including those that may have the same taskID( ) or name( ) values.

VX_ID taskId() const; 

returns the target-specific task ID, which may not be unique because task IDs can be reused by VxWorks. To uniquely identify a task within the event base, use the uniqueID( ) method to get a unique integer value.

string name() const; 

returns the task name (for example, tMainTask).

int priority() const; 

returns the task priority.

iterator begin() const; 

returns a WVContext::iterator representing the start of the sequence.

iterator end() const; 

returns a WVContext::iterator representing the first position past the end of the sequence.

BOOL isInterrupt() const; 

tests whether this is an interrupt context (as opposed to a task context).

BOOL isIdle() const; 

tests whether this is the idle context.

This section details the public member functions and public data members of the class WVEvent, which represents a single event from the event base. When you create an object of this class, it retrieves the real event data from the private event-base data structures within the API library and stores them in the private data members of the WVEvent object. You then access this data using public member functions.

Do not create too many WVEvent objects at once when dealing with a large event log, because each object takes up some small but significant amount of application memory when created. Instead, create events one at a time within a loop, by iterating over a WVContext with an WVContext::iterator object and dereferencing the iterator each time, as shown by the following example:

WVContext::iterator i; 
for (i = ctxt.begin(); i != ctxt.end(); i++) 
{ 
WVEvent e = *i; 
 
// do something useful with e like look at its time, its 
// parameters, etc... 
}

The following public member-functions are available from the class:

string name() const; 

returns a C++ SL string object containing the event name (for example, semTake).

UINT32 type() const; 

returns the event-type code as an integer number (for example, 10015).

WV_TIME timeStamp() const; 

returns the timestamp of the event in standard WindView format.

int numParams() const; 

returns the number of parameters to the event.

UINT32 param(int index) const; 

returns the indexth parameter of the event. The order, type, and meanings of the event parameters can be found in the event dictionary (see the online WindView User's Reference).

bool isStateChange() const; 

indicates whether a particular event was a state-change event.

UINT32 state() const; 

returns the current state of the task or context. It works for all events, not just state-change events.

Public member functions for comparison and equality of two event objects are also provided. These allow WVEvent objects to be stored in STL containers and manipulated by STL algorithms. Thus, an application can make a copy of small parts of the event base and manipulate it in many ways.

This class provides a simple way of traversing the event base and limiting or filtering the events displayed in various ways. Given an existing WVEventBase object, a WVCoords object can be created to look at events inside the event base, applying various restrictions. These restrictions include the type of event to look at, which can be any event or a specific type, and the context to search, which can be any context or a specific one.

The public member function move( ) and the operators ++ and -- move the WVCoords object through the event base. They return a boolean value indicating whether the movement was made or not. If not, no more events meeting the current search criteria could be found. The WVCoords object can be dereferenced using the operator *( ) and results in a WVContext::iterator, which can itself be dereferenced to retrieve an actual WVEvent object.

The following public member functions are available from the class:

WVCoords(); 

is the default constructor.

WVCoords(const WVEventBase*, WV_TIME, const WVContext&, EVENT_TYPE); 

is a constructor where the caller must provide a particular context and a particular event type.

WVCoords(const WVEventBase*, const WVContext::iterator&); 

is a constructor where the caller must provide an existing WVContext::iterator, in other words, an existing event location within the event base.

BOOL move(int direction); 

moves the coordinates object forwards (direction = 1) or backwards (direction = -1) through the event base, with possible restrictions applied.

static WVContext anyContext(); 

is a helper function which returns a pseudo-NULL value meaning any context. This is to used when constructing an object using the WVCoords constructor in the four-argument form.

static EVENT_TYPE anyEvent(); 

is a helper function which returns a pseudo-NULL value meaning any event. This is used when constructing an object using the WVCoords constructor in the four-argument form.

const WVEventBase& eventBase() const; 

returns the event-base object referenced by the coordinates object.

WVContext::iterator operator*() const; 

is the dereference operation; it returns an iterator indicating the specific event pointed to by the current coordinates.

BOOL operator++(int); 

is a shortcut for move(-1).

BOOL operator--(int); 

is a shortcut for move(1).

void contextLock(BOOL); 

locks the search to the current context.

void eventTypeLock(BOOL); 

locks the search to the current event type.

void eventTypeSet(EVENT_TYPE); 

sets the search target event type.

void contextSet(const WVContext&); 

sets the search target context.

void timeSet(WV_TIME); 

sets the search target time.

string contextName() const; 

returns the name of current context.

Table B-1 shows the compiler that can be used with the C++ API library on each host. The API library can only be expected to work with other applications if compiled with these toolchains.

In general, the WindView API classes report runtime errors with C++ exceptions. All standard library exceptions, like bad_alloc, are caught internally. The API classes re-throw wv_error exceptions with suitable human-readable messages plus an integer error code. The error-code values are defined in the header installDir/host/include/wvapi.h which ships with the library.

The Tcl programming interface provides a special command to load an event base into memory and to instantiate extra commands that allow the event base and its associated contexts to be manipulated directly from the command line. This procedure is written in C++ and uses the WindView C++ API to access the event base. The event-base library initializes a Tcl interpreter and then adds its own commands to the interpreter.

The syntax for wvEventBaseLoad is as follows:

wtxtcl> wvEventBaseLoad "filename" eventBaseRootName 

It returns a special handle which represents the event base. It also creates a number of new commands which work directly on the loaded event base and its task contexts; these commands start with the string specified by eventBaseRootName. The returned handle must be saved so it can be used with the command wvCoordsCreate to instantiate a coordinates object for navigating around the event base.

To load the event base logfile.wvr with the root name eb and save the handle to the constant ebHandle, enter the following:

wtxtcl> set ebHandle [wvEventBaseLoad "logfile.wvr" eb]

If the event-base root name is eb then a command eb is created, plus one extra command for each task-context identified by the context name. For example, if there is a context called tFtpdTask, it is accessible through the command eb.tFtpdTask.

The event-base commands accept the following extra command arguments:

returns a list of all context names.

returns a 2-element list containing the start and end timestamps.

removes all the context commands and frees all memory allocated for the event base.

The context commands accept the following arguments:

returns the task VxWorks ID.

returns the task priority.

returns the index of the nearest event to the given time.

returns M, the number of events in the context, numbered 0...M-1.

returns a list representing the Nth event in the context where N is an integer between 0 and M-1. Optional formatting of the output of this command is available via the -format option.

The default string format of an event returned by the N context command is:

eventName timeStamp argList state

where argList is a Tcl list with each item in the list being a name:value pair and state is a hexadecimal value representing the wind state bits defined in installDir/host/include/wvapi.h.

The output of an event record can be reformatted if the default style is inadequate for your needs. For example, the event parameters can be omitted or the timestamp can be printed first. In the context N command described above, an optional -format formatString can be appended. The formatString argument is a string containing literal characters and %-escaped field specifiers. The field specifiers can take the following values:

event name

time stamp

task state after the occurrence of the event

event parameters 1 to 7. Event parameters are always printed as a name:value pair.

For example, to print only event type and timestamp information, use the following option:

-format %n %t

The default format string (including backslashes escaping the open- and close-braces) is equivalent to the following:

-format %n %t \{ %1 %2 %3 %4 %5 %6 %7 \} %s 

To create a coordinates object, given an established event base, the command wvCoordsCreate is invoked with the following format:

wtxtcl> wvCoordsCreate coordsName ebHandle timeStamp [contextName] [eventType]

The ebHandle argument is be the result of a previous wvEventBaseLoad command. The coordsName argument is user specified; it is used for subsequent commands on the coordinates object. The time stamp must be a real number between the limits indicated by the result of an ebHandle interval operation. Optionally, the name of a context (one of the values returned by ebHandle names) can be supplied, and also an event type (the numeric value).

The command creates a new Tcl command, named after the coordsName given in the invocation, which represents the WVCoords object. It responds to the following commands, assuming coordsName is cc:

cc ++ 

move forward one event.

cc -- 

move backward one event.

cc * 

return a description of the event currently referenced by the coordinates object.

cc contextLock 0|[1 contextName] 

If the second argument is 0, this command unlocks the coordinates object from any particular context. If it is 1, the third argument must be supplied and the command locks the coordinates object to the specified context.

cc eventTypeLock 0|[1 eventType] 

If the second argument is 0, this command unlocks the coordinates object from any particular event type. If it is 1, the third argument must be supplied and the command locks the coordinates object to the specified event type (by full, upper-case name, as given in the event definition file). This would be, for example, EVENT_SEMTAKE rather than semTake.

cc print 

print out the internal indexing information or status of the coordinates object.

cc timeSet time 

set the internal time of the coordinates object to the given value, then move it to the next valid event after that time.

cc destroy 

remove the cc command and destroy the associated WVCoords object.

This section shows a typical session. User input is shown in bold.

The first command loads an event base, creating the command eb and its associated context commands. The second command prints the names of all contexts. The third command uses the command form eb.contextName with the taskId argument to find the task ID for tLogTask.

wtxtcl> wvEventBaseLoad "eventlog.wvr" eb 
<<informational stuff during loading>> 
wtxtcl> eb names 
INT3 INT6 tLogTask tWdbTask tTask1 idle 
wtxtcl> eb.tLogTask taskId 
3567312

The fourth command uses the names command again, but assigns its result to the variable cnames. The fifth command shows the number of events in tLogTask.

wtxtcl> set cnames [eb names] 
INT3 INT6 tLogTask tWdbTask tTask1 idle 
wtxtcl> eb.tLogTask events 
514

The sixth command iterates over all context names (using $cnames) and builds a command to print the number of events for each context, using eval.

wtxtcl> foreach ctx $cnames { set cmd "eb.$ctx" ; eval $cmd events } 
12 
23 
514 
211 
67 
478

The sixth command displays the interval that the event log covers. The seventh command illustrates the Nth index command for a context, printing the third event in the INT6 context.

wtxtcl> eb interval 
0.000000 1.804050 
wtxtcl> eb.INT6 3 
intEnt-6 0.0100023 {} 

Upon startup, the API library sources the Tcl script:

installDir/host/resource/tcl/app-config/WindView/database.tcl 

It reads the first event in the event log (which must be EVENT_CONFIG) to determine which kernel is running on the target. It loads the appropriate event-description files for that kernel. The file defines all the events the parser can handle. It defines the event name and its binary format (the number and type of its arguments) and it also includes human-readable information regarding the nominal meaning of each argument.

The file format is free-form plain text; each entry is separated by at least one blank line. Comment lines begin with #. An entry defines a single event format and has the style:

wvEvent EVENT_NAME value {[-notimestamp] [-nosearch] [-name=altName] 
                         [-helpid][-trigger][-icon]}{ 
    argType argName 
    argType argName [*] 
}

There can be between zero and seven arguments for a single event. The value is the 16-bit unsigned value (expressed in decimal) of the event-type. The argType field can be either UINT32 for an unsigned 32-bit integer or STRING for a textual or binary block, whose length is always defined by the previous field, which must be of type UINT32. The argName field is the name with which the argument is displayed in the WindView GUI; it must start with a lower-case character. The optional asterisk indicates the object ID argument (the argument that contains the unique object ID).

The -notimestamp option indicates that the event has no time stamp when emitted by the target, requiring that one be added by synthesis at the host. The -name argument allows a more user-friendly name to be added, if required. The -nosearch option indicates that events of this type are not reported by searches in the GUI.

The -helpid option specifies the help ID to bring up in the Event Dictionary. The -trigger option means that the event appears in the event list in the trigger dialogs. The -icon option selects a specific icon for the event. Several events can share the same icon.

Two sample event, taken from the vxworks.e file, are the following:

wvEvent EVENT_BEGIN 0 { -notimestamp -nosearch }| 
    UINT32 CPU 
    UINT32 bspSize 
    STRING bspName 
    UINT32 taskIdCurrent 
    UINT32 collectionMode 
    UINT32 revision 
}

wvEvent EVENT_SEMTAKE 10015 ( -name=semTake }{ 
    UINT32 recurse 
    UINT32 semOwner  
    UINT32 semId *  
}

This format allows user events to be given sophisticated descriptions.

The following C++ example uses the event base API to print out an entire event log in text form.