1 /* 2 * Percepio Trace Recorder for Tracealyzer v4.8.1 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 #if (TRC_USE_TRACEALYZER_RECORDER == 1) 19 20 #if (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) 21 22 #include <trcTypes.h> 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 /** 29 * @defgroup trace_runnable_apis Trace Runnable APIs 30 * @ingroup trace_recorder_apis 31 * @{ 32 */ 33 34 typedef enum TraceRunnableRegisterMethod 35 { 36 TRC_RUNNABLE_REGISTER_METHOD_USE_ENTRY_TABLE, 37 TRC_RUNNABLE_REGISTER_METHOD_USE_STRING_ADDRESS, 38 TRC_RUNNABLE_REGISTER_METHOD_USE_HANDLE_ADDRESS, 39 } TraceRunnableRegisterMethod_t; 40 41 /** 42 * @brief Registers a runnable. Can be called multiple times, will not create additional entries. 43 * 44 * @param[in] szName Name. 45 * @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. 46 * TRC_RUNNABLE_REGISTER_METHOD_USE_ENTRY_TABLE: Store in entry table normally and handle will point to entry. 47 * TRC_RUNNABLE_REGISTER_METHOD_USE_STRING_ADDRESS: For this method the string address must be unique and will be used as handle value. 48 * TRC_RUNNABLE_REGISTER_METHOD_USE_HANDLE_ADDRESS: For this method the handle address must be unique and will be used as handle value. 49 * @param[out] pxRunnableHandle Pointer to 0 initialized TraceRunnableHandle_t. If handle that is pointed to is not 0 no entry will be created. 50 * 51 * @retval TRC_FAIL Failure 52 * @retval TRC_SUCCESS Success 53 */ 54 traceResult xTraceRunnableRegister(const char* szName, TraceRunnableRegisterMethod_t uxRegisterMethod, TraceRunnableHandle_t* pxRunnableHandle); 55 56 /** 57 * @brief Creates an event indicating a runnable started. 58 * 59 * @param[in] xRunnableHandle Runnable handle. 60 * 61 * @retval TRC_FAIL Failure 62 * @retval TRC_SUCCESS Success 63 */ 64 #define xTraceRunnableStart(xRunnableHandle) xTraceEventCreate1(PSF_EVENT_RUNNABLE_START, (TraceUnsignedBaseType_t)(xRunnableHandle)) 65 66 /** 67 * @brief Creates an event indicating a runnable stopped. 68 * 69 * @retval TRC_FAIL Failure 70 * @retval TRC_SUCCESS Success 71 */ 72 #define xTraceRunnableStop() xTraceEventCreate0(PSF_EVENT_RUNNABLE_STOP) 73 74 /** 75 * @brief Registers a set of static runnables. Requires XML configuration to properly interpret. 76 * 77 * @param[in] szName Name. 78 * @param[in] uiMajor Major version. 79 * @param[in] uiMinor Minor version. 80 * @param[in] uiPatch Patch version. 81 * @param[in] uiRunnableCount Runnables count. 82 * @param[out] pxRunnableSetHandle Pointer to uninitialized TraceRunnableStaticSetHandle_t. 83 * 84 * @retval TRC_FAIL Failure 85 * @retval TRC_SUCCESS Success 86 */ 87 #define xTraceRunnableRegisterStaticSet(szName, uiMajor, uiMinor, uiPatch, uiRunnableCount, pxRunnableSetHandle) xTraceExtensionCreate(szName, uiMajor, uiMinor, uiPatch, uiRunnableCount, pxRunnableSetHandle) 88 89 /** 90 * @brief Start a static runnable. Requires XML configuration to properly interpret. 91 * 92 * @param[in] xRunnableSetHandle Pointer to initialized runnable set handle. 93 * @param[out] puiBaseEventId Base event id. 94 * 95 * @retval TRC_FAIL Failure 96 * @retval TRC_SUCCESS Success 97 */ 98 #define xTraceRunnableStartStatic(xRunnableSetHandle, uiRunnableId) xTraceEventCreate0(xTraceExtensionGetEventId(xRunnableSetHandle, uiRunnableId)) 99 100 /** 101 * @brief Stop a static runnable. Requires XML configuration to properly interpret. 102 * 103 * @retval TRC_FAIL Failure 104 * @retval TRC_SUCCESS Success 105 */ 106 #define xTraceRunnableStopStatic() xTraceRunnableStop() 107 108 /** @} */ 109 110 #ifdef __cplusplus 111 } 112 #endif 113 114 #else 115 116 #ifndef xTraceRunnableRegister 117 #define xTraceRunnableRegister(szName, uxRegisterMethod, pxRunnableHandle) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(szName), (void)(uxRegisterMethod), (void)(pxRunnableHandle), TRC_SUCCESS) 118 #endif 119 120 #ifndef xTraceRunnableStart 121 #define xTraceRunnableStart(xRunnableHandle) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)(xRunnableHandle), TRC_SUCCESS) 122 #endif 123 124 #ifndef xTraceRunnableStop 125 #define xTraceRunnableStop() (TRC_SUCCESS) 126 #endif 127 128 #endif 129 130 #else 131 132 #ifndef xTraceRunnableRegister 133 #define xTraceRunnableRegister(szName, uxRegisterMethod, pxRunnableHandle) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(szName), (void)(uxRegisterMethod), (void)(pxRunnableHandle), TRC_SUCCESS) 134 #endif 135 136 #ifndef xTraceRunnableStart 137 #define xTraceRunnableStart(xRunnableHandle) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)(xRunnableHandle), TRC_SUCCESS) 138 #endif 139 140 #ifndef xTraceRunnableStop 141 #define xTraceRunnableStop() (TRC_SUCCESS) 142 #endif 143 144 #endif 145 146 #endif 147
