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 heap APIs. 13 */ 14 15 #ifndef TRC_HEAP_H 16 #define TRC_HEAP_H 17 18 #ifndef TRC_USE_HEAPS 19 #define TRC_USE_HEAPS 1 20 #endif 21 22 #if (TRC_USE_TRACEALYZER_RECORDER == 1) && (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) && (TRC_USE_HEAPS == 1) 23 24 #include <trcTypes.h> 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 #define TRC_HEAP_STATE_INDEX_CURRENT 0u 31 #define TRC_HEAP_STATE_INDEX_HIGHWATERMARK 1u 32 #define TRC_HEAP_STATE_INDEX_MAX 2u 33 34 /** 35 * @defgroup trace_heap_apis Trace Heap APIs 36 * @ingroup trace_recorder_apis 37 * @{ 38 */ 39 40 /** 41 * @brief Creates trace heap. 42 * 43 * @param[in] szName Name. 44 * @param[in] uxCurrent Current level. 45 * @param[in] uxHighWaterMark High water mark 46 * @param[in] uxMax Maximum level. 47 * @param[out] pxHeapHandle Pointer to uninitialized trace heap handle. 48 * @return traceResult 49 */ 50 traceResult xTraceHeapCreate(const char *szName, TraceUnsignedBaseType_t uxCurrent, TraceUnsignedBaseType_t uxHighWaterMark, TraceUnsignedBaseType_t uxMax, TraceHeapHandle_t *pxHeapHandle); 51 52 /** 53 * @brief Signals trace heap alloc. 54 * 55 * @param[in] xHeapHandle Trace heap handle. 56 * @param[in] pvAddress Address. 57 * @param[in] uxSize Size. 58 * 59 * @retval TRC_FAIL Failure 60 * @retval TRC_SUCCESS Success 61 */ 62 traceResult xTraceHeapAlloc(TraceHeapHandle_t xHeapHandle, void *pvAddress, TraceUnsignedBaseType_t uxSize); 63 64 /** 65 * @brief Signals trace heap free. 66 * 67 * @param[in] xHeapHandle Trace heap handle. 68 * @param[in] pvAddress Address. 69 * @param[in] uxSize Size. 70 * 71 * @retval TRC_FAIL Failure 72 * @retval TRC_SUCCESS Success 73 */ 74 traceResult xTraceHeapFree(TraceHeapHandle_t xHeapHandle, void* pvAddress, TraceUnsignedBaseType_t uxSize); 75 76 /** 77 * @brief Gets trace heap current allocation size. 78 * 79 * @param[in] xHeapHandle Trace heap handle. 80 * @param[out] puxCurrent Current. 81 * 82 * @retval TRC_FAIL Failure 83 * @retval TRC_SUCCESS Success 84 */ 85 #define xTraceHeapGetCurrent(xHeapHandle, puxCurrent) xTraceEntryGetState(xHeapHandle, TRC_HEAP_STATE_INDEX_CURRENT, puxCurrent) 86 87 /** 88 * @brief Sets trace heap current allocation size. 89 * 90 * @param[in] xHeapHandle Trace heap handle. 91 * @param[in] uxCurrent Current. 92 * 93 * @retval TRC_FAIL Failure 94 * @retval TRC_SUCCESS Success 95 */ 96 #define xTraceHeapSetCurrent(xHeapHandle, uxCurrent) xTraceEntrySetState(xHeapHandle, TRC_HEAP_STATE_INDEX_CURRENT, uxCurrent) 97 98 /** 99 * @brief Gets trace heap high water mark. 100 * 101 * @param[in] xHeapHandle Trace heap handle. 102 * @param[out] puxHighWaterMark High water mark. 103 * 104 * @retval TRC_FAIL Failure 105 * @retval TRC_SUCCESS Success 106 */ 107 #define xTraceHeapGetHighWaterMark(xHeapHandle, puxHighWaterMark) xTraceEntryGetState(xHeapHandle, TRC_HEAP_STATE_INDEX_HIGHWATERMARK, puxHighWaterMark) 108 109 /** 110 * @brief Sets trace heap high water mark. 111 * 112 * @param[in] xHeapHandle Trace heap handle. 113 * @param[in] uxHighWaterMark High water mark. 114 * 115 * @retval TRC_FAIL Failure 116 * @retval TRC_SUCCESS Success 117 */ 118 #define xTraceHeapSetHighWaterMark(xHeapHandle, uxHighWaterMark) xTraceEntrySetState(xHeapHandle, TRC_HEAP_STATE_INDEX_HIGHWATERMARK, uxHighWaterMark) 119 120 /** 121 * @brief Gets trace heap max size. 122 * 123 * @param[in] xHeapHandle Trace heap handle. 124 * @param[out] puxMax Max. 125 * 126 * @retval TRC_FAIL Failure 127 * @retval TRC_SUCCESS Success 128 */ 129 #define xTraceHeapGetMax(xHeapHandle, puxMax) xTraceEntryGetState(xHeapHandle, TRC_HEAP_STATE_INDEX_MAX, puxMax) 130 131 /** 132 * @brief Sets trace heap max size. 133 * 134 * @param[in] xHeapHandle Trace heap handle. 135 * @param[in] uxMax Max heap size. 136 * 137 * @retval TRC_FAIL Failure 138 * @retval TRC_SUCCESS Success 139 */ 140 #define xTraceHeapSetMax(xHeapHandle, uxMax) xTraceEntrySetState(xHeapHandle, TRC_HEAP_STATE_INDEX_MAX, uxMax) 141 142 /** @} */ 143 144 #ifdef __cplusplus 145 } 146 #endif 147 148 #else 149 150 #define xTraceHeapCreate(__szName, __uxCurrent, __uxHighWaterMark, __uxMax, __pxHeapHandle) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_6((void)(__szName), (void)(__uxCurrent), (void)(__uxHighWaterMark), (void)(__uxMax), (void)(__pxHeapHandle), TRC_SUCCESS) 151 152 #define xTraceHeapAlloc(__xHeapHandle, __pvAddress, __uxSize) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(__xHeapHandle), (void)(__pvAddress), (void)(__uxSize), TRC_SUCCESS) 153 154 #define xTraceHeapFree(__xHeapHandle, __pvAddress, __uxSize) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(__xHeapHandle), (void)(__pvAddress), (void)(__uxSize), TRC_SUCCESS) 155 156 #define xTraceHeapGetCurrent(__xHeapHandle, __puxCurrent) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(__xHeapHandle), (void)(__puxCurrent), TRC_SUCCESS) 157 158 #define xTraceHeapGetHighWaterMark(__xHeapHandle, __puxHighWaterMark) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(__xHeapHandle), (void)(__puxHighWaterMark), TRC_SUCCESS) 159 160 #define xTraceHeapGetMax(__xHeapHandle, __puxMax) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(__xHeapHandle), (void)(__puxMax), TRC_SUCCESS) 161 162 #endif 163 164 #endif 165
