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 object APIs. 13 */ 14 15 #ifndef TRC_OBJECT_H 16 #define TRC_OBJECT_H 17 18 #if (TRC_USE_TRACEALYZER_RECORDER == 1) && (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) 19 20 #include <trcTypes.h> 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 /** 27 * @defgroup trace_object_apis Trace Object APIs 28 * @ingroup trace_recorder_apis 29 * @{ 30 */ 31 32 /** 33 * @brief Registers trace object. 34 * 35 * @param[in] uiEventCode Event code. 36 * @param[in] pvObject Object. 37 * @param[in] szName Name. 38 * @param[in] uxStateCount State count. 39 * @param[in] uxStates States. 40 * @param[in] uxOptions Options. 41 * @param[out] pxObjectHandle Pointer to uninitialized trace object. 42 * 43 * @retval TRC_FAIL Failure 44 * @retval TRC_SUCCESS Success 45 */ 46 traceResult xTraceObjectRegisterInternal(uint32_t uiEventCode, void* const pvObject, const char* szName, TraceUnsignedBaseType_t uxStateCount, const TraceUnsignedBaseType_t uxStates[], TraceUnsignedBaseType_t uxOptions, TraceObjectHandle_t* pxObjectHandle); 47 48 /** 49 * @brief Registers trace object. 50 * 51 * @param[in] uiEventCode Event code. 52 * @param[in] pvObject Object. 53 * @param[in] szName Name. 54 * @param[in] uxState State. 55 * @param[out] pxObjectHandle Pointer to uninitialized trace object. 56 * 57 * @retval TRC_FAIL Failure 58 * @retval TRC_SUCCESS Success 59 */ 60 traceResult xTraceObjectRegister(uint32_t uiEventCode, void* const pvObject, const char* szName, TraceUnsignedBaseType_t uxState, TraceObjectHandle_t *pxObjectHandle); 61 62 /** 63 * @brief Registers trace object with two initial states. 64 * 65 * @param[in] uiEventCode Event code. 66 * @param[in] pvObject Object. 67 * @param[in] szName Name. 68 * @param[in] uxState1 State 1. 69 * @param[in] uxState2 State 2. 70 * @param[out] pxObjectHandle Pointer to uninitialized trace object. 71 * 72 * @retval TRC_FAIL Failure 73 * @retval TRC_SUCCESS Success 74 */ 75 traceResult xTraceObjectRegister2(uint32_t uiEventCode, void* const pvObject, const char* szName, TraceUnsignedBaseType_t uxState1, TraceUnsignedBaseType_t uxState2, TraceObjectHandle_t *pxObjectHandle); 76 77 /** 78 * @brief Unregisters trace object. 79 * 80 * @param[in] xObjectHandle Pointer to initialized trace object. 81 * @param[in] uiEventCode Event code. 82 * @param[in] uxState State. 83 * 84 * @retval TRC_FAIL Failure 85 * @retval TRC_SUCCESS Success 86 */ 87 traceResult xTraceObjectUnregister(TraceObjectHandle_t xObjectHandle, uint32_t uiEventCode, TraceUnsignedBaseType_t uxState); 88 89 /** 90 * @brief Sets trace object name. 91 * 92 * @param[in] xObjectHandle Pointer to initialized trace object. 93 * @param[in] szName Name. 94 * 95 * @retval TRC_FAIL Failure 96 * @retval TRC_SUCCESS Success 97 */ 98 traceResult xTraceObjectSetName(TraceObjectHandle_t xObjectHandle, const char *szName); 99 100 /** 101 * @brief Sets trace object state. 102 * 103 * @param[in] xObjectHandle Pointer to initialized trace object. 104 * @param[in] uxState State. 105 * 106 * @retval TRC_FAIL Failure 107 * @retval TRC_SUCCESS Success 108 */ 109 #define xTraceObjectSetState(xObjectHandle, uxState) xTraceObjectSetSpecificState(xObjectHandle, 0, uxState) 110 111 /** 112 * @brief Sets trace object specific state state. 113 * 114 * @param[in] xObjectHandle Pointer to initialized trace object. 115 * @param[in] uiIndex State Index. 116 * @param[in] uxState State. 117 * 118 * @retval TRC_FAIL Failure 119 * @retval TRC_SUCCESS Success 120 */ 121 #define xTraceObjectSetSpecificState(xObjectHandle, uiIndex, uxState) xTraceEntrySetState((TraceEntryHandle_t)(xObjectHandle), uiIndex, uxState) 122 123 /** 124 * @brief Sets trace object options. 125 * 126 * @param[in] xObjectHandle Pointer to initialized trace object. 127 * @param[in] uiOptions Options. 128 * 129 * @retval TRC_FAIL Failure 130 * @retval TRC_SUCCESS Success 131 */ 132 #define xTraceObjectSetOptions(xObjectHandle, uiOptions) xTraceEntrySetOptions((TraceEntryHandle_t)(xObjectHandle), uiOptions) 133 134 /** 135 * @brief Registers trace object without trace object handle. 136 * 137 * @param[in] uiEventCode Event code. 138 * @param[in] pvObject Object. 139 * @param[in] szName Name. 140 * @param[in] uxState State. 141 * 142 * @retval TRC_FAIL Failure 143 * @retval TRC_SUCCESS Success 144 */ 145 traceResult xTraceObjectRegisterWithoutHandle(uint32_t uiEventCode, void* pvObject, const char* szName, TraceUnsignedBaseType_t uxState); 146 147 /** 148 * @brief Registers trace object with two initial states without trace object handle. 149 * 150 * @param[in] uiEventCode Event code. 151 * @param[in] pvObject Object. 152 * @param[in] szName Name. 153 * @param[in] uxState1 State 1. 154 * @param[in] uxState2 State 2. 155 * 156 * @retval TRC_FAIL Failure 157 * @retval TRC_SUCCESS Success 158 */ 159 traceResult xTraceObjectRegisterWithoutHandle2(uint32_t uiEventCode, void* pvObject, const char* szName, TraceUnsignedBaseType_t uxState1, TraceUnsignedBaseType_t uxState2); 160 161 /** 162 * @brief Unregisters trace object without trace object handle. 163 * 164 * @param[in] uiEventCode Event code. 165 * @param[in] pvObject Object. 166 * @param[in] uxState State. 167 * 168 * @retval TRC_FAIL Failure 169 * @retval TRC_SUCCESS Success 170 */ 171 traceResult xTraceObjectUnregisterWithoutHandle(uint32_t uiEventCode, void* pvObject, TraceUnsignedBaseType_t uxState); 172 173 /** 174 * @brief Set trace object name without trace object handle. 175 * 176 * @param[in] pvObject Object. 177 * @param[in] szName Name. 178 * 179 * @retval TRC_FAIL Failure 180 * @retval TRC_SUCCESS Success 181 */ 182 traceResult xTraceObjectSetNameWithoutHandle(void* pvObject, const char* szName); 183 184 /** 185 * @brief Set trace object state without trace object handle. 186 * 187 * @param[in] pvObject Object. 188 * @param[in] uxState State. 189 * 190 * @retval TRC_FAIL Failure 191 * @retval TRC_SUCCESS Success 192 */ 193 #define xTraceObjectSetStateWithoutHandle(pvObject, uxState) xTraceObjectSetSpecificStateWithoutHandle(pvObject, 0, uxState) 194 195 /** 196 * @brief Sets trace object specific state without trace object 197 * handle. 198 * 199 * @param[in] pvObject Object. 200 * @param[in] uiIndex State index. 201 * @param[in] uxState State. 202 * 203 * @retval TRC_FAIL Failure 204 * @retval TRC_SUCCESS Success 205 */ 206 traceResult xTraceObjectSetSpecificStateWithoutHandle(void* pvObject, uint32_t uiIndex, TraceUnsignedBaseType_t uxState); 207 208 /** 209 * @brief Sets trace object options without trace object handle. 210 * 211 * @param[in] pvObject Object. 212 * @param[in] uiOptions Options. 213 * 214 * @retval TRC_FAIL Failure 215 * @retval TRC_SUCCESS Success 216 */ 217 traceResult xTraceObjectSetOptionsWithoutHandle(void* pvObject, uint32_t uiOptions); 218 219 /** @} */ 220 221 #ifdef __cplusplus 222 } 223 #endif 224 225 #else 226 227 #define xTraceObjectRegisterInternal(_uiEventCode, _pvObject, _szName, _uxStateCount, _uxStates, _uxOptions, _pxObjectHandle) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_8((void)(_uiEventCode), (void)(_pvObject), (void)(_szName), (void)(_uxStateCount), (void)(_uxStates), (void)(_uxOptions), (void)(_pxObjectHandle), TRC_SUCCESS) 228 229 #define xTraceObjectRegister(_uiEventCode, _pvObject, _szName, _uxState, _pxObjectHandle) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_6((void)(_uiEventCode), (void)(_pvObject), (void)(_szName), (void)(_uxState), (void)(_pxObjectHandle), TRC_SUCCESS) 230 231 #define xTraceObjectUnregister(_xObjectHandle, _uiEventCode, _uxState) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(_xObjectHandle), (void)(_uiEventCode), (void)(_uxState), TRC_SUCCESS) 232 233 #define xTraceObjectSetName(_xObjectHandle, _szName) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(_xObjectHandle), (void)(_szName), TRC_SUCCESS) 234 235 #define xTraceObjectSetState(_xObjectHandle, _uxState) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(_xObjectHandle), (void)(_uxState), TRC_SUCCESS) 236 237 #define xTraceObjectSetSpecificState(_xObjectHandle, _uiIndex, _uxState) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(_xObjectHandle), (void)(_uiIndex), (void)(_uxState), TRC_SUCCESS) 238 239 #define xTraceObjectSetOptions(_xObjectHandle, _uiOptions) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(_xObjectHandle), (void)(_uiOptions), TRC_SUCCESS) 240 241 #define xTraceObjectRegisterWithoutHandle(_uiEventCode, _pvObject, _szName, _uxState) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_5((void)(_uiEventCode), (void)(_pvObject), (void)(_szName), (void)(_uxState), TRC_SUCCESS) 242 243 #define xTraceObjectUnregisterWithoutHandle(_uiEventCode, _pvObject, _uxState) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(_uiEventCode), (void)(_pvObject), (void)(_uxState), TRC_SUCCESS) 244 245 #define xTraceObjectSetNameWithoutHandle(_pvObject, _szName) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(_pvObject), (void)(_szName), TRC_SUCCESS) 246 247 #define xTraceObjectSetStateWithoutHandle(_pvObject, _uxState) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(_pvObject), (void)(_uxState), TRC_SUCCESS) 248 249 #define xTraceObjectSetSpecificStateWithoutHandle(_pvObject, _uiIndex, _uxState) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(_pvObject), (void)(_uiIndex), (void)(_uxState), TRC_SUCCESS) 250 251 #define xTraceObjectSetOptionsWithoutHandle(_pvObject, _uiOptions) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(_pvObject), (void)(_uiOptions), TRC_SUCCESS) 252 253 #endif 254 255 #endif 256
