1 /* 2 * Percepio Trace Recorder for Tracealyzer v4.9.2 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 entry table APIs. 13 */ 14 15 #ifndef TRC_ENTRY_TABLE_H 16 #define TRC_ENTRY_TABLE_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_entry_table_apis Trace Entry Table APIs 28 * @ingroup trace_recorder_apis 29 * @{ 30 */ 31 32 #define TRC_ENTRY_CREATE_WITH_ADDRESS(_pvAddress, _pxEntryHandle) (xTraceEntryCreate(_pxEntryHandle) == TRC_SUCCESS ? (((TraceEntry_t*)*(_pxEntryHandle))->pvAddress = (_pvAddress), TRC_SUCCESS) : TRC_FAIL) 33 #define TRC_ENTRY_SET_STATE(xEntryHandle, uxStateIndex, uxState) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(((TraceEntry_t*)(xEntryHandle))->xStates[uxStateIndex] = (uxState), TRC_SUCCESS) 34 #define TRC_ENTRY_SET_OPTIONS(xEntryHandle, uiMask) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(((TraceEntry_t*)(xEntryHandle))->uiOptions |= (uiMask), TRC_SUCCESS) 35 #define TRC_ENTRY_CLEAR_OPTIONS(xEntryHandle, uiMask) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(((TraceEntry_t*)(xEntryHandle))->uiOptions &= ~(uiMask), TRC_SUCCESS) 36 #define TRC_ENTRY_GET_ADDRESS(xEntryHandle, ppvAddress) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(*(ppvAddress) = ((TraceEntry_t*)(xEntryHandle))->pvAddress, TRC_SUCCESS) 37 #define TRC_ENTRY_GET_ADDRESS_RETURN(xEntryHandle) (((TraceEntry_t*)(xEntryHandle))->pvAddress) 38 #define TRC_ENTRY_GET_SYMBOL(xEntryHandle, pszSymbol) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(*(pszSymbol) = ((TraceEntry_t*)(xEntryHandle))->szSymbol, TRC_SUCCESS) 39 #define TRC_ENTRY_GET_STATE(xEntryHandle, uxStateIndex, puxState) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(*(puxState) = ((TraceEntry_t*)(xEntryHandle))->xStates[uxStateIndex], TRC_SUCCESS) 40 #define TRC_ENTRY_GET_STATE_RETURN(xEntryHandle, uxStateIndex) (((TraceEntry_t*)(xEntryHandle))->xStates[uxStateIndex]) 41 #define TRC_ENTRY_GET_OPTIONS(xEntryHandle, puiOptions) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(*(puiOptions) = ((TraceEntry_t*)(xEntryHandle))->uiOptions, TRC_SUCCESS) 42 43 #define TRC_ENTRY_TABLE_STATE_COUNT (3UL) 44 #define TRC_ENTRY_TABLE_SYMBOL_LENGTH ((uint32_t)(TRC_CFG_ENTRY_SYMBOL_MAX_LENGTH)) 45 46 /* TRC_ENTRY_TABLE_SLOT_SYMBOL_SIZE has to be aligned to TraceUnsignedBaseType_t but with a uint32_t padding to ensure that TraceEntry_t size is aligned (uiOptions is uint32_t) */ 47 #define TRC_ENTRY_TABLE_SLOT_SYMBOL_SIZE (((((sizeof(char) * (uint32_t)(TRC_ENTRY_TABLE_SYMBOL_LENGTH) - sizeof(uint32_t)) + (sizeof(TraceUnsignedBaseType_t) - 1UL)) / sizeof(TraceUnsignedBaseType_t)) * sizeof(TraceUnsignedBaseType_t)) + sizeof(uint32_t)) 48 49 #if (TRC_CFG_ENTRY_SLOTS > 256UL) 50 typedef uint16_t TraceEntryIndex_t; 51 #define TRC_ENTRY_INDEX_ALIGNMENT_MULTIPLE (4) /* Must align to 64-bit (sizeof(uint64_t) / sizeof(uint16_t)) */ 52 #else 53 typedef uint8_t TraceEntryIndex_t; 54 #define TRC_ENTRY_INDEX_ALIGNMENT_MULTIPLE (8) /* Must align to 64-bit (sizeof(uint64_t) / sizeof(uint8_t)) */ 55 #endif 56 57 #define TRC_ENTRY_TABLE_SLOTS ((((TRC_CFG_ENTRY_SLOTS) + (TRC_ENTRY_INDEX_ALIGNMENT_MULTIPLE) - 1) / TRC_ENTRY_INDEX_ALIGNMENT_MULTIPLE) * TRC_ENTRY_INDEX_ALIGNMENT_MULTIPLE) 58 59 typedef struct EntryIndexTable /* Aligned because TRC_ENTRY_TABLE_SLOTS is always a multiple that aligns to 64-bit */ 60 { 61 TraceEntryIndex_t axFreeIndexes[TRC_ENTRY_TABLE_SLOTS]; /* slot count and size is aligned to 64-bit */ 62 uint32_t uiFreeIndexCount; 63 uint32_t reserved; /* alignment */ 64 } TraceEntryIndexTable_t; 65 66 /** Trace Entry Structure */ 67 typedef struct TraceEntry /* Aligned because TRC_ENTRY_TABLE_SLOT_SYMBOL_SIZE will align together with uiOptions */ 68 { 69 void* pvAddress; /**< */ 70 TraceUnsignedBaseType_t xStates[TRC_ENTRY_TABLE_STATE_COUNT]; /**< */ 71 uint32_t uiOptions; /**< */ 72 char szSymbol[TRC_ENTRY_TABLE_SLOT_SYMBOL_SIZE]; /**< */ 73 } TraceEntry_t; 74 75 typedef struct TraceEntryTable /* Aligned */ 76 { 77 TraceUnsignedBaseType_t uxSlots; 78 TraceUnsignedBaseType_t uxEntrySymbolLength; 79 TraceUnsignedBaseType_t uxEntryStateCount; 80 TraceEntry_t axEntries[TRC_ENTRY_TABLE_SLOTS]; 81 } TraceEntryTable_t; 82 83 /** 84 * @internal Initialize trace entry index table. 85 * 86 * This routine initializes the trace entry index table which keeps track 87 * of availables indexes. 88 * 89 * @param[in] pxBuffer Pointer to uninitialized trace entry index table buffer. 90 * 91 * @retval TRC_FAIL Failure 92 * @retval TRC_SUCCESS Success 93 */ 94 traceResult xTraceEntryIndexTableInitialize(TraceEntryIndexTable_t* const pxBuffer); 95 96 /** 97 * @internal Initialize trace entry table. 98 * 99 * This routine initializes the trace entry table which maps objects to 100 * symbolic identifiers, state information, and options. 101 * 102 * @param[in] pxBuffer Pointer to uninitialized trace entry table buffer. 103 * 104 * @retval TRC_FAIL Failure 105 * @retval TRC_SUCCESS Success 106 */ 107 traceResult xTraceEntryTableInitialize(TraceEntryTable_t* const pxBuffer); 108 109 /** 110 * @brief Creates trace entry. 111 * 112 * @param[out] pxEntryHandle Pointer to uninitialized trace entry handle. 113 * 114 * @retval TRC_FAIL Failure 115 * @retval TRC_SUCCESS Success 116 */ 117 traceResult xTraceEntryCreate(TraceEntryHandle_t *pxEntryHandle); 118 119 /** 120 * @brief Deletes trace entry. 121 * 122 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 123 * 124 * @retval TRC_FAIL Failure 125 * @retval TRC_SUCCESS Success 126 */ 127 traceResult xTraceEntryDelete(TraceEntryHandle_t xEntryHandle); 128 129 /** 130 * @brief Finds trace entry mapped to object address. 131 * 132 * @param[in] pvAddress Address of object. 133 * @param[out] pxEntryHandle Pointer to uninitialized trace entry handle. 134 * 135 * @retval TRC_FAIL Failure 136 * @retval TRC_SUCCESS Success 137 */ 138 traceResult xTraceEntryFind(const void* const pvAddress, TraceEntryHandle_t* pxEntryHandle); 139 140 /** 141 * @brief Gets the number of entries in the trace entry table. 142 * 143 * @param[out] puiCount Count. 144 * 145 * @retval TRC_FAIL Failure 146 * @retval TRC_SUCCESS Success 147 */ 148 traceResult xTraceEntryGetCount(uint32_t* puiCount); 149 150 /** 151 * @brief Gets trace table entry at index. 152 * 153 * @param[in] index Entry index. 154 * @param[out] pxEntryHandle Pointer to uninitialized trace entry handle. 155 * 156 * @retval TRC_FAIL Failure 157 * @retval TRC_SUCCESS Success 158 */ 159 traceResult xTraceEntryGetAtIndex(uint32_t index, TraceEntryHandle_t* pxEntryHandle); 160 161 /** 162 * @brief Sets symbol for entry. 163 * 164 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 165 * @param[in] szSymbol Pointer to symbol string, set by function 166 * @param[in] uiLength Symbol length 167 * 168 * @retval TRC_FAIL Failure 169 * @retval TRC_SUCCESS Success 170 */ 171 traceResult xTraceEntrySetSymbol(const TraceEntryHandle_t xEntryHandle, const char* szSymbol, uint32_t uiLength); 172 173 #if ((TRC_CFG_USE_TRACE_ASSERT) == 1) 174 175 /** 176 * @brief Creates trace entry mapped to memory address. 177 * 178 * @param[in] pvAddress Address. 179 * @param[out] pxEntryHandle Pointer to uninitialized trace entry handle. 180 * 181 * @retval TRC_FAIL Failure 182 * @retval TRC_SUCCESS Success 183 */ 184 traceResult xTraceEntryCreateWithAddress(void* const pvAddress, TraceEntryHandle_t* pxEntryHandle); 185 186 /** 187 * @brief Sets trace entry state. 188 * 189 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 190 * @param[in] uxStateIndex Index of state (< TRC_ENTRY_TABLE_STATE_COUNT). 191 * @param[in] uxState State. 192 * 193 * @retval TRC_FAIL Failure 194 * @retval TRC_SUCCESS Success 195 */ 196 traceResult xTraceEntrySetState(const TraceEntryHandle_t xEntryHandle, TraceUnsignedBaseType_t uxStateIndex, TraceUnsignedBaseType_t uxState); 197 198 /** 199 * @brief Sets trace entry option(s). 200 * 201 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 202 * @param[in] uiMask Option(s) set mask. 203 * 204 * @retval TRC_FAIL Failure 205 * @retval TRC_SUCCESS Success 206 */ 207 traceResult xTraceEntrySetOptions(const TraceEntryHandle_t xEntryHandle, uint32_t uiMask); 208 209 /** 210 * @brief Clears trace entry option(s). 211 * 212 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 213 * @param[in] uiMask Options(s) clear mask. 214 * 215 * @retval TRC_FAIL Failure 216 * @retval TRC_SUCCESS Success 217 */ 218 traceResult xTraceEntryClearOptions(const TraceEntryHandle_t xEntryHandle, uint32_t uiMask); 219 220 /** 221 * @brief Gets linked address for trace entry. 222 * 223 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 224 * @param[out] ppvAddress Address. 225 * 226 * @retval TRC_FAIL Failure 227 * @retval TRC_SUCCESS Success 228 */ 229 traceResult xTraceEntryGetAddress(const TraceEntryHandle_t xEntryHandle, void **ppvAddress); 230 231 /** 232 * @brief Returns linked address for trace entry. 233 * 234 * @param[in] xEntryHandle Trace entry handle. 235 * 236 * @returns Address. 237 */ 238 void* xTraceEntryGetAddressReturn(const TraceEntryHandle_t xEntryHandle); 239 240 /** 241 * @brief Gets symbol for trace entry. 242 * 243 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 244 * @param[out] pszSymbol Symbol. 245 * 246 * @retval TRC_FAIL Failure 247 * @retval TRC_SUCCESS Success 248 */ 249 traceResult xTraceEntryGetSymbol(const TraceEntryHandle_t xEntryHandle, const char** pszSymbol); 250 251 /** 252 * @brief Gets state for trace entry. 253 * 254 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 255 * @param[in] uxStateIndex State index (< TRC_ENTRY_TABLE_STATE_COUNT). 256 * @param[out] puxState State. 257 * 258 * @retval TRC_FAIL Failure 259 * @retval TRC_SUCCESS Success 260 */ 261 traceResult xTraceEntryGetState(const TraceEntryHandle_t xEntryHandle, TraceUnsignedBaseType_t uxStateIndex, TraceUnsignedBaseType_t *puxState); 262 263 /** 264 * @internal Returns state for trace entry. 265 * 266 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 267 * @param[in] uxStateIndex State index (< TRC_ENTRY_TABLE_STATE_COUNT). 268 * 269 * @returns State 270 */ 271 TraceUnsignedBaseType_t xTraceEntryGetStateReturn(const TraceEntryHandle_t xEntryHandle, TraceUnsignedBaseType_t uxStateIndex); 272 273 /** 274 * @brief Gets options for trace entry. 275 * 276 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 277 * @param[out] puiOptions Options. 278 * 279 * @retval TRC_FAIL Failure 280 * @retval TRC_SUCCESS Success 281 */ 282 traceResult xTraceEntryGetOptions(const TraceEntryHandle_t xEntryHandle, uint32_t *puiOptions); 283 284 #else 285 286 #define xTraceEntryCreateWithAddress TRC_ENTRY_CREATE_WITH_ADDRESS 287 288 #define xTraceEntrySetState TRC_ENTRY_SET_STATE 289 #define xTraceEntrySetOptions TRC_ENTRY_SET_OPTIONS 290 #define xTraceEntryClearOptions TRC_ENTRY_CLEAR_OPTIONS 291 292 #define xTraceEntryGetAddress TRC_ENTRY_GET_ADDRESS 293 #define xTraceEntryGetAddressReturn TRC_ENTRY_GET_ADDRESS_RETURN 294 #define xTraceEntryGetSymbol TRC_ENTRY_GET_SYMBOL 295 #define xTraceEntryGetState TRC_ENTRY_GET_STATE 296 #define xTraceEntryGetStateReturn TRC_ENTRY_GET_STATE_RETURN 297 #define xTraceEntryGetOptions TRC_ENTRY_GET_OPTIONS 298 299 #endif /* ((TRC_CFG_USE_TRACE_ASSERT) == 1) */ 300 301 /** @} */ 302 303 #ifdef __cplusplus 304 } 305 #endif 306 307 #else 308 309 #define xTraceEntryCreate(_pxEntryHandle) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)(_pxEntryHandle), TRC_SUCCESS) 310 311 #define xTraceEntryDelete(_xEntryHandle) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)(_xEntryHandle), TRC_SUCCESS) 312 313 #define xTraceEntryFind(_pvAddress, _pxEntryHandle) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(_pvAddress), (void)(_pxEntryHandle), TRC_SUCCESS) 314 315 #define xTraceEntryGetCount(_puiCount) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)(_puiCount), TRC_SUCCESS) 316 317 #define xTraceEntryGetAtIndex(_index, _pxEntryHandle) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(_index), (void)(_pxEntryHandle), TRC_SUCCESS) 318 319 #define xTraceEntrySetSymbol(_xEntryHandle, _szSymbol, _uiLength) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(_xEntryHandle), (void)(_szSymbol), (void)(_uiLength), TRC_SUCCESS) 320 321 #define xTraceEntryCreateWithAddress(_pvAddress, _pxEntryHandle) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(_pvAddress), (void)(_pxEntryHandle), TRC_SUCCESS) 322 323 #define xTraceEntrySetState(_xEntryHandle, _uxStateIndex, _uxState) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(_xEntryHandle), (void)(_uxStateIndex), (void)(_uxState), TRC_SUCCESS) 324 325 #define xTraceEntrySetOptions(_xEntryHandle, _uiMask) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(_xEntryHandle), (void)(_uiMask), TRC_SUCCESS) 326 327 #define xTraceEntryClearOptions(_xEntryHandle, _uiMask) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(_xEntryHandle), (void)(_uiMask), TRC_SUCCESS) 328 329 #define xTraceEntryGetAddress(_xEntryHandle, _ppvAddress) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(_xEntryHandle), (void)(_ppvAddress), TRC_SUCCESS) 330 331 #define xTraceEntryGetAddressReturn(_xEntryHandle) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)(_xEntryHandle), (void*)0) 332 333 #define xTraceEntryGetSymbol(_xEntryHandle, _pszSymbol) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(_xEntryHandle), (void)(_pszSymbol), TRC_SUCCESS) 334 335 #define xTraceEntryGetState(_xEntryHandle, _uxStateIndex, _puxState) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(_xEntryHandle), (void)(_uxStateIndex), (void)(_puxState), TRC_SUCCESS) 336 337 #define xTraceEntryGetStateReturn(_xEntryHandle, _uxStateIndex) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(_xEntryHandle), (void)(_uxStateIndex), 0) 338 339 #define xTraceEntryGetOptions(_xEntryHandle, _puiOptions) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(_xEntryHandle), (void)(_puiOptions), TRC_SUCCESS) 340 341 #endif 342 343 #endif 344
