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 object APIs. 13 */ 14 15 #ifndef TRC_OBJECT_H 16 #define TRC_OBJECT_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_object_apis Trace Object APIs 30 * @ingroup trace_recorder_apis 31 * @{ 32 */ 33 34 /** 35 * @brief Registers trace object. 36 * 37 * @param[in] uiEventCode Event code. 38 * @param[in] pvObject Object. 39 * @param[in] szName Name. 40 * @param[in] uxStateCount State count. 41 * @param[in] uxStates States. 42 * @param[in] uxOptions Options. 43 * @param[out] pxObjectHandle Pointer to uninitialized trace object. 44 * 45 * @retval TRC_FAIL Failure 46 * @retval TRC_SUCCESS Success 47 */ 48 traceResult xTraceObjectRegisterInternal(uint32_t uiEventCode, void* const pvObject, const char* szName, TraceUnsignedBaseType_t uxStateCount, const TraceUnsignedBaseType_t uxStates[], TraceUnsignedBaseType_t uxOptions, TraceObjectHandle_t* pxObjectHandle); 49 50 /** 51 * @brief Registers trace object. 52 * 53 * @param[in] uiEventCode Event code. 54 * @param[in] pvObject Object. 55 * @param[in] szName Name. 56 * @param[in] uxState State. 57 * @param[out] pxObjectHandle Pointer to uninitialized trace object. 58 * 59 * @retval TRC_FAIL Failure 60 * @retval TRC_SUCCESS Success 61 */ 62 traceResult xTraceObjectRegister(uint32_t uiEventCode, void* const pvObject, const char* szName, TraceUnsignedBaseType_t uxState, TraceObjectHandle_t *pxObjectHandle); 63 64 /** 65 * @brief Unregisters trace object. 66 * 67 * @param[in] xObjectHandle Pointer to initialized trace object. 68 * @param[in] uiEventCode Event code. 69 * @param[in] uxState State. 70 * 71 * @retval TRC_FAIL Failure 72 * @retval TRC_SUCCESS Success 73 */ 74 traceResult xTraceObjectUnregister(TraceObjectHandle_t xObjectHandle, uint32_t uiEventCode, TraceUnsignedBaseType_t uxState); 75 76 /** 77 * @brief Sets trace object name. 78 * 79 * @param[in] xObjectHandle Pointer to initialized trace object. 80 * @param[in] szName Name. 81 * 82 * @retval TRC_FAIL Failure 83 * @retval TRC_SUCCESS Success 84 */ 85 traceResult xTraceObjectSetName(TraceObjectHandle_t xObjectHandle, const char *szName); 86 87 /** 88 * @brief Sets trace object state. 89 * 90 * @param[in] xObjectHandle Pointer to initialized trace object. 91 * @param[in] uxState State. 92 * 93 * @retval TRC_FAIL Failure 94 * @retval TRC_SUCCESS Success 95 */ 96 #define xTraceObjectSetState(xObjectHandle, uxState) xTraceObjectSetSpecificState(xObjectHandle, 0, uxState) 97 98 /** 99 * @brief Sets trace object specific state state. 100 * 101 * @param[in] xObjectHandle Pointer to initialized trace object. 102 * @param[in] uiIndex State Index. 103 * @param[in] uxState State. 104 * 105 * @retval TRC_FAIL Failure 106 * @retval TRC_SUCCESS Success 107 */ 108 #define xTraceObjectSetSpecificState(xObjectHandle, uiIndex, uxState) xTraceEntrySetState((TraceEntryHandle_t)(xObjectHandle), uiIndex, uxState) 109 110 /** 111 * @brief Sets trace object options. 112 * 113 * @param[in] xObjectHandle Pointer to initialized trace object. 114 * @param[in] uiOptions Options. 115 * 116 * @retval TRC_FAIL Failure 117 * @retval TRC_SUCCESS Success 118 */ 119 #define xTraceObjectSetOptions(xObjectHandle, uiOptions) xTraceEntrySetOptions((TraceEntryHandle_t)(xObjectHandle), uiOptions) 120 121 /** 122 * @brief Registers trace object without trace object handle. 123 * 124 * @param[in] uiEventCode Event code. 125 * @param[in] pvObject Object. 126 * @param[in] szName Name. 127 * @param[in] uxState State. 128 * 129 * @retval TRC_FAIL Failure 130 * @retval TRC_SUCCESS Success 131 */ 132 traceResult xTraceObjectRegisterWithoutHandle(uint32_t uiEventCode, void* pvObject, const char* szName, TraceUnsignedBaseType_t uxState); 133 134 /** 135 * @brief Unregisters trace object without trace object handle. 136 * 137 * @param[in] uiEventCode Event code. 138 * @param[in] pvObject Object. 139 * @param[in] uxState State. 140 * 141 * @retval TRC_FAIL Failure 142 * @retval TRC_SUCCESS Success 143 */ 144 traceResult xTraceObjectUnregisterWithoutHandle(uint32_t uiEventCode, void* pvObject, TraceUnsignedBaseType_t uxState); 145 146 /** 147 * @brief Set trace object name without trace object handle. 148 * 149 * @param[in] pvObject Object. 150 * @param[in] szName Name. 151 * 152 * @retval TRC_FAIL Failure 153 * @retval TRC_SUCCESS Success 154 */ 155 traceResult xTraceObjectSetNameWithoutHandle(void* pvObject, const char* szName); 156 157 /** 158 * @brief Set trace object state without trace object handle. 159 * 160 * @param[in] pvObject Object. 161 * @param[in] uxState State. 162 * 163 * @retval TRC_FAIL Failure 164 * @retval TRC_SUCCESS Success 165 */ 166 #define xTraceObjectSetStateWithoutHandle(pvObject, uxState) xTraceObjectSetSpecificStateWithoutHandle(pvObject, 0, uxState) 167 168 /** 169 * @brief Sets trace object specific state without trace object 170 * handle. 171 * 172 * @param[in] pvObject Object. 173 * @param[in] uiIndex State index. 174 * @param[in] uxState State. 175 * 176 * @retval TRC_FAIL Failure 177 * @retval TRC_SUCCESS Success 178 */ 179 traceResult xTraceObjectSetSpecificStateWithoutHandle(void* pvObject, uint32_t uiIndex, TraceUnsignedBaseType_t uxState); 180 181 /** 182 * @brief Sets trace object options without trace object handle. 183 * 184 * @param[in] pvObject Object. 185 * @param[in] uiOptions Options. 186 * 187 * @retval TRC_FAIL Failure 188 * @retval TRC_SUCCESS Success 189 */ 190 traceResult xTraceObjectSetOptionsWithoutHandle(void* pvObject, uint32_t uiOptions); 191 192 /** @} */ 193 194 #ifdef __cplusplus 195 } 196 #endif 197 198 #endif /* (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) */ 199 200 #endif /* (TRC_USE_TRACEALYZER_RECORDER == 1) */ 201 202 #endif /* TRC_OBJECT_H */ 203
