1 /* 2 * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 #pragma once 7 8 #include "sdkconfig.h" 9 #include "sys/queue.h" 10 #include <stdint.h> 11 #include <esp_err.h> 12 13 #ifdef __cplusplus 14 extern "C" { 15 #endif 16 17 #if !defined(CONFIG_HEAP_TRACING) && !defined(HEAP_TRACE_SRCFILE) 18 #warning "esp_heap_trace.h is included but heap tracing is disabled in menuconfig, functions are no-ops" 19 #endif 20 21 #ifndef CONFIG_HEAP_TRACING_STACK_DEPTH 22 #define CONFIG_HEAP_TRACING_STACK_DEPTH 0 23 #endif 24 25 typedef enum { 26 HEAP_TRACE_ALL, 27 HEAP_TRACE_LEAKS, 28 } heap_trace_mode_t; 29 30 /** 31 * @brief Trace record data type. Stores information about an allocated region of memory. 32 */ 33 typedef struct heap_trace_record_t { 34 uint32_t ccount; ///< CCOUNT of the CPU when the allocation was made. LSB (bit value 1) is the CPU number (0 or 1). 35 void *address; ///< Address which was allocated. If NULL, then this record is empty. 36 size_t size; ///< Size of the allocation 37 void *alloced_by[CONFIG_HEAP_TRACING_STACK_DEPTH]; ///< Call stack of the caller which allocated the memory. 38 void *freed_by[CONFIG_HEAP_TRACING_STACK_DEPTH]; ///< Call stack of the caller which freed the memory (all zero if not freed.) 39 #if CONFIG_HEAP_TRACING_STANDALONE 40 TAILQ_ENTRY(heap_trace_record_t) tailq_list; ///< Linked list: prev & next records 41 #if CONFIG_HEAP_TRACE_HASH_MAP 42 TAILQ_ENTRY(heap_trace_record_t) tailq_hashmap; ///< Linked list: prev & next in hashmap entry list 43 #endif // CONFIG_HEAP_TRACE_HASH_MAP 44 #endif // CONFIG_HEAP_TRACING_STANDALONE 45 } heap_trace_record_t; 46 47 /** 48 * @brief Stores information about the result of a heap trace. 49 */ 50 typedef struct { 51 heap_trace_mode_t mode; ///< The heap trace mode we just completed / are running 52 size_t total_allocations; ///< The total number of allocations made during tracing 53 size_t total_frees; ///< The total number of frees made during tracing 54 size_t count; ///< The number of records in the internal buffer 55 size_t capacity; ///< The capacity of the internal buffer 56 size_t high_water_mark; ///< The maximum value that 'count' got to 57 size_t has_overflowed; ///< True if the internal buffer overflowed at some point 58 #if CONFIG_HEAP_TRACE_HASH_MAP 59 size_t total_hashmap_hits; ///< If hashmap is used, the total number of hits 60 size_t total_hashmap_miss; ///< If hashmap is used, the total number of misses (possibly due to overflow) 61 #endif 62 } heap_trace_summary_t; 63 64 /** 65 * @brief Initialise heap tracing in standalone mode. 66 * 67 * This function must be called before any other heap tracing functions. 68 * 69 * To disable heap tracing and allow the buffer to be freed, stop tracing and then call heap_trace_init_standalone(NULL, 0); 70 * 71 * @param record_buffer Provide a buffer to use for heap trace data. 72 * Note: External RAM is allowed, but it prevents recording allocations made from ISR's. 73 * @param num_records Size of the heap trace buffer, as number of record structures. 74 * @return 75 * - ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. 76 * - ESP_ERR_INVALID_STATE Heap tracing is currently in progress. 77 * - ESP_OK Heap tracing initialised successfully. 78 */ 79 esp_err_t heap_trace_init_standalone(heap_trace_record_t *record_buffer, size_t num_records); 80 81 /** 82 * @brief Initialise heap tracing in host-based mode. 83 * 84 * This function must be called before any other heap tracing functions. 85 * 86 * @return 87 * - ESP_ERR_INVALID_STATE Heap tracing is currently in progress. 88 * - ESP_OK Heap tracing initialised successfully. 89 */ 90 esp_err_t heap_trace_init_tohost(void); 91 92 /** 93 * @brief Start heap tracing. All heap allocations & frees will be traced, until heap_trace_stop() is called. 94 * 95 * @note heap_trace_init_standalone() must be called to provide a valid buffer, before this function is called. 96 * 97 * @note Calling this function while heap tracing is running will reset the heap trace state and continue tracing. 98 * 99 * @param mode Mode for tracing. 100 * - HEAP_TRACE_ALL means all heap allocations and frees are traced. 101 * - HEAP_TRACE_LEAKS means only suspected memory leaks are traced. (When memory is freed, the record is removed from the trace buffer.) 102 * @return 103 * - ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. 104 * - ESP_ERR_INVALID_STATE A non-zero-length buffer has not been set via heap_trace_init_standalone(). 105 * - ESP_OK Tracing is started. 106 */ 107 esp_err_t heap_trace_start(heap_trace_mode_t mode); 108 109 /** 110 * @brief Stop heap tracing. 111 * 112 * @return 113 * - ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. 114 * - ESP_ERR_INVALID_STATE Heap tracing was not in progress. 115 * - ESP_OK Heap tracing stopped.. 116 */ 117 esp_err_t heap_trace_stop(void); 118 119 /** 120 * @brief Resume heap tracing which was previously stopped. 121 * 122 * Unlike heap_trace_start(), this function does not clear the 123 * buffer of any pre-existing trace records. 124 * 125 * The heap trace mode is the same as when heap_trace_start() was 126 * last called (or HEAP_TRACE_ALL if heap_trace_start() was never called). 127 * 128 * @return 129 * - ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. 130 * - ESP_ERR_INVALID_STATE Heap tracing was already started. 131 * - ESP_OK Heap tracing resumed. 132 */ 133 esp_err_t heap_trace_resume(void); 134 135 /** 136 * @brief Return number of records in the heap trace buffer 137 * 138 * It is safe to call this function while heap tracing is running. 139 */ 140 size_t heap_trace_get_count(void); 141 142 /** 143 * @brief Return a raw record from the heap trace buffer 144 * 145 * @note It is safe to call this function while heap tracing is 146 * running, however in HEAP_TRACE_LEAK mode record indexing may 147 * skip entries unless heap tracing is stopped first. 148 * 149 * @param index Index (zero-based) of the record to return. 150 * @param[out] record Record where the heap trace record will be copied. 151 * @return 152 * - ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. 153 * - ESP_ERR_INVALID_STATE Heap tracing was not initialised. 154 * - ESP_ERR_INVALID_ARG Index is out of bounds for current heap trace record count. 155 * - ESP_OK Record returned successfully. 156 */ 157 esp_err_t heap_trace_get(size_t index, heap_trace_record_t *record); 158 159 /** 160 * @brief Dump heap trace record data to stdout 161 * 162 * @note It is safe to call this function while heap tracing is 163 * running, however in HEAP_TRACE_LEAK mode the dump may skip 164 * entries unless heap tracing is stopped first. 165 */ 166 void heap_trace_dump(void); 167 168 /** 169 * @brief Dump heap trace from the memory of the capabilities passed as parameter. 170 * 171 * @param caps Capability(ies) of the memory from which to dump the trace. 172 * Set MALLOC_CAP_INTERNAL to dump heap trace data from internal memory. 173 * Set MALLOC_CAP_SPIRAM to dump heap trace data from PSRAM. 174 * Set both to dump both heap trace data. 175 */ 176 void heap_trace_dump_caps(const uint32_t caps); 177 178 /** 179 * @brief Get summary information about the result of a heap trace 180 * 181 * @note It is safe to call this function while heap tracing is running. 182 */ 183 esp_err_t heap_trace_summary(heap_trace_summary_t *summary); 184 185 #ifdef __cplusplus 186 } 187 #endif 188
