From 2e158d88c106825d43eb1717799e02385bd5caea Mon Sep 17 00:00:00 2001 From: Wilson Snyder Date: Sat, 20 Mar 2021 21:11:53 -0400 Subject: [PATCH] Commentary. Remove dox comments from private members, --- include/verilated.cpp | 2 +- include/verilated.h | 92 ++++++++++++++++++++--------------- include/verilated_cov.cpp | 48 +++++++++--------- include/verilated_cov.h | 20 +++++--- include/verilated_dpi.cpp | 21 ++++---- include/verilated_fst_c.h | 6 +-- include/verilated_imp.h | 28 +++++------ include/verilated_save.h | 81 ++++++++++++++++++++++-------- include/verilated_sym_props.h | 22 ++++----- include/verilated_threads.h | 2 +- include/verilated_trace.h | 26 +++++----- include/verilated_vcd_c.cpp | 4 +- include/verilated_vcd_c.h | 34 ++++++------- include/verilated_vpi.cpp | 13 +++-- include/verilated_vpi.h | 14 +++--- include/verilatedos.h | 50 +++++++++++-------- 16 files changed, 268 insertions(+), 195 deletions(-) diff --git a/include/verilated.cpp b/include/verilated.cpp index 47747556c..c7cfceecf 100644 --- a/include/verilated.cpp +++ b/include/verilated.cpp @@ -67,7 +67,7 @@ #endif // clang-format on -/// Max static char array for VL_VALUE_STRING +// Max characters in static char string for VL_VALUE_STRING constexpr unsigned VL_VALUE_STRING_MAX_WIDTH = 8192; //=========================================================================== diff --git a/include/verilated.h b/include/verilated.h index 1e6bffc65..749d1dcbe 100644 --- a/include/verilated.h +++ b/include/verilated.h @@ -134,7 +134,7 @@ enum VerilatedVarFlags { //========================================================================= // Mutex and threading support -/// Return current thread ID (or 0), not super fast, cache if needed +// Return current thread ID (or 0), not super fast, cache if needed extern vluint32_t VL_THREAD_ID() VL_MT_SAFE; #if VL_THREADED @@ -253,7 +253,7 @@ class VerilatedModule VL_NOT_FINAL { VL_UNCOPYABLE(VerilatedModule); private: - const char* m_namep; ///< Module name + const char* m_namep; // Module name public: explicit VerilatedModule(const char* namep); ///< Create module with given hierarchy name ~VerilatedModule(); @@ -580,15 +580,15 @@ public: }; // Type of a scope, currently module is only interesting private: // Fastpath: - VerilatedSyms* m_symsp = nullptr; ///< Symbol table - void** m_callbacksp = nullptr; ///< Callback table pointer (Fastpath) - int m_funcnumMax = 0; ///< Maxium function number stored (Fastpath) + VerilatedSyms* m_symsp = nullptr; // Symbol table + void** m_callbacksp = nullptr; // Callback table pointer (Fastpath) + int m_funcnumMax = 0; // Maxium function number stored (Fastpath) // 4 bytes padding (on -m64), for rent. - VerilatedVarNameMap* m_varsp = nullptr; ///< Variable map - const char* m_namep = nullptr; ///< Scope name (Slowpath) - const char* m_identifierp = nullptr; ///< Identifier of scope (with escapes removed) - vlsint8_t m_timeunit = 0; ///< Timeunit in negative power-of-10 - Type m_type = SCOPE_OTHER; ///< Type of the scope + VerilatedVarNameMap* m_varsp = nullptr; // Variable map + const char* m_namep = nullptr; // Scope name (Slowpath) + const char* m_identifierp = nullptr; // Identifier of scope (with escapes removed) + vlsint8_t m_timeunit = 0; // Timeunit in negative power-of-10 + Type m_type = SCOPE_OTHER; // Type of the scope public: // But internals only - called from VerilatedModule's VerilatedScope() = default; @@ -639,9 +639,9 @@ class Verilated final { // Internal note: Globals may multi-construct, see verilated.cpp top. // Debug is reloaded from on command-line settings, so do not need to persist - static int s_debug; ///< See accessors... only when VL_DEBUG set + static int s_debug; // See accessors... only when VL_DEBUG set - static VerilatedContext* s_lastContextp; ///< Last context constructed/attached + static VerilatedContext* s_lastContextp; // Last context constructed/attached // Not covered by mutex, as per-thread static VL_THREAD_LOCAL struct ThreadLocal { @@ -655,9 +655,9 @@ class Verilated final { // Messages maybe pending on thread, needs end-of-eval calls vluint32_t t_endOfEvalReqd = 0; #endif - const VerilatedScope* t_dpiScopep = nullptr; ///< DPI context scope - const char* t_dpiFilename = nullptr; ///< DPI context filename - int t_dpiLineno = 0; ///< DPI context line number + const VerilatedScope* t_dpiScopep = nullptr; // DPI context scope + const char* t_dpiFilename = nullptr; // DPI context filename + int t_dpiLineno = 0; // DPI context line number ThreadLocal() = default; ~ThreadLocal() = default; @@ -715,11 +715,13 @@ public: #ifndef VL_NO_LEGACY /// Call VerilatedContext::assertOn using current thread's VerilatedContext static void assertOn(bool flag) VL_MT_SAFE { Verilated::threadContextp()->assertOn(flag); } + /// Return VerilatedContext::assertOn() using current thread's VerilatedContext static bool assertOn() VL_MT_SAFE { return Verilated::threadContextp()->assertOn(); } /// Call VerilatedContext::calcUnusedSigs using current thread's VerilatedContext static void calcUnusedSigs(bool flag) VL_MT_SAFE { Verilated::threadContextp()->calcUnusedSigs(flag); } + /// Return VerilatedContext::calcUnusedSigs using current thread's VerilatedContext static bool calcUnusedSigs() VL_MT_SAFE { return Verilated::threadContextp()->calcUnusedSigs(); } @@ -730,43 +732,55 @@ public: static void commandArgs(int argc, char** argv) VL_MT_SAFE { commandArgs(argc, const_cast(argv)); } + /// Call VerilatedContext::commandArgsAdd using current thread's VerilatedContext static void commandArgsAdd(int argc, const char** argv) { Verilated::threadContextp()->commandArgsAdd(argc, argv); } + /// Return VerilatedContext::commandArgsPlusMatch using current thread's VerilatedContext static const char* commandArgsPlusMatch(const char* prefixp) VL_MT_SAFE { return Verilated::threadContextp()->commandArgsPlusMatch(prefixp); } /// Call VerilatedContext::errorLimit using current thread's VerilatedContext static void errorLimit(int val) VL_MT_SAFE { Verilated::threadContextp()->errorLimit(val); } + /// Return VerilatedContext::errorLimit using current thread's VerilatedContext static int errorLimit() VL_MT_SAFE { return Verilated::threadContextp()->errorLimit(); } /// Call VerilatedContext::fatalOnError using current thread's VerilatedContext static void fatalOnError(bool flag) VL_MT_SAFE { Verilated::threadContextp()->fatalOnError(flag); } + /// Return VerilatedContext::fatalOnError using current thread's VerilatedContext static bool fatalOnError() VL_MT_SAFE { return Verilated::threadContextp()->fatalOnError(); } /// Call VerilatedContext::fatalOnVpiError using current thread's VerilatedContext static void fatalOnVpiError(bool flag) VL_MT_SAFE { Verilated::threadContextp()->fatalOnVpiError(flag); } + /// Return VerilatedContext::fatalOnVpiError using current thread's VerilatedContext static bool fatalOnVpiError() VL_MT_SAFE { return Verilated::threadContextp()->fatalOnVpiError(); } /// Call VerilatedContext::gotError using current thread's VerilatedContext static void gotError(bool flag) VL_MT_SAFE { Verilated::threadContextp()->gotError(flag); } + /// Return VerilatedContext::gotError using current thread's VerilatedContext static bool gotError() VL_MT_SAFE { return Verilated::threadContextp()->gotError(); } /// Call VerilatedContext::gotFinish using current thread's VerilatedContext static void gotFinish(bool flag) VL_MT_SAFE { Verilated::threadContextp()->gotFinish(flag); } + /// Return VerilatedContext::gotFinish using current thread's VerilatedContext static bool gotFinish() VL_MT_SAFE { return Verilated::threadContextp()->gotFinish(); } /// Call VerilatedContext::randReset using current thread's VerilatedContext static void randReset(int val) VL_MT_SAFE { Verilated::threadContextp()->randReset(val); } + /// Return VerilatedContext::randReset using current thread's VerilatedContext static int randReset() VL_MT_SAFE { return Verilated::threadContextp()->randReset(); } /// Call VerilatedContext::randSeed using current thread's VerilatedContext static void randSeed(int val) VL_MT_SAFE { Verilated::threadContextp()->randSeed(val); } + /// Return VerilatedContext::randSeed using current thread's VerilatedContext static int randSeed() VL_MT_SAFE { return Verilated::threadContextp()->randSeed(); } /// Call VerilatedContext::time using current thread's VerilatedContext static void time(vluint64_t val) VL_MT_SAFE { Verilated::threadContextp()->time(val); } + /// Return VerilatedContext::time using current thread's VerilatedContext static vluint64_t time() VL_MT_SAFE { return Verilated::threadContextp()->time(); } + /// Call VerilatedContext::timeInc using current thread's VerilatedContext static void timeInc(vluint64_t add) VL_MT_UNSAFE { Verilated::threadContextp()->timeInc(add); } + // Deprecated static int timeunit() VL_MT_SAFE { return Verilated::threadContextp()->timeunit(); } static int timeprecision() VL_MT_SAFE { return Verilated::threadContextp()->timeprecision(); } /// Call VerilatedContext::tracesEverOn using current thread's VerilatedContext @@ -775,7 +789,8 @@ public: } #endif - typedef void (*VoidPCb)(void*); // Callback type for below + /// Callback typedef for addFlushCb, addExitCb + using VoidPCb = void (*)(void*); /// Add callback to run on global flush static void addFlushCb(VoidPCb cb, void* datap) VL_MT_SAFE; /// Remove callback to run on global flush @@ -921,7 +936,7 @@ extern vluint64_t vl_rand64() VL_MT_SAFE; inline IData VL_RANDOM_I(int obits) VL_MT_SAFE { return vl_rand64() & VL_MASK_I(obits); } inline QData VL_RANDOM_Q(int obits) VL_MT_SAFE { return vl_rand64() & VL_MASK_Q(obits); } #ifndef VL_NO_LEGACY -extern WDataOutP VL_RANDOM_W(int obits, WDataOutP outwp); ///< Randomize a signal +extern WDataOutP VL_RANDOM_W(int obits, WDataOutP outwp); #endif extern IData VL_RANDOM_SEEDED_II(int obits, IData seed) VL_MT_SAFE; inline IData VL_URANDOM_RANGE_I(IData hi, IData lo) { @@ -934,10 +949,13 @@ inline IData VL_URANDOM_RANGE_I(IData hi, IData lo) { } } -/// Init time only, so slow is fine -extern IData VL_RAND_RESET_I(int obits); ///< Random reset a signal -extern QData VL_RAND_RESET_Q(int obits); ///< Random reset a signal -extern WDataOutP VL_RAND_RESET_W(int obits, WDataOutP outwp); ///< Random reset a signal +// These are init time only, so slow is fine +/// Random reset a signal of given width +extern IData VL_RAND_RESET_I(int obits); +/// Random reset a signal of given width +extern QData VL_RAND_RESET_Q(int obits); +/// Random reset a signal of given width +extern WDataOutP VL_RAND_RESET_W(int obits, WDataOutP outwp); /// Zero reset a signal (slow - else use VL_ZERO_W) extern WDataOutP VL_ZERO_RESET_W(int obits, WDataOutP outwp); @@ -953,11 +971,9 @@ inline QData VL_RDTSC_Q() { extern void VL_PRINTTIMESCALE(const char* namep, const char* timeunitp, const VerilatedContext* contextp) VL_MT_SAFE; -/// Math extern WDataOutP _vl_moddiv_w(int lbits, WDataOutP owp, WDataInP lwp, WDataInP rwp, bool is_modulus); -/// File I/O extern IData VL_FGETS_IXI(int obits, void* destp, IData fpi); extern void VL_FFLUSH_I(IData fdi); @@ -1019,31 +1035,31 @@ extern const char* vl_mc_scan_plusargs(const char* prefixp); // PLIish | (static_cast((lwp)[1]) << (static_cast(VL_EDATASIZE)))) #define VL_SET_QII(ld, rd) ((static_cast(ld) << 32ULL) | static_cast(rd)) -/// Return FILE* from IData +// Return FILE* from IData extern FILE* VL_CVT_I_FP(IData lhs) VL_MT_SAFE; // clang-format off // Use a union to avoid cast-to-different-size warnings -/// Return void* from QData +// Return void* from QData static inline void* VL_CVT_Q_VP(QData lhs) VL_PURE { union { void* fp; QData q; } u; u.q = lhs; return u.fp; } -/// Return QData from const void* +// Return QData from const void* static inline QData VL_CVT_VP_Q(const void* fp) VL_PURE { union { const void* fp; QData q; } u; u.q = 0; u.fp = fp; return u.q; } -/// Return double from QData (bits, not numerically) +// Return double from QData (bits, not numerically) static inline double VL_CVT_D_Q(QData lhs) VL_PURE { union { double d; QData q; } u; u.q = lhs; return u.d; } -/// Return QData from double (bits, not numerically) +// Return QData from double (bits, not numerically) static inline QData VL_CVT_Q_D(double lhs) VL_PURE { union { double d; QData q; } u; u.d = lhs; @@ -1051,7 +1067,7 @@ static inline QData VL_CVT_Q_D(double lhs) VL_PURE { } // clang-format on -/// Return double from lhs (numeric) unsigned +// Return double from lhs (numeric) unsigned double VL_ITOR_D_W(int lbits, WDataInP lwp) VL_PURE; static inline double VL_ITOR_D_I(int, IData lhs) VL_PURE { return static_cast(static_cast(lhs)); @@ -1059,7 +1075,7 @@ static inline double VL_ITOR_D_I(int, IData lhs) VL_PURE { static inline double VL_ITOR_D_Q(int, QData lhs) VL_PURE { return static_cast(static_cast(lhs)); } -/// Return double from lhs (numeric) signed +// Return double from lhs (numeric) signed double VL_ISTOR_D_W(int lbits, WDataInP lwp) VL_PURE; static inline double VL_ISTOR_D_I(int lbits, IData lhs) VL_PURE { if (lbits == 32) return static_cast(static_cast(lhs)); @@ -1073,7 +1089,7 @@ static inline double VL_ISTOR_D_Q(int lbits, QData lhs) VL_PURE { VL_SET_WQ(lwp, lhs); return VL_ISTOR_D_W(lbits, lwp); } -/// Return QData from double (numeric) +// Return QData from double (numeric) static inline IData VL_RTOI_I_D(double lhs) VL_PURE { return static_cast(VL_TRUNC(lhs)); } @@ -1162,24 +1178,24 @@ inline vluint64_t VerilatedContext::time() const VL_MT_SAFE { #define VL_TIME_Q() (Verilated::threadContextp()->time()) #define VL_TIME_D() (static_cast(VL_TIME_Q())) -/// Time scaled from 1-per-precision into a module's time units ("Unit"-ed, not "United") +// Time scaled from 1-per-precision into a module's time units ("Unit"-ed, not "United") // Optimized assuming scale is always constant. // Can't use multiply in Q flavor, as might lose precision #define VL_TIME_UNITED_Q(scale) (VL_TIME_Q() / static_cast(scale)) #define VL_TIME_UNITED_D(scale) (VL_TIME_D() / static_cast(scale)) -/// Time imported from units to time precision +// Return time precision as multiplier of time units double vl_time_multiplier(int scale) VL_PURE; -/// Evaluate expression if debug enabled +/// Evaluate statement if debug enabled #ifdef VL_DEBUG -# define VL_DEBUG_IF(text) \ +# define VL_DEBUG_IF(stmt) \ do { \ - if (VL_UNLIKELY(Verilated::debug())) {text} \ + if (VL_UNLIKELY(Verilated::debug())) {stmt} \ } while (false) #else -// We intentionally do not compile the text to improve compile speed -# define VL_DEBUG_IF(text) do {} while (false) +// We intentionally do not compile the stmt to improve compile speed +# define VL_DEBUG_IF(stmt) do {} while (false) #endif // clang-format on diff --git a/include/verilated_cov.cpp b/include/verilated_cov.cpp index e8716a59e..9d52259e1 100644 --- a/include/verilated_cov.cpp +++ b/include/verilated_cov.cpp @@ -36,19 +36,19 @@ struct VerilatedCovConst VL_NOT_FINAL { // TYPES - enum { MAX_KEYS = 33 }; /// Maximum user arguments + filename+lineno - enum { KEY_UNDEF = 0 }; /// Magic key # for unspecified values + enum { MAX_KEYS = 33 }; // Maximum user arguments + filename+lineno + enum { KEY_UNDEF = 0 }; // Magic key # for unspecified values }; //============================================================================= // VerilatedCovImpItem -/// Implementation class for a VerilatedCov item +// Implementation class for a VerilatedCov item class VerilatedCovImpItem VL_NOT_FINAL { public: // But only local to this file // MEMBERS - int m_keys[VerilatedCovConst::MAX_KEYS]; ///< Key - int m_vals[VerilatedCovConst::MAX_KEYS]; ///< Value for specified key + int m_keys[VerilatedCovConst::MAX_KEYS]; // Key + int m_vals[VerilatedCovConst::MAX_KEYS]; // Value for specified key // CONSTRUCTORS // Derived classes should call zero() in their constructor VerilatedCovImpItem() { @@ -63,15 +63,15 @@ public: // But only local to this file }; //============================================================================= -/// VerilatedCoverItem templated for a specific class -/// Creates a new coverage item for the specified type. -/// This isn't in the header file for auto-magic conversion because it -/// inlines to too much code and makes compilation too slow. +// VerilatedCoverItem templated for a specific class +// Creates a new coverage item for the specified type. +// This isn't in the header file for auto-magic conversion because it +// inlines to too much code and makes compilation too slow. template class VerilatedCoverItemSpec final : public VerilatedCovImpItem { private: // MEMBERS - T* m_countp; ///< Count value + T* m_countp; // Count value public: // METHODS // cppcheck-suppress truncLongCastReturn @@ -88,11 +88,11 @@ public: //============================================================================= // VerilatedCovImp -/// -/// Implementation class for VerilatedCovContext. See that class for -/// public method information. All value and keys are indexed into a -/// unique number. Thus we can greatly reduce the storage requirements for -/// otherwise identical keys. +// +// Implementation class for VerilatedCovContext. See that class for +// public method information. All value and keys are indexed into a +// unique number. Thus we can greatly reduce the storage requirements for +// otherwise identical keys. class VerilatedCovImp final : public VerilatedCovContext { private: @@ -102,17 +102,17 @@ private: using ItemList = std::deque; // MEMBERS - VerilatedMutex m_mutex; ///< Protects all members - ValueIndexMap m_valueIndexes VL_GUARDED_BY(m_mutex); ///< Unique arbitrary value for values - IndexValueMap m_indexValues VL_GUARDED_BY(m_mutex); ///< Unique arbitrary value for keys - ItemList m_items VL_GUARDED_BY(m_mutex); ///< List of all items + VerilatedMutex m_mutex; // Protects all members + ValueIndexMap m_valueIndexes VL_GUARDED_BY(m_mutex); // Unique arbitrary value for values + IndexValueMap m_indexValues VL_GUARDED_BY(m_mutex); // Unique arbitrary value for keys + ItemList m_items VL_GUARDED_BY(m_mutex); // List of all items int m_nextIndex VL_GUARDED_BY(m_mutex) - = (VerilatedCovConst::KEY_UNDEF + 1); ///< Next insert value + = (VerilatedCovConst::KEY_UNDEF + 1); // Next insert value - VerilatedCovImpItem* m_insertp VL_GUARDED_BY(m_mutex) = nullptr; ///< Item about to insert - const char* m_insertFilenamep VL_GUARDED_BY(m_mutex) = nullptr; ///< Filename about to insert - int m_insertLineno VL_GUARDED_BY(m_mutex) = 0; ///< Line number about to insert - bool m_forcePerInstance VL_GUARDED_BY(m_mutex) = false; ///< Force per_instance + VerilatedCovImpItem* m_insertp VL_GUARDED_BY(m_mutex) = nullptr; // Item about to insert + const char* m_insertFilenamep VL_GUARDED_BY(m_mutex) = nullptr; // Filename about to insert + int m_insertLineno VL_GUARDED_BY(m_mutex) = 0; // Line number about to insert + bool m_forcePerInstance VL_GUARDED_BY(m_mutex) = false; // Force per_instance public: // CONSTRUCTORS diff --git a/include/verilated_cov.h b/include/verilated_cov.h index 4b859f319..552c6c1c0 100644 --- a/include/verilated_cov.h +++ b/include/verilated_cov.h @@ -68,6 +68,7 @@ class VerilatedCovImp; /// Comments for type==block: 'if', 'else', 'elsif', 'case' /// thresh Threshold to consider fully covered. /// If unspecified, downstream tools will determine it. +/// per_instance If non-zero don't combine all hierarchies into one count /// /// Example: /// @@ -97,6 +98,9 @@ template std::string vlCovCvtToStr(const T& t) VL_PURE { // VerilatedCov /// Verilator coverage per-context structure. /// All public methods in this class are thread safe. +/// +/// This structure is accessed and constructed on first access via +/// VerilatedContext::coveragep() class VerilatedCovContext VL_NOT_FINAL : public VerilatedVirtualBase { VL_UNCOPYABLE(VerilatedCovContext); @@ -117,10 +121,10 @@ public: void zero() VL_MT_SAFE; public: // But Internal use only - /// Insert a coverage item - /// We accept from 1-30 key/value pairs, all as strings. - /// Call _insert1, followed by _insert2 and _insert3 - /// Do not call directly; use VL_COVER_INSERT or higher level macros instead + // Insert a coverage item + // We accept from 1-30 key/value pairs, all as strings. + // Call _insert1, followed by _insert2 and _insert3 + // Do not call directly; use VL_COVER_INSERT or higher level macros instead // _insert1: Remember item pointer with count. (Not const, as may add zeroing function) void _inserti(vluint32_t* itemp) VL_MT_SAFE; void _inserti(vluint64_t* itemp) VL_MT_SAFE; @@ -163,9 +167,9 @@ protected: // VerilatedCov /// Verilator coverage global class /// -/// Global class that accesses via current thread's context. These are -/// provided for backward-compatibility, use VerilatedContext->coveragep() -/// instead. +/// Global class that accesses via current thread's context's +/// VerilatedCovContext. This class is provided only for +/// backward-compatibility, use VerilatedContext::coveragep() instead. #ifndef VL_NO_LEGACY class VerilatedCov final { @@ -189,7 +193,7 @@ public: static void zero() VL_MT_SAFE { threadCovp()->zero(); } private: - /// Current thread's coverage structure + // Current thread's coverage structure static VerilatedCovContext* threadCovp() VL_MT_SAFE; }; #endif diff --git a/include/verilated_dpi.cpp b/include/verilated_dpi.cpp index 65579865e..47139cd1e 100644 --- a/include/verilated_dpi.cpp +++ b/include/verilated_dpi.cpp @@ -20,6 +20,9 @@ /// Declare any DPI routine inside Verilog to add this to the Makefile for /// the linker. /// +/// For documentation on the exported functions (named sv*) that are +/// implemented here, refer to the IEEE DPI chapter. +/// //========================================================================= #define VERILATOR_VERILATED_DPI_CPP_ @@ -200,13 +203,13 @@ int svIncrement(const svOpenArrayHandle h, int d) { return _vl_openhandle_varp(h int svSize(const svOpenArrayHandle h, int d) { return _vl_openhandle_varp(h)->elements(d); } int svDimensions(const svOpenArrayHandle h) { return _vl_openhandle_varp(h)->udims(); } -/// Return pointer to open array data, or nullptr if not in IEEE standard C layout +// Return pointer to open array data, or nullptr if not in IEEE standard C layout void* svGetArrayPtr(const svOpenArrayHandle h) { const VerilatedDpiOpenVar* varp = _vl_openhandle_varp(h); if (VL_UNLIKELY(!varp->isDpiStdLayout())) return nullptr; return varp->datap(); } -/// Return size of open array, or 0 if not in IEEE standard C layout +// Return size of open array, or 0 if not in IEEE standard C layout int svSizeOfArray(const svOpenArrayHandle h) { const VerilatedDpiOpenVar* varp = _vl_openhandle_varp(h); if (VL_UNLIKELY(!varp->isDpiStdLayout())) return 0; @@ -256,7 +259,7 @@ static void* _vl_sv_adjusted_datap(const VerilatedDpiOpenVar* varp, int nargs, i return datap; } -/// Return pointer to simulator open array element, or nullptr if outside range +// Return pointer to simulator open array element, or nullptr if outside range static void* _vl_svGetArrElemPtr(const svOpenArrayHandle h, int nargs, int indx1, int indx2, int indx3) VL_MT_SAFE { const VerilatedDpiOpenVar* varp = _vl_openhandle_varp(h); @@ -265,7 +268,7 @@ static void* _vl_svGetArrElemPtr(const svOpenArrayHandle h, int nargs, int indx1 return datap; } -/// Copy to user bit array from simulator open array +// Copy to user bit array from simulator open array static void _vl_svGetBitArrElemVecVal(svBitVecVal* d, const svOpenArrayHandle s, int nargs, int indx1, int indx2, int indx3) VL_MT_SAFE { const VerilatedDpiOpenVar* varp = _vl_openhandle_varp(s); @@ -293,7 +296,7 @@ static void _vl_svGetBitArrElemVecVal(svBitVecVal* d, const svOpenArrayHandle s, return; // LCOV_EXCL_STOP } } -/// Copy to user logic array from simulator open array +// Copy to user logic array from simulator open array static void _vl_svGetLogicArrElemVecVal(svLogicVecVal* d, const svOpenArrayHandle s, int nargs, int indx1, int indx2, int indx3) VL_MT_SAFE { const VerilatedDpiOpenVar* varp = _vl_openhandle_varp(s); @@ -336,7 +339,7 @@ static void _vl_svGetLogicArrElemVecVal(svLogicVecVal* d, const svOpenArrayHandl } } -/// Copy to simulator open array from from user bit array +// Copy to simulator open array from from user bit array static void _vl_svPutBitArrElemVecVal(const svOpenArrayHandle d, const svBitVecVal* s, int nargs, int indx1, int indx2, int indx3) VL_MT_SAFE { const VerilatedDpiOpenVar* varp = _vl_openhandle_varp(d); @@ -358,7 +361,7 @@ static void _vl_svPutBitArrElemVecVal(const svOpenArrayHandle d, const svBitVecV return; // LCOV_EXCL_STOP } } -/// Copy to simulator open array from from user logic array +// Copy to simulator open array from from user logic array static void _vl_svPutLogicArrElemVecVal(const svOpenArrayHandle d, const svLogicVecVal* s, int nargs, int indx1, int indx2, int indx3) VL_MT_SAFE { const VerilatedDpiOpenVar* varp = _vl_openhandle_varp(d); @@ -381,7 +384,7 @@ static void _vl_svPutLogicArrElemVecVal(const svOpenArrayHandle d, const svLogic } } -/// Return bit from simulator open array +// Return bit from simulator open array static svBit _vl_svGetBitArrElem(const svOpenArrayHandle s, int nargs, int indx1, int indx2, int indx3, int indx4) VL_MT_SAFE { // One extra index supported, as need bit number @@ -396,7 +399,7 @@ static svBit _vl_svGetBitArrElem(const svOpenArrayHandle s, int nargs, int indx1 return 0; // LCOV_EXCL_STOP } } -/// Update simulator open array from bit +// Update simulator open array from bit static void _vl_svPutBitArrElem(const svOpenArrayHandle d, svBit value, int nargs, int indx1, int indx2, int indx3, int indx4) VL_MT_SAFE { // One extra index supported, as need bit number diff --git a/include/verilated_fst_c.h b/include/verilated_fst_c.h index fd43f365b..786058f10 100644 --- a/include/verilated_fst_c.h +++ b/include/verilated_fst_c.h @@ -49,8 +49,8 @@ private: std::map m_code2symbol; std::map m_local2fstdtype; std::list m_curScope; - fstHandle* m_symbolp = nullptr; ///< same as m_code2symbol, but as an array - char* m_strbuf = nullptr; ///< String buffer long enough to hold maxBits() chars + fstHandle* m_symbolp = nullptr; // same as m_code2symbol, but as an array + char* m_strbuf = nullptr; // String buffer long enough to hold maxBits() chars // CONSTRUCTORS VL_UNCOPYABLE(VerilatedFst); @@ -128,7 +128,7 @@ template <> void VerilatedTrace::set_time_resolution(const std::st /// Also derived for use in SystemC simulations. class VerilatedFstC final { - VerilatedFst m_sptrace; ///< Trace file being created + VerilatedFst m_sptrace; // Trace file being created // CONSTRUCTORS VL_UNCOPYABLE(VerilatedFstC); diff --git a/include/verilated_imp.h b/include/verilated_imp.h index 7a37b1017..3cf36bf0e 100644 --- a/include/verilated_imp.h +++ b/include/verilated_imp.h @@ -61,8 +61,8 @@ public: private: // MEMBERS - vluint32_t m_mtaskId; ///< MTask that did enqueue - std::function m_cb; ///< Lambda to execute when message received + vluint32_t m_mtaskId; // MTask that did enqueue + std::function m_cb; // Lambda to execute when message received public: // CONSTRUCTORS explicit VerilatedMsg(const std::function& cb) @@ -85,10 +85,10 @@ public: class VerilatedEvalMsgQueue final { using VerilatedThreadQueue = std::multiset; - std::atomic m_depth; ///< Current depth of queue (see comments below) + std::atomic m_depth; // Current depth of queue (see comments below) - VerilatedMutex m_mutex; ///< Mutex protecting queue - VerilatedThreadQueue m_queue VL_GUARDED_BY(m_mutex); ///< Message queue + VerilatedMutex m_mutex; // Mutex protecting queue + VerilatedThreadQueue m_queue VL_GUARDED_BY(m_mutex); // Message queue public: // CONSTRUCTORS VerilatedEvalMsgQueue() @@ -197,7 +197,7 @@ public: //====================================================================== // VerilatedContextImpData -/// Class for hidden implementation members inside VerilatedContext +// Class for hidden implementation members inside VerilatedContext // Avoids needing std::unordered_map inside verilated.h class VerilatedContextImpData final { friend class VerilatedContext; @@ -206,7 +206,7 @@ class VerilatedContextImpData final { protected: /// Map of // Used by scopeInsert, scopeFind, scopeErase, scopeNameMap - mutable VerilatedMutex m_nameMutex; ///< Protect m_nameMap + mutable VerilatedMutex m_nameMutex; // Protect m_nameMap VerilatedScopeNameMap m_nameMap VL_GUARDED_BY(m_nameMutex); }; @@ -407,22 +407,22 @@ protected: // MEMBERS // Nothing below here is save-restored; users expected to re-register appropriately - VerilatedMutex m_userMapMutex; ///< Protect m_userMap + VerilatedMutex m_userMapMutex; // Protect m_userMap // For userInsert, userFind. As indexed by pointer is common across contexts. - UserMap m_userMap VL_GUARDED_BY(m_userMapMutex); ///< Map of <(scope,userkey), userData> + UserMap m_userMap VL_GUARDED_BY(m_userMapMutex); // Map of <(scope,userkey), userData> - VerilatedMutex m_hierMapMutex; ///< Protect m_hierMap - /// Map that represents scope hierarchy + VerilatedMutex m_hierMapMutex; // Protect m_hierMap + // Map that represents scope hierarchy // Used by hierarchyAdd, hierarchyRemove, hierarchyMap VerilatedHierarchyMap m_hierMap VL_GUARDED_BY(m_hierMapMutex); // Slow - somewhat static: - VerilatedMutex m_exportMutex; ///< Protect m_nameMap - /// Map of + VerilatedMutex m_exportMutex; // Protect m_nameMap + // Map of // Used by exportInsert, exportFind, exportName. // Export numbers same across all contexts as just a string-to-number conversion ExportNameMap m_exportMap VL_GUARDED_BY(m_exportMutex); - int m_exportNext VL_GUARDED_BY(m_exportMutex) = 0; ///< Next export funcnum + int m_exportNext VL_GUARDED_BY(m_exportMutex) = 0; // Next export funcnum // CONSTRUCTORS VerilatedImpData() = default; diff --git a/include/verilated_save.h b/include/verilated_save.h index 23595f377..c2f5ec8a4 100644 --- a/include/verilated_save.h +++ b/include/verilated_save.h @@ -28,18 +28,23 @@ #include //============================================================================= -// VerilatedSerialize - convert structures to a stream representation -// This class is not thread safe, it must be called by a single thread +// VerilatedSerialize +/// Convert structures to a stream representation. +/// +/// User wrapper code will more typically use VerilatedSave which uses this +/// as a subclass to write a file. +/// +/// This class is not thread safe, it must be called by a single thread class VerilatedSerialize VL_NOT_FINAL { protected: // MEMBERS // For speed, keep m_cp as the first member of this structure - vluint8_t* m_cp; ///< Current pointer into m_bufp buffer - vluint8_t* m_bufp; ///< Output buffer - bool m_isOpen = false; ///< True indicates open file/stream - std::string m_filename; ///< Filename, for error messages - VerilatedAssertOneThread m_assertOne; ///< Assert only called from single thread + vluint8_t* m_cp; // Current pointer into m_bufp buffer + vluint8_t* m_bufp; // Output buffer + bool m_isOpen = false; // True indicates open file/stream + std::string m_filename; // Filename, for error messages + VerilatedAssertOneThread m_assertOne; // Assert only called from single thread static constexpr size_t bufferSize() { return 256 * 1024; } // See below for slack calculation static constexpr size_t bufferInsertSize() { return 16 * 1024; } @@ -51,19 +56,26 @@ protected: VL_UNCOPYABLE(VerilatedSerialize); public: + /// Construct VerilatedSerialize() { m_bufp = new vluint8_t[bufferSize()]; m_cp = m_bufp; } + /// Flish, close, and destruct virtual ~VerilatedSerialize() { close(); if (m_bufp) VL_DO_CLEAR(delete[] m_bufp, m_bufp = nullptr); } // METHODS + /// Return true if file is open bool isOpen() const { return m_isOpen; } + /// Return current filename std::string filename() const { return m_filename; } + /// Close the stream virtual void close() VL_MT_UNSAFE_ONE { flush(); } + /// Flush pending data to stream virtual void flush() VL_MT_UNSAFE_ONE {} + /// Write data to stream VerilatedSerialize& write(const void* __restrict datap, size_t size) VL_MT_UNSAFE_ONE { const vluint8_t* __restrict dp = (const vluint8_t* __restrict)datap; while (size) { @@ -87,19 +99,24 @@ private: }; //============================================================================= -// VerilatedDeserial - load structures from a stream representation -// This class is not thread safe, it must be called by a single thread +// VerilatedDeserialize +/// Load structures from a stream representation +/// +/// User wrapper code will more typically use VerilatedRestore which uses +/// this as a subclass to a read from a file. +/// +/// This class is not thread safe, it must be called by a single thread class VerilatedDeserialize VL_NOT_FINAL { protected: // MEMBERS // For speed, keep m_cp as the first member of this structure - vluint8_t* m_cp; ///< Current pointer into m_bufp buffer - vluint8_t* m_bufp; ///< Output buffer - vluint8_t* m_endp = nullptr; ///< Last valid byte in m_bufp buffer - bool m_isOpen = false; ///< True indicates open file/stream - std::string m_filename; ///< Filename, for error messages - VerilatedAssertOneThread m_assertOne; ///< Assert only called from single thread + vluint8_t* m_cp; // Current pointer into m_bufp buffer + vluint8_t* m_bufp; // Output buffer + vluint8_t* m_endp = nullptr; // Last valid byte in m_bufp buffer + bool m_isOpen = false; // True indicates open file/stream + std::string m_filename; // Filename, for error messages + VerilatedAssertOneThread m_assertOne; // Assert only called from single thread static constexpr size_t bufferSize() { return 256 * 1024; } // See below for slack calculation static constexpr size_t bufferInsertSize() { return 16 * 1024; } @@ -112,19 +129,26 @@ protected: VL_UNCOPYABLE(VerilatedDeserialize); public: + /// Construct VerilatedDeserialize() { m_bufp = new vluint8_t[bufferSize()]; m_cp = m_bufp; } + /// Destruct virtual ~VerilatedDeserialize() { close(); if (m_bufp) VL_DO_CLEAR(delete[] m_bufp, m_bufp = nullptr); } // METHODS + /// Return true if file is open bool isOpen() const { return m_isOpen; } + /// Return current filename std::string filename() const { return m_filename; } + /// Close the stream virtual void close() VL_MT_UNSAFE_ONE { flush(); } + /// Flush pending data to stream virtual void flush() VL_MT_UNSAFE_ONE {} + /// Read data from stream VerilatedDeserialize& read(void* __restrict datap, size_t size) VL_MT_UNSAFE_ONE { vluint8_t* __restrict dp = static_cast(datap); while (size) { @@ -137,6 +161,8 @@ public: } return *this; // For function chaining } + + // Internal use: // Read a datum and compare with expected value VerilatedDeserialize& readAssert(const void* __restrict datap, size_t size) VL_MT_UNSAFE_ONE; VerilatedDeserialize& readAssert(vluint64_t data) VL_MT_UNSAFE_ONE { @@ -154,42 +180,55 @@ private: }; //============================================================================= -// VerilatedSave - serialize to a file -// This class is not thread safe, it must be called by a single thread +// VerilatedSave +/// Stream-like object that serializes Verilated model to a file. +/// +/// This class is not thread safe, it must be called by a single thread class VerilatedSave final : public VerilatedSerialize { private: - int m_fd = -1; ///< File descriptor we're writing to + int m_fd = -1; // File descriptor we're writing to public: // CONSTRUCTORS + /// Construct new object VerilatedSave() = default; + /// Flush, close and destruct virtual ~VerilatedSave() override { close(); } // METHODS /// Open the file; call isOpen() to see if errors void open(const char* filenamep) VL_MT_UNSAFE_ONE; + /// Open the file; call isOpen() to see if errors void open(const std::string& filename) VL_MT_UNSAFE_ONE { open(filename.c_str()); } + /// Flush and close the file virtual void close() override VL_MT_UNSAFE_ONE; + /// Flush data to file virtual void flush() override VL_MT_UNSAFE_ONE; }; //============================================================================= -// VerilatedRestore - deserialize from a file -// This class is not thread safe, it must be called by a single thread +// VerilatedRestore +/// Stream-like object that serializes Verilated model from a file. +/// +/// This class is not thread safe, it must be called by a single thread class VerilatedRestore final : public VerilatedDeserialize { private: - int m_fd = -1; ///< File descriptor we're writing to + int m_fd = -1; // File descriptor we're writing to public: // CONSTRUCTORS + /// Construct new object VerilatedRestore() = default; + /// Flush, close and destruct virtual ~VerilatedRestore() override { close(); } // METHODS /// Open the file; call isOpen() to see if errors void open(const char* filenamep) VL_MT_UNSAFE_ONE; + /// Open the file; call isOpen() to see if errors void open(const std::string& filename) VL_MT_UNSAFE_ONE { open(filename.c_str()); } + /// Close the file virtual void close() override VL_MT_UNSAFE_ONE; virtual void flush() override VL_MT_UNSAFE_ONE {} virtual void fill() override VL_MT_UNSAFE_ONE; diff --git a/include/verilated_sym_props.h b/include/verilated_sym_props.h index c1d896731..4294aa0c6 100644 --- a/include/verilated_sym_props.h +++ b/include/verilated_sym_props.h @@ -15,7 +15,7 @@ /// \brief Verilated symbol inspection header /// /// This file is for inclusion by internal files that need to inspect -/// specific symbols. +/// specific symbols. Applications typically use the VPI instead. /// /// User wrapper code wanting to inspect the symbol table should use /// verilated_syms.h instead. @@ -31,8 +31,8 @@ #include //=========================================================================== -/// Verilator range -/// Thread safety: Assume is constructed only with model, then any number of readers +// Verilator range +// Thread safety: Assume is constructed only with model, then any number of readers // See also V3Ast::VNumRange class VerilatedRange final { @@ -64,8 +64,8 @@ public: }; //=========================================================================== -/// Verilator variable -/// Thread safety: Assume is constructed only with model, then any number of readers +// Verilator variable +// Thread safety: Assume is constructed only with model, then any number of readers class VerilatedVarProps VL_NOT_FINAL { // TYPES @@ -144,7 +144,7 @@ public: } vluint32_t entSize() const; bool isPublicRW() const { return ((m_vlflags & VLVF_PUB_RW) != 0); } - /// DPI compatible C standard layout + // DPI compatible C standard layout bool isDpiCLayout() const { return ((m_vlflags & VLVF_DPI_CLAY) != 0); } int udims() const { return m_udims; } int dims() const { return m_pdims + m_udims; } @@ -177,14 +177,14 @@ public: ? m_packed.elements() : VL_LIKELY(dim >= 1 && dim <= udims()) ? m_unpacked[dim - 1].elements() : 0; } - /// Total size in bytes (note DPI limited to 4GB) + // Total size in bytes (note DPI limited to 4GB) size_t totalSize() const; - /// Adjust a data pointer to access a given array element, NuLL if something goes bad + // Adjust a data pointer to access a given array element, NuLL if something goes bad void* datapAdjustIndex(void* datap, int dim, int indx) const; }; //=========================================================================== -/// Verilator DPI open array variable +// Verilator DPI open array variable class VerilatedDpiOpenVar final { // MEMBERS @@ -221,8 +221,8 @@ public: }; //=========================================================================== -/// Verilator variable -/// Thread safety: Assume is constructed only with model, then any number of readers +// Verilator variable +// Thread safety: Assume is constructed only with model, then any number of readers class VerilatedVar final : public VerilatedVarProps { // MEMBERS diff --git a/include/verilated_threads.h b/include/verilated_threads.h index 433d28f58..3416ae965 100644 --- a/include/verilated_threads.h +++ b/include/verilated_threads.h @@ -55,7 +55,7 @@ using VlThrSymTab = void*; using VlExecFnp = void (*)(bool, VlThrSymTab); -/// Track dependencies for a single MTask. +// Track dependencies for a single MTask. class VlMTaskVertex final { // MEMBERS static std::atomic s_yields; // Statistics diff --git a/include/verilated_trace.h b/include/verilated_trace.h index 3d0ccce3b..b0173f7fd 100644 --- a/include/verilated_trace.h +++ b/include/verilated_trace.h @@ -139,20 +139,20 @@ private: , m_userp{userp} {} }; - vluint32_t* m_sigs_oldvalp; ///< Old value store - vluint64_t m_timeLastDump; ///< Last time we did a dump - std::vector m_initCbs; ///< Routines to initialize traciong - std::vector m_fullCbs; ///< Routines to perform full dump - std::vector m_chgCbs; ///< Routines to perform incremental dump - std::vector m_cleanupCbs; ///< Routines to call at the end of dump - bool m_fullDump; ///< Whether a full dump is required on the next call to 'dump' - vluint32_t m_nextCode; ///< Next code number to assign - vluint32_t m_numSignals; ///< Number of distinct signals - vluint32_t m_maxBits; ///< Number of bits in the widest signal - std::string m_moduleName; ///< Name of module being trace initialized now + vluint32_t* m_sigs_oldvalp; // Old value store + vluint64_t m_timeLastDump; // Last time we did a dump + std::vector m_initCbs; // Routines to initialize traciong + std::vector m_fullCbs; // Routines to perform full dump + std::vector m_chgCbs; // Routines to perform incremental dump + std::vector m_cleanupCbs; // Routines to call at the end of dump + bool m_fullDump; // Whether a full dump is required on the next call to 'dump' + vluint32_t m_nextCode; // Next code number to assign + vluint32_t m_numSignals; // Number of distinct signals + vluint32_t m_maxBits; // Number of bits in the widest signal + std::string m_moduleName; // Name of module being trace initialized now char m_scopeEscape; - double m_timeRes; ///< Time resolution (ns/ms etc) - double m_timeUnit; ///< Time units (ns/ms etc) + double m_timeRes; // Time resolution (ns/ms etc) + double m_timeUnit; // Time units (ns/ms etc) void addCallbackRecord(std::vector& cbVec, CallbackRecord& cbRec) VL_MT_SAFE_EXCLUDES(m_mutex); diff --git a/include/verilated_vcd_c.cpp b/include/verilated_vcd_c.cpp index e1e3eb5c7..f7a18d138 100644 --- a/include/verilated_vcd_c.cpp +++ b/include/verilated_vcd_c.cpp @@ -53,14 +53,14 @@ // This size comes form VCD allowing use of printable ASCII characters between // '!' and '~' inclusive, which are a total of 94 different values. Encoding a // 32 bit code hence needs a maximum of ceil(log94(2**32-1)) == 5 bytes. -constexpr unsigned VL_TRACE_MAX_VCD_CODE_SIZE = 5; ///< Maximum length of a VCD string code +constexpr unsigned VL_TRACE_MAX_VCD_CODE_SIZE = 5; // Maximum length of a VCD string code // We use 8 bytes per code in a suffix buffer array. // 1 byte optional separator + VL_TRACE_MAX_VCD_CODE_SIZE bytes for code // + 1 byte '\n' + 1 byte suffix size. This luckily comes out to a power of 2, // meaning the array can be aligned such that entries never straddle multiple // cache-lines. -constexpr unsigned VL_TRACE_SUFFIX_ENTRY_SIZE = 8; ///< Size of a suffix entry +constexpr unsigned VL_TRACE_SUFFIX_ENTRY_SIZE = 8; // Size of a suffix entry //============================================================================= // Specialization of the generics for this trace format diff --git a/include/verilated_vcd_c.h b/include/verilated_vcd_c.h index 74efa39ca..0e5e2e336 100644 --- a/include/verilated_vcd_c.h +++ b/include/verilated_vcd_c.h @@ -38,7 +38,7 @@ class VerilatedVcd; class VerilatedVcdFile VL_NOT_FINAL { private: - int m_fd = 0; ///< File descriptor we're writing to + int m_fd = 0; // File descriptor we're writing to public: // METHODS VerilatedVcdFile() = default; @@ -61,25 +61,25 @@ private: //========================================================================= // VCD specific internals - VerilatedVcdFile* m_filep; ///< File we're writing to - bool m_fileNewed; ///< m_filep needs destruction - bool m_isOpen = false; ///< True indicates open file - bool m_evcd = false; ///< True for evcd format - std::string m_filename; ///< Filename we're writing to (if open) - vluint64_t m_rolloverMB = 0; ///< MB of file size to rollover at - int m_modDepth = 0; ///< Depth of module hierarchy + VerilatedVcdFile* m_filep; // File we're writing to + bool m_fileNewed; // m_filep needs destruction + bool m_isOpen = false; // True indicates open file + bool m_evcd = false; // True for evcd format + std::string m_filename; // Filename we're writing to (if open) + vluint64_t m_rolloverMB = 0; // MB of file size to rollover at + int m_modDepth = 0; // Depth of module hierarchy - char* m_wrBufp; ///< Output buffer - char* m_wrFlushp; ///< Output buffer flush trigger location - char* m_writep; ///< Write pointer into output buffer - vluint64_t m_wrChunkSize; ///< Output buffer size - vluint64_t m_wroteBytes = 0; ///< Number of bytes written to this file + char* m_wrBufp; // Output buffer + char* m_wrFlushp; // Output buffer flush trigger location + char* m_writep; // Write pointer into output buffer + vluint64_t m_wrChunkSize; // Output buffer size + vluint64_t m_wroteBytes = 0; // Number of bytes written to this file - std::vector m_suffixes; ///< VCD line end string codes + metadata - const char* m_suffixesp; ///< Pointer to first element of above + std::vector m_suffixes; // VCD line end string codes + metadata + const char* m_suffixesp; // Pointer to first element of above using NameMap = std::map; - NameMap* m_namemapp = nullptr; ///< List of names for the header + NameMap* m_namemapp = nullptr; // List of names for the header void bufferResize(vluint64_t minsize); void bufferFlush() VL_MT_UNSAFE_ONE; @@ -331,7 +331,7 @@ template <> void VerilatedTrace::set_time_resolution(const std::st /// Also derived for use in SystemC simulations. class VerilatedVcdC VL_NOT_FINAL { - VerilatedVcd m_sptrace; ///< Trace file being created + VerilatedVcd m_sptrace; // Trace file being created // CONSTRUCTORS VL_UNCOPYABLE(VerilatedVcdC); diff --git a/include/verilated_vpi.cpp b/include/verilated_vpi.cpp index 5089ad5e4..69c37a876 100644 --- a/include/verilated_vpi.cpp +++ b/include/verilated_vpi.cpp @@ -19,6 +19,9 @@ /// /// Use "verilator --vpi" to add this to the Makefile for the linker. /// +/// For documentation on the exported functions (named vpi_*) that are +/// implemented here, refer to the IEEE DPI chapter. +/// //========================================================================= #define VERILATOR_VERILATED_VPI_CPP_ @@ -57,8 +60,8 @@ constexpr unsigned VL_VPI_LINE_SIZE_ = 8192; // Base VPI handled object class VerilatedVpio VL_NOT_FINAL { // CONSTANTS - /// Magic value stored in front of object to detect double free etc - /// Must be odd, as aligned pointer can never be odd + // Magic value stored in front of object to detect double free etc + // Must be odd, as aligned pointer can never be odd static constexpr vluint32_t activeMagic() { return 0xfeed100f; } // MEM MANGLEMENT @@ -489,7 +492,7 @@ public: }; struct VerilatedVpiTimedCbsCmp { - /// Ordering sets keyed by time, then callback unique id + // Ordering sets keyed by time, then callback unique id bool operator()(const std::pair& a, const std::pair& b) const { if (a.first < b.first) return true; @@ -509,7 +512,7 @@ class VerilatedVpiImp final { VpioCbList m_cbObjLists[CB_ENUM_MAX_VALUE]; // Callbacks for each supported reason VpioTimedCbs m_timedCbs; // Time based callbacks VerilatedVpiError* m_errorInfop = nullptr; // Container for vpi error info - VerilatedAssertOneThread m_assertOne; ///< Assert only called from single thread + VerilatedAssertOneThread m_assertOne; // Assert only called from single thread vluint64_t m_nextCallbackId = 1; // Id to identify callback static VerilatedVpiImp& s() { // Singleton @@ -652,7 +655,7 @@ VL_THREAD_LOCAL vluint8_t* VerilatedVpio::t_freeHead = nullptr; //====================================================================== // VerilatedVpiError -/// Internal container for vpi error info +// Internal container for vpi error info class VerilatedVpiError final { t_vpi_error_info m_errorInfo; diff --git a/include/verilated_vpi.h b/include/verilated_vpi.h index 58ca002bb..d24600498 100644 --- a/include/verilated_vpi.h +++ b/include/verilated_vpi.h @@ -37,17 +37,17 @@ class VerilatedVpi final { public: - /// Call timed callbacks - /// Users should call this from their main loops + /// Call timed callbacks. + /// User wrapper code should call this from their main loops. static void callTimedCbs() VL_MT_UNSAFE_ONE; - /// Call value based callbacks - /// Users should call this from their main loops + /// Call value based callbacks. + /// User wrapper code should call this from their main loops. static bool callValueCbs() VL_MT_UNSAFE_ONE; - /// Call callbacks of arbitrary types - /// Users can call this from their application code + /// Call callbacks of arbitrary types. + /// User wrapper code should call this from their main loops. static bool callCbs(vluint32_t reason) VL_MT_UNSAFE_ONE; /// Returns time of the next registered VPI callback, or - /// ~(0) if none are registered + /// ~(0ULL) if none are registered static QData cbNextDeadline() VL_MT_UNSAFE_ONE; // Self test, for internal use only diff --git a/include/verilatedos.h b/include/verilatedos.h index 503fedb45..bdc71add4 100644 --- a/include/verilatedos.h +++ b/include/verilatedos.h @@ -120,15 +120,16 @@ # define VL_LIKELY(x) (!!(x)) ///< Boolean expression more often true than false # define VL_UNLIKELY(x) (!!(x)) ///< Boolean expression more often false than true #endif -# define VL_UNCOVERABLE(x) VL_UNLIKELY(x) ///< Boolean expression never hit by users (no coverage) +/// Boolean expression never hit by users (branch coverage disabled) +# define VL_UNCOVERABLE(x) VL_UNLIKELY(x) #ifndef VL_UNREACHABLE # define VL_UNREACHABLE ///< Point that may never be reached #endif #ifndef VL_PREFETCH_RD -# define VL_PREFETCH_RD(p) ///< Prefetch data with read intent +# define VL_PREFETCH_RD(p) ///< Prefetch pointed-to-data with read intent #endif #ifndef VL_PREFETCH_RW -# define VL_PREFETCH_RW(p) ///< Prefetch data with read/write intent +# define VL_PREFETCH_RW(p) ///< Prefetch pointed-to-data with read/write intent #endif #if defined(VL_THREADED) && !defined(VL_CPPCHECK) @@ -141,31 +142,38 @@ # else # error "Unsupported compiler for VL_THREADED: No thread-local declarator" # endif -# define VL_THREAD_LOCAL thread_local ///< Use new C++ static local thread +# define VL_THREAD_LOCAL thread_local ///< "thread_local" when supported #else -# define VL_THREAD_LOCAL ///< Use new C++ static local thread +# define VL_THREAD_LOCAL ///< "thread_local" when supported #endif #ifndef VL_NO_LEGACY -# define VL_THREAD ///< Deprecated -# define VL_STATIC_OR_THREAD static ///< Deprecated +# define VL_THREAD // Deprecated +# define VL_STATIC_OR_THREAD static // Deprecated #endif -#define VL_PURE ///< Comment tag that Function is pure (and thus also VL_MT_SAFE) -#define VL_MT_SAFE ///< Comment tag that function is threadsafe when VL_THREADED -#define VL_MT_SAFE_POSTINIT ///< Comment tag that function is threadsafe when VL_THREADED, only - ///< during normal operation (post-init) -#define VL_MT_SAFE_EXCLUDES(mutex) VL_EXCLUDES(mutex) ///< Threadsafe and uses given mutex -#define VL_MT_UNSAFE ///< Comment tag that function is not threadsafe when VL_THREADED -#define VL_MT_UNSAFE_ONE ///< Comment tag that function is not threadsafe when VL_THREADED, - ///< protected to make sure single-caller +/// Comment tag that Function is pure (and thus also VL_MT_SAFE) +#define VL_PURE +/// Comment tag that function is threadsafe when VL_THREADED +#define VL_MT_SAFE +/// Comment tag that function is threadsafe when VL_THREADED, only +/// during normal operation (post-init) +#define VL_MT_SAFE_POSTINIT +/// Clang threadsafe and uses given mutex +#define VL_MT_SAFE_EXCLUDES(mutex) VL_EXCLUDES(mutex) +/// Comment tag that function is not threadsafe when VL_THREADED +#define VL_MT_UNSAFE +/// Comment tag that function is not threadsafe when VL_THREADED, +/// protected to make sure single-caller +#define VL_MT_UNSAFE_ONE #ifndef VL_NO_LEGACY -# define VL_ULL(c) (c##ULL) ///< Add appropriate suffix to 64-bit constant (deprecated) +# define VL_ULL(c) (c##ULL) // Add appropriate suffix to 64-bit constant (deprecated) #endif -// This is not necessarily the same as #UL, depending on what the IData typedef is. -#define VL_UL(c) (static_cast(c##UL)) ///< Add appropriate suffix to 32-bit constant +/// Convert argument to IData +/// This is not necessarily the same as #UL, depending on what the IData typedef is. +#define VL_UL(c) (static_cast(c##UL)) #if defined(VL_CPPCHECK) || defined(__clang_analyzer__) || __cplusplus < 201103L # define VL_DANGLING(var) @@ -384,7 +392,7 @@ typedef unsigned long long vluint64_t; ///< 64-bit unsigned type #define VL_CACHE_LINE_BYTES 64 ///< Bytes in a cache line (for alignment) #ifndef VL_NO_LEGACY -# define VL_WORDSIZE VL_IDATASIZE ///< Legacy define +# define VL_WORDSIZE VL_IDATASIZE // Legacy define #endif /// Bytes this number of bits needs (1 bit=1 byte) @@ -397,10 +405,10 @@ typedef unsigned long long vluint64_t; ///< 64-bit unsigned type //========================================================================= // Class definition helpers -/// Used to indicate a base class, e.g. cannot label "class final" +/// Comment tag to indicate a base class, e.g. cannot label "class final" #define VL_NOT_FINAL -/// Used to declare a class as uncopyable; put after a private: +/// Declare a class as uncopyable; put after a private: #define VL_UNCOPYABLE(Type) \ Type(const Type& other) = delete; \ Type& operator=(const Type&) = delete