1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 #pragma once 15 16 #include "sdkconfig.h" 17 #include <stdint.h> 18 #include <esp_err.h> 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 #if !defined(CONFIG_HEAP_TRACING) && !defined(HEAP_TRACE_SRCFILE) 25 #warning "esp_heap_trace.h is included but heap tracing is disabled in menuconfig, functions are no-ops" 26 #endif 27 28 #ifndef CONFIG_HEAP_TRACING_STACK_DEPTH 29 #define CONFIG_HEAP_TRACING_STACK_DEPTH 0 30 #endif 31 32 typedef enum { 33 HEAP_TRACE_ALL, 34 HEAP_TRACE_LEAKS, 35 } heap_trace_mode_t; 36 37 /** 38 * @brief Trace record data type. Stores information about an allocated region of memory. 39 */ 40 typedef struct { 41 uint32_t ccount; ///< CCOUNT of the CPU when the allocation was made. LSB (bit value 1) is the CPU number (0 or 1). 42 void *address; ///< Address which was allocated 43 size_t size; ///< Size of the allocation 44 void *alloced_by[CONFIG_HEAP_TRACING_STACK_DEPTH]; ///< Call stack of the caller which allocated the memory. 45 void *freed_by[CONFIG_HEAP_TRACING_STACK_DEPTH]; ///< Call stack of the caller which freed the memory (all zero if not freed.) 46 } heap_trace_record_t; 47 48 /** 49 * @brief Initialise heap tracing in standalone mode. 50 * 51 * This function must be called before any other heap tracing functions. 52 * 53 * To disable heap tracing and allow the buffer to be freed, stop tracing and then call heap_trace_init_standalone(NULL, 0); 54 * 55 * @param record_buffer Provide a buffer to use for heap trace data. Must remain valid any time heap tracing is enabled, meaning 56 * it must be allocated from internal memory not in PSRAM. 57 * @param num_records Size of the heap trace buffer, as number of record structures. 58 * @return 59 * - ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. 60 * - ESP_ERR_INVALID_STATE Heap tracing is currently in progress. 61 * - ESP_OK Heap tracing initialised successfully. 62 */ 63 esp_err_t heap_trace_init_standalone(heap_trace_record_t *record_buffer, size_t num_records); 64 65 /** 66 * @brief Initialise heap tracing in host-based mode. 67 * 68 * This function must be called before any other heap tracing functions. 69 * 70 * @return 71 * - ESP_ERR_INVALID_STATE Heap tracing is currently in progress. 72 * - ESP_OK Heap tracing initialised successfully. 73 */ 74 esp_err_t heap_trace_init_tohost(void); 75 76 /** 77 * @brief Start heap tracing. All heap allocations & frees will be traced, until heap_trace_stop() is called. 78 * 79 * @note heap_trace_init_standalone() must be called to provide a valid buffer, before this function is called. 80 * 81 * @note Calling this function while heap tracing is running will reset the heap trace state and continue tracing. 82 * 83 * @param mode Mode for tracing. 84 * - HEAP_TRACE_ALL means all heap allocations and frees are traced. 85 * - HEAP_TRACE_LEAKS means only suspected memory leaks are traced. (When memory is freed, the record is removed from the trace buffer.) 86 * @return 87 * - ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. 88 * - ESP_ERR_INVALID_STATE A non-zero-length buffer has not been set via heap_trace_init_standalone(). 89 * - ESP_OK Tracing is started. 90 */ 91 esp_err_t heap_trace_start(heap_trace_mode_t mode); 92 93 /** 94 * @brief Stop heap tracing. 95 * 96 * @return 97 * - ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. 98 * - ESP_ERR_INVALID_STATE Heap tracing was not in progress. 99 * - ESP_OK Heap tracing stopped.. 100 */ 101 esp_err_t heap_trace_stop(void); 102 103 /** 104 * @brief Resume heap tracing which was previously stopped. 105 * 106 * Unlike heap_trace_start(), this function does not clear the 107 * buffer of any pre-existing trace records. 108 * 109 * The heap trace mode is the same as when heap_trace_start() was 110 * last called (or HEAP_TRACE_ALL if heap_trace_start() was never called). 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 already started. 115 * - ESP_OK Heap tracing resumed. 116 */ 117 esp_err_t heap_trace_resume(void); 118 119 /** 120 * @brief Return number of records in the heap trace buffer 121 * 122 * It is safe to call this function while heap tracing is running. 123 */ 124 size_t heap_trace_get_count(void); 125 126 /** 127 * @brief Return a raw record from the heap trace buffer 128 * 129 * @note It is safe to call this function while heap tracing is running, however in HEAP_TRACE_LEAK mode record indexing may 130 * skip entries unless heap tracing is stopped first. 131 * 132 * @param index Index (zero-based) of the record to return. 133 * @param[out] record Record where the heap trace record will be copied. 134 * @return 135 * - ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. 136 * - ESP_ERR_INVALID_STATE Heap tracing was not initialised. 137 * - ESP_ERR_INVALID_ARG Index is out of bounds for current heap trace record count. 138 * - ESP_OK Record returned successfully. 139 */ 140 esp_err_t heap_trace_get(size_t index, heap_trace_record_t *record); 141 142 /** 143 * @brief Dump heap trace record data to stdout 144 * 145 * @note It is safe to call this function while heap tracing is running, however in HEAP_TRACE_LEAK mode the dump may skip 146 * entries unless heap tracing is stopped first. 147 * 148 * 149 */ 150 void heap_trace_dump(void); 151 152 #ifdef __cplusplus 153 } 154 #endif 155
