1 /* 2 * Percepio Trace Recorder for Tracealyzer v4.6.6 3 * Copyright 2021 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, uiStateIndex, uxState) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(((TraceEntry_t*)(xEntryHandle))->xStates[uiStateIndex] = (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, uiStateIndex, puxState) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(*(puxState) = ((TraceEntry_t*)(xEntryHandle))->xStates[uiStateIndex], TRC_SUCCESS) 41 #define TRC_ENTRY_GET_STATE_RETURN(xEntryHandle, uiStateIndex) (((TraceEntry_t*)(xEntryHandle))->xStates[uiStateIndex]) 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_SLOTS (TRC_CFG_ENTRY_SLOTS) 45 #define TRC_ENTRY_TABLE_STATE_COUNT (3) 46 #define TRC_ENTRY_TABLE_SYMBOL_LENGTH (TRC_CFG_ENTRY_SYMBOL_MAX_LENGTH) 47 #define TRC_ENTRY_TABLE_SLOT_SYMBOL_SIZE ((((sizeof(char) * TRC_ENTRY_TABLE_SYMBOL_LENGTH) + (sizeof(uint32_t) - 1)) / sizeof(uint32_t)) * sizeof(uint32_t)) 48 49 /** Trace Entry Structure */ 50 typedef struct TraceEntry 51 { 52 void* pvAddress; /**< */ 53 TraceUnsignedBaseType_t xStates[TRC_ENTRY_TABLE_STATE_COUNT]; /**< */ 54 uint32_t uiOptions; /**< */ 55 char szSymbol[TRC_ENTRY_TABLE_SLOT_SYMBOL_SIZE]; /**< */ 56 } TraceEntry_t; 57 58 #define TRC_ENTRY_TABLE_SIZE (sizeof(uint32_t) + sizeof(uint32_t) + sizeof(uint32_t) + (sizeof(TraceEntry_t) * (TRC_ENTRY_TABLE_SLOTS))) 59 60 /** Trace Entry Table Buffer Structure */ 61 typedef struct TraceEntryTableBuffer 62 { 63 uint8_t buffer[(TRC_ENTRY_TABLE_SIZE)]; /**< */ 64 } TraceEntryTableBuffer_t; 65 66 /** 67 * @internal Initialize trace entry table. 68 * 69 * This routine initializes the trace entry table which maps objects to 70 * symbolic identifiers, state information, and options. 71 * 72 * @param[in] pxBuffer Pointer to uninitialized trace entry table buffer. 73 * 74 * @retval TRC_FAIL Failure 75 * @retval TRC_SUCCESS Success 76 */ 77 traceResult xTraceEntryTableInitialize(TraceEntryTableBuffer_t* pxBuffer); 78 79 /** 80 * @brief Creates trace entry. 81 * 82 * @param[out] pxEntryHandle Pointer to uninitialized trace entry handle. 83 * 84 * @retval TRC_FAIL Failure 85 * @retval TRC_SUCCESS Success 86 */ 87 traceResult xTraceEntryCreate(TraceEntryHandle_t *pxEntryHandle); 88 89 /** 90 * @brief Deletes trace entry. 91 * 92 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 93 * 94 * @retval TRC_FAIL Failure 95 * @retval TRC_SUCCESS Success 96 */ 97 traceResult xTraceEntryDelete(TraceEntryHandle_t xEntryHandle); 98 99 /** 100 * @brief Finds trace entry mapped to object address. 101 * 102 * @param[in] pvAddress Address of object. 103 * @param[out] pxEntryHandle Pointer to uninitialized trace entry handle. 104 * 105 * @retval TRC_FAIL Failure 106 * @retval TRC_SUCCESS Success 107 */ 108 traceResult xTraceEntryFind(void* pvAddress, TraceEntryHandle_t* pxEntryHandle); 109 110 /** 111 * @brief Gets the number of entries in the trace entry table. 112 * 113 * @param[out] puiCount Count. 114 * 115 * @retval TRC_FAIL Failure 116 * @retval TRC_SUCCESS Success 117 */ 118 traceResult xTraceEntryGetCount(uint32_t* puiCount); 119 120 /** 121 * @brief Gets trace table entry at index. 122 * 123 * @param[in] index Entry index. 124 * @param[out] pxEntryHandle Pointer to uninitialized trace entry handle. 125 * 126 * @retval TRC_FAIL Failure 127 * @retval TRC_SUCCESS Success 128 */ 129 traceResult xTraceEntryGetAtIndex(uint32_t index, TraceEntryHandle_t* pxEntryHandle); 130 131 /** 132 * @brief Sets symbol for entry. 133 * 134 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 135 * @param[out] szSymbol Pointer to symbol string, set by function 136 * 137 * @retval TRC_FAIL Failure 138 * @retval TRC_SUCCESS Success 139 */ 140 traceResult xTraceEntrySetSymbol(TraceEntryHandle_t xEntryHandle, const char* szSymbol); 141 142 #if ((TRC_CFG_USE_TRACE_ASSERT) == 1) 143 144 /** 145 * @brief Creates trace entry mapped to memory address. 146 * 147 * @param[in] pvAddress Address. 148 * @param[out] pxEntryHandle Pointer to uninitialized trace entry handle. 149 * 150 * @retval TRC_FAIL Failure 151 * @retval TRC_SUCCESS Success 152 */ 153 traceResult xTraceEntryCreateWithAddress(void* pvAddress, TraceEntryHandle_t* pxEntryHandle); 154 155 /** 156 * @brief Sets trace entry state. 157 * 158 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 159 * @param[in] uiStateIndex Index of state (< TRC_ENTRY_TABLE_STATE_COUNT). 160 * @param[in] uxState State. 161 * 162 * @retval TRC_FAIL Failure 163 * @retval TRC_SUCCESS Success 164 */ 165 traceResult xTraceEntrySetState(TraceEntryHandle_t xEntryHandle, uint32_t uiStateIndex, TraceUnsignedBaseType_t uxState); 166 167 /** 168 * @brief Sets trace entry option(s). 169 * 170 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 171 * @param[in] uiMask Option(s) set mask. 172 * 173 * @retval TRC_FAIL Failure 174 * @retval TRC_SUCCESS Success 175 */ 176 traceResult xTraceEntrySetOptions(TraceEntryHandle_t xEntryHandle, uint32_t uiMask); 177 178 /** 179 * @brief Clears trace entry option(s). 180 * 181 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 182 * @param[in] uiMask Options(s) clear mask. 183 * 184 * @retval TRC_FAIL Failure 185 * @retval TRC_SUCCESS Success 186 */ 187 traceResult xTraceEntryClearOptions(TraceEntryHandle_t xEntryHandle, uint32_t uiMask); 188 189 /** 190 * @brief Gets linked address for trace entry. 191 * 192 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 193 * @param[out] ppvAddress Address. 194 * 195 * @retval TRC_FAIL Failure 196 * @retval TRC_SUCCESS Success 197 */ 198 traceResult xTraceEntryGetAddress(TraceEntryHandle_t xEntryHandle, void **ppvAddress); 199 200 /** 201 * @brief Gets symbol for trace entry. 202 * 203 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 204 * @param[out] pszSymbol Symbol. 205 * 206 * @retval TRC_FAIL Failure 207 * @retval TRC_SUCCESS Success 208 */ 209 traceResult xTraceEntryGetSymbol(TraceEntryHandle_t xEntryHandle, const char** pszSymbol); 210 211 /** 212 * @brief Gets state for trace entry. 213 * 214 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 215 * @param[in] uiStateIndex State index (< TRC_ENTRY_TABLE_STATE_COUNT). 216 * @param[out] puxState State. 217 * 218 * @retval TRC_FAIL Failure 219 * @retval TRC_SUCCESS Success 220 */ 221 traceResult xTraceEntryGetState(TraceEntryHandle_t xEntryHandle, uint32_t uiStateIndex, TraceUnsignedBaseType_t *puxState); 222 223 /** 224 * @internal Returns state for trace entry. 225 * 226 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 227 * @param[in] uiStateIndex State index (< TRC_ENTRY_TABLE_STATE_COUNT). 228 * 229 * @returns State 230 */ 231 TraceUnsignedBaseType_t xTraceEntryGetStateReturn(TraceEntryHandle_t xEntryHandle, uint32_t uiStateIndex); 232 233 /** 234 * @brief Gets options for trace entry. 235 * 236 * @param[in] xEntryHandle Pointer to initialized trace entry handle. 237 * @param[out] puiOptions Options. 238 * 239 * @retval TRC_FAIL Failure 240 * @retval TRC_SUCCESS Success 241 */ 242 traceResult xTraceEntryGetOptions(TraceEntryHandle_t xEntryHandle, uint32_t *puiOptions); 243 244 #else 245 246 #define xTraceEntryCreateWithAddress TRC_ENTRY_CREATE_WITH_ADDRESS 247 248 #define xTraceEntrySetState TRC_ENTRY_SET_STATE 249 #define xTraceEntrySetOptions TRC_ENTRY_SET_OPTIONS 250 #define xTraceEntryClearOptions TRC_ENTRY_CLEAR_OPTIONS 251 252 #define xTraceEntryGetAddress TRC_ENTRY_GET_ADDRESS 253 #define xTraceEntryGetSymbol TRC_ENTRY_GET_SYMBOL 254 #define xTraceEntryGetState TRC_ENTRY_GET_STATE 255 #define xTraceEntryGetStateReturn TRC_ENTRY_GET_STATE_RETURN 256 #define xTraceEntryGetOptions TRC_ENTRY_GET_OPTIONS 257 258 #endif /* ((TRC_CFG_USE_TRACE_ASSERT) == 1) */ 259 260 /** @} */ 261 262 #ifdef __cplusplus 263 } 264 #endif 265 266 #endif /* (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) */ 267 268 #endif /* (TRC_USE_TRACEALYZER_RECORDER == 1) */ 269 270 #endif /* TRC_ENTRY_TABLE_H */ 271
