Percepio Trace Recorder v4.8.0.hotfix1
Loading...
Searching...
No Matches
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 <trcSnapshotConfig.h>
#include <trcKernelPortSnapshotConfig.h>
#include <trcHardwarePort.h>
#include <trcKernelPort.h>
#include <trcStreamingConfig.h>
#include <trcKernelPortStreamingConfig.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 <trcRunnable.h>
#include <trcDependency.h>
#include <trcInterval.h>
#include <trcStateMachine.h>
#include <trcCounter.h>
#include <stdarg.h>

Go to the source code of this file.

Data Structures

struct  objectHandleStackType
 Object handle stack struct. More...
 
struct  ObjectPropertyTableType
 Object property table struct. More...
 
struct  symbolTableType
 Symbol table structure. More...
 

Macros

#define prvTraceStoreEvent_None(...)
 Stores an event without parameters.
 
#define prvTraceStoreEvent_Handle(...)
 Stores an event with a handle parameter.
 
#define prvTraceStoreEvent_Param(...)
 Stores an event with one parameter.
 
#define prvTraceStoreEvent_HandleParam(...)
 Stores an event with a handle and one parameter.
 
#define prvTraceStoreEvent_ParamParam(...)
 Stores an event with two parameters.
 
#define prvTraceStoreEvent_HandleParamParam(...)
 Stores an event with a handle and two parameters.
 
#define prvTraceStoreEvent_ParamParamParam(...)
 Stores an event with three parameters.
 
#define TRACE_GET_LOW16(value)   ((uint16_t)((value) & 0x0000FFFF))
 Returns lower 16 bits of a value.
 
#define TRACE_GET_HIGH16(value)   ((uint16_t)(((value) >> 16) & 0x0000FFFF))
 Returns upper 16 bits.
 
#define TRACE_SET_LOW16(current, value)   (((current) & 0xFFFF0000) | (value))
 Sets lower 16 bits.
 
#define TRACE_SET_HIGH16(current, value)   (((current) & 0x0000FFFF) | (((uint32_t)(value)) << 16))
 Sets upper 16 bits.
 
#define xTraceIsRecorderEnabled(void)   (xTraceIsRecorderInitialized() && pxTraceRecorderData->uiRecorderEnabled)
 Query if recorder is enabled.
 
#define xTraceIsRecorderInitialized()   xTraceIsComponentInitialized(TRC_RECORDER_COMPONENT_CORE)
 Query if recorder initialized.
 
#define xTraceSetComponentInitialized(uiComponentBit)   TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(RecorderInitialized |= (uiComponentBit), TRC_SUCCESS)
 Flag component as initialized.
 
#define xTraceIsComponentInitialized(uiComponentBit)   (RecorderInitialized & (uiComponentBit))
 Query if component is initialized.
 
#define xTraceStateSet(uxState)   TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(pxTraceRecorderData->uxTraceSystemStates[TRC_CFG_GET_CURRENT_CORE()] = (uxState), TRC_SUCCESS)
 Set the trace state.
 
#define xTraceStateGet(puxState)   TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(*(puxState) = pxTraceRecorderData->uxTraceSystemStates[TRC_CFG_GET_CURRENT_CORE()], TRC_SUCCESS)
 Query the trace state.
 
#define prvTraceStoreEvent_None(_eventID)   xTraceEventCreate0(_eventID)
 Stores an event without parameters.
 
#define prvTraceStoreEvent_Handle(_eventID, _handle)   xTraceEventCreate1(_eventID, (TraceUnsignedBaseType_t)(_handle))
 Stores an event with a handle parameter.
 
#define prvTraceStoreEvent_Param(_eventID, _param1)   xTraceEventCreate1(_eventID, (TraceUnsignedBaseType_t)(_param1))
 Stores an event with one parameter.
 
#define prvTraceStoreEvent_HandleParam(_eventID, _handle, _param1)   xTraceEventCreate2(_eventID, (TraceUnsignedBaseType_t)(_handle), (TraceUnsignedBaseType_t)(_param1))
 Stores an event with a handle and one parameter.
 
#define prvTraceStoreEvent_ParamParam(_eventID, _param1, _param2)   xTraceEventCreate2(_eventID, (TraceUnsignedBaseType_t)(_param1), (TraceUnsignedBaseType_t)(_param2))
 Stores an event with two parameters.
 
#define prvTraceStoreEvent_HandleParamParam(_eventID, _handle, _param1, _param2)   xTraceEventCreate3(_eventID, (TraceUnsignedBaseType_t)(_handle), (TraceUnsignedBaseType_t)(_param1), (TraceUnsignedBaseType_t)(_param2))
 Stores an event with a handle and two parameters.
 
#define prvTraceStoreEvent_ParamParamParam(_eventID, _param1, _param2, _param3)   xTraceEventCreate3(_eventID, (TraceUnsignedBaseType_t)(_param1), (TraceUnsignedBaseType_t)(_param2), (TraceUnsignedBaseType_t)(_param3))
 Stores an event with three parameters.
 
#define vTraceSetStopHook(x)   (void)(x)
 Snapshot mode only. Trace stop hook.
 
#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((TraceRecorderData_t*)(pxBuffer))
 

Typedefs

typedef void(* TRACE_STOP_HOOK) (void)
 Trace stop callback type.
 

Functions

traceResult xTraceInitialize (void)
 Initializes the recorder data. xTraceInitialize() or xTraceEnable(...) must be called before any attempts at adding trace data/information. xTraceInitialize() can be called before timestamp source is initialized since timestamps aren't used until xTraceEnable(...) is called.
 
traceResult xTraceDisable (void)
 Disables tracing.
 
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.
 
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.
 
void prvAddTaskToStackMonitor (void *task)
 Adds a task to the stack monitor.
 
void prvRemoveTaskFromStackMonitor (void *task)
 Remove a task from the stack monitor.
 
void prvReportStackUsage (void)
 Reports on the current stack usage.
 
traceResult xTraceISRRegister (const char *szName, uint32_t uiPriority, TraceISRHandle_t *pxISRHandle)
 Registers an ISR.
 
traceResult xTraceISRBegin (TraceISRHandle_t xHandle)
 Registers the beginning of an Interrupt Service Routine, using a TraceISRHandle_t provided by xTraceISRRegister.
 
traceResult xTraceISREnd (int pendingISR)
 Registers the end of an Interrupt Service Routine.
 
traceResult xTraceTaskInstanceFinishedNow (void)
 Creates an event that ends the current task instance at this very instant. This makes the viewer to splits the current fragment at this point and begin a new actor instance, even if no task-switch has occurred.
 
traceResult xTraceTaskInstanceFinishedNext (void)
 Marks the current "task instance" as finished on the next kernel call.
 
traceResult xTraceStringRegister (const char *label, TraceStringHandle_t *pxString)
 Registers a string and returns a handle that can be used when tracing.
 
TraceStringHandle_t xTraceRegisterString (const char *name)
 Registers a string and returns a handle that can be used when tracing.
 
traceResult xTracePrintF (TraceStringHandle_t chn, const char *fmt,...)
 Generates "User Events", with formatted text and data, similar to a "printf". User Events can be used for very efficient logging from your application code. It is very fast since the actual string formatting is done on the host side, when the trace is displayed. The execution time is just some microseconds on a 32-bit MCU.
 
traceResult xTraceVPrintF (TraceStringHandle_t eventLabel, const char *formatStr, va_list vl)
 xTracePrintF variant that accepts a va_list. See xTracePrintF documentation for further details.
 
traceResult xTracePrint (TraceStringHandle_t chn, const char *str)
 A faster version of xTracePrintF, that only allows for logging a string.
 
void vTraceSetStopHook (TRACE_STOP_HOOK stopHookFunction)
 Sets a function to be called when the recorder is stopped.
 
void vTraceClear (void)
 Resets the recorder.
 
void prvTraceSetReadyEventsEnabled (uint32_t flag)
 Dynamically enables ready events.
 
void prvTraceStoreTaskReady (traceHandle handle)
 Stores a Task Ready event.
 
void prvTraceStoreLowPower (uint32_t flag)
 Stores a Low Power mode event.
 
void prvTraceStoreTaskswitch (traceHandle task_handle)
 Stores a Task Switch event.
 
void prvTraceStoreKernelCall (uint32_t eventcode, traceObjectClass objectClass, uint32_t objectNumber)
 Stores a Kernel Service call event with an Object handle parameter.
 
void prvTraceStoreKernelCallWithNumericParamOnly (uint32_t evtcode, uint32_t param)
 Stores a Kernel Service call event with only a numeric parameter.
 
void prvTraceStoreKernelCallWithParam (uint32_t evtcode, traceObjectClass objectClass, uint32_t objectNumber, uint32_t param)
 Stores a Kernel Service call event with an Object handle and a numeric parameter.
 
void prvTraceSetTaskInstanceFinished (traceHandle handle)
 Flags a task instance as finished.
 
void prvTraceSetPriorityProperty (uint8_t objectclass, traceHandle id, uint8_t value)
 Set priority.
 
uint8_t prvTraceGetPriorityProperty (uint8_t objectclass, traceHandle id)
 Get priority.
 
void prvTraceSetObjectState (uint8_t objectclass, traceHandle id, uint8_t value)
 Set object state.
 
void prvMarkObjectAsUsed (traceObjectClass objectclass, traceHandle handle)
 Mark object as used.
 
void prvTraceStoreObjectNameOnCloseEvent (uint8_t evtcode, traceHandle handle, traceObjectClass objectclass)
 Stores the name of an object because it is being deleted.
 
void prvTraceStoreObjectPropertiesOnCloseEvent (uint8_t evtcode, traceHandle handle, traceObjectClass objectclass)
 Stores the property of an object because it is being deleted.
 
void * xTraceGetTraceBuffer (void)
 Returns a pointer to the recorder data structure. Use this together with uiTraceGetTraceBufferSize if you wish to implement an own store/upload solution, e.g., in case a debugger connection is not available for uploading the data.
 
uint32_t uiTraceGetTraceBufferSize (void)
 Gets the size of the recorder data structure. For use together with xTraceGetTraceBuffer if you wish to implement an own store/upload solution, e.g., in case a debugger connection is not available for uploading the data.
 
void prvTraceError (const char *msg)
 Signals a trace error.
 
void prvTracePortGetTimeStamp (uint32_t *puiTimestamp)
 Returns the current time based on the HWTC macros which provide a hardware isolation layer towards the hardware timer/counter.
 
traceHandle prvTraceGetObjectHandle (traceObjectClass objectclass)
 Reserve an object handle.
 
void prvTraceFreeObjectHandle (traceObjectClass objectclass, traceHandle handle)
 Free an object handle.
 
void prvTraceSetObjectName (traceObjectClass objectclass, traceHandle handle, const char *name)
 Set the object name.
 
traceResult xTraceHeaderInitialize (TraceHeaderBuffer_t *pxBuffer)
 Initializes the header data.
 
traceResult xTraceTzCtrl (void)
 Call this function periodically.
 
traceResult xTraceSetBuffer (TraceRecorderData_t *pxBuffer)
 Set the recorder data buffer.
 
traceResult xTraceGetEventBuffer (void **ppvBuffer, TraceUnsignedBaseType_t *puiSize)
 Retrieve the event buffer and event buffer size.
 

Detailed Description

The public API of the Percepio trace recorder.

Macro Definition Documentation

◆ prvTraceStoreEvent_Handle [1/2]

#define prvTraceStoreEvent_Handle (   ...)

Stores an event with a handle parameter.

Parameters
[in]_eventIDEvent id
[in]_handleHandle

◆ prvTraceStoreEvent_Handle [2/2]

#define prvTraceStoreEvent_Handle (   _eventID,
  _handle 
)    xTraceEventCreate1(_eventID, (TraceUnsignedBaseType_t)(_handle))

Stores an event with a handle parameter.

Parameters
[in]_eventIDEvent id
[in]_handleHandle

◆ prvTraceStoreEvent_HandleParam [1/2]

#define prvTraceStoreEvent_HandleParam (   ...)

Stores an event with a handle and one parameter.

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

◆ prvTraceStoreEvent_HandleParam [2/2]

#define prvTraceStoreEvent_HandleParam (   _eventID,
  _handle,
  _param1 
)    xTraceEventCreate2(_eventID, (TraceUnsignedBaseType_t)(_handle), (TraceUnsignedBaseType_t)(_param1))

Stores an event with a handle and one parameter.

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

◆ prvTraceStoreEvent_HandleParamParam [1/2]

#define prvTraceStoreEvent_HandleParamParam (   ...)

Stores an event with a handle and two parameters.

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

◆ prvTraceStoreEvent_HandleParamParam [2/2]

#define prvTraceStoreEvent_HandleParamParam (   _eventID,
  _handle,
  _param1,
  _param2 
)    xTraceEventCreate3(_eventID, (TraceUnsignedBaseType_t)(_handle), (TraceUnsignedBaseType_t)(_param1), (TraceUnsignedBaseType_t)(_param2))

Stores an event with a handle and two parameters.

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

◆ prvTraceStoreEvent_None [1/2]

#define prvTraceStoreEvent_None (   ...)

Stores an event without parameters.

Parameters
[in]_eventIDEvent id

◆ prvTraceStoreEvent_None [2/2]

#define prvTraceStoreEvent_None (   _eventID)    xTraceEventCreate0(_eventID)

Stores an event without parameters.

Parameters
[in]_eventIDEvent id

◆ prvTraceStoreEvent_Param [1/2]

#define prvTraceStoreEvent_Param (   ...)

Stores an event with one parameter.

Parameters
[in]_eventIDEvent id
[in]_param1Param

◆ prvTraceStoreEvent_Param [2/2]

#define prvTraceStoreEvent_Param (   _eventID,
  _param1 
)    xTraceEventCreate1(_eventID, (TraceUnsignedBaseType_t)(_param1))

Stores an event with one parameter.

Parameters
[in]_eventIDEvent id
[in]_param1Param

◆ prvTraceStoreEvent_ParamParam [1/2]

#define prvTraceStoreEvent_ParamParam (   ...)

Stores an event with two parameters.

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

◆ prvTraceStoreEvent_ParamParam [2/2]

#define prvTraceStoreEvent_ParamParam (   _eventID,
  _param1,
  _param2 
)    xTraceEventCreate2(_eventID, (TraceUnsignedBaseType_t)(_param1), (TraceUnsignedBaseType_t)(_param2))

Stores an event with two parameters.

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

◆ prvTraceStoreEvent_ParamParamParam [1/2]

#define prvTraceStoreEvent_ParamParamParam (   ...)

Stores an event with three parameters.

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

◆ prvTraceStoreEvent_ParamParamParam [2/2]

#define prvTraceStoreEvent_ParamParamParam (   _eventID,
  _param1,
  _param2,
  _param3 
)    xTraceEventCreate3(_eventID, (TraceUnsignedBaseType_t)(_param1), (TraceUnsignedBaseType_t)(_param2), (TraceUnsignedBaseType_t)(_param3))

Stores an event with three parameters.

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

◆ TRACE_GET_HIGH16

#define TRACE_GET_HIGH16 (   value)    ((uint16_t)(((value) >> 16) & 0x0000FFFF))

Returns upper 16 bits.

Parameters
[in]valueThe starting value

◆ TRACE_GET_LOW16

#define TRACE_GET_LOW16 (   value)    ((uint16_t)((value) & 0x0000FFFF))

Returns lower 16 bits of a value.

Parameters
[in]valueThe starting value

◆ TRACE_SET_HIGH16

#define TRACE_SET_HIGH16 (   current,
  value 
)    (((current) & 0x0000FFFF) | (((uint32_t)(value)) << 16))

Sets upper 16 bits.

Parameters
[in]currentThe starting value
[in]valueThe value to set

◆ TRACE_SET_LOW16

#define TRACE_SET_LOW16 (   current,
  value 
)    (((current) & 0xFFFF0000) | (value))

Sets lower 16 bits.

Parameters
[in]currentThe starting value
[in]valueThe value to set

◆ 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((TraceRecorderData_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))

Query if component is initialized.

Parameters
[in]uiComponentBitComponent bit
Return values
Non-zeroComponent initialized
0Component not initialized

◆ xTraceIsRecorderEnabled

uint32_t xTraceIsRecorderEnabled (   void)    (xTraceIsRecorderInitialized() && pxTraceRecorderData->uiRecorderEnabled)

Query if recorder is enabled.

Return values
1if recorder is enabled
0if recorder is disabled
Return values
Non-zeroRecorder enabled
0Recorder not enabled

◆ xTraceIsRecorderInitialized

uint32_t xTraceIsRecorderInitialized (   void)    xTraceIsComponentInitialized(TRC_RECORDER_COMPONENT_CORE)

Query if recorder initialized.

Return values
1if recorder is initialized
0if recorder isn't initialized
Return values
Non-zeroRecorder 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 (   puxState)    TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(*(puxState) = pxTraceRecorderData->uxTraceSystemStates[TRC_CFG_GET_CURRENT_CORE()], TRC_SUCCESS)

Query the trace state.

Parameters
[out]puiStateState
Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

◆ xTraceStateSet

#define xTraceStateSet (   uxState)    TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(pxTraceRecorderData->uxTraceSystemStates[TRC_CFG_GET_CURRENT_CORE()] = (uxState), TRC_SUCCESS)

Set the trace state.

Parameters
[in]uiStateState
Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

Function Documentation

◆ prvAddTaskToStackMonitor()

void prvAddTaskToStackMonitor ( void *  task)

Adds a task to the stack monitor.

Parameters
[in]taskThe task

◆ prvMarkObjectAsUsed()

void prvMarkObjectAsUsed ( traceObjectClass  objectclass,
traceHandle  handle 
)

Mark object as used.

Parameters
[in]objectclassObject class
[in]handleObject handle

◆ prvRemoveTaskFromStackMonitor()

void prvRemoveTaskFromStackMonitor ( void *  task)

Remove a task from the stack monitor.

Parameters
[in]taskThe task

◆ prvTraceError()

void prvTraceError ( const char *  msg)

Signals a trace error.

Parameters
[in]msgMessage

◆ prvTraceFreeObjectHandle()

void prvTraceFreeObjectHandle ( traceObjectClass  objectclass,
traceHandle  handle 
)

Free an object handle.

Parameters
[in]objectclassObject class
[in]handleHandle

◆ prvTraceGetObjectHandle()

traceHandle prvTraceGetObjectHandle ( traceObjectClass  objectclass)

Reserve an object handle.

Parameters
[in]objectclassObject class
Returns
traceHandle

◆ prvTraceGetPriorityProperty()

uint8_t prvTraceGetPriorityProperty ( uint8_t  objectclass,
traceHandle  id 
)

Get priority.

Parameters
[in]objectclassObject class
[in]idObject handle
Returns
uint8_t Value

◆ prvTracePortGetTimeStamp()

void prvTracePortGetTimeStamp ( uint32_t *  puiTimestamp)

Returns the current time based on the HWTC macros which provide a hardware isolation layer towards the hardware timer/counter.

The HWTC macros and prvTracePortGetTimeStamp is the main porting issue or the trace recorder library. Typically you should not need to change the code of prvTracePortGetTimeStamp if using the HWTC macros.

Parameters
[out]puiTimestampTimestamp

◆ prvTraceSetObjectName()

void prvTraceSetObjectName ( traceObjectClass  objectclass,
traceHandle  handle,
const char *  name 
)

Set the object name.

Parameters
[in]objectclassObject class
[in]handleHandle
[in]nameName

◆ prvTraceSetObjectState()

void prvTraceSetObjectState ( uint8_t  objectclass,
traceHandle  id,
uint8_t  value 
)

Set object state.

Parameters
[in]objectclassObject class
[in]idObject handle
[in]valueValue

◆ prvTraceSetPriorityProperty()

void prvTraceSetPriorityProperty ( uint8_t  objectclass,
traceHandle  id,
uint8_t  value 
)

Set priority.

Parameters
[in]objectclassObject class
[in]idObject handle
[in]valueValue

◆ prvTraceSetReadyEventsEnabled()

void prvTraceSetReadyEventsEnabled ( uint32_t  flag)

Dynamically enables ready events.

Parameters
[in]flagFlag

◆ prvTraceSetTaskInstanceFinished()

void prvTraceSetTaskInstanceFinished ( traceHandle  handle)

Flags a task instance as finished.

Parameters
[in]handleTask handle

◆ prvTraceStoreKernelCall()

void prvTraceStoreKernelCall ( uint32_t  eventcode,
traceObjectClass  objectClass,
uint32_t  objectNumber 
)

Stores a Kernel Service call event with an Object handle parameter.

Parameters
[in]eventcodeEvent code
[in]objectClassObject class
[in]objectNumberObject handle

◆ prvTraceStoreKernelCallWithNumericParamOnly()

void prvTraceStoreKernelCallWithNumericParamOnly ( uint32_t  evtcode,
uint32_t  param 
)

Stores a Kernel Service call event with only a numeric parameter.

Parameters
[in]evtcodeEvent code
[in]paramParameter

◆ prvTraceStoreKernelCallWithParam()

void prvTraceStoreKernelCallWithParam ( uint32_t  evtcode,
traceObjectClass  objectClass,
uint32_t  objectNumber,
uint32_t  param 
)

Stores a Kernel Service call event with an Object handle and a numeric parameter.

Parameters
[in]evtcodeEvent code
[in]objectClassObject class
[in]objectNumberObject handle
[in]paramParameter

◆ prvTraceStoreLowPower()

void prvTraceStoreLowPower ( uint32_t  flag)

Stores a Low Power mode event.

Parameters
[in]flagFlag

◆ prvTraceStoreObjectNameOnCloseEvent()

void prvTraceStoreObjectNameOnCloseEvent ( uint8_t  evtcode,
traceHandle  handle,
traceObjectClass  objectclass 
)

Stores the name of an object because it is being deleted.

Parameters
[in]evtcodeEvent code
[in]handleObject handle
[in]objectclassObject class

◆ prvTraceStoreObjectPropertiesOnCloseEvent()

void prvTraceStoreObjectPropertiesOnCloseEvent ( uint8_t  evtcode,
traceHandle  handle,
traceObjectClass  objectclass 
)

Stores the property of an object because it is being deleted.

Parameters
[in]evtcodeEvent code
[in]handleObject handle
[in]objectclassObject class

◆ prvTraceStoreTaskReady()

void prvTraceStoreTaskReady ( traceHandle  handle)

Stores a Task Ready event.

Parameters
[in]handleTask handle

◆ prvTraceStoreTaskswitch()

void prvTraceStoreTaskswitch ( traceHandle  task_handle)

Stores a Task Switch event.

Parameters
[in]task_handleTask

◆ uiTraceGetTraceBufferSize()

uint32_t uiTraceGetTraceBufferSize ( void  )

Gets the size of the recorder data structure. For use together with xTraceGetTraceBuffer if you wish to implement an own store/upload solution, e.g., in case a debugger connection is not available for uploading the data.

Returns
uint32_t Buffer size

◆ vTraceClear()

void vTraceClear ( void  )

Resets the recorder.

Only necessary if a restart is desired - this is not needed in the startup initialization.

Note
Snapshot mode only!

◆ 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

◆ vTraceSetStopHook()

void vTraceSetStopHook ( TRACE_STOP_HOOK  stopHookFunction)

Sets a function to be called when the recorder is stopped.

Note
Snapshot mode only!
Parameters
[in]stopHookFunction

◆ 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

◆ xTraceGetTraceBuffer()

void * xTraceGetTraceBuffer ( void  )

Returns a pointer to the recorder data structure. Use this together with uiTraceGetTraceBufferSize if you wish to implement an own store/upload solution, e.g., in case a debugger connection is not available for uploading the data.

Returns
void* Buffer pointer

◆ 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. xTraceInitialize() can be called before timestamp source is initialized since timestamps aren't used until xTraceEnable(...) is called.

See xTraceEnable(...) for more information.

Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

◆ xTraceISREnd()

traceResult xTraceISREnd ( int  pendingISR)

Registers the end of an Interrupt Service Routine.

The parameter pendingISR indicates if the interrupt has requested a task-switch (= 1), e.g., by signaling a semaphore. Otherwise (= 0) the interrupt is assumed to return to the previous context.

Example: #define PRIO_ISR_TIMER1 3 // the hardware priority of the interrupt ... TraceISRHandle_t Timer1Handle; xTraceISRRegister("ISRTimer1", PRIO_ISR_TIMER1, &Timer1Handle); ... void ISR_handler() { xTraceISRBegin(Timer1Handle); ... xTraceISREnd(0); }

Parameters
[in]pendingISRFlag that indicates whether an ISR is pending
Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

◆ xTraceRegisterString()

TraceStringHandle_t xTraceRegisterString ( const char *  name)

Registers a string and returns a handle that can be used when tracing.

Deprecated:
Backwards compatibility
Parameters
[in]nameName.
Returns
TraceStringHandle_t String handle

◆ xTraceSetBuffer()

traceResult xTraceSetBuffer ( TraceRecorderData_t *  pxBuffer)

Set the recorder data buffer.

Parameters
[in]pxBufferPointer to the recorder data buffer
Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

◆ xTraceStringRegister()

traceResult xTraceStringRegister ( const char *  label,
TraceStringHandle_t *  pxString 
)

Registers a string and returns a handle that can be used when tracing.

Parameters
[in]labelLabel
[out]pxStringString handle
Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

◆ xTraceTaskInstanceFinishedNext()

traceResult xTraceTaskInstanceFinishedNext ( void  )

Marks the current "task instance" as finished on the next kernel call.

If that kernel call is blocking, the instance ends after the blocking event and the corresponding return event is then the start of the next instance. If the kernel call is not blocking, the viewer instead splits the current fragment right before the kernel call, which makes this call the first event of the next instance.

Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

◆ xTraceTaskInstanceFinishedNow()

traceResult xTraceTaskInstanceFinishedNow ( void  )

Creates an event that ends the current task instance at this very instant. This makes the viewer to splits the current fragment at this point and begin a new actor instance, even if no task-switch has occurred.

Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

◆ xTraceTzCtrl()

traceResult xTraceTzCtrl ( void  )

Call this function periodically.

Return values
TRC_FAILFailure
TRC_SUCCESSSuccess