/* * Percepio Trace Recorder for Tracealyzer v4.6.0 * Copyright 2021 Percepio AB * www.percepio.com * * SPDX-License-Identifier: Apache-2.0 */ /** * @file * * @brief Public trace event APIs. */ #ifndef TRC_EVENT_H #define TRC_EVENT_H #if ( TRC_USE_TRACEALYZER_RECORDER == 1 ) #if ( TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING ) #include #ifdef __cplusplus extern "C" { #endif /** * @defgroup trace_event_apis Trace Event APIs * @ingroup trace_recorder_apis * @{ */ /** * @internal Macro helper for setting trace event parameter count. */ #define TRC_EVENT_SET_PARAM_COUNT( id, n ) ( ( ( uint16_t ) ( id ) ) | ( ( ( ( uint16_t ) ( n ) ) & 0xF ) << 12 ) ) /** * @internal Macro helper for getting trace event parameter count. */ #define TRC_EVENT_GET_PARAM_COUNT( id ) ( ( ( id ) >> 12 ) & 0xF ) #if ( TRC_CFG_CORE_COUNT > 1 ) #define TRC_EVENT_SET_EVENT_COUNT( c ) ( ( ( TRC_CFG_GET_CURRENT_CORE() & 0xF ) << 12 ) | ( ( uint16_t ) ( c ) & 0xFFF ) ) #else #define TRC_EVENT_SET_EVENT_COUNT( c ) ( uint16_t ) ( c ) #endif /** * @internal Macro helpder for setting base event data. */ #define SET_BASE_EVENT_DATA( pxEvent, eventId, paramCount, eventCount ) \ ( \ ( pxEvent )->EventID = TRC_EVENT_SET_PARAM_COUNT( eventId, paramCount ), \ ( pxEvent )->EventCount = TRC_EVENT_SET_EVENT_COUNT( eventCount ), \ xTraceTimestampGet( &( pxEvent )->TS ) \ ) /** * @internal Macro helper for resetting trace event data. */ #define RESET_EVENT_DATA( p ) \ ( \ ( p )->pvBlob = 0, \ ( p )->size = 0, \ ( p )->offset = 0 \ ) /** * @internal Macro optimization for getting trace event size. */ #define TRC_EVENT_GET_SIZE( pvAddress, puiSize ) ( *( uint32_t * ) ( puiSize ) = sizeof( TraceBaseEvent_t ) + ( TRC_EVENT_GET_PARAM_COUNT( ( ( TraceBaseEvent_t * ) ( pvAddress ) )->EventID ) ) * sizeof( uint32_t ), TRC_SUCCESS ) /** * @internal Macro optimization for getting trace event data pointer with an offset. */ #define TRC_EVENT_GET_RAW_DATA( xEventHandle, uiOffset, uiSize, ppvData ) ( ( void ) ( uiSize ), *( void ** ) ( ppvData ) = ( void * ) &( ( uint8_t * ) ( ( TraceEventData_t * ) ( xEventHandle ) )->pvBlob )[ uiOffset ], TRC_SUCCESS ) /** * @internal Macro optimization for getting trace event payload pointer with an offset. */ #define TRC_EVENT_GET_PAYLOAD( xEventHandle, uiOffset, uiSize, ppvData ) ( ( void ) ( uiSize ), *( void ** ) ( ppvData ) = ( void * ) &( ( uint8_t * ) ( ( TraceEventData_t * ) ( xEventHandle ) )->pvBlob )[ sizeof( TraceBaseEvent_t ) + ( uiOffset ) ], TRC_SUCCESS ) /** * @internal Macro optimization for getting trace event remaining payload size. */ #define TRC_EVENT_PAYLOAD_REMAINING( xEventHandle, puiValue ) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2( *( uint32_t * ) ( puiValue ) = ( ( TraceEventData_t * ) ( xEventHandle ) )->size - ( ( TraceEventData_t * ) ( xEventHandle ) )->offset, TRC_SUCCESS ) /** * @internal Macro optimization for getting trace event used payload size. */ #define TRC_EVENT_PAYLOAD_USED( xEventHandle, puiValue ) ( *( uint32_t * ) ( puiValue ) = ( ( TraceEventData_t * ) ( xEventHandle ) )->offset - sizeof( TraceBaseEvent_t ), TRC_SUCCESS ) /** * @internal Macro optimization getting trace event payload size. */ #define TRC_EVENT_PAYLOAD_SIZE( xEventHandle, puiValue ) ( *( uint32_t * ) ( puiValue ) = ( ( TraceEventData_t * ) ( xEventHandle ) )->size - sizeof( TraceBaseEvent_t ), TRC_SUCCESS ) /** * @internal Macro optimization for adding a pointer address to trace event. */ #define TRC_EVENT_ADD_POINTER( xEventHandle, value ) \ TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3( \ ( ( void ** ) ( ( TraceEventData_t * ) ( xEventHandle ) )->pvBlob )[ ( ( TraceEventData_t * ) ( xEventHandle ) )->offset / sizeof( void * ) ] = ( value ), \ ( ( TraceEventData_t * ) ( xEventHandle ) )->offset += sizeof( void * ), \ TRC_SUCCESS \ ) /** * @internal Macro optimization for adding a unsigned base type to trace event. */ #define TRC_EVENT_ADD_UNSIGNED_BASE_TYPE( xEventHandle, value ) \ TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3( \ ( ( TraceUnsignedBaseType_t * ) ( ( TraceEventData_t * ) ( xEventHandle ) )->pvBlob )[ ( ( TraceEventData_t * ) ( xEventHandle ) )->offset / sizeof( TraceUnsignedBaseType_t ) ] = ( value ), \ ( ( TraceEventData_t * ) ( xEventHandle ) )->offset += sizeof( TraceUnsignedBaseType_t ), \ TRC_SUCCESS \ ) /** * @internal Macro optimization for adding a 32-bit value to trace event. */ #define TRC_EVENT_ADD_32( xEventHandle, value ) \ TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3( \ ( ( uint32_t * ) ( ( TraceEventData_t * ) ( xEventHandle ) )->pvBlob )[ ( ( TraceEventData_t * ) ( xEventHandle ) )->offset / sizeof( uint32_t ) ] = ( value ), \ ( ( TraceEventData_t * ) ( xEventHandle ) )->offset += sizeof( uint32_t ), \ TRC_SUCCESS \ ) /** * @internal Macro optimization for adding a 16-bit value to trace event. */ #define TRC_EVENT_ADD_16( xEventHandle, value ) \ TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3( \ ( ( uint16_t * ) ( ( TraceEventData_t * ) ( xEventHandle ) )->pvBlob )[ ( ( TraceEventData_t * ) ( xEventHandle ) )->offset / sizeof( uint16_t ) ] = ( value ), \ ( ( TraceEventData_t * ) ( xEventHandle ) )->offset += sizeof( uint16_t ), \ TRC_SUCCESS \ ) /** * @internal Macro optimization for adding a 8-bit value to trace event. */ #define TRC_EVENT_ADD_8( xEventHandle, value ) \ TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3( \ ( ( uint8_t * ) ( ( TraceEventData_t * ) ( xEventHandle ) )->pvBlob )[ ( ( TraceEventData_t * ) ( xEventHandle ) )->offset / sizeof( uint8_t ) ] = ( value ), \ ( ( TraceEventData_t * ) ( xEventHandle ) )->offset += sizeof( uint8_t ), \ TRC_SUCCESS \ ) /** * @internal Macro optimization for beginning an offline trace event. */ #define TRC_EVENT_BEGIN_OFFLINE( uiEventCode, uiPayloadSize, pxEventHandle ) \ ( \ ( xTraceEventBeginRawOffline( sizeof( TraceBaseEvent_t ) + ( uiPayloadSize ), pxEventHandle ) ) == TRC_SUCCESS ? \ ( \ pxTraceEventDataTable->coreEventData[ TRC_CFG_GET_CURRENT_CORE() ].eventCounter++, \ SET_BASE_EVENT_DATA( ( TraceBaseEvent_t * ) ( ( ( TraceEventData_t * ) *( pxEventHandle ) )->pvBlob ), \ uiEventCode, \ ( ( ( TraceEventData_t * ) *( pxEventHandle ) )->size - sizeof( TraceBaseEvent_t ) ) / sizeof( uint32_t ), \ pxTraceEventDataTable->coreEventData[ TRC_CFG_GET_CURRENT_CORE() ].eventCounter ), \ ( ( TraceEventData_t * ) *( pxEventHandle ) )->offset += sizeof( TraceBaseEvent_t ), \ TRC_SUCCESS \ ) : TRC_FAIL \ ) /** * @internal Macro optimization for ending an offline trace event. */ #define TRC_EVENT_END_OFFLINE( xEventHandle ) \ TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4( \ xTraceStreamPortCommit( ( ( TraceEventData_t * ) ( xEventHandle ) )->pvBlob, \ ( ( TraceEventData_t * ) ( xEventHandle ) )->size, &DUMMY_iTraceBytesCommitted ), \ RESET_EVENT_DATA( ( TraceEventData_t * ) ( xEventHandle ) ), \ TRC_SUCCESS \ ) /** * @internal Trace Base Event Structure */ typedef struct { uint16_t EventID; /**< */ uint16_t EventCount; /**< */ uint32_t TS; /**< */ } TraceBaseEvent_t; /** * @internal Trace Event Data Structure */ typedef struct TraceEventData { void * pvBlob; /**< */ uint32_t size; /**< */ uint32_t offset; /**< */ } TraceEventData_t; /** * @internal Trace Core Event Data Structure */ typedef struct TraceCoreEventData { TraceEventData_t eventData[ ( TRC_CFG_MAX_ISR_NESTING ) + 1 ]; /**< */ uint32_t eventCounter; /**< */ } TraceCoreEventData_t; /** * @internal Trace Event Data Table Structure. */ typedef struct TraceEventDataTable { TraceCoreEventData_t coreEventData[ TRC_CFG_CORE_COUNT ]; /**< Holds data about current event for each core/isr depth */ } TraceEventDataTable_t; #define TRC_EVENT_DATA_BUFFER_SIZE ( sizeof( TraceEventDataTable_t ) ) /** * @internal Trace Event Data Buffer Structure. */ typedef struct TraceEventDataBuffer { uint8_t buffer[ TRC_EVENT_DATA_BUFFER_SIZE ]; /**< */ } TraceEventDataBuffer_t; extern TraceEventDataTable_t * pxTraceEventDataTable; /** * @internal Initialize event trace system. * * @param[in] pxBuffer Pointer to memory that will be used by the event * trace system. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ traceResult xTraceEventInitialize( TraceEventDataBuffer_t * pxBuffer ); /** * @brief Gets trace event size. * * @param[in] pvAddress Pointer to initialized trace event. * @param[out] puiSize Size. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ traceResult xTraceEventGetSize( void * pvAddress, uint32_t * puiSize ); /** * @internal Begins a raw trace event offline. * * This routine begins a trace event with specified size. Must call xTraceEventEnd() * to finalize event creation. Does not care about RecorderEnabled. * * @param[in] uiSize Size. * @param[in] pxEventHandle Pointer to initialized trace event. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ traceResult xTraceEventBeginRawOffline( uint32_t uiSize, TraceEventHandle_t * pxEventHandle ); /** * @internal Begins a blocking trace event offline. * * This routine begins a trace event with specified size. Must call xTraceEventEnd() * to finalize event creation. Does not care about RecorderEnabled. * * @param[in] uiSize Size. * @param[in] pxEventHandle Pointer to initialized trace event. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ traceResult xTraceEventBeginRawOfflineBlocking( uint32_t uiSize, TraceEventHandle_t * pxEventHandle ); /** * @internal Begins a trace event offline. * * This routine begins a trace event with specified size. Must call xTraceEventEnd() * to finalize event creation. Does not care about RecorderEnabled. * * @param[in] uiSize Size. * @param[in] pxEventHandle Pointer to initialized trace event. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ #define xTraceEventBeginOffline TRC_EVENT_BEGIN_OFFLINE /** * @brief Begins a trace event. * * This routine begins a trace event with specified size. Must call xTraceEventEnd() * to finalize event creation. Does not care about RecorderEnabled. * * @param[in] uiSize Size. * @param[in] pxEventHandle Pointer to initialized trace event. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ #define xTraceEventBegin( uiEventCode, uiTotalPayloadSize, pxEventHandle ) \ ( xTraceIsRecorderEnabled() ? xTraceEventBeginOffline( uiEventCode, uiTotalPayloadSize, pxEventHandle ) : TRC_FAIL ) /** * @internal Ends a trace event offline. * * This routine ends the event that was begun by calling on xTraceEventBegin(). * Does not care about uiRecorderEnabled. * * @param[in] xEventHandle Pointer to initialized trace event. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ traceResult xTraceEventEndOffline( TraceEventHandle_t xEventHandle ); /** * @internal Ends a blocking event offline. * * Ends the event that was begun by calling on xTraceEventBegin() * * @param[in] xEventHandle Pointer to initialized trace event. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ traceResult xTraceEventEndOfflineBlocking( TraceEventHandle_t xEventHandle ); /** * @brief Ends a trace event. * * This routine ends the event that was begun by calling on xTraceEventBegin(). * Does not care about uiRecorderEnabled. * * @param[in] xEventHandle Pointer to initialized trace event. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ #define xTraceEventEnd( xEventHandle ) \ ( xTraceIsRecorderEnabled() == 0 ? TRC_FAIL : xTraceEventEndOffline( xEventHandle ) ) /** * @brief Adds data to event payload. * * @param[in] xEventHandle Pointer to initialized trace event. * @param[in] pvData Pointer to data. * @param[in] uiSize Size. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ traceResult xTraceEventAddData( TraceEventHandle_t xEventHandle, void * pvData, uint32_t uiSize ); #if ( ( TRC_CFG_USE_TRACE_ASSERT ) == 1 ) /** * @brief Gets trace event data pointer with an offset. * * This routine gets a trace event data pointer with an offset. It also verfies * that the size so it won't go outside its buffer. * * @param[in] xEventHandle Pointer to initialized trace event. * @param[in] uiOffset Offset. * @param[in] uiSize Size. * @param[out] ppvData Data. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ traceResult xTraceEventGetRawData( TraceEventHandle_t xEventHandle, uint32_t uiOffset, uint32_t uiSize, void ** ppvData ); /** * @brief Gets trace event payload pointer with an offset. * * This routine gets a trace event payload pointer with an offset. It also verifies * that the size so it won't go outside its payload buffer. * * @param[in] xEventHandle Pointer to initialized trace event. * @param[in] uiOffset Offset. * @param[in] uiSize Size. * @param[out] ppvData Data. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ traceResult xTraceEventGetPayload( TraceEventHandle_t xEventHandle, uint32_t uiOffset, uint32_t uiSize, void ** ppvData ); /** * @brief Gets the amount of remaining trace event payload. * * @param[in] xEventHandle Pointer to initialized trace event. * @param[out] puiValue Value. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ traceResult xTraceEventPayloadRemaining( TraceEventHandle_t xEventHandle, uint32_t * puiValue ); /** * @brief Gets the amount of used trace event payload. * * @param[in] xEventHandle Pointer to initialized trace event. * @param[out] puiValue Value * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ traceResult xTraceEventPayloadUsed( TraceEventHandle_t xEventHandle, uint32_t * puiValue ); /** * @brief Gets trace event payload size. * * @param[in] xEventHandle Pointer to initialized trace event. * @param[out] puiValue Value * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ traceResult xTraceEventPayloadSize( TraceEventHandle_t xEventHandle, uint32_t * puiValue ); /** * @brief Adds an unsigned base type value as trace event payload * * @param[in] xEventHandle Pointer to initialized trace event. * @param[in] uxValue Value. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ traceResult xTraceEventAddUnsignedBaseType( TraceEventHandle_t xEventHandle, TraceUnsignedBaseType_t uxValue ); /** * @brief Adds a pointer address as trace event payload * * @param[in] xEventHandle Pointer to initialized trace event. * @param[in] pvAddress Address. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ traceResult xTraceEventAddPointer( TraceEventHandle_t xEventHandle, void * pvAddress ); /** * @brief Adds an uint32_t as trace event payload * * @param[in] xEventHandle Pointer to initialized trace event. * @param[in] value Value. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ traceResult xTraceEventAdd32( TraceEventHandle_t xEventHandle, uint32_t value ); /** * @brief Adds an uint16_t as trace event payload * * @param[in] xEventHandle Pointer to initialized trace event. * @param[in] value Value. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ traceResult xTraceEventAdd16( TraceEventHandle_t xEventHandle, uint16_t value ); /** * @brief Adds an uint8_t as trace event payload. * * @param[in] xEventHandle Pointer to initialized trace event. * @param[in] value Value. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ traceResult xTraceEventAdd8( TraceEventHandle_t xEventHandle, uint8_t value ); #else /* ((TRC_CFG_USE_TRACE_ASSERT) == 1) */ /** * @brief Gets trace event size. * * @param[in] pvAddress Pointer to initialized trace event. * @param[out] puiSize Size. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ #define xTraceEventGetSize( pvAddress, puiSize ) ( *( uint32_t * ) ( puiSize ) = sizeof( TraceBaseEvent_t ) + ( TRC_EVENT_GET_PARAM_COUNT( ( ( TraceBaseEvent_t * ) ( pvAddress ) )->EventID ) ) * sizeof( uint32_t ), TRC_SUCCESS ) /** * @brief Gets trace event data pointer with an offset. * * This routine gets a trace event data pointer with an offset. It also verfies * that the size so it won't go outside its buffer. * * @param[in] xEventHandle Pointer to initialized trace event. * @param[in] uiOffset Offset. * @param[in] uiSize Size. * @param[out] ppvData Data. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ #define xTraceEventGetRawData TRC_EVENT_GET_RAW_DATA /** * @brief Gets trace event payload pointer with an offset. * * This routine gets a trace event payload pointer with an offset. It also verifies * that the size so it won't go outside its payload buffer. * * @param[in] xEventHandle Pointer to initialized trace event. * @param[in] uiOffset Offset. * @param[in] uiSize Size. * @param[out] ppvData Data. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ #define xTraceEventGetPayload TRC_EVENT_GET_PAYLOAD /** * @brief Gets the amount of remaining trace event payload. * * @param[in] xEventHandle Pointer to initialized trace event. * @param[out] puiValue Value. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ #define xTraceEventPayloadRemaining TRC_EVENT_PAYLOAD_REMAINING /** * @brief Gets the amount of used trace event payload. * * @param[in] xEventHandle Pointer to initialized trace event. * @param[out] puiValue Value * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ #define xTraceEventPayloadUsed TRC_EVENT_PAYLOAD_USED /** * @brief Gets trace event payload size. * * @param[in] xEventHandle Pointer to initialized trace event. * @param[out] puiValue Value * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ #define xTraceEventPayloadSize TRC_EVENT_PAYLOAD_SIZE /* Adds a pointer as event payload with no errors checks */ #define xTraceEventAddPointer TRC_EVENT_ADD_POINTER /** * @brief Adds an unsigned base type value as trace event payload * * @param[in] xEventHandle Pointer to initialized trace event. * @param[in] uxValue Value. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ #define xTraceEventAddUnsignedBaseType TRC_EVENT_ADD_UNSIGNED_BASE_TYPE /** * @brief Adds an uint32_t as trace event payload * * @param[in] xEventHandle Pointer to initialized trace event. * @param[in] value Value. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ #define xTraceEventAdd32 TRC_EVENT_ADD_32 /** * @brief Adds an uint16_t as trace event payload * * @param[in] xEventHandle Pointer to initialized trace event. * @param[in] value Value. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ #define xTraceEventAdd16 TRC_EVENT_ADD_16 /** * @brief Adds an uint8_t as trace event payload. * * @param[in] xEventHandle Pointer to initialized trace event. * @param[in] value Value. * * @retval TRC_FAIL Failure * @retval TRC_SUCCESS Success */ #define xTraceEventAdd8 TRC_EVENT_ADD_8 #endif /* ((TRC_CFG_USE_TRACE_ASSERT) == 1) */ /** @} */ #ifdef __cplusplus } #endif #endif /* (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) */ #endif /* (TRC_USE_TRACEALYZER_RECORDER == 1) */ #endif /* TRC_EVENT_H */