1 /* 2 * Percepio Trace Recorder for Tracealyzer v4.10.3 3 * Copyright 2023 Percepio AB 4 * www.percepio.com 5 * 6 * SPDX-License-Identifier: Apache-2.0 7 */ 8 9 /** 10 * @file 11 * 12 * @brief Public trace runnable APIs. 13 */ 14 15 #ifndef TRC_RUNNABLE_H 16 #define TRC_RUNNABLE_H 17 18 typedef enum TraceRunnableRegisterMethod 19 { 20 TRC_RUNNABLE_REGISTER_METHOD_USE_ENTRY_TABLE, 21 TRC_RUNNABLE_REGISTER_METHOD_USE_STRING_ADDRESS, 22 TRC_RUNNABLE_REGISTER_METHOD_USE_HANDLE_ADDRESS, 23 } TraceRunnableRegisterMethod_t; 24 25 #if (TRC_USE_TRACEALYZER_RECORDER == 1) && (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) 26 27 #include <trcTypes.h> 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 /** 34 * @defgroup trace_runnable_apis Trace Runnable APIs 35 * @ingroup trace_recorder_apis 36 * @{ 37 */ 38 39 /** 40 * @brief Registers a runnable. Can be called multiple times, will not create additional entries. 41 * 42 * @param[in] szName Name. 43 * @param[in] uxRegisterMethod Indicates how to register the runnable. Since there can be thousands of runnables, storing in entry table is not always a good idea. 44 * TRC_RUNNABLE_REGISTER_METHOD_USE_ENTRY_TABLE: Store in entry table normally and handle will point to entry. 45 * TRC_RUNNABLE_REGISTER_METHOD_USE_STRING_ADDRESS: For this method the string address must be unique and will be used as handle value. 46 * TRC_RUNNABLE_REGISTER_METHOD_USE_HANDLE_ADDRESS: For this method the handle address must be unique and will be used as handle value. 47 * @param[out] pxRunnableHandle Pointer to zero-initialized TraceRunnableHandle_t. If handle that is pointed to is not 0 no entry will be created. 48 * 49 * @retval TRC_FAIL Failure 50 * @retval TRC_SUCCESS Success 51 */ 52 traceResult xTraceRunnableRegister(const char* szName, TraceRunnableRegisterMethod_t uxRegisterMethod, TraceRunnableHandle_t* pxRunnableHandle); 53 54 /** 55 * @brief Creates an event indicating a runnable started. 56 * 57 * @param[in] xRunnableHandle Runnable handle. 58 * 59 * @retval TRC_FAIL Failure 60 * @retval TRC_SUCCESS Success 61 */ 62 #define xTraceRunnableStart(xRunnableHandle) xTraceEventCreate1(PSF_EVENT_RUNNABLE_START, (TraceUnsignedBaseType_t)(xRunnableHandle)) 63 64 /** 65 * @brief Creates an event indicating a runnable stopped. 66 * 67 * @retval TRC_FAIL Failure 68 * @retval TRC_SUCCESS Success 69 */ 70 #define xTraceRunnableStop() xTraceEventCreate0(PSF_EVENT_RUNNABLE_STOP) 71 72 /** 73 * @brief Registers a set of static runnables. Requires XML configuration to properly interpret. 74 * 75 * @param[in] szName Name. 76 * @param[in] uiMajor Major version. 77 * @param[in] uiMinor Minor version. 78 * @param[in] uiPatch Patch version. 79 * @param[in] uiRunnableCount Runnables count. 80 * @param[out] pxRunnableSetHandle Pointer to uninitialized TraceRunnableStaticSetHandle_t. 81 * 82 * @retval TRC_FAIL Failure 83 * @retval TRC_SUCCESS Success 84 */ 85 #define xTraceRunnableRegisterStaticSet(szName, uiMajor, uiMinor, uiPatch, uiRunnableCount, pxRunnableSetHandle) xTraceExtensionCreate(szName, uiMajor, uiMinor, uiPatch, uiRunnableCount, pxRunnableSetHandle) 86 87 /** 88 * @brief Start a static runnable. Requires XML configuration to properly interpret. 89 * 90 * @param[in] xRunnableSetHandle Handle to initialized runnable set. 91 * @param[in] uiRunnableId Index in the runnable set. 92 * 93 * @retval TRC_FAIL Failure 94 * @retval TRC_SUCCESS Success 95 */ 96 #define xTraceRunnableStartStatic(xRunnableSetHandle, uiRunnableId) xTraceEventCreate0(xTraceExtensionGetEventId(xRunnableSetHandle, uiRunnableId)) 97 98 /** 99 * @brief Stop a static runnable. Requires XML configuration to properly interpret. 100 * 101 * @retval TRC_FAIL Failure 102 * @retval TRC_SUCCESS Success 103 */ 104 #define xTraceRunnableStopStatic() xTraceRunnableStop() 105 106 /** @} */ 107 108 #ifdef __cplusplus 109 } 110 #endif 111 112 #else 113 114 #define xTraceRunnableRegister(_szName, _uxRegisterMethod, _pxRunnableHandle) \ 115 TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(_szName), (void)(_uxRegisterMethod), (void)(_pxRunnableHandle), TRC_SUCCESS) 116 117 #define xTraceRunnableStart(_xRunnableHandle) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)(_xRunnableHandle), TRC_SUCCESS) 118 119 #define xTraceRunnableStop() (TRC_SUCCESS) 120 121 #define xTraceRunnableRegisterStaticSet(_szName, _uiMajor, _uiMinor, _uiPatch, _uiRunnableCount, _pxRunnableSetHandle) \ 122 TRC_COMMA_EXPR_TO_STATEMENT_EXPR_7((void)(_szName), (void)(_uiMajor), (void)(_uiMinor), (void)(_uiPatch), (void)(_uiRunnableCount), (void)(_pxRunnableSetHandle), TRC_SUCCESS) 123 124 #define xTraceRunnableStartStatic(_xRunnableSetHandle, _uiRunnableId) \ 125 TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(_xRunnableSetHandle), (void)(_uiRunnableId), TRC_SUCCESS) 126 127 #define xTraceRunnableStopStatic() (TRC_SUCCESS) 128 129 #endif 130 131 #endif 132
