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 <stdint.h> 17 #include <stdlib.h> 18 #include "multi_heap.h" 19 #include <sdkconfig.h> 20 #include "esp_err.h" 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 /** 27 * @brief Flags to indicate the capabilities of the various memory systems 28 */ 29 #define MALLOC_CAP_EXEC (1<<0) ///< Memory must be able to run executable code 30 #define MALLOC_CAP_32BIT (1<<1) ///< Memory must allow for aligned 32-bit data accesses 31 #define MALLOC_CAP_8BIT (1<<2) ///< Memory must allow for 8/16/...-bit data accesses 32 #define MALLOC_CAP_DMA (1<<3) ///< Memory must be able to accessed by DMA 33 #define MALLOC_CAP_PID2 (1<<4) ///< Memory must be mapped to PID2 memory space (PIDs are not currently used) 34 #define MALLOC_CAP_PID3 (1<<5) ///< Memory must be mapped to PID3 memory space (PIDs are not currently used) 35 #define MALLOC_CAP_PID4 (1<<6) ///< Memory must be mapped to PID4 memory space (PIDs are not currently used) 36 #define MALLOC_CAP_PID5 (1<<7) ///< Memory must be mapped to PID5 memory space (PIDs are not currently used) 37 #define MALLOC_CAP_PID6 (1<<8) ///< Memory must be mapped to PID6 memory space (PIDs are not currently used) 38 #define MALLOC_CAP_PID7 (1<<9) ///< Memory must be mapped to PID7 memory space (PIDs are not currently used) 39 #define MALLOC_CAP_SPIRAM (1<<10) ///< Memory must be in SPI RAM 40 #define MALLOC_CAP_INTERNAL (1<<11) ///< Memory must be internal; specifically it should not disappear when flash/spiram cache is switched off 41 #define MALLOC_CAP_DEFAULT (1<<12) ///< Memory can be returned in a non-capability-specific memory allocation (e.g. malloc(), calloc()) call 42 #define MALLOC_CAP_IRAM_8BIT (1<<13) ///< Memory must be in IRAM and allow unaligned access 43 #define MALLOC_CAP_RETENTION (1<<14) 44 45 #define MALLOC_CAP_INVALID (1<<31) ///< Memory can't be used / list end marker 46 47 /** 48 * @brief callback called when a allocation operation fails, if registered 49 * @param size in bytes of failed allocation 50 * @param caps capabillites requested of failed allocation 51 * @param function_name function which generated the failure 52 */ 53 typedef void (*esp_alloc_failed_hook_t) (size_t size, uint32_t caps, const char * function_name); 54 55 /** 56 * @brief registers a callback function to be invoked if a memory allocation operation fails 57 * @param callback caller defined callback to be invoked 58 * @return ESP_OK if callback was registered. 59 */ 60 esp_err_t heap_caps_register_failed_alloc_callback(esp_alloc_failed_hook_t callback); 61 62 /** 63 * @brief Allocate a chunk of memory which has the given capabilities 64 * 65 * Equivalent semantics to libc malloc(), for capability-aware memory. 66 * 67 * In IDF, ``malloc(p)`` is equivalent to ``heap_caps_malloc(p, MALLOC_CAP_8BIT)``. 68 * 69 * @param size Size, in bytes, of the amount of memory to allocate 70 * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type 71 * of memory to be returned 72 * 73 * @return A pointer to the memory allocated on success, NULL on failure 74 */ 75 void *heap_caps_malloc(size_t size, uint32_t caps); 76 77 78 /** 79 * @brief Free memory previously allocated via heap_caps_malloc() or heap_caps_realloc(). 80 * 81 * Equivalent semantics to libc free(), for capability-aware memory. 82 * 83 * In IDF, ``free(p)`` is equivalent to ``heap_caps_free(p)``. 84 * 85 * @param ptr Pointer to memory previously returned from heap_caps_malloc() or heap_caps_realloc(). Can be NULL. 86 */ 87 void heap_caps_free( void *ptr); 88 89 /** 90 * @brief Reallocate memory previously allocated via heap_caps_malloc() or heap_caps_realloc(). 91 * 92 * Equivalent semantics to libc realloc(), for capability-aware memory. 93 * 94 * In IDF, ``realloc(p, s)`` is equivalent to ``heap_caps_realloc(p, s, MALLOC_CAP_8BIT)``. 95 * 96 * 'caps' parameter can be different to the capabilities that any original 'ptr' was allocated with. In this way, 97 * realloc can be used to "move" a buffer if necessary to ensure it meets a new set of capabilities. 98 * 99 * @param ptr Pointer to previously allocated memory, or NULL for a new allocation. 100 * @param size Size of the new buffer requested, or 0 to free the buffer. 101 * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type 102 * of memory desired for the new allocation. 103 * 104 * @return Pointer to a new buffer of size 'size' with capabilities 'caps', or NULL if allocation failed. 105 */ 106 void *heap_caps_realloc( void *ptr, size_t size, uint32_t caps); 107 108 /** 109 * @brief Allocate a aligned chunk of memory which has the given capabilities 110 * 111 * Equivalent semantics to libc aligned_alloc(), for capability-aware memory. 112 * @param alignment How the pointer received needs to be aligned 113 * must be a power of two 114 * @param size Size, in bytes, of the amount of memory to allocate 115 * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type 116 * of memory to be returned 117 * 118 * @return A pointer to the memory allocated on success, NULL on failure 119 * 120 * 121 */ 122 void *heap_caps_aligned_alloc(size_t alignment, size_t size, uint32_t caps); 123 124 /** 125 * @brief Used to deallocate memory previously allocated with heap_caps_aligned_alloc 126 * 127 * @param ptr Pointer to the memory allocated 128 * @note This function is deprecated, plase consider using heap_caps_free() instead 129 */ 130 void __attribute__((deprecated)) heap_caps_aligned_free(void *ptr); 131 132 /** 133 * @brief Allocate a aligned chunk of memory which has the given capabilities. The initialized value in the memory is set to zero. 134 * 135 * @param alignment How the pointer received needs to be aligned 136 * must be a power of two 137 * @param n Number of continuing chunks of memory to allocate 138 * @param size Size, in bytes, of a chunk of memory to allocate 139 * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type 140 * of memory to be returned 141 * 142 * @return A pointer to the memory allocated on success, NULL on failure 143 * 144 */ 145 void *heap_caps_aligned_calloc(size_t alignment, size_t n, size_t size, uint32_t caps); 146 147 148 /** 149 * @brief Allocate a chunk of memory which has the given capabilities. The initialized value in the memory is set to zero. 150 * 151 * Equivalent semantics to libc calloc(), for capability-aware memory. 152 * 153 * In IDF, ``calloc(p)`` is equivalent to ``heap_caps_calloc(p, MALLOC_CAP_8BIT)``. 154 * 155 * @param n Number of continuing chunks of memory to allocate 156 * @param size Size, in bytes, of a chunk of memory to allocate 157 * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type 158 * of memory to be returned 159 * 160 * @return A pointer to the memory allocated on success, NULL on failure 161 */ 162 void *heap_caps_calloc(size_t n, size_t size, uint32_t caps); 163 164 /** 165 * @brief Get the total size of all the regions that have the given capabilities 166 * 167 * This function takes all regions capable of having the given capabilities allocated in them 168 * and adds up the total space they have. 169 * 170 * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type 171 * of memory 172 * 173 * @return total size in bytes 174 */ 175 176 size_t heap_caps_get_total_size(uint32_t caps); 177 178 /** 179 * @brief Get the total free size of all the regions that have the given capabilities 180 * 181 * This function takes all regions capable of having the given capabilities allocated in them 182 * and adds up the free space they have. 183 * 184 * Note that because of heap fragmentation it is probably not possible to allocate a single block of memory 185 * of this size. Use heap_caps_get_largest_free_block() for this purpose. 186 187 * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type 188 * of memory 189 * 190 * @return Amount of free bytes in the regions 191 */ 192 size_t heap_caps_get_free_size( uint32_t caps ); 193 194 195 /** 196 * @brief Get the total minimum free memory of all regions with the given capabilities 197 * 198 * This adds all the low water marks of the regions capable of delivering the memory 199 * with the given capabilities. 200 * 201 * Note the result may be less than the global all-time minimum available heap of this kind, as "low water marks" are 202 * tracked per-region. Individual regions' heaps may have reached their "low water marks" at different points in time. However 203 * this result still gives a "worst case" indication for all-time minimum free heap. 204 * 205 * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type 206 * of memory 207 * 208 * @return Amount of free bytes in the regions 209 */ 210 size_t heap_caps_get_minimum_free_size( uint32_t caps ); 211 212 /** 213 * @brief Get the largest free block of memory able to be allocated with the given capabilities. 214 * 215 * Returns the largest value of ``s`` for which ``heap_caps_malloc(s, caps)`` will succeed. 216 * 217 * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type 218 * of memory 219 * 220 * @return Size of largest free block in bytes. 221 */ 222 size_t heap_caps_get_largest_free_block( uint32_t caps ); 223 224 225 /** 226 * @brief Get heap info for all regions with the given capabilities. 227 * 228 * Calls multi_heap_info() on all heaps which share the given capabilities. The information returned is an aggregate 229 * across all matching heaps. The meanings of fields are the same as defined for multi_heap_info_t, except that 230 * ``minimum_free_bytes`` has the same caveats described in heap_caps_get_minimum_free_size(). 231 * 232 * @param info Pointer to a structure which will be filled with relevant 233 * heap metadata. 234 * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type 235 * of memory 236 * 237 */ 238 void heap_caps_get_info( multi_heap_info_t *info, uint32_t caps ); 239 240 241 /** 242 * @brief Print a summary of all memory with the given capabilities. 243 * 244 * Calls multi_heap_info on all heaps which share the given capabilities, and 245 * prints a two-line summary for each, then a total summary. 246 * 247 * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type 248 * of memory 249 * 250 */ 251 void heap_caps_print_heap_info( uint32_t caps ); 252 253 /** 254 * @brief Check integrity of all heap memory in the system. 255 * 256 * Calls multi_heap_check on all heaps. Optionally print errors if heaps are corrupt. 257 * 258 * Calling this function is equivalent to calling heap_caps_check_integrity 259 * with the caps argument set to MALLOC_CAP_INVALID. 260 * 261 * @param print_errors Print specific errors if heap corruption is found. 262 * 263 * @return True if all heaps are valid, False if at least one heap is corrupt. 264 */ 265 bool heap_caps_check_integrity_all(bool print_errors); 266 267 /** 268 * @brief Check integrity of all heaps with the given capabilities. 269 * 270 * Calls multi_heap_check on all heaps which share the given capabilities. Optionally 271 * print errors if the heaps are corrupt. 272 * 273 * See also heap_caps_check_integrity_all to check all heap memory 274 * in the system and heap_caps_check_integrity_addr to check memory 275 * around a single address. 276 * 277 * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type 278 * of memory 279 * @param print_errors Print specific errors if heap corruption is found. 280 * 281 * @return True if all heaps are valid, False if at least one heap is corrupt. 282 */ 283 bool heap_caps_check_integrity(uint32_t caps, bool print_errors); 284 285 /** 286 * @brief Check integrity of heap memory around a given address. 287 * 288 * This function can be used to check the integrity of a single region of heap memory, 289 * which contains the given address. 290 * 291 * This can be useful if debugging heap integrity for corruption at a known address, 292 * as it has a lower overhead than checking all heap regions. Note that if the corrupt 293 * address moves around between runs (due to timing or other factors) then this approach 294 * won't work and you should call heap_caps_check_integrity or 295 * heap_caps_check_integrity_all instead. 296 * 297 * @note The entire heap region around the address is checked, not only the adjacent 298 * heap blocks. 299 * 300 * @param addr Address in memory. Check for corruption in region containing this address. 301 * @param print_errors Print specific errors if heap corruption is found. 302 * 303 * @return True if the heap containing the specified address is valid, 304 * False if at least one heap is corrupt or the address doesn't belong to a heap region. 305 */ 306 bool heap_caps_check_integrity_addr(intptr_t addr, bool print_errors); 307 308 /** 309 * @brief Enable malloc() in external memory and set limit below which 310 * malloc() attempts are placed in internal memory. 311 * 312 * When external memory is in use, the allocation strategy is to initially try to 313 * satisfy smaller allocation requests with internal memory and larger requests 314 * with external memory. This sets the limit between the two, as well as generally 315 * enabling allocation in external memory. 316 * 317 * @param limit Limit, in bytes. 318 */ 319 void heap_caps_malloc_extmem_enable(size_t limit); 320 321 /** 322 * @brief Allocate a chunk of memory as preference in decreasing order. 323 * 324 * @attention The variable parameters are bitwise OR of MALLOC_CAP_* flags indicating the type of memory. 325 * This API prefers to allocate memory with the first parameter. If failed, allocate memory with 326 * the next parameter. It will try in this order until allocating a chunk of memory successfully 327 * or fail to allocate memories with any of the parameters. 328 * 329 * @param size Size, in bytes, of the amount of memory to allocate 330 * @param num Number of variable paramters 331 * 332 * @return A pointer to the memory allocated on success, NULL on failure 333 */ 334 void *heap_caps_malloc_prefer( size_t size, size_t num, ... ); 335 336 /** 337 * @brief Allocate a chunk of memory as preference in decreasing order. 338 * 339 * @param ptr Pointer to previously allocated memory, or NULL for a new allocation. 340 * @param size Size of the new buffer requested, or 0 to free the buffer. 341 * @param num Number of variable paramters 342 * 343 * @return Pointer to a new buffer of size 'size', or NULL if allocation failed. 344 */ 345 void *heap_caps_realloc_prefer( void *ptr, size_t size, size_t num, ... ); 346 347 /** 348 * @brief Allocate a chunk of memory as preference in decreasing order. 349 * 350 * @param n Number of continuing chunks of memory to allocate 351 * @param size Size, in bytes, of a chunk of memory to allocate 352 * @param num Number of variable paramters 353 * 354 * @return A pointer to the memory allocated on success, NULL on failure 355 */ 356 void *heap_caps_calloc_prefer( size_t n, size_t size, size_t num, ... ); 357 358 /** 359 * @brief Dump the full structure of all heaps with matching capabilities. 360 * 361 * Prints a large amount of output to serial (because of locking limitations, 362 * the output bypasses stdout/stderr). For each (variable sized) block 363 * in each matching heap, the following output is printed on a single line: 364 * 365 * - Block address (the data buffer returned by malloc is 4 bytes after this 366 * if heap debugging is set to Basic, or 8 bytes otherwise). 367 * - Data size (the data size may be larger than the size requested by malloc, 368 * either due to heap fragmentation or because of heap debugging level). 369 * - Address of next block in the heap. 370 * - If the block is free, the address of the next free block is also printed. 371 * 372 * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type 373 * of memory 374 */ 375 void heap_caps_dump(uint32_t caps); 376 377 /** 378 * @brief Dump the full structure of all heaps. 379 * 380 * Covers all registered heaps. Prints a large amount of output to serial. 381 * 382 * Output is the same as for heap_caps_dump. 383 * 384 */ 385 void heap_caps_dump_all(void); 386 387 /** 388 * @brief Return the size that a particular pointer was allocated with. 389 * 390 * @param ptr Pointer to currently allocated heap memory. Must be a pointer value previously 391 * returned by heap_caps_malloc,malloc,calloc, etc. and not yet freed. 392 * 393 * @note The app will crash with an assertion failure if the pointer is not valid. 394 * 395 * @return Size of the memory allocated at this block. 396 * 397 */ 398 size_t heap_caps_get_allocated_size( void *ptr ); 399 400 #ifdef __cplusplus 401 } 402 #endif 403