/** * @file include/ActivMiddleware/ActivBase/Tracing/TraceBufferBase.h * * @brief Header for the TraceBufferBase class. */ #if (!defined ACTIV_BASE_TRACING_TRACE_BUFFER_BASE_H) #define ACTIV_BASE_TRACING_TRACE_BUFFER_BASE_H #include "ActivMiddleware/ActivBase/External.h" #include "ActivMiddleware/ActivBase/Tracing/TimestampedTraceEvent.h" #include "ActivMiddleware/CxxYZ/memory.h" #include "ActivMiddleware/Misc/StringView.h" #include //! Activ namespace. namespace Activ { //! TracingDetail namespace. namespace TracingDetail { //! Empty static data class. struct EmptyStaticData {}; // --------------------------------------------------------------------------------------------------------------------------------- //! Invoke Decode with static data. template String DispatchDecode(const T &event, const StaticData &staticData) { return event.Decode(staticData); } // --------------------------------------------------------------------------------------------------------------------------------- //! Invoke Decode without static data. template String DispatchDecode(const T &event, const EmptyStaticData &staticData) { return event.Decode(); } } // namespace TracingDetail // --------------------------------------------------------------------------------------------------------------------------------- // --------------------------------------------------------------------------------------------------------------------------------- //! Buffer to store recent trace history. class TraceBufferBase { public: typedef TracingDetail::EmptyStaticData EmptyStaticData; /** * @brief Default constructor. * * @param entryCount number of entries. */ ACTIV_BASE_API explicit TraceBufferBase(const uint32_t entryCount); //! Destructor. ACTIV_BASE_API virtual ~TraceBufferBase(); /** * @brief Register a statically allocated trace point. * * @tparam T the event type. */ template void Register(); /** * @brief Register a statically allocated trace point. * * Statically allocated trace point ids are a little more efficient. * * @param staticData argument to be passed to T::Decode(). * * @tparam T the event type. */ template void Register(const StaticData &staticData); /** * @brief Register a statically allocated timestamp trace point. * * @param id * @param event */ ACTIV_BASE_API void RegisterTimestamp(const TracePointId id, const String &event); /** * @brief Remove a trace point. * * @param tracePoint the trace point object. */ ACTIV_BASE_API void Remove(const TracePointId tracePointId); /** * @brief Record an event. * * The trace point id must be available from T::ID. * * @tparam The trace event type to record. * * @return User structure to record the event data. */ template T &Record(); /** * @brief Record an event with the provided timestamp. * * The trace point id must be available from T::ID. * * @tparam The trace event type to record. * * @param timestamp provided timestamp to record. * * @return User structure to record the event data. */ template T &Record(const uint64_t timestamp); /** * @brief Record an event with the provided id. * * @tparam The trace event type to record. * * @param tracePointId the trace point id. * * @return User structure to record the event data. */ template T &Record(const TracePointId tracePointId); /** * @brief Record an event with the provided id and timestamp. * * @tparam The trace event type to record. * * @param timestamp provided timestamp to record. * * @return User structure to record the event data. */ template T &Record(const TracePointId tracePointId, const uint64_t timestamp); /** * @brief Record a timestamp event. * * @param tracePointId id of the trace point. * @param timestamp the timestamp to record. */ void RecordTimestamp(const TracePointId tracePointId, const uint64_t timestamp = IntervalTimer::GetNanosecondTimeStamp()); /** * @brief Record a timestamp event with a literal string. * * @param string string to be copied into the event, truncated if necessary. * @param timestamp the timestamp to record. */ void RecordTimestamp(const String &string, const uint64_t timestamp = IntervalTimer::GetNanosecondTimeStamp()); /** * @brief Record a timestamp event with a string view. * * @param string string to be copied into the event, truncated if necessary. * @param timestamp the timestamp to record. */ void RecordTimestamp(const CxxYZ::string_view &string, const uint64_t timestamp = IntervalTimer::GetNanosecondTimeStamp()); /** * @brief Record a timestamp event with a string literal. * * This method should only be used with pointers that are valid for the scope of the TraceBuffer. * * @param pString string literal pointer copied into the event. * @param timestamp the timestamp to record. */ void RecordTimestampLiteral(const char * const pString, const uint64_t timestamp = IntervalTimer::GetNanosecondTimeStamp()); /** * @brief Record a generic event to the trace buffer without a timestamp. * * @param string string to write to buffer, truncated if exceeds maximum length. */ void RecordGeneric(const String &string); /** * @brief Record a generic event to the trace buffer without a timestamp. * * @param string string to write to buffer, truncated if exceeds maximum length. */ void RecordGeneric(const CxxYZ::string_view &string); /** * @brief Record a generic event to the trace buffer without a timestamp using a string literal. * * This method should only be used with pointers that are valid for the scope of the TraceBuffer. * * @param pString string literal pointer copied into the event. */ void RecordGenericLiteral(const char * const pString); //! The maximum size of a trace event. static const size_t MAX_EVENT_SIZE = 64; //! The maximum size of the user content of a trace event. static const size_t MAX_USER_SIZE = 64 - sizeof(TraceEvent); static const TracePointId TRACE_POINT_INVALID = 0; static const TracePointId TRACE_POINT_TIMESTAMP_STRING = 1; static const TracePointId TRACE_POINT_TIMESTAMP_LITERAL = 2; static const TracePointId TRACE_POINT_GENERIC_STRING = 3; static const TracePointId TRACE_POINT_GENERIC_LITERAL = 4; static const TracePointId TRACE_POINT_DYNAMIC_START = 100000; protected: //! Base trace point class. class ITracePoint { public: virtual ~ITracePoint() { } virtual void Decode(const TraceEvent &event, String &string, uint64_t ×tamp) const = 0; virtual String GetEventTypeName() const = 0; }; //! Trace point template class forwarding the Decode() call with the correct type. template class TracePointT : public ITracePoint { public: TracePointT(const StaticData &staticData) : m_staticData(staticData) { } virtual void Decode(const TraceEvent &event, String &string, uint64_t ×tamp) const ACTIV_OVERRIDE { // Simplify usage by providing the right event type. // DispatchDecode hides static data if it is empty. string = TracingDetail::DispatchDecode(static_cast(event), m_staticData); timestamp = static_cast(event).GetTimestamp(); } virtual String GetEventTypeName() const ACTIV_OVERRIDE { return String(typeid(T).name()); } StaticData m_staticData; }; //! Padded event struct to build the array from. struct Event : TraceEvent { uint8_t m_data[MAX_USER_SIZE]; }; //! Struct used in RecordTimestamp. struct TimestampEvent : TimestampedTraceEvent { String Decode(const String &event) const { return event; } }; //! Struct used in RecordTimestamp taking a string. struct TimestampStringEvent : TimestampedTraceEvent { String Decode() const { return String(m_string, m_length); } static const TracePointId ID = TRACE_POINT_TIMESTAMP_STRING; uint8_t m_length; char m_string[MAX_USER_SIZE - (sizeof(TimestampedTraceEvent) + sizeof(uint8_t))]; }; //! Struct used in RecordTimestampLiteral. struct TimestampLiteralEvent : TimestampedTraceEvent { String Decode() const { return String(m_pString); } static const TracePointId ID = TRACE_POINT_TIMESTAMP_LITERAL; const char * m_pString; }; //! Struct used in RecordGeneric. struct GenericStringEvent : TraceEvent { String Decode() const { return String(m_string, m_length); } static const TracePointId ID = TRACE_POINT_GENERIC_STRING; uint8_t m_length; char m_string[MAX_USER_SIZE - sizeof(uint8_t)]; }; //! Struct used in RecordGenericLiteral. struct GenericLiteralEvent : TraceEvent { String Decode() const { return String(m_pString); } static const TracePointId ID = TRACE_POINT_GENERIC_LITERAL; const char * m_pString; }; /** * @brief Add a trace point class with a dynamically allocated id. * * @param pTracePoint pointer to an ITracePoint object. */ ACTIV_BASE_API TracePointId Add(CxxYZ::unique_ptr &pTracePoint); //! Regiser a trace point to a statically allocated id. ACTIV_BASE_API void Register(const TracePointId tracePointId, CxxYZ::unique_ptr &pTracePoint); //! Swap the m_pEventList buffer, used by ActivFramework when logging. ACTIV_BASE_API void SwapBuffers(); /** * @brief Get a trace point object for an id. * * @return pointer to the trace point or null if not found. */ ACTIV_BASE_API const ITracePoint *GetTracePoint(const TracePointId tracePointId) const; // Check event is the right size. ACTIV_BOOST_STATIC_ASSERT(sizeof(Event) == MAX_EVENT_SIZE); class Impl; Event * m_pEventList; ///< Pointer to the current event array. uint32_t m_eventNumber; ///< The current event number. uint32_t m_eventMask; ///< The mask to apply to the event number to get an index. CxxYZ::unique_ptr m_pImpl; ///< Private implementation details. }; // --------------------------------------------------------------------------------------------------------------------------------- template inline T &TraceBufferBase::Record() { return Record(T::ID); } // --------------------------------------------------------------------------------------------------------------------------------- template inline T &TraceBufferBase::Record(const uint64_t timestamp) { return Record(T::ID, timestamp); } // --------------------------------------------------------------------------------------------------------------------------------- template inline T &TraceBufferBase::Record(const TracePointId tracePointId) { ACTIV_BOOST_STATIC_ASSERT(sizeof(T) <= MAX_EVENT_SIZE); TraceEvent &event = m_pEventList[m_eventNumber++ & m_eventMask]; event.m_tracePointId = tracePointId; // Generates a timestamp if supported. static_cast(event).GenerateTimestamp(); return static_cast(event); } // --------------------------------------------------------------------------------------------------------------------------------- template inline T &TraceBufferBase::Record(const TracePointId tracePointId, const uint64_t timestamp) { ACTIV_BOOST_STATIC_ASSERT(sizeof(T) <= MAX_EVENT_SIZE); TraceEvent &event = m_pEventList[m_eventNumber++ & m_eventMask]; event.m_tracePointId = tracePointId; static_cast(event).SetTimestamp(timestamp); return static_cast(event); } // --------------------------------------------------------------------------------------------------------------------------------- inline void TraceBufferBase::RecordTimestamp(const TracePointId tracePointId, const uint64_t timestamp) { Record(tracePointId, timestamp); } // --------------------------------------------------------------------------------------------------------------------------------- inline void TraceBufferBase::RecordTimestamp(const String &string, const uint64_t timestamp) { RecordTimestamp(ToStringType(string), timestamp); } // --------------------------------------------------------------------------------------------------------------------------------- inline void TraceBufferBase::RecordTimestamp(const CxxYZ::string_view &string, const uint64_t timestamp) { TimestampStringEvent &event = Record(timestamp); event.m_length = static_cast(std::min(string.length(), sizeof(event.m_string))); ::memcpy(event.m_string, string.data(), event.m_length); } // --------------------------------------------------------------------------------------------------------------------------------- inline void TraceBufferBase::RecordTimestampLiteral(const char * const pString, const uint64_t timestamp) { TimestampLiteralEvent &event = Record(timestamp); event.m_pString = pString; } // --------------------------------------------------------------------------------------------------------------------------------- inline void TraceBufferBase::RecordGeneric(const String &string) { RecordGeneric(ToStringType(string)); } // --------------------------------------------------------------------------------------------------------------------------------- inline void TraceBufferBase::RecordGeneric(const CxxYZ::string_view &string) { GenericStringEvent &event = Record(); event.m_length = static_cast(std::min(string.length(), sizeof(event.m_string))); ::memcpy(event.m_string, string.data(), event.m_length); } // --------------------------------------------------------------------------------------------------------------------------------- inline void TraceBufferBase::RecordGenericLiteral(const char * const pString) { assert(pString); GenericLiteralEvent &event = Record(); event.m_pString = pString; } // --------------------------------------------------------------------------------------------------------------------------------- template void TraceBufferBase::Register() { CxxYZ::unique_ptr pTracePoint(new TracePointT(EmptyStaticData())); Register(T::ID, pTracePoint); } // --------------------------------------------------------------------------------------------------------------------------------- template void TraceBufferBase::Register(const StaticData &staticData) { CxxYZ::unique_ptr pTracePoint(new TracePointT(staticData)); Register(T::ID, pTracePoint); } } // namespace Activ #endif // (!defined ACTIV_BASE_TRACING_TRACE_BUFFER_BASE_H)