WDB (Wave Database) API Header File to Access WDB
API Functions to process data contained in the Wave Database.
The read API uses WDB types defined in the wdb.h header file.
WDB-Read Datatypes
Reader Handle
The opaque Wread handle is used by all API functions.
typedef struct WreadStruct Wread;Scope ID
The opaque data type WreadScopeId is returned and used as arguments by the other API functions.
typedef int WreadScopeId;
#define WreadNullScopeId (WreadScopeId)(-1)
#define WreadInvalidScopeId (WreadScopeId)(-2)
#define WreadScopeIdIsNull(scpId) ((scpId) == WreadNullScopeId)
#define WreadScopeIdIsInvalid(scpId) ((scpId) == WreadInvalidScopeId)Variable ID
The opaque data type WreadVarId is returned and used as arguments by the other API functions.
typedef struct {
int id;
int mem;
} WreadVarId;
#define WreadNullVarId (-1)
#define WreadInvalidVarId (-2)
#define WreadFirstGrpVarId (-3)
#define WreadFirstCloneVarId -((int)(((unsigned)-1)>>2))
#define WreadNullMem (((unsigned)-1)>>2)
#define WreadVarIdIsNull(varId) ((varId).id == WreadNullVarId)
#define WreadVarIdIsInvalid(varId) ((varId).id == WreadInvalidVarId)
#define WreadVarIdIsNullMem(varId) ((varId).mem == WreadNullMem)
#define WreadVarIdSet(varId,i,m) ((varId).id = (i), (varId).mem = (m))WDB-Read API Functions
Allocate and Free a WDB Reader
All reader access functions need a 'Wread*' handle, which is allocated by WreadAlloc() and freed by WreadFree(). After a call to WreadFree() the handle is invalid.
Wread* WreadAlloc(Wdb*);
void WreadFree( Wread*);Get Associated Wdb
Wdb* WreadGetWdb(Wread*);Get Header Information
The functions WreadDate() and WreadVersion() return date and version string. The functions WreadTimeFactor() and WreadTimeUnit() return timescale information.
const char* WreadDate( Wread*);
const char* WreadVersion( Wread*);
unsigned WreadTimeFactor(Wread*);
WdbTimeUnit WreadTimeUnit( Wread*);Convert Functions
The function WreadTime2Str() converts a given time step into a string. The returned value contains a integer followed by the time unit. If useBest is true it uses the smallest possible integer, by changing the unit given by timescale. The returned string is only valid until the next call to a Wread API function. The functions WreadStr2Time converts a string including unit into a time step. The functions WreadTime2Pix and WreadPix2Time convert pixel coordinates into time steps and vice versa. They return -1 or WdbTimeInvalid for wrong parameter. The function WreadCalcZoom changes the tfrom and tto time by a factor relative to the time range and tcenter. Factor can be positive to zoom in, or negative to zoom out. tcenter time is tried to stay near the same pixel position. If tcenter is WdbTimeInvalid the center of tfrom/tto is used.
const char* WreadTime2Str(Wread*, WdbTime, zBool useFraction, zBool useBest);
WdbTime WreadStr2Time(Wread*, const char* str, zBool allowFraction);
int WreadTime2Pix(Wread*, WdbTime tfrom, WdbTime tto,
int pixelCnt, WdbTime t);
WdbTime WreadPix2Time(Wread*, WdbTime tfrom, WdbTime tto,
int pixelCnt, int pix);
zBool WreadCalcZoom(Wread* wread, WdbTime* tfrom, WdbTime* tto,
double factor, WdbTime tmarker);Get Scope Information
The functions WreadScopeType() WreadScopeName() return the type and name of a given scope.
The function WreadScopeDown() is used to go down the hierarchy from a given scope, using 'WreadNullScopeId' as a start value.
The function WreadScopeSibling() returns the next scope in the same hierarchy as the given scope.
The function WreadScopeFind() search a scope under the given scope, using 'WreadNullScopeId' as the root value. Returns the scopeId or WreadNullScopeId if not found.
The function WreadScopeFindNamePath works like WreadScopeFind, but searches a list of scope names down the hierarchy, stating at the given scope or root.
In the case of an error the functions return 'WreadInvalidScopeId'.
The function WreadScopeDownVar() return the first variable for given scope or 'WreadNullScopeId' is there are no variables. In the case of an error the function return 'WreadInvalidVarId'.
The function WreadScopePath() is a service function to set a scope list (and it’s length) containing all scopes from top to the given scope. In case of an error False is returned. If fromDUT is true, the path does begin at the DUT hierarchy.
The function WreadScopeNamePath() is a service function works like WreadScopePath() but returns the names of the scopes. If fromDUT is true, the path does begin at the DUT hierarchy. The top name is taken from the DUTtopName.
WdbScopeType WreadScopeType( Wread*, WreadScopeId);
const char* WreadScopeName( Wread*, WreadScopeId);
WreadScopeId WreadScopeUp( Wread*, WreadScopeId);
WreadScopeId WreadScopeDown( Wread*, WreadScopeId);
WreadScopeId WreadScopeSibling(Wread*, WreadScopeId);
WreadScopeId WreadScopeFind( Wread*, WreadScopeId, const char* name);
WreadScopeId WreadScopeFindNamePath(Wread*, WreadScopeId, const char**, int);
WreadScopeId WreadScopeFindIcase( Wread*, WreadScopeId, const char* name,
ce_Bool icase);
WreadVarId WreadScopeDownVar(Wread*, WreadScopeId);
zBool WreadScopePath( Wread*, WreadScopeId, zBool fromDUT,
WreadScopeId**, int* len);
zBool WreadScopeNamePath(Wread*, WreadScopeId, zBool fromDUT,
const char***, int* len);DUT Information
The functions WreadSetDUT() and WreadDUTscope()/WreadDUTtopName set and get the DUT scope and top name.
void WreadSetDUT( Wread*, WreadScopeId, const char* topName);
WreadScopeId WreadDUTscope( Wread*);
const char* WreadDUTtopName(Wread*);Get Variable Information
The functions WreadVarType() WreadVarName() return the type and name of a given variable.
The function WreadVarScope() is used to get the scope of a given variable.
The function WreadVarSibling() returns the next scope in the same hierarchy as the given variable.
WreadVarWidth() gets the width of a vector or group. All other types get 0.
WreadVarBit() gets the bit number of a vector member
The functions WreadVarFirst() and WreadVarNext() can be used to iterate over all variables.
The functions WreadVarFirstMem(), WreadVarLastMem, WreadVarNextMem() and WreadVarPrevMem() can be used to iterate over all members of one variable. Returns 'WreadNullVarId' if there no more members.
WreadVarSibling(), WreadVarFirst() and WreadVarNext() return 'WreadNullVarId' if there no more variables.
WreadMem2Var() returns the parent variable of a member variable.
WreadVar2MemIdx() returns the member index.
WreadVar2Bus() returns the group or vector of the member.
WreadVarHasMem() get zTrue if id has member variable (vector or group).
WreadVarHasChanges() get zTrue if there are any value changes.
WreadVarHasVectorMem() get zTrue if group contains vector members.
WreadVarFind() returns a variable with the given name under the given scope or WreadNullVarId if it is not found.
WreadVarAliasType() returns the alias type or VarAliasInvalid for 'normal' variables.
WreadVarAliasInstName() return the inst name of pin aliases.
In the case of an error the functions return 'WreadInvalidVarId' or zFalse.
WdbVarType WreadVarType( Wread*, WreadVarId);
const char* WreadVarName( Wread*, WreadVarId);
WreadScopeId WreadVarScope( Wread*, WreadVarId);
WreadVarId WreadVarSibling(Wread*, WreadVarId);
WreadVarId WreadVarFirst( Wread*);
WreadVarId WreadVarNext( Wread*, WreadVarId);
zBool WreadVarWidth( Wread*, WreadVarId, int*);
zBool WreadVarBit( Wread*, WreadVarId, int*);
WreadVarId WreadVarFirstMem(Wread*, WreadVarId);
WreadVarId WreadVarNextMem( Wread*, WreadVarId);
WreadVarId WreadVarLastMem( Wread*, WreadVarId);
WreadVarId WreadVarPrevMem( Wread*, WreadVarId);
WreadVarId WreadMem2Var( Wread*, WreadVarId);
int WreadVar2MemIdx( Wread*, WreadVarId);
WreadVarId WreadVar2Bus( Wread*, WreadVarId);
zBool WreadVarHasMem( Wread*, WreadVarId);
zBool WreadVarHasChanges(Wread*, WreadVarId, zBool*);
zBool WreadVarHasVectorMem(Wread*, WreadVarId, zBool*);
WreadVarId WreadVarFind( Wread*, WreadScopeId, const char* name);
WreadVarId WreadVarAliasFind(Wread*, WreadScopeId, WdbAliasType,
const char* name, const char* iname);
WdbAliasType WreadVarAliasType( Wread*, WreadVarId);
const char* WreadVarAliasInstName(Wread*, WreadVarId);Hide Variable
WreadVarSetHide() and WreadVarGetHide() get be used to set/get the hide flag.
In the case of an error the functions return zFalse.
zBool WreadVarSetHide( Wread*, WreadVarId, zBool);
zBool WreadVarGetHide( Wread*, WreadVarId, zBool*);Dir Variable
WreadVarSetDir() and WreadVarGetDir() get be used to set/get the direction.
In the case of an error the functions return zFalse.
zBool WreadVarSetDir( Wread*, WreadVarId, WdbVarDir);
zBool WreadVarGetDir( Wread*, WreadVarId, WdbVarDir*);Get Signal Change Times
The functions WreadTimeFirst() and WreadTimeLast() return the minimum and maximum time.
The functions WreadTimePrev() and WreadTimeNext() return the time of the previous/next value change of the given array of variables 'varIdLst' starting with the given 'time' and a limit of 'tlimit'. The argument 'varIdLstLen' gives the size of the 'varIdLst' array. If no value change exits 'WdbTimeNoChange' is returned.
If there is an error 'WdbTimeInvalid' is returned.
WdbTime WreadTimeFirst(Wread*);
WdbTime WreadTimeLast( Wread*);
WdbTime WreadTimePrev(Wread*, WdbTime time, WdbTime tlimit,
WreadVarId varIdLst[], int varIdLstLen);
WdbTime WreadTimeNext(Wread*, WdbTime time, WdbTime tlimit,
WreadVarId varIdLst[], int varIdLstLen);Get the Value Type of a Variable
The function WreadValType() returns the type of a given signal. If there is an error 'WdbValInvalid' is returned.
WdbValType WreadValType(Wread*, WreadVarId varId);Get the Signal No of a Variable
The function WreadSigNo() returns the signal number of a given signal. Multiple variables may return the same signal number. If there is an error 'WdbValInvalid' is returned.
int WreadSigNo(Wread*, WreadVarId varId);Get Signal Value Changes
The functions WreadValueScalar() and WreadValueVector() set the value for a given variable at the given time into 'val'. For a vector the argument 'sz' defines the available space.
|
Note
|
Todo
The function WreadValueReal() is not yet implemented.
|
zBool WreadValueScalar(Wread*, WdbTime, WreadVarId, WdbValue*);
zBool WreadValueVector(Wread*, WdbTime, WreadVarId, WdbValue*, int sz);
zBool WreadValueReal( Wread*, WdbTime, WreadVarId, double*);
zBool WreadValueMember(Wread*, WdbTime, WreadVarId, WdbValue*, int sz);
zBool WreadValueGroup( Wread*, WdbTime, WreadVarId, WdbValue*, int sz);
zBool WreadValueScalarS(Wread*, WdbTime, WreadVarId, const char**);
zBool WreadValueVectorS(Wread*, WdbTime, WreadVarId, const char**);
zBool WreadValueRealS( Wread*, WdbTime, WreadVarId, const char**);
zBool WreadValueMemberS(Wread*, WdbTime, WreadVarId, const char**);
zBool WreadValueGroupS( Wread*, WdbTime, WreadVarId, const char**);
zBool WreadValueS( Wread*, WdbTime, WreadVarId, const char**);The function WreadValArray() sets an internal buffer with "pixel"-information for a width of 'pixelCnt' corresponding to a time range 'tfrom' to 'tto' (and + 1 '\0'). The start of each line is set into pixelLinesPtr. The number of lines (which is the same as valIdLstLen) is set into pixelLineCntPtr for a consistent API interface.
Each "pixel" stores one character depending on the different values which lie an this "pixel".
-
' ' - no values on this pixel
-
'0' - all values on this pixel are 0
-
'1' - all values on this pixel are 1
-
'B' - constant bus value (no x or z)
-
'*' - there are '0' and '1' on this pixel
-
'C' - value change in bus
-
'Z' - all values on this pixel are Z
-
'X' - all values on this pixel are X
-
'Y' - all values in the bus on this pixel are X
-
'z' - multiple values on this pixel, at least one 'Z'
-
'x' - multiple values on this pixel, at least one 'X'
If there is an error '0' is returned.
zBool WreadValArray(
Wread* wread,
WdbTime tfrom,
WdbTime tto,
WreadVarId* varIdLst,
int varIdLstLen,
int pixelCnt,
const char*** pixelLinesPtr,
int* pixelLineCntPtr
);Group Scalars to Virtual Vectors
-
WreadGroupCreate - return group varId or WreadInvalidVarId.
-
WreadGroupDelete - return zFalse on error.
-
WreadGroupFirst - returns group varId or WreadNullVarId.
-
WreadGroupNext - returns group varId or WreadNullVarId.
-
WreadGroupBuild - find groups by looking at scalar bus member names.
-
WreadGroupRename - set new name for given group.
-
WreadGroupRedefine - set new member list for group. The varIdList which defines the members of the group is stored with the LSB first.
WreadVarId WreadGroupCreate( Wread*,
const char* name,
WreadVarId varIdList[], int len,
WreadScopeId,
WdbVarType varType,
zBool hide,
zBool autoScope,
zBool expandVectors
);
zBool WreadGroupDelete( Wread*, WreadVarId);
WreadVarId WreadGroupFirst( Wread*);
WreadVarId WreadGroupNext ( Wread*, WreadVarId);
zBool WreadGroupBuild( Wread*, WreadScopeId,
WdbVarType varType, zBool hide,
zBool rangeDown);
zBool WreadGroupRename( Wread*, WreadVarId, const char* name);
zBool WreadGroupRedefine(Wread*,WreadVarId,
WreadVarId varIdLst[],
int len,
zBool hide,
zBool expandVectors
);
WreadVarId WreadGroupFind(
Wread* wread,
const char* groupName
);Clones
-
WreadCloneCreate - return Clone varId or WreadInvalidVarId.
-
WreadCloneDelete - return zFalse on error.
-
WreadCloneFirst - returns Clone varId or WreadNullVarId.
-
WreadCloneNext - returns Clone varId or WreadNullVarId.
WreadVarId WreadCloneCreate( Wread*, WreadVarId varId);
zBool WreadCloneDelete( Wread*, WreadVarId);
WreadVarId WreadCloneFirst( Wread*);
WreadVarId WreadCloneNext ( Wread*, WreadVarId);Get Time For Given Value
The functions WreadValuePrev() and WreadValueNext() return the time of the previous/next value change of the given array of variables 'varIdLst' starting with the given 'time' and a limit of 'tlimit', which matches the given value. The argument 'varIdLstLen' gives the size of the 'varIdLst' array. If no matching value exits 'WdbTimeNoChange' is returned.
If there is an error 'WdbTimeInvalid' is returned.
WdbTime WreadValuePrev(Wread*, WdbTime time, WdbTime tlimit,
WreadVarId varIdLst[], int varIdLstLen,
WdbValue* values, int w);
WdbTime WreadValueNext(Wread*, WdbTime time, WdbTime tlimit,
WreadVarId varIdLst[], int varIdLstLen,
WdbValue* values, int w);Get Error Message
If there was an error reported by one of the Wread API functions WreadErrorMsg returns a detailed message.
const char* WreadErrorMsg(Wread*);Set Error Message
Set API error message. For convenience returns always false.
zBool WreadSetErrorMsg(Wread*, const char* fmt, ...);Get Debug Flag For Util
Return true if util debug messages are enabled.
zBool WreadDebugUtil(Wread*);Scope Iterator Functions
Scope iterator support.
void* WreadForeachScopeInit(Wread* ,WreadScopeId);
zBool WreadForeachScopeNext(Wread* ,void*, WreadScopeId*);
void WreadForeachScopeFinit(Wread* ,void*);Var Iterator Functions
Var iterator support.
void* WreadForeachVarInit(Wread* ,WreadScopeId);
zBool WreadForeachVarNext(Wread* ,void*, WreadVarId*);
void WreadForeachVarFinit(Wread* ,void*);Clone Iterator Functions
Clone iterator support.
void* WreadForeachCloneInit(Wread* ,WreadScopeId);
zBool WreadForeachCloneNext(Wread* ,void*, WreadVarId*);
void WreadForeachCloneFinit(Wread* ,void*);Group Iterator Functions
Group iterator support.
void* WreadForeachGroupInit(Wread* ,WreadScopeId);
zBool WreadForeachGroupNext(Wread* ,void*, WreadVarId*);
void WreadForeachGroupFinit(Wread* ,void*);VarItem Iterator Functions
VarItem iterator support.
void* WreadForeachVarItemInit(Wread* ,WreadScopeId);
zBool WreadForeachVarItemNext(Wread* ,void*, WreadVarId*);
void WreadForeachVarItemFinit(Wread* ,void*);Member Iterator Functions
Member iterator support.
void* WreadForeachMemberInit(Wread* ,WreadVarId,
zBool lsbFirst, zBool msbFirst);
zBool WreadForeachMemberNext(Wread* ,void*, WreadVarId*);
void WreadForeachMemberFinit(Wread* ,void*);WreadVarId2Str
Converts a VarId to string. result needs to be freed.
zBool WreadVarId2Str(
Wread* reader,
WreadVarId varId,
char** str
);WreadStr2VarId
Converts a string to VarId.
zBool WreadStr2VarId(
Wread* reader,
const char* str,
WreadVarId* varId
);Usage Example
The following examples show how the above functions are used together.
Open a WDB for Reading and Create a Reader
WdbRestore is used to open an existing WDB file. WreadAlloc then creates a reader, which must be freed after use.
Example
#include "wdb/wdbread.h"
zBool ok = zTrue;
Wdb* wdb;
Wread* rdr;
wdb = WdbRestore("file.wdb", &callbacks, &ok);
if (!ok) ...
rdr = WreadAlloc(wdb);
...
WreadFree(wdb);Get Header Information
WreadDate, WreadVersion, WreadTimeScale are used to retrieve header information.
Example
Wread* rdr;
const char* str;
...
str = WreadDate(rdr);
str = WreadVersion(rdr);
str = WreadTimeScale(rdr);Get Scope Information
The hierarchical scope data is stored in a tree structure. It can be recursively traversed with the WreadScopeDown, WreadScopeSibling functions. The type, name and first variable of the scope can then be retrieved.
Example
...
void traverseScopes(Wread* rdr, WreadScopeId* parent) {
WreadScopeId* scopeid;
scopeid = WreadScopeDown(rdr, parent);
while (scopeid != WreadNullScopeId) {
WdbScopeType scopetype;
const char* name;
WreadVarId vid;
scopetype = WreadScopeType(rdr, scopeid);
name = WreadScopeName(rdr, scopeid);
vid = WreadScopeDownVar(rdr, scopeid);
...
traverseScopes(rdr, scopeid);
scopeid = WreadScopeSibling(rdr, scopeid);
}
}
...
traverseScopes(rdr, WreadNullScopeId);Get Variable Information
The variables can be iterated with two pair functions. Use WreadVarFirst and WreadVarNext for looping over all variables.
Example
WreadVarId vid;
...
vid = WreadVarFirst(rdr);
while (vid != WreadNullVarId) {
... process all variables
vid = WreadVarNext(rdr, vid);
}Use WreadScopeDownVar and WreadVarSibling for looping over all variables of a given scope.
Example
WreadScopeId* scopeid;
...
vid = WreadScopeDownVar(rdr, scopeid);
while (vid != WreadNullVarId) {
... process variables of current scope
vid = WreadVarSibling(rdr, vid);
}Get Value Changes
The value changes of a signal can be retrieved at any timestep with WreadScalarValue, WreadVectorValue etc. To get timesteps where some signals really change, WreadTimePrev or WreadTimeNext can be used.
Example
WdbTime t1, t2, t3;
WreadVarId vid1, vid2;
WreadVarId vidList[2];
WdbValue val1;
int width;
WdbValue val2[10];
const char* str;
...
t1 = WreadTimeFirst(rdr);
t2 = WreadTimeLast(rdr);
...
ok = WreadScalarValue(rdr, t1+100, vid1, &val1);
ok = WreadVectorValue(rdr, t2-500, vid2, val2, width);
...
vidList[0] = vid1;
vidList[1] = vid2;
t3 = WreadTimePrev(rdr, t1+200, 10000, vidList, 2);
t3 = WreadTimeNext(rdr, t1+900, 0, vidList, 2);
str = WreadTime2Str(rdr, t3);