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