Percepio Trace Recorder  v4.6.6
trcRecorder.h File Reference

The public API of the Percepio trace recorder. More...

#include <trcDefines.h>
#include <trcConfig.h>
#include <trcKernelPortConfig.h>
#include <trcTypes.h>
#include <trcStreamingConfig.h>
#include <trcKernelPortStreamingConfig.h>
#include <trcHardwarePort.h>
#include <trcKernelPort.h>
#include <trcString.h>
#include <trcStaticBuffer.h>
#include <trcError.h>
#include <trcEvent.h>
#include <trcEventBuffer.h>
#include <trcMultiCoreEventBuffer.h>
#include <trcTimestamp.h>
#include <trcEntryTable.h>
#include <trcStreamPort.h>
#include <trcISR.h>
#include <trcTask.h>
#include <trcObject.h>
#include <trcPrint.h>
#include <trcHeap.h>
#include <trcExtension.h>
#include <trcUtility.h>
#include <trcStackMonitor.h>
#include <trcInternalEventBuffer.h>
#include <trcDiagnostics.h>
#include <trcAssert.h>
#include <trcInterval.h>
#include <trcStateMachine.h>
#include <trcCounter.h>

Go to the source code of this file.

Macros

#define xTraceIsRecorderEnabled()   (xTraceIsRecorderInitialized() & pxTraceRecorderData->uiRecorderEnabled)
 Query if recorder is enabled. More...
 
#define xTraceIsRecorderInitialized()   xTraceIsComponentInitialized(TRC_RECORDER_COMPONENT_CORE)
 Query if recorder initialized. More...
 
#define xTraceSetComponentInitialized(uiComponentBit)   TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(RecorderInitialized |= (uiComponentBit), TRC_SUCCESS)
 Flag component as initialized. More...
 
#define xTraceIsComponentInitialized(uiComponentBit)   ((RecorderInitialized & (uiComponentBit)) ? 1 : 0)
 Query if component is initialized. More...
 
#define xTraceStateSet(uiState)   TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(pxTraceRecorderData->uiTraceSystemState = (uiState), TRC_SUCCESS)
 Set the trace state. More...
 
#define xTraceStateGet(puiState)   TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(*(puiState) = pxTraceRecorderData->uiTraceSystemState, TRC_SUCCESS)
 Query the trace state. More...
 
#define prvTraceStoreEvent_None(_eventID)
 Stores an event without parameters. More...
 
#define prvTraceStoreEvent_Handle(_eventID, _handle)
 Stores an event with a handle parameter. More...
 
#define prvTraceStoreEvent_Param(_eventID, _param1)
 Stores an event with one 32-bit parameter. More...
 
#define prvTraceStoreEvent_HandleParam(_eventID, _handle, _param1)
 Stores an event with a handle and one 32-bit parameter. More...
 
#define prvTraceStoreEvent_ParamParam(_eventID, _param1, _param2)
 Stores an event with two 32-bit parameters. More...
 
#define prvTraceStoreEvent_HandleParamParam(_eventID, _handle, _param1, _param2)
 Stores an event with a handle and two 32-bit parameters. More...
 
#define prvTraceStoreEvent_ParamParamParam(_eventID, _param1, _param2, _param3)
 Stores an event with three 32-bit parameters. More...
 
#define vTraceSetStopHook(x)   (void)(x)
 Snapshot mode only. Trace stop hook. More...
 
#define vTraceInitTimestamps()
 Snapshot mode only. Initialize timestamps.
 
#define vTraceInitialize   (void)xTraceInitialize
 
#define vTraceEnable   (void)xTraceEnable
 
#define vTraceStop   (void)xTraceDisable
 
#define vTraceInstanceFinishedNow   (void)xTraceTaskInstanceFinishedNow
 
#define vTraceInstanceFinishedNext   (void)xTraceTaskInstanceFinishedNext
 
#define vTracePrintF   (void)xTracePrintF
 
#define vTraceVPrintF   (void)xTraceVPrintF
 
#define vTracePrint   (void)xTracePrint
 
#define vTraceSetRecorderDataBuffer(pxBuffer)   xTraceSetBuffer((TraceRecorderDataBuffer_t*)(pxBuffer))
 

Functions

traceResult xTraceInitialize (void)
 Initializes the recorder data. xTraceInitialize() or xTraceEnable(...) must be called before any attempts at adding trace data/information. See xTraceEnable(...) for more information. More...
 
traceResult xTraceDisable (void)
 Disables tracing. More...
 
void vTraceSetFilterGroup (uint16_t filterGroup)
 For snapshot mode only: Sets the "filter group" to assign when creating RTOS objects, such as tasks, queues, semaphores and mutexes. This together with vTraceSetFilterMask allows you to control what events that are recorded, based on the objects they refer to. More...
 
void vTraceSetFilterMask (uint16_t filterMask)
 For snapshot mode only: Sets the "filter mask" that is used to filter the events by object. This can be used to reduce the trace data rate, i.e., if your streaming interface is a bottleneck or if you want longer snapshot traces without increasing the buffer size. More...
 
traceResult xTraceHeaderInitialize (TraceHeaderBuffer_t *pxBuffer)
 Initializes the header data. More...
 
traceResult xTraceTzCtrl (void)
 Call this function periodically. More...
 
traceResult xTraceGetEventBuffer (void **ppvBuffer, TraceUnsignedBaseType_t *puiSize)
 Retrieve the event buffer and event buffer size. More...
 

Detailed Description

The public API of the Percepio trace recorder.

Macro Definition Documentation

◆ prvTraceStoreEvent_Handle

#define prvTraceStoreEvent_Handle (   _eventID,
  _handle 
)
Value:
{ \
TraceEventHandle_t _xEventHandle = 0; \
if (xTraceEventBegin(_eventID, sizeof(void*), &_xEventHandle) == TRC_SUCCESS) \
{ \
xTraceEventAddPointer(_xEventHandle, (void*)(_handle)); \
xTraceEventEnd(_xEventHandle); \
} \
}

Stores an event with a handle parameter.

Parameters
[in]_eventIDEvent id
[in]_handleHandle

◆ prvTraceStoreEvent_HandleParam

#define prvTraceStoreEvent_HandleParam (   _eventID,
  _handle,
  _param1 
)
Value:
{ \
TraceEventHandle_t _xEventHandle = 0; \
if (xTraceEventBegin(_eventID, sizeof(void*) + sizeof(uint32_t), &_xEventHandle) == TRC_SUCCESS) \
{ \
xTraceEventAddPointer(_xEventHandle, (void*)(_handle)); \
xTraceEventAdd32(_xEventHandle, (uint32_t)(_param1)); \
xTraceEventEnd(_xEventHandle); \
} \
}

Stores an event with a handle and one 32-bit parameter.

Parameters
[in]_eventIDEvent id
[in]_handleHandle
[in]_param1Param

◆ prvTraceStoreEvent_HandleParamParam

#define prvTraceStoreEvent_HandleParamParam (   _eventID,
  _handle,
  _param1,
  _param2 
)
Value:
{ \
TraceEventHandle_t _xEventHandle = 0; \
if (xTraceEventBegin(_eventID, sizeof(void*) + sizeof(uint32_t) + sizeof(uint32_t), &_xEventHandle) == TRC_SUCCESS) \
{ \
xTraceEventAddPointer(_xEventHandle, (void*)(_handle)); \
xTraceEventAdd32(_xEventHandle, (uint32_t)(_param1)); \
xTraceEventAdd32(_xEventHandle, (uint32_t)(_param2)); \
xTraceEventEnd(_xEventHandle); \
} \
}

Stores an event with a handle and two 32-bit parameters.

Parameters
[in]_eventIDEvent id
[in]_handleHandle
[in]_param1Param 1
[in]_param2Param 2

◆ prvTraceStoreEvent_None

#define prvTraceStoreEvent_None (   _eventID)
Value:
{ \
TraceEventHandle_t _xEventHandle = 0; \
if (xTraceEventBegin(_eventID, 0, &_xEventHandle) == TRC_SUCCESS) \
{ \
xTraceEventEnd(_xEventHandle); \
} \
}

Stores an event without parameters.

Parameters
[in]_eventIDEvent id

◆ prvTraceStoreEvent_Param

#define prvTraceStoreEvent_Param (   _eventID,
  _param1 
)
Value:
{ \
TraceEventHandle_t _xEventHandle = 0; \
if (xTraceEventBegin(_eventID, sizeof(uint32_t), &_xEventHandle) == TRC_SUCCESS) \
{ \
xTraceEventAdd32(_xEventHandle, (uint32_t)(_param1)); \
xTraceEventEnd(_xEventHandle); \
} \
}

Stores an event with one 32-bit parameter.

Parameters
[in]_eventIDEvent id
[in]_param1Param

◆ prvTraceStoreEvent_ParamParam

#define prvTraceStoreEvent_ParamParam (   _eventID,
  _param1,
  _param2 
)
Value:
{ \
TraceEventHandle_t _xEventHandle = 0; \
if (xTraceEventBegin(_eventID, sizeof(uint32_t) + sizeof(uint32_t), &_xEventHandle) == TRC_SUCCESS) \
{ \
xTraceEventAdd32(_xEventHandle, (uint32_t)(_param1)); \
xTraceEventAdd32(_xEventHandle, (uint32_t)(_param2)); \
xTraceEventEnd(_xEventHandle); \
} \
}

Stores an event with two 32-bit parameters.

Parameters
[in]_eventIDEvent id
[in]_param1Param 1
[in]_param2Param 2

◆ prvTraceStoreEvent_ParamParamParam

#define prvTraceStoreEvent_ParamParamParam (   _eventID,
  _param1,
  _param2,
  _param3 
)
Value:
{ \
TraceEventHandle_t _xEventHandle = 0; \
if (xTraceEventBegin(_eventID, sizeof(uint32_t) + sizeof(uint32_t) + sizeof(uint32_t), &_xEventHandle) == TRC_SUCCESS) \
{ \
xTraceEventAdd32(_xEventHandle, (uint32_t)(_param1)); \
xTraceEventAdd32(_xEventHandle, (uint32_t)(_param2)); \
xTraceEventAdd32(_xEventHandle, (uint32_t)(_param3)); \
xTraceEventEnd(_xEventHandle); \
} \
}

Stores an event with three 32-bit parameters.

Parameters
[in]_eventIDEvent id
[in]_param1Param 1
[in]_param2Param 2
[in]_param3Param 3

◆ vTraceEnable

#define vTraceEnable   (void)xTraceEnable
Deprecated:
Backwards compatibility. Use xTraceEnable instead.

◆ vTraceInitialize

#define vTraceInitialize   (void)xTraceInitialize
Deprecated:
Backwards compatibility. Use xTraceInitialize instead.

◆ vTraceInstanceFinishedNext

#define vTraceInstanceFinishedNext   (void)xTraceTaskInstanceFinishedNext
Deprecated:
Backwards compatibility. Use xTraceTaskInstanceFinishedNext instead.

◆ vTraceInstanceFinishedNow

#define vTraceInstanceFinishedNow   (void)xTraceTaskInstanceFinishedNow
Deprecated:
Backwards compatibility. Use xTraceTaskInstanceFinishedNow instead.

◆ vTracePrint

#define vTracePrint   (void)xTracePrint
Deprecated:
Backwards compatibility. Use xTracePrint instead.

◆ vTracePrintF

#define vTracePrintF   (void)xTracePrintF
Deprecated:
Backwards compatibility. Use xTracePrintF instead.

◆ vTraceSetRecorderDataBuffer

#define vTraceSetRecorderDataBuffer (   pxBuffer)    xTraceSetBuffer((TraceRecorderDataBuffer_t*)(pxBuffer))
Deprecated:
Backwards compatibility. Use xTraceSetBuffer instead.

◆ vTraceSetStopHook

#define vTraceSetStopHook (   x)    (void)(x)

Snapshot mode only. Trace stop hook.

Parameters
[in]x

◆ vTraceStop

#define vTraceStop   (void)xTraceDisable
Deprecated:
Backwards compatibility. Use xTraceDisable instead.

◆ vTraceVPrintF

#define vTraceVPrintF   (void)xTraceVPrintF
Deprecated:
Backwards compatibility. Use xTraceVPrintF instead.

◆ xTraceIsComponentInitialized

#define xTraceIsComponentInitialized (   uiComponentBit)    ((RecorderInitialized & (uiComponentBit)) ? 1 : 0)

Query if component is initialized.

Parameters
[in]uiComponentBitComponent bit
Return values
1Component initialized
0Component not initialized

◆ xTraceIsRecorderEnabled

#define xTraceIsRecorderEnabled ( )    (xTraceIsRecorderInitialized() & pxTraceRecorderData->uiRecorderEnabled)

Query if recorder is enabled.

Return values
1Recorder enabled
0Recorder not enabled

◆ xTraceIsRecorderInitialized

#define xTraceIsRecorderInitialized ( )    xTraceIsComponentInitialized(TRC_RECORDER_COMPONENT_CORE)

Query if recorder initialized.

Return values
1Recorder initialized
0Recorder not initialized

◆ xTraceSetComponentInitialized

#define xTraceSetComponentInitialized (   uiComponentBit)    TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(RecorderInitialized |= (uiComponentBit), TRC_SUCCESS)

Flag component as initialized.

Parameters
[in]uiComponentBitComponent bit
Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

◆ xTraceStateGet

#define xTraceStateGet (   puiState)    TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(*(puiState) = pxTraceRecorderData->uiTraceSystemState, TRC_SUCCESS)

Query the trace state.

Parameters
[out]puiStateState
Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

◆ xTraceStateSet

#define xTraceStateSet (   uiState)    TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(pxTraceRecorderData->uiTraceSystemState = (uiState), TRC_SUCCESS)

Set the trace state.

Parameters
[in]uiStateState
Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

Function Documentation

◆ vTraceSetFilterGroup()

void vTraceSetFilterGroup ( uint16_t  filterGroup)

For snapshot mode only: Sets the "filter group" to assign when creating RTOS objects, such as tasks, queues, semaphores and mutexes. This together with vTraceSetFilterMask allows you to control what events that are recorded, based on the objects they refer to.

There are 16 filter groups named FilterGroup0 .. FilterGroup15.

Note: We don't recommend filtering out the Idle task, so make sure to call vTraceSetFilterGroup just before initializing the RTOS, in order to assign such "default" objects to the right Filter Group (typically group 0).

Example:

// Assign tasks T1 to FilterGroup0 (default)
<Create Task T1>  

// Assign Q1 and Q2 to FilterGroup1
vTraceSetFilterGroup(FilterGroup1);
<Create Queue Q1> 
<Create Queue Q2>

// Assigns Q3 to FilterGroup2
vTraceSetFilterGroup(FilterGroup2);
<Create Queue Q3>

// Only include FilterGroup0 and FilterGroup2, exclude FilterGroup1 (Q1 and Q2) from the trace
vTraceSetFilterMask( FilterGroup0 | FilterGroup2 );

// Assign the default RTOS objects (e.g. Idle task) to FilterGroup0
vTraceSetFilterGroup(FilterGroup0);
<Start the RTOS scheduler>

Note that you may define your own names for the filter groups using preprocessor definitions, to make the code easier to understand.

Example:

#define BASE FilterGroup0
#define USB_EVENTS FilterGroup1
#define CAN_EVENTS FilterGroup2

Note that filtering per event type (regardless of object) is also available in trcKernelPortConfig.h for certain kernels.

Parameters
[in]filterGroupFilter group

◆ vTraceSetFilterMask()

void vTraceSetFilterMask ( uint16_t  filterMask)

For snapshot mode only: Sets the "filter mask" that is used to filter the events by object. This can be used to reduce the trace data rate, i.e., if your streaming interface is a bottleneck or if you want longer snapshot traces without increasing the buffer size.

Note: There are two kinds of filters in the recorder. The other filter type excludes all events of certain kinds (e.g., OS ticks). See trcConfig.h.

The filtering is based on bitwise AND with the Filter Group ID, assigned to RTOS objects such as tasks, queues, semaphores and mutexes. This together with vTraceSetFilterGroup allows you to control what events that are recorded, based on the objects they refer to.

See example for vTraceSetFilterGroup.

Parameters
[in]filterMaskFilter mask

◆ xTraceDisable()

traceResult xTraceDisable ( void  )

Disables tracing.

Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

◆ xTraceGetEventBuffer()

traceResult xTraceGetEventBuffer ( void **  ppvBuffer,
TraceUnsignedBaseType_t *  puiSize 
)

Retrieve the event buffer and event buffer size.

Parameters
[out]ppvBufferPointer where event buffer pointer will be written
[out]puiSizeEvent buffer size
Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

◆ xTraceHeaderInitialize()

traceResult xTraceHeaderInitialize ( TraceHeaderBuffer_t *  pxBuffer)

Initializes the header data.

Parameters
[in]pxBufferPointer to header buffer
Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

◆ xTraceInitialize()

traceResult xTraceInitialize ( void  )

Initializes the recorder data. xTraceInitialize() or xTraceEnable(...) must be called before any attempts at adding trace data/information. See xTraceEnable(...) for more information.

Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

◆ xTraceTzCtrl()

traceResult xTraceTzCtrl ( void  )

Call this function periodically.

Return values
TRC_FAILFailure
TRC_SUCCESSSuccess
xTraceEventBegin
#define xTraceEventBegin(uiEventCode, uiTotalPayloadSize, pxEventHandle)
Begins a trace event.
Definition: trcEvent.h:303