WDB (Wave Database) API Header File to Create and Access a WDB
API Functions to create a file or in memory Wave Database and to process the waveform data.
WDB Datatypes
Time Data
All time data uses the WdbTime data type.
typedef zUInt64 WdbTime;
#define WdbTimeInvalid ((WdbTime)(-1))
#define WdbTimeNoChange ((WdbTime)(-2))
typedef enum {
WdbTimeUnitUndef = 0,
WdbTimeUnitSecond = 1,
WdbTimeUnitMilli = 2,
WdbTimeUnitMicro = 3,
WdbTimeUnitNano = 4,
WdbTimeUnitPico = 5,
WdbTimeUnitFemto = 6
} WdbTimeUnit;
Value Types
Signal value use the WdbValue enumeration.
typedef enum {
WdbVx=0,
WdbVz=1,
WdbV0=2,
WdbV1=3,
WdbVv=4,
WdbVw=5,
WdbV_=6, /* no value */
WdbV__=7 /* never stored */
} WdbValue;
Signal Number
The data type WdbSigNo is returned and used as arguments by the other API functions.
typedef int WdbSigNo;
#define WdbInvalidSigNo (-1)
Variable Types
Variable types use the WdbVarType enumeration.
typedef enum {
WdbVarUnknown,
WdbVarEvent,
WdbVarInteger,
WdbVarParameter,
WdbVarReal,
WdbVarReg,
WdbVarSupply0,
WdbVarSupply1,
WdbVarTime,
WdbVarTri,
WdbVarTriand,
WdbVarTrior,
WdbVarTrireg,
WdbVarTri0,
WdbVarTri1,
WdbVarWand,
WdbVarWire,
WdbVarWor,
WdbVarGroup,
WdbVarAlias,
WdbVarInvalid
} WdbVarType;
Alias Types
Types of alias variables.
typedef enum {
WdbAliasNone,
WdbAliasPin,
WdbAliasPort,
WdbAliasNet,
WdbAliasInvalid
} WdbAliasType;
Var Dir
Directions of variables.
typedef enum {
WdbVarDirNone,
WdbVarDirIn,
WdbVarDirOut,
WdbVarDirInOut,
WdbVarDirInvalid
} WdbVarDir;
Signal Types
Type of a signal and it’s value.
typedef enum {
WdbValUnknown,
WdbValScalar,
WdbValVector,
WdbValReal,
WdbValMember, /* of a vector or group */
WdbValGroup,
WdbValInvalid
} WdbValType;
Scope Types
Scope types use the WdbScopeType enumeration.
typedef enum {
WdbScopeUnknown,
WdbScopeModule,
WdbScopeTask,
WdbScopeFunction,
WdbScopeBegin,
WdbScopeFork,
WdbScopeInvalid
} WdbScopeType;
String Conversion Helpers
Helper functions to convert types to strings.
const char* WdbValue2Str(WdbValue value);
const char* WdbVarType2Str(WdbVarType vartype);
const char* WdbAliasType2Str(WdbAliasType aliastype);
const char* WdbValType2Str(WdbValType valtype);
const char* WdbScopeType2Str(WdbScopeType stype);
const char* WdbVarDir2Str(WdbVarDir vardir);
WdbVarType WdbStr2VarType(const char* str);
WdbAliasType WdbStr2AliasType(const char* str);
WdbValType WdbStr2ValType(const char* str);
WdbScopeType WdbStr2ScopeType(const char* str);
WdbVarDir WdbStr2VarDir(const char* str);
void WdbVarTypeUsageList(const char*** list);
void WdbAliasTypeUsageList(const char*** list);
void WdbValTypeUsageList(const char*** list);
void WdbScopeTypeUsageList(const char*** list);
void WdbVarDirUsageList(const char*** list);
WDB-Read Datatypes
Scope ID
The opaque data type WdbReadScopeId is returned and used as arguments by the other API functions.
typedef int WdbReadScopeId;
#define WdbReadNullScopeId (WdbReadScopeId)(-1)
#define WdbReadInvalidScopeId (WdbReadScopeId)(-2)
#define WdbReadScopeIdIsNull(scpId) ((scpId) == WdbReadNullScopeId)
#define WdbReadScopeIdIsInvalid(scpId) ((scpId) == WdbReadInvalidScopeId)
Variable ID
The opaque data type WdbReadVarId is returned and used as arguments by the other API functions.
typedef struct {
int id;
int mem;
} WdbReadVarId;
#define WdbReadNullVarId (-1)
#define WdbReadInvalidVarId (-2)
#define WdbReadNullMem (((unsigned)-1)>>2)
#define WdbReadVarIdIsNull(varId) ((varId).id == WdbReadNullVarId)
#define WdbReadVarIdIsInvalid(varId) ((varId).id == WdbReadInvalidVarId)
#define WdbReadVarIdIsNullMem(varId) ((varId).mem == WdbReadNullMem)
#define WdbReadVarIdSet(varId,i,m) ((varId).id = (i), (varId).mem = (m))
Callbacks
Wdb util structure is used to generate progress information, error messages, message output, and debug info.
typedef struct {
int (*progress) (const char* what, double percent);
void (*msg) (zMessage_Type type, const char* fmt, va_list);
void (*printError) (const char* fmt, va_list);
const char* (*getError) (void);
zBool (*isDebug) (void);
} WdbUtil;
Default Callbacks
Default functions for progress and messaging.
#define WdbUtilDefault ((WdbUtil*)1)
No Callbacks
No functions for progress and messaging.
#define WdbUtilNone ((WdbUtil*)NULL)
int WdbUtilProgress( WdbUtil*, const char* what, double percent);
void WdbUtilMsg( WdbUtil*, zMessage_Type, const char* fmt, ...);
void WdbUtilPrintError(WdbUtil*, const char* fmt, ...);
const char* WdbUtilGetError( WdbUtil*);
void WdbUtilDbg( WdbUtil* util, const char* fmt, ...);
WDB API Functions
Allocate A New Wdb
The WdbNew() function allocates a new Wdb.
If ok is set to zFalse there was an error - details are store via util→printError.
During execution the callback functions are called if the are not set to NULL.
Wdb* WdbNew(WdbUtil* util, WdbFuncs* funcs, WdbData* data);
Allocate A New Bindb
The WdbNewBindb() function allocates a new Bindb.
If ok is set to zFalse there was an error - details are store via util→printError.
During execution the callback functions are called if the are not set to NULL.
Wdb* WdbNewBindb(
WdbUtil* util,
zBool zip,
zBool gcd,
zBool skipDupl,
zBool collapse,
zBool skipLeadX,
zBool enableStats,
const char* outFname /* NULL -> create in memory */
);
Restore a Bindb
The WdbRestoreBindb() function restores a Bindb.
If ok is set to zFalse there was an error - details are store via util→printError.
During execution the callback functions are called if the are not set to NULL.
Wdb* WdbRestoreBindb(
WdbUtil* util,
zBool zip,
zBool gcd,
zBool skipDupl,
zBool collapse,
zBool skipLeadX,
zBool enableStats,
const char* fname
);
Close the WDB
The WdbClose() function empties all internal buffer, writes all pending data and close the database. The given handling is not valid anymore.
It returns zTrue if everything is ok. If there are problems zFalse is returned - details are stored via util→printError.
zBool WdbClose(Wdb*);
Dump WDB In Internal Format
The WdbMemDump() function dumps the in memory database to a file.
It returns zTrue if everything is ok. If there are problems zFalse is returned - details are stored via util→printError.
zBool WdbMemDump(Wdb*, const char* fname);
Dump Wdb In Generic Format
The WdbDump() function dumps the in memory database to a vcd file.
It returns zTrue if everything is ok. If there are problems zFalse is returned - details are stored via util→printError.
zBool WdbDump(Wdb*, const char* fname);
Write Wdb in VCD Format
The WdbWriteVcd() function dumps the in memory database to a vcd file.
It returns zTrue if everything is ok. If there are problems zFalse is returned - details are stored via util→printError.
zBool WdbWriteVcd(Wdb*, const char* fname);
Save the WDB
The WdbSave() function saves the in memory database to a file.
It returns zTrue if everything is ok. If there are problems zFalse is returned - details are stored via util→printError.
zBool WdbSave(Wdb*, const char* fname);
Memusage the WDB
The WdbMemUsage() function returns the used memory.
zULong WdbMemUsage(Wdb*);
Print Stats Of The WDB
The WdbStatistics() function prints different statistics about the wdb. Stats about compressed and uncompressed blocks per signal or accumulatively.
zBool WdbStatistics(Wdb*, zBool details);
Store Header Information
The WdbSetDate(), WdbSetVersion() functions are used to store header information in the WDB. The data is store as strings. The WdbSetTimescale() is used to store header information in the WDB needed to convert from WdbTime steps into real time and vice versa.
They return zTrue if everything is ok. If there are problems zFalse is returned - details are stored via util→printError.
zBool WdbSetDate( Wdb*, const char* str);
zBool WdbSetVersion( Wdb*, const char* str);
zBool WdbSetTimeScale(Wdb*, unsigned timeFactor, WdbTimeUnit unit);
zBool WdbSetTimeScaleFromString(Wdb* wdb, const char* timeFactorAndUnit);
Store Variable and Scope Definitions
All variables belong to a hierarchical scope. During the definition of variables with WdbVar() the scope can be changed by calling WdbScope(). WdbUpScope() or WdbPathScope(). The signal identifier sigNo can be used multiple times in different scopes. The next usable sigNo is returned by a call to WdbNextSigNo().
The end the variable definitions and start adding value changes the function WdbEndDefinitions() needs to be called.
The function WdbAddDefinitions() reenables adding Scopes, Variables.
The function WdbFindVar() returns the sigNo of a named variable or -1 if not found. This works only for in memory databases.
The function WdbFindAlias() returns the sigNo of a named and typed alias variable or -1 if not found. This works only for in memory databases.
The function WdbHideVar() hides the variable referenced by sigNo, if hide is zTrue, otherwise unhides it. This works only for in memory databases.
The functions, except WdbNextSigNo(), return zTrue if everything is ok. If there are problems zFalse is returned - call WdbErrorMsg() to get the error message.
zBool WdbScope( Wdb*, WdbScopeType, const char* name);
zBool WdbPathScope( Wdb*, WdbScopeType, zBool rel,
const char** names, int namesLen);
zBool WdbUpScope( Wdb*);
WdbSigNo WdbNextSigNo( Wdb*);
zBool WdbVar( Wdb*, WdbVarType, WdbValType,
const char* name, unsigned w, WdbSigNo sigNo);
zBool WdbAlias( Wdb*, WdbAliasType,
const char* name, unsigned w, WdbSigNo sigNo, const char* iname);
zBool WdbEndDefinitions(Wdb*);
zBool WdbAddDefinitions(Wdb*);
zBool WdbFindVar( Wdb*, const char* name, WdbSigNo* sigNo);
zBool WdbFindAlias( Wdb*, const char* name, WdbAliasType,
const char* iname, WdbSigNo*);
zBool WdbHideVar( Wdb*, const char* name, zBool hide);
zBool WdbDirVar( Wdb*, const char* name, WdbVarDir dir);
Store Signal Value Changes
The function WdbAddTime() defines a new time which is used for all following value changes until a new call to WdbAddTime() is made.
The function WdbAddScalar() stores a new value for given signal.
WdbAddVector() store a complete bit vector. The given width w must match the width given to WdbVar() during variable definition.
The function WdbDone() marks the end of all value changes.
If there are problems zFalse is returned - details are stored via util→printError.
Note
|
Todo
WdbAddEvent() and WdbAddReal() are not implemented yet.
|
zBool WdbAddTime( Wdb*, WdbTime tm, zBool* stopPtr);
zBool WdbAddScalar( Wdb*, WdbSigNo sigNo, WdbValue val);
zBool WdbAddScalarStr(Wdb*, WdbSigNo sigNo, const char*);
zBool WdbAddVector( Wdb*, WdbSigNo sigNo, WdbValue* values, unsigned w);
zBool WdbAddVectorStr(Wdb*, WdbSigNo sigNo, const char*, unsigned w);
zBool WdbAddEvent( Wdb*, WdbSigNo sigNo);
zBool WdbAddReal( Wdb*, WdbSigNo sigNo, double value);
zBool WdbDone( Wdb*);
Wdb Is Ready For Reader Creation
Return true is wdb is ready for reader creation.
zBool WdbIsReady(Wdb*);
Get Error Message
The WdbErrorMsg() is used to get a more detailed on the last error occurred.
const char* WdbErrorMsg(Wdb*);
WdbProcess
traverse db and call funcs.
zBool WdbProcess(
Wdb* wdb,
WdbProcessFuncs* funcs,
WdbProcessData* data
);
Create A New Reader
The WdbNewReader() function creates a new reader and adds it to list.
It returns the reader if everything is ok. If there are problems NULL is returned - details are stored via util→printError.
WdbRead* WdbNewReader(
Wdb* wdb,
const char** options,
int optc
);
Set a Custom Wdb
The WdbRegisterCustomdb() function registers a custom wdb.
typedef Wdb* (*WdbCustomdb)(
WdbUtil* util,
const char* fname,
const char** options,
int optc
);
void WdbRegisterCustomdb(WdbCustomdb customdb);
WDB-Read API Functions
Allocate and Free a WDB Reader
All reader access functions need a 'WdbRead*' handle, which is allocated by WdbReadAlloc() and freed by WdbReadFree(). After a call to WdbReadFree() the handle is invalid.
WdbRead* WdbReadAlloc(Wdb* wdb, WdbReadFuncs* funcs, WdbReadData* data);
void WdbReadFree( WdbRead*);
Get Reader Options
The function WdbReadOption() returns the list of options used to create the reader.
ce_Bool WdbReadOptions(WdbRead* wdbRead, const char*** optionListPtr, int* len);
Get Header Information
The functions WdbReadDate() and WdbReadVersion() return date and version string. The functions WdbReadTimeFactor() and WdbReadTimeUnit() return timescale information.
const char* WdbReadDate( WdbRead*);
const char* WdbReadVersion( WdbRead*);
unsigned WdbReadTimeFactor(WdbRead*);
WdbTimeUnit WdbReadTimeUnit( WdbRead*);
Convert Functions
The function WdbReadTime2Str() 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 WdbRead API function. The functions WdbReadStr2Time converts a string including unit into a time step. The functions WdbReadTime2Pix and WdbReadPix2Time convert pixel coordinates into time steps and vice versa. They return -1 or WdbTimeInvalid for wrong parameter. The function WdbReadCalcZoom 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* WdbReadTime2Str(WdbRead*, WdbTime, zBool useFraction,
zBool useBest);
WdbTime WdbReadStr2Time(WdbRead*, const char* str, zBool allowFraction);
int WdbReadTime2Pix(WdbRead*, WdbTime tfrom, WdbTime tto,
int pixelCnt, WdbTime t);
WdbTime WdbReadPix2Time(WdbRead*, WdbTime tfrom, WdbTime tto,
int pixelCnt, int pix);
zBool WdbReadCalcZoom(WdbRead* wdbread, WdbTime* tfrom, WdbTime* tto,
double factor, WdbTime tmarker);
Get Scope Information
The functions WdbReadScopeType() WdbReadScopeName() return the type and name of a given scope.
The function WdbReadScopeDown() is used to go down the hierarchy from a given scope, using 'WdbReadNullScopeId' as a start value.
The function WdbReadScopeSibling() returns the next scope in the same hierarchy as the given scope.
The function WdbReadScopeFind() search a scope under the given scope, using 'WdbReadNullScopeId' as the root value. Returns the scopeId or WdbReadNullScopeId if not found.
The function WdbReadScopeFindNamePath works like WdbReadScopeFind, 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 'WdbReadInvalidScopeId'.
The function WdbReadScopeDownVar() return the first variable for given scope or 'WdbReadNullScopeId' is there are no variables. In the case of an error the function return 'WdbReadInvalidVarId'.
The function WdbReadScopePath() 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 WdbReadScopeNamePath() is a service function works like WdbReadScopePath() 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 WdbReadScopeType( WdbRead*, WdbReadScopeId);
const char* WdbReadScopeName( WdbRead*, WdbReadScopeId);
WdbReadScopeId WdbReadScopeUp( WdbRead*, WdbReadScopeId);
WdbReadScopeId WdbReadScopeDown( WdbRead*, WdbReadScopeId);
WdbReadScopeId WdbReadScopeSibling(WdbRead*, WdbReadScopeId);
WdbReadScopeId WdbReadScopeFind( WdbRead*, WdbReadScopeId, const char* name);
WdbReadScopeId WdbReadScopeFindNamePath(WdbRead*, WdbReadScopeId,
const char**, int);
WdbReadScopeId WdbReadScopeFindIcase( WdbRead*, WdbReadScopeId,
const char* name, ce_Bool icase);
WdbReadVarId WdbReadScopeDownVar(WdbRead*, WdbReadScopeId);
zBool WdbReadScopePath( WdbRead*, WdbReadScopeId, zBool fromDUT,
WdbReadScopeId**, int* len);
zBool WdbReadScopeNamePath(WdbRead*, WdbReadScopeId, zBool fromDUT,
const char***, int* len);
DUT Information
The functions WdbReadSetDUT() and WdbReadDUTscope()/WdbReadDUTtopName set and get the DUT scope and top name.
void WdbReadSetDUT( WdbRead*, WdbReadScopeId, const char* topName);
WdbReadScopeId WdbReadDUTscope( WdbRead*);
const char* WdbReadDUTtopName(WdbRead*);
Get Variable Information
The functions WdbReadVarType() WdbReadVarName() return the type and name of a given variable.
The function WdbReadVarScope() is used to get the scope of a given variable.
The function WdbReadVarSibling() returns the next scope in the same hierarchy as the given variable.
WdbReadVarWidth() gets the width of a vector or group. All other types get 0.
WdbReadVarBit() gets the bit number of a vector member
The functions WdbReadVarFirst() and WdbReadVarNext() can be used to iterate over all variables.
The functions WdbReadVarFirstMem(), WdbReadVarLastMem, WdbReadVarNextMem() and WdbReadVarPrevMem() can be used to iterate over all members of one variable. Returns 'WdbReadNullVarId' if there no more members.
WdbReadVarSibling(), WdbReadVarFirst() and WdbReadVarNext() return 'WdbReadNullVarId' if there no more variables.
WdbReadMem2Var() returns the parent variable of a member variable.
WdbReadVar2MemIdx() returns the member index.
WdbReadVar2Bus() returns the group or vector of the member.
WdbReadVarHasMem() get zTrue if id has member variable (vector or group)
WdbReadVarHasChanges() get zTrue if there are any value changes.
WdbReadVarHasVectorMem() get zTrue if group contains vector members.
WdbReadVarFind() returns a variable with the given name under the given scope or WdbReadNullVarId if it is not found.
WdbReadVarAliasType() returns the alias type or VarAliasInvalid for 'normal' variables.
WdbReadVarAliasInstName() return the inst name of pin aliases.
In the case of an error the functions return 'WdbReadInvalidVarId' or zFalse.
WdbVarType WdbReadVarType( WdbRead*, WdbReadVarId);
const char* WdbReadVarName( WdbRead*, WdbReadVarId);
const char* WdbReadVarBaseName(WdbRead*, WdbReadVarId);
WdbReadScopeId WdbReadVarScope( WdbRead*, WdbReadVarId);
WdbReadVarId WdbReadVarSibling(WdbRead*, WdbReadVarId);
WdbReadVarId WdbReadVarFirst( WdbRead*);
WdbReadVarId WdbReadVarNext( WdbRead*, WdbReadVarId);
zBool WdbReadVarWidth( WdbRead*, WdbReadVarId, int*);
zBool WdbReadVarBit( WdbRead*, WdbReadVarId, int*);
WdbReadVarId WdbReadVarFirstMem(WdbRead*, WdbReadVarId);
WdbReadVarId WdbReadVarNextMem( WdbRead*, WdbReadVarId);
WdbReadVarId WdbReadVarLastMem( WdbRead*, WdbReadVarId);
WdbReadVarId WdbReadVarPrevMem( WdbRead*, WdbReadVarId);
WdbReadVarId WdbReadMem2Var( WdbRead*, WdbReadVarId);
int WdbReadVar2MemIdx( WdbRead*, WdbReadVarId);
WdbReadVarId WdbReadVar2Bus( WdbRead*, WdbReadVarId);
zBool WdbReadVarHasMem( WdbRead*, WdbReadVarId);
zBool WdbReadVarHasChanges(WdbRead*, WdbReadVarId, zBool*);
zBool WdbReadVarHasVectorMem(WdbRead*, WdbReadVarId, zBool*);
WdbReadVarId WdbReadVarFind( WdbRead*, WdbReadScopeId, const char* name);
WdbReadVarId WdbReadVarAliasFind(WdbRead*, WdbReadScopeId, WdbAliasType,
const char* name, const char* iname);
WdbAliasType WdbReadVarAliasType( WdbRead*, WdbReadVarId);
const char* WdbReadVarAliasInstName(WdbRead*, WdbReadVarId);
Hide Variable
WdbReadVarSetHide() and WdbReadVarGetHide() get be used to set/get the hide flag.
In the case of an error the functions return zFalse.
zBool WdbReadVarSetHide( WdbRead*, WdbReadVarId, zBool);
zBool WdbReadVarGetHide( WdbRead*, WdbReadVarId, zBool*);
Dir Variable
WdbReadVarSetDir() and WdbReadVarGetDir() get be used to set/get the direction.
In the case of an error the functions return zFalse.
zBool WdbReadVarSetDir( WdbRead*, WdbReadVarId, WdbVarDir);
zBool WdbReadVarGetDir( WdbRead*, WdbReadVarId, WdbVarDir*);
Get Signal Change Times
The functions WdbReadTimeFirst() and WdbReadTimeLast() return the minimum and maximum time.
The functions WdbReadTimePrev() and WdbReadTimeNext() 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 WdbReadTimeFirst(WdbRead*);
WdbTime WdbReadTimeLast( WdbRead*);
WdbTime WdbReadTimePrev(WdbRead*, WdbTime time, WdbTime tlimit,
WdbReadVarId varIdLst[], int varIdLstLen);
WdbTime WdbReadTimeNext(WdbRead*, WdbTime time, WdbTime tlimit,
WdbReadVarId varIdLst[], int varIdLstLen);
Get the Value Type of a Variable
The function WdbReadValType() returns the type of a given signal. If there is an error 'WdbValInvalid' is returned.
WdbValType WdbReadValType(WdbRead*, WdbReadVarId varId);
Get the Signal No of a Variable
The function WdbReadSigNo() 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 WdbReadSigNo(WdbRead*, WdbReadVarId varId);
Get Signal Value Changes
The functions WdbReadValueScalar() and WdbReadValueVector() 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 WdbReadValueReal() is not yet implemented.
|
zBool WdbReadValueScalar(WdbRead*, WdbTime, WdbReadVarId, WdbValue*);
zBool WdbReadValueVector(WdbRead*, WdbTime, WdbReadVarId, WdbValue*, int sz);
zBool WdbReadValueReal( WdbRead*, WdbTime, WdbReadVarId, double*);
zBool WdbReadValueMember(WdbRead*, WdbTime, WdbReadVarId, WdbValue*, int sz);
zBool WdbReadValueGroup( WdbRead*, WdbTime, WdbReadVarId, WdbValue*, int sz);
zBool WdbReadValueScalarS(WdbRead*, WdbTime, WdbReadVarId, const char**);
zBool WdbReadValueVectorS(WdbRead*, WdbTime, WdbReadVarId, const char**);
zBool WdbReadValueRealS( WdbRead*, WdbTime, WdbReadVarId, const char**);
zBool WdbReadValueMemberS(WdbRead*, WdbTime, WdbReadVarId, const char**);
zBool WdbReadValueGroupS( WdbRead*, WdbTime, WdbReadVarId, const char**);
zBool WdbReadValueS( WdbRead*, WdbTime, WdbReadVarId, const char**);
The function WdbReadValArray() 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 WdbReadValArray(
WdbRead* wdbread,
WdbTime tfrom,
WdbTime tto,
WdbReadVarId* varIdLst,
int varIdLstLen,
int pixelCnt,
const char*** pixelLinesPtr,
int* pixelLineCntPtr
);
Group Scalars to Virtual Vectors
-
WdbReadGroupCreate - return group varId or WdbReadInvalidVarId.
-
WdbReadGroupDelete - return zFalse on error.
-
WdbReadGroupFirst - returns group varId or WdbReadNullVarId.
-
WdbReadGroupNext - returns group varId or WdbReadNullVarId.
-
WdbReadGroupBuild - find groups by looking at scalar bus member names
-
WdbReadGroupRename - set new name for given group.
-
WdbReadGroupRedefine - set new member list for group. The varIdList which defines the members of the group is stored with the LSB first.
WdbReadVarId WdbReadGroupCreate( WdbRead*,
const char* name,
WdbReadVarId varIdList[], int len,
WdbReadScopeId,
WdbVarType varType,
zBool hide,
zBool autoScope,
zBool expandVectors
);
zBool WdbReadGroupDelete( WdbRead*, WdbReadVarId);
WdbReadVarId WdbReadGroupFirst( WdbRead*);
WdbReadVarId WdbReadGroupNext ( WdbRead*, WdbReadVarId);
zBool WdbReadGroupBuild( WdbRead*, WdbReadScopeId,
WdbVarType varType, zBool hide,
zBool rangeDown);
zBool WdbReadGroupRename( WdbRead*, WdbReadVarId, const char* name);
zBool WdbReadGroupRedefine(WdbRead*,WdbReadVarId,
WdbReadVarId varIdLst[],
int len,
zBool hide,
zBool expandVectors
);
WdbReadGroup* WdbReadGroupGet( WdbRead* wdbread, WdbReadVarId varId);
WdbReadVarId WdbReadGroupFind(WdbRead* wdbread, const char* groupName);
Clones
-
WdbReadCloneCreate - return Clone varId or WdbReadInvalidVarId.
-
WdbReadCloneDelete - return zFalse on error.
-
WdbReadCloneFirst - returns Clone varId or WdbReadNullVarId.
-
WdbReadCloneNext - returns Clone varId or WdbReadNullVarId.
WdbReadVarId WdbReadCloneCreate( WdbRead*, WdbReadVarId varId);
zBool WdbReadCloneDelete( WdbRead*, WdbReadVarId);
WdbReadVarId WdbReadCloneFirst( WdbRead*);
WdbReadVarId WdbReadCloneNext ( WdbRead*, WdbReadVarId);
zBool WdbReadResolveClone(WdbRead* wdbRead,WdbReadVarId* varId);
Get Time For Given Value
The functions WdbReadValuePrev() and WdbReadValueNext() 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 WdbReadValuePrev(WdbRead*, WdbTime time, WdbTime tlimit,
WdbReadVarId varIdLst[], int varIdLstLen,
WdbValue* values, int w);
WdbTime WdbReadValueNext(WdbRead*, WdbTime time, WdbTime tlimit,
WdbReadVarId varIdLst[], int varIdLstLen,
WdbValue* values, int w);
Get Error Message
If there was an error reported by one of the WdbRead API functions WdbReadErrorMsg returns a detailed message.
const char* WdbReadErrorMsg(WdbRead*);
Get Debug Flag For Util
Return true if util debug messages are enabled.
zBool WdbReadDebugUtil(WdbRead*);
Scope Iterator Functions
Scope iterator support.
void* WdbReadForeachScopeInit(WdbRead* ,WdbReadScopeId);
zBool WdbReadForeachScopeNext(WdbRead* ,void*, WdbReadScopeId*);
void WdbReadForeachScopeFinit(WdbRead* ,void*);
Var Iterator Functions
Var iterator support.
void* WdbReadForeachVarInit(WdbRead* ,WdbReadScopeId);
zBool WdbReadForeachVarNext(WdbRead* ,void*, WdbReadVarId*);
void WdbReadForeachVarFinit(WdbRead* ,void*);
Clone Iterator Functions
Clone iterator support.
void* WdbReadForeachCloneInit(WdbRead* ,WdbReadScopeId);
zBool WdbReadForeachCloneNext(WdbRead* ,void*, WdbReadVarId*);
void WdbReadForeachCloneFinit(WdbRead* ,void*);
Group Iterator Functions
Group iterator support.
void* WdbReadForeachGroupInit(WdbRead* ,WdbReadScopeId);
zBool WdbReadForeachGroupNext(WdbRead* ,void*, WdbReadVarId*);
void WdbReadForeachGroupFinit(WdbRead* ,void*);
VarItem Iterator Functions
VarItem iterator support.
void* WdbReadForeachVarItemInit(WdbRead* ,WdbReadScopeId);
zBool WdbReadForeachVarItemNext(WdbRead* ,void*, WdbReadVarId*);
void WdbReadForeachVarItemFinit(WdbRead* ,void*);
Member Iterator Functions
Member iterator support.
void* WdbReadForeachMemberInit(WdbRead* ,WdbReadVarId,
zBool lsbFirst, zBool msbFirst);
zBool WdbReadForeachMemberNext(WdbRead* ,void*, WdbReadVarId*);
void WdbReadForeachMemberFinit(WdbRead* ,void*);
WdbReadVarId2Str
Converts a VarId to string. result needs to be freed.
zBool WdbReadVarId2Str(
WdbRead* reader,
WdbReadVarId varId,
char** str
);
WdbReadStr2VarId
Converts a string to VarId.
zBool WdbReadStr2VarId(
WdbRead* reader,
const char* str,
WdbReadVarId* 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. WdbReadAlloc then creates a reader, which must be freed after use.
Example
#include "wdb/wdb.h"
zBool ok = zTrue;
Wdb* wdb;
WdbRead* rdr;
wdb = WdbRestore("file.wdb", &callbacks, &ok);
if (!ok) ...
rdr = WdbReadAlloc(wdb);
...
WdbReadFree(wdb);
Get Header Information
WdbReadDate, WdbReadVersion, WdbReadTimeScale are used to retrieve header information.
Example
WdbRead* rdr;
const char* str;
...
str = WdbReadDate(rdr);
str = WdbReadVersion(rdr);
str = WdbReadTimeScale(rdr);
Get Scope Information
The hierarchical scope data is stored in a tree structure. It can be recursively traversed with the WdbReadScopeDown, WdbReadScopeSibling functions. The type, name and first variable of the scope can then be retrieved.
Example
...
void traverseScopes(WdbRead* rdr, WdbReadScopeId* parent) {
WdbReadScopeId* scopeid;
scopeid = WdbReadScopeDown(rdr, parent);
while (scopeid != WdbReadNullScopeId) {
WdbScopeType scopetype;
const char* name;
WdbReadVarId vid;
scopetype = WdbReadScopeType(rdr, scopeid);
name = WdbReadScopeName(rdr, scopeid);
vid = WdbReadScopeDownVar(rdr, scopeid);
...
traverseScopes(rdr, scopeid);
scopeid = WdbReadScopeSibling(rdr, scopeid);
}
}
...
traverseScopes(rdr, WdbReadNullScopeId);
Get Variable Information
The variables can be iterated with two pair functions. Use WdbReadVarFirst and WdbReadVarNext for looping over all variables.
Example
WdbReadVarId vid;
...
vid = WdbReadVarFirst(rdr);
while (vid != WdbReadNullVarId) {
... process all variables
vid = WdbReadVarNext(rdr, vid);
}
Use WdbReadScopeDownVar and WdbReadVarSibling for looping over all variables of a given scope.
Example
WdbReadScopeId* scopeid;
...
vid = WdbReadScopeDownVar(rdr, scopeid);
while (vid != WdbReadNullVarId) {
... process variables of current scope
vid = WdbReadVarSibling(rdr, vid);
}
Get Value Changes
The value changes of a signal can be retrieved at any timestep with WdbReadScalarValue, WdbReadVectorValue etc. To get timesteps where some signals really change, WdbReadTimePrev or WdbReadTimeNext can be used.
Example
WdbTime t1, t2, t3;
WdbReadVarId vid1, vid2;
WdbReadVarId vidList[2];
WdbValue val1;
int width;
WdbValue val2[10];
const char* str;
...
t1 = WdbReadTimeFirst(rdr);
t2 = WdbReadTimeLast(rdr);
...
ok = WdbReadScalarValue(rdr, t1+100, vid1, &val1);
ok = WdbReadVectorValue(rdr, t2-500, vid2, val2, width);
...
vidList[0] = vid1;
vidList[1] = vid2;
t3 = WdbReadTimePrev(rdr, t1+200, 10000, vidList, 2);
t3 = WdbReadTimeNext(rdr, t1+900, 0, vidList, 2);
str = WdbReadTime2Str(rdr, t3);