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