/* * Copyright (c) 2009-2018 Tony Bybell. * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), * to deal in the Software without restriction, including without limitation * the rights to use, copy, modify, merge, publish, distribute, sublicense, * and/or sell copies of the Software, and to permit persons to whom the * Software is furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in * all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER * DEALINGS IN THE SOFTWARE. * * SPDX-License-Identifier: MIT */ #ifndef FST_API_H #define FST_API_H #ifdef __cplusplus extern "C" { #endif #include #include #include #include #include #include #if defined(_MSC_VER) #include "fst_win_unistd.h" #else #include #endif #include #define FST_RDLOAD "FSTLOAD | " typedef uint32_t fstHandle; typedef uint32_t fstEnumHandle; enum fstWriterPackType { FST_WR_PT_ZLIB = 0, FST_WR_PT_FASTLZ = 1, FST_WR_PT_LZ4 = 2 }; enum fstFileType { FST_FT_MIN = 0, FST_FT_VERILOG = 0, FST_FT_VHDL = 1, FST_FT_VERILOG_VHDL = 2, FST_FT_MAX = 2 }; enum fstBlockType { FST_BL_HDR = 0, FST_BL_VCDATA = 1, FST_BL_BLACKOUT = 2, FST_BL_GEOM = 3, FST_BL_HIER = 4, FST_BL_VCDATA_DYN_ALIAS = 5, FST_BL_HIER_LZ4 = 6, FST_BL_HIER_LZ4DUO = 7, FST_BL_VCDATA_DYN_ALIAS2 = 8, FST_BL_ZWRAPPER = 254, /* indicates that whole trace is gz wrapped */ FST_BL_SKIP = 255 /* used while block is being written */ }; enum fstScopeType { FST_ST_MIN = 0, FST_ST_VCD_MODULE = 0, FST_ST_VCD_TASK = 1, FST_ST_VCD_FUNCTION = 2, FST_ST_VCD_BEGIN = 3, FST_ST_VCD_FORK = 4, FST_ST_VCD_GENERATE = 5, FST_ST_VCD_STRUCT = 6, FST_ST_VCD_UNION = 7, FST_ST_VCD_CLASS = 8, FST_ST_VCD_INTERFACE = 9, FST_ST_VCD_PACKAGE = 10, FST_ST_VCD_PROGRAM = 11, FST_ST_VHDL_ARCHITECTURE = 12, FST_ST_VHDL_PROCEDURE = 13, FST_ST_VHDL_FUNCTION = 14, FST_ST_VHDL_RECORD = 15, FST_ST_VHDL_PROCESS = 16, FST_ST_VHDL_BLOCK = 17, FST_ST_VHDL_FOR_GENERATE = 18, FST_ST_VHDL_IF_GENERATE = 19, FST_ST_VHDL_GENERATE = 20, FST_ST_VHDL_PACKAGE = 21, FST_ST_MAX = 21, FST_ST_GEN_ATTRBEGIN = 252, FST_ST_GEN_ATTREND = 253, FST_ST_VCD_SCOPE = 254, FST_ST_VCD_UPSCOPE = 255 }; enum fstVarType { FST_VT_MIN = 0, /* start of vartypes */ FST_VT_VCD_EVENT = 0, FST_VT_VCD_INTEGER = 1, FST_VT_VCD_PARAMETER = 2, FST_VT_VCD_REAL = 3, FST_VT_VCD_REAL_PARAMETER = 4, FST_VT_VCD_REG = 5, FST_VT_VCD_SUPPLY0 = 6, FST_VT_VCD_SUPPLY1 = 7, FST_VT_VCD_TIME = 8, FST_VT_VCD_TRI = 9, FST_VT_VCD_TRIAND = 10, FST_VT_VCD_TRIOR = 11, FST_VT_VCD_TRIREG = 12, FST_VT_VCD_TRI0 = 13, FST_VT_VCD_TRI1 = 14, FST_VT_VCD_WAND = 15, FST_VT_VCD_WIRE = 16, FST_VT_VCD_WOR = 17, FST_VT_VCD_PORT = 18, FST_VT_VCD_SPARRAY = 19, /* used to define the rownum (index) port for a sparse array */ FST_VT_VCD_REALTIME = 20, FST_VT_GEN_STRING = 21, /* generic string type (max len is defined dynamically via fstWriterEmitVariableLengthValueChange) */ FST_VT_SV_BIT = 22, FST_VT_SV_LOGIC = 23, FST_VT_SV_INT = 24, /* declare as size = 32 */ FST_VT_SV_SHORTINT = 25, /* declare as size = 16 */ FST_VT_SV_LONGINT = 26, /* declare as size = 64 */ FST_VT_SV_BYTE = 27, /* declare as size = 8 */ FST_VT_SV_ENUM = 28, /* declare as appropriate type range */ FST_VT_SV_SHORTREAL = 29, /* declare and emit same as FST_VT_VCD_REAL (needs to be emitted as double, not a float) */ FST_VT_MAX = 29 /* end of vartypes */ }; enum fstVarDir { FST_VD_MIN = 0, FST_VD_IMPLICIT = 0, FST_VD_INPUT = 1, FST_VD_OUTPUT = 2, FST_VD_INOUT = 3, FST_VD_BUFFER = 4, FST_VD_LINKAGE = 5, FST_VD_MAX = 5 }; enum fstHierType { FST_HT_MIN = 0, FST_HT_SCOPE = 0, FST_HT_UPSCOPE = 1, FST_HT_VAR = 2, FST_HT_ATTRBEGIN = 3, FST_HT_ATTREND = 4, /* FST_HT_TREEBEGIN and FST_HT_TREEEND are not yet used by FST but are currently used when fstHier bridges other formats */ FST_HT_TREEBEGIN = 5, FST_HT_TREEEND = 6, FST_HT_MAX = 6 }; enum fstAttrType { FST_AT_MIN = 0, FST_AT_MISC = 0, /* self-contained: does not need matching FST_HT_ATTREND */ FST_AT_ARRAY = 1, FST_AT_ENUM = 2, FST_AT_PACK = 3, FST_AT_MAX = 3 }; enum fstMiscType { FST_MT_MIN = 0, FST_MT_COMMENT = 0, /* use fstWriterSetComment() to emit */ FST_MT_ENVVAR = 1, /* use fstWriterSetEnvVar() to emit */ FST_MT_SUPVAR = 2, /* use fstWriterCreateVar2() to emit */ FST_MT_PATHNAME = 3, /* reserved for fstWriterSetSourceStem() string -> number management */ FST_MT_SOURCESTEM = 4, /* use fstWriterSetSourceStem() to emit */ FST_MT_SOURCEISTEM = 5, /* use fstWriterSetSourceInstantiationStem() to emit */ FST_MT_VALUELIST = 6, /* use fstWriterSetValueList() to emit, followed by fstWriterCreateVar*() */ FST_MT_ENUMTABLE = 7, /* use fstWriterCreateEnumTable() and fstWriterEmitEnumTableRef() to emit */ FST_MT_UNKNOWN = 8, FST_MT_MAX = 8 }; enum fstArrayType { FST_AR_MIN = 0, FST_AR_NONE = 0, FST_AR_UNPACKED = 1, FST_AR_PACKED = 2, FST_AR_SPARSE = 3, FST_AR_MAX = 3 }; enum fstEnumValueType { FST_EV_SV_INTEGER = 0, FST_EV_SV_BIT = 1, FST_EV_SV_LOGIC = 2, FST_EV_SV_INT = 3, FST_EV_SV_SHORTINT = 4, FST_EV_SV_LONGINT = 5, FST_EV_SV_BYTE = 6, FST_EV_SV_UNSIGNED_INTEGER = 7, FST_EV_SV_UNSIGNED_BIT = 8, FST_EV_SV_UNSIGNED_LOGIC = 9, FST_EV_SV_UNSIGNED_INT = 10, FST_EV_SV_UNSIGNED_SHORTINT = 11, FST_EV_SV_UNSIGNED_LONGINT = 12, FST_EV_SV_UNSIGNED_BYTE = 13, FST_EV_REG = 14, FST_EV_TIME = 15, FST_EV_MAX = 15 }; enum fstPackType { FST_PT_NONE = 0, FST_PT_UNPACKED = 1, FST_PT_PACKED = 2, FST_PT_TAGGED_PACKED = 3, FST_PT_MAX = 3 }; enum fstSupplementalVarType { FST_SVT_MIN = 0, FST_SVT_NONE = 0, FST_SVT_VHDL_SIGNAL = 1, FST_SVT_VHDL_VARIABLE = 2, FST_SVT_VHDL_CONSTANT = 3, FST_SVT_VHDL_FILE = 4, FST_SVT_VHDL_MEMORY = 5, FST_SVT_MAX = 5 }; enum fstSupplementalDataType { FST_SDT_MIN = 0, FST_SDT_NONE = 0, FST_SDT_VHDL_BOOLEAN = 1, FST_SDT_VHDL_BIT = 2, FST_SDT_VHDL_BIT_VECTOR = 3, FST_SDT_VHDL_STD_ULOGIC = 4, FST_SDT_VHDL_STD_ULOGIC_VECTOR = 5, FST_SDT_VHDL_STD_LOGIC = 6, FST_SDT_VHDL_STD_LOGIC_VECTOR = 7, FST_SDT_VHDL_UNSIGNED = 8, FST_SDT_VHDL_SIGNED = 9, FST_SDT_VHDL_INTEGER = 10, FST_SDT_VHDL_REAL = 11, FST_SDT_VHDL_NATURAL = 12, FST_SDT_VHDL_POSITIVE = 13, FST_SDT_VHDL_TIME = 14, FST_SDT_VHDL_CHARACTER = 15, FST_SDT_VHDL_STRING = 16, FST_SDT_MAX = 16, FST_SDT_SVT_SHIFT_COUNT = 10, /* FST_SVT_* is ORed in by fstWriterCreateVar2() to the left after shifting FST_SDT_SVT_SHIFT_COUNT */ FST_SDT_ABS_MAX = ((1<<(FST_SDT_SVT_SHIFT_COUNT))-1) }; struct fstHier { unsigned char htyp; union { /* if htyp == FST_HT_SCOPE */ struct fstHierScope { unsigned char typ; /* FST_ST_MIN ... FST_ST_MAX */ const char *name; const char *component; uint32_t name_length; /* strlen(u.scope.name) */ uint32_t component_length; /* strlen(u.scope.component) */ } scope; /* if htyp == FST_HT_VAR */ struct fstHierVar { unsigned char typ; /* FST_VT_MIN ... FST_VT_MAX */ unsigned char direction; /* FST_VD_MIN ... FST_VD_MAX */ unsigned char svt_workspace; /* zeroed out by FST reader, for client code use */ unsigned char sdt_workspace; /* zeroed out by FST reader, for client code use */ unsigned int sxt_workspace; /* zeroed out by FST reader, for client code use */ const char *name; uint32_t length; fstHandle handle; uint32_t name_length; /* strlen(u.var.name) */ unsigned is_alias : 1; } var; /* if htyp == FST_HT_ATTRBEGIN */ struct fstHierAttr { unsigned char typ; /* FST_AT_MIN ... FST_AT_MAX */ unsigned char subtype; /* from fstMiscType, fstArrayType, fstEnumValueType, fstPackType */ const char *name; uint64_t arg; /* number of array elements, struct members, or some other payload (possibly ignored) */ uint64_t arg_from_name; /* for when name is overloaded as a variable-length integer (FST_AT_MISC + FST_MT_SOURCESTEM) */ uint32_t name_length; /* strlen(u.attr.name) */ } attr; } u; }; struct fstETab { char *name; uint32_t elem_count; char **literal_arr; char **val_arr; }; /* * writer functions */ void fstWriterClose(void *ctx); void * fstWriterCreate(const char *nam, int use_compressed_hier); fstEnumHandle fstWriterCreateEnumTable(void *ctx, const char *name, uint32_t elem_count, unsigned int min_valbits, const char **literal_arr, const char **val_arr); /* used for Verilog/SV */ fstHandle fstWriterCreateVar(void *ctx, enum fstVarType vt, enum fstVarDir vd, uint32_t len, const char *nam, fstHandle aliasHandle); /* future expansion for VHDL and other languages. The variable type, data type, etc map onto the current Verilog/SV one. The "type" string is optional for a more verbose or custom description */ fstHandle fstWriterCreateVar2(void *ctx, enum fstVarType vt, enum fstVarDir vd, uint32_t len, const char *nam, fstHandle aliasHandle, const char *type, enum fstSupplementalVarType svt, enum fstSupplementalDataType sdt); void fstWriterEmitDumpActive(void *ctx, int enable); void fstWriterEmitEnumTableRef(void *ctx, fstEnumHandle handle); void fstWriterEmitValueChange(void *ctx, fstHandle handle, const void *val); void fstWriterEmitValueChange32(void *ctx, fstHandle handle, uint32_t bits, uint32_t val); void fstWriterEmitValueChange64(void *ctx, fstHandle handle, uint32_t bits, uint64_t val); void fstWriterEmitValueChangeVec32(void *ctx, fstHandle handle, uint32_t bits, const uint32_t *val); void fstWriterEmitValueChangeVec64(void *ctx, fstHandle handle, uint32_t bits, const uint64_t *val); void fstWriterEmitVariableLengthValueChange(void *ctx, fstHandle handle, const void *val, uint32_t len); void fstWriterEmitTimeChange(void *ctx, uint64_t tim); void fstWriterFlushContext(void *ctx); int fstWriterGetDumpSizeLimitReached(void *ctx); int fstWriterGetFseekFailed(void *ctx); void fstWriterSetAttrBegin(void *ctx, enum fstAttrType attrtype, int subtype, const char *attrname, uint64_t arg); void fstWriterSetAttrEnd(void *ctx); void fstWriterSetComment(void *ctx, const char *comm); void fstWriterSetDate(void *ctx, const char *dat); void fstWriterSetDumpSizeLimit(void *ctx, uint64_t numbytes); void fstWriterSetEnvVar(void *ctx, const char *envvar); void fstWriterSetFileType(void *ctx, enum fstFileType filetype); void fstWriterSetPackType(void *ctx, enum fstWriterPackType typ); void fstWriterSetParallelMode(void *ctx, int enable); void fstWriterSetRepackOnClose(void *ctx, int enable); /* type = 0 (none), 1 (libz) */ void fstWriterSetScope(void *ctx, enum fstScopeType scopetype, const char *scopename, const char *scopecomp); void fstWriterSetSourceInstantiationStem(void *ctx, const char *path, unsigned int line, unsigned int use_realpath); void fstWriterSetSourceStem(void *ctx, const char *path, unsigned int line, unsigned int use_realpath); void fstWriterSetTimescale(void *ctx, int ts); void fstWriterSetTimescaleFromString(void *ctx, const char *s); void fstWriterSetTimezero(void *ctx, int64_t tim); void fstWriterSetUpscope(void *ctx); void fstWriterSetValueList(void *ctx, const char *vl); void fstWriterSetVersion(void *ctx, const char *vers); /* * reader functions */ void fstReaderClose(void *ctx); void fstReaderClrFacProcessMask(void *ctx, fstHandle facidx); void fstReaderClrFacProcessMaskAll(void *ctx); uint64_t fstReaderGetAliasCount(void *ctx); const char * fstReaderGetCurrentFlatScope(void *ctx); void * fstReaderGetCurrentScopeUserInfo(void *ctx); int fstReaderGetCurrentScopeLen(void *ctx); const char * fstReaderGetDateString(void *ctx); int fstReaderGetDoubleEndianMatchState(void *ctx); uint64_t fstReaderGetDumpActivityChangeTime(void *ctx, uint32_t idx); unsigned char fstReaderGetDumpActivityChangeValue(void *ctx, uint32_t idx); uint64_t fstReaderGetEndTime(void *ctx); int fstReaderGetFacProcessMask(void *ctx, fstHandle facidx); int fstReaderGetFileType(void *ctx); int fstReaderGetFseekFailed(void *ctx); fstHandle fstReaderGetMaxHandle(void *ctx); uint64_t fstReaderGetMemoryUsedByWriter(void *ctx); uint32_t fstReaderGetNumberDumpActivityChanges(void *ctx); uint64_t fstReaderGetScopeCount(void *ctx); uint64_t fstReaderGetStartTime(void *ctx); signed char fstReaderGetTimescale(void *ctx); int64_t fstReaderGetTimezero(void *ctx); uint64_t fstReaderGetValueChangeSectionCount(void *ctx); char * fstReaderGetValueFromHandleAtTime(void *ctx, uint64_t tim, fstHandle facidx, char *buf); uint64_t fstReaderGetVarCount(void *ctx); const char * fstReaderGetVersionString(void *ctx); struct fstHier *fstReaderIterateHier(void *ctx); int fstReaderIterateHierRewind(void *ctx); int fstReaderIterBlocks(void *ctx, void (*value_change_callback)(void *user_callback_data_pointer, uint64_t time, fstHandle facidx, const unsigned char *value), void *user_callback_data_pointer, FILE *vcdhandle); int fstReaderIterBlocks2(void *ctx, void (*value_change_callback)(void *user_callback_data_pointer, uint64_t time, fstHandle facidx, const unsigned char *value), void (*value_change_callback_varlen)(void *user_callback_data_pointer, uint64_t time, fstHandle facidx, const unsigned char *value, uint32_t len), void *user_callback_data_pointer, FILE *vcdhandle); void fstReaderIterBlocksSetNativeDoublesOnCallback(void *ctx, int enable); void * fstReaderOpen(const char *nam); void * fstReaderOpenForUtilitiesOnly(void); const char * fstReaderPopScope(void *ctx); int fstReaderProcessHier(void *ctx, FILE *vcdhandle); const char * fstReaderPushScope(void *ctx, const char *nam, void *user_info); void fstReaderResetScope(void *ctx); void fstReaderSetFacProcessMask(void *ctx, fstHandle facidx); void fstReaderSetFacProcessMaskAll(void *ctx); void fstReaderSetLimitTimeRange(void *ctx, uint64_t start_time, uint64_t end_time); void fstReaderSetUnlimitedTimeRange(void *ctx); void fstReaderSetVcdExtensions(void *ctx, int enable); /* * utility functions */ int fstUtilityBinToEscConvertedLen(const unsigned char *s, int len); /* used for mallocs for fstUtilityBinToEsc() */ int fstUtilityBinToEsc(unsigned char *d, const unsigned char *s, int len); int fstUtilityEscToBin(unsigned char *d, unsigned char *s, int len); struct fstETab *fstUtilityExtractEnumTableFromString(const char *s); void fstUtilityFreeEnumTable(struct fstETab *etab); /* must use to free fstETab properly */ #ifdef __cplusplus } #endif #endif