Percepio Trace Recorder
v4.6.6
|
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... | |
The public API of the Percepio trace recorder.
#define prvTraceStoreEvent_Handle | ( | _eventID, | |
_handle | |||
) |
Stores an event with a handle parameter.
[in] | _eventID | Event id |
[in] | _handle | Handle |
#define prvTraceStoreEvent_HandleParam | ( | _eventID, | |
_handle, | |||
_param1 | |||
) |
Stores an event with a handle and one 32-bit parameter.
[in] | _eventID | Event id |
[in] | _handle | Handle |
[in] | _param1 | Param |
#define prvTraceStoreEvent_HandleParamParam | ( | _eventID, | |
_handle, | |||
_param1, | |||
_param2 | |||
) |
Stores an event with a handle and two 32-bit parameters.
[in] | _eventID | Event id |
[in] | _handle | Handle |
[in] | _param1 | Param 1 |
[in] | _param2 | Param 2 |
#define prvTraceStoreEvent_None | ( | _eventID | ) |
Stores an event without parameters.
[in] | _eventID | Event id |
#define prvTraceStoreEvent_Param | ( | _eventID, | |
_param1 | |||
) |
Stores an event with one 32-bit parameter.
[in] | _eventID | Event id |
[in] | _param1 | Param |
#define prvTraceStoreEvent_ParamParam | ( | _eventID, | |
_param1, | |||
_param2 | |||
) |
Stores an event with two 32-bit parameters.
[in] | _eventID | Event id |
[in] | _param1 | Param 1 |
[in] | _param2 | Param 2 |
#define prvTraceStoreEvent_ParamParamParam | ( | _eventID, | |
_param1, | |||
_param2, | |||
_param3 | |||
) |
Stores an event with three 32-bit parameters.
[in] | _eventID | Event id |
[in] | _param1 | Param 1 |
[in] | _param2 | Param 2 |
[in] | _param3 | Param 3 |
#define vTraceEnable (void)xTraceEnable |
#define vTraceInitialize (void)xTraceInitialize |
#define vTraceInstanceFinishedNext (void)xTraceTaskInstanceFinishedNext |
#define vTraceInstanceFinishedNow (void)xTraceTaskInstanceFinishedNow |
#define vTracePrint (void)xTracePrint |
#define vTracePrintF (void)xTracePrintF |
#define vTraceSetRecorderDataBuffer | ( | pxBuffer | ) | xTraceSetBuffer((TraceRecorderDataBuffer_t*)(pxBuffer)) |
#define vTraceSetStopHook | ( | x | ) | (void)(x) |
Snapshot mode only. Trace stop hook.
[in] | x |
#define vTraceStop (void)xTraceDisable |
#define vTraceVPrintF (void)xTraceVPrintF |
#define xTraceIsComponentInitialized | ( | uiComponentBit | ) | ((RecorderInitialized & (uiComponentBit)) ? 1 : 0) |
Query if component is initialized.
[in] | uiComponentBit | Component bit |
1 | Component initialized |
0 | Component not initialized |
#define xTraceIsRecorderEnabled | ( | ) | (xTraceIsRecorderInitialized() & pxTraceRecorderData->uiRecorderEnabled) |
Query if recorder is enabled.
1 | Recorder enabled |
0 | Recorder not enabled |
#define xTraceIsRecorderInitialized | ( | ) | xTraceIsComponentInitialized(TRC_RECORDER_COMPONENT_CORE) |
Query if recorder initialized.
1 | Recorder initialized |
0 | Recorder not initialized |
#define xTraceSetComponentInitialized | ( | uiComponentBit | ) | TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(RecorderInitialized |= (uiComponentBit), TRC_SUCCESS) |
Flag component as initialized.
[in] | uiComponentBit | Component bit |
TRC_FAIL | Failure |
TRC_SUCCESS | Success |
#define xTraceStateGet | ( | puiState | ) | TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(*(puiState) = pxTraceRecorderData->uiTraceSystemState, TRC_SUCCESS) |
Query the trace state.
[out] | puiState | State |
TRC_FAIL | Failure |
TRC_SUCCESS | Success |
#define xTraceStateSet | ( | uiState | ) | TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(pxTraceRecorderData->uiTraceSystemState = (uiState), TRC_SUCCESS) |
Set the trace state.
[in] | uiState | State |
TRC_FAIL | Failure |
TRC_SUCCESS | Success |
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.
[in] | filterGroup | Filter group |
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.
[in] | filterMask | Filter mask |
traceResult xTraceDisable | ( | void | ) |
Disables tracing.
TRC_FAIL | Failure |
TRC_SUCCESS | Success |
traceResult xTraceGetEventBuffer | ( | void ** | ppvBuffer, |
TraceUnsignedBaseType_t * | puiSize | ||
) |
Retrieve the event buffer and event buffer size.
[out] | ppvBuffer | Pointer where event buffer pointer will be written |
[out] | puiSize | Event buffer size |
TRC_FAIL | Failure |
TRC_SUCCESS | Success |
traceResult xTraceHeaderInitialize | ( | TraceHeaderBuffer_t * | pxBuffer | ) |
Initializes the header data.
[in] | pxBuffer | Pointer to header buffer |
TRC_FAIL | Failure |
TRC_SUCCESS | Success |
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.
TRC_FAIL | Failure |
TRC_SUCCESS | Success |
traceResult xTraceTzCtrl | ( | void | ) |
Call this function periodically.
TRC_FAIL | Failure |
TRC_SUCCESS | Success |