Espressif ESP32-S2 Programming Manual page 988

Chapter 2. API Reference
When external memory is in use, the allocation strategy is to initially try to satisfy smaller allocation requests
with internal memory and larger requests with external memory. This sets the limit between the two, as well
as generally enabling allocation in external memory.
Parameters
• limit: Limit, in bytes.
void *heap_caps_malloc_prefer(size_t size, size_t num, ...)
Allocate a chunk of memory as preference in decreasing order.
Attention The variable parameters are bitwise OR of MALLOC_CAP_* flags indicating the type of memory.
This API prefers to allocate memory with the first parameter. If failed, allocate memory with the next
parameter. It will try in this order until allocating a chunk of memory successfully or fail to allocate
memories with any of the parameters.
Return A pointer to the memory allocated on success, NULL on failure
Parameters
• size: Size, in bytes, of the amount of memory to allocate
• num: Number of variable paramters
void *heap_caps_realloc_prefer(void *ptr, size_t size, size_t num, ...)
Allocate a chunk of memory as preference in decreasing order.
Return Pointer to a new buffer of size 'size', or NULL if allocation failed.
Parameters
• ptr: Pointer to previously allocated memory, or NULL for a new allocation.
• size: Size of the new buffer requested, or 0 to free the buffer.
• num: Number of variable paramters
void *heap_caps_calloc_prefer(size_t n, size_t size, size_t num, ...)
Allocate a chunk of memory as preference in decreasing order.
Return A pointer to the memory allocated on success, NULL on failure
Parameters
• n: Number of continuing chunks of memory to allocate
• size: Size, in bytes, of a chunk of memory to allocate
• num: Number of variable paramters
void heap_caps_dump(uint32_t caps)
Dump the full structure of all heaps with matching capabilities.
Prints a large amount of output to serial (because of locking limitations, the output bypasses stdout/stderr).
For each (variable sized) block in each matching heap, the following output is printed on a single line:
• Block address (the data buffer returned by malloc is 4 bytes after this if heap debugging is set to Basic,
or 8 bytes otherwise).
• Data size (the data size may be larger than the size requested by malloc, either due to heap fragmentation
or because of heap debugging level).
• Address of next block in the heap.
• If the block is free, the address of the next free block is also printed.
Parameters
• caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory
void heap_caps_dump_all(void)
Dump the full structure of all heaps.
Covers all registered heaps. Prints a large amount of output to serial.
Output is the same as for heap_caps_dump.
size_t heap_caps_get_allocated_size(void *ptr)
Return the size that a particular pointer was allocated with.
Note The app will crash with an assertion failure if the pointer is not valid.
Return Size of the memory allocated at this block.
Parameters
Espressif Systems 977
Submit Document Feedback
Release v4.4