Chapter 2. API Reference
Return
• ESP_OK on success
• ESP_ERR_INVALID_ARG if a parameter is invalid
• ESP_ERR_NO_MEM if no memory to register new heap.
• ESP_ERR_INVALID_SIZE if the memory region is too small to fit a heap
• ESP_FAIL if region overlaps the start and/or end of an existing region
Parameters
• caps: Ordered array of capability masks for the new region, in order of priority. Must have length
SOC_MEMORY_TYPE_NO_PRIOS. Does not need to remain valid after the call returns.
• start: Start address of new region.
• end: End address of new region.
Implementation Notes
Knowledge about the regions of memory in the chip comes from the “soc”component, which contains memory
layout information for the chip, and the different capabilities of each region. Each region’s capabilities are prioritised,
so that (for example) dedicated DRAM and IRAM regions will be used for allocations ahead of the more versatile
D/IRAM regions.
Each contiguous region of memory contains its own memory heap. The heaps are created using the multi_heap
functionality. multi_heap allows any contiguous region of memory to be used as a heap.
The heap capabilities allocator uses knowledge of the memory regions to initialize each individual heap. Allocation
functions in the heap capabilities API will find the most appropriate heap for the allocation (based on desired ca-
pabilities, available space, and preferences for each region’s use) and then calling multi_heap_malloc() or
multi_heap_calloc() for the heap situated in that particular region.
Calling free() involves finding the particular heap corresponding to the freed address, and then calling
multi_heap_free() on that particular multi_heap instance.
API Reference - Multi Heap API
(Note: The multi heap API is used internally by the heap capabilities allocator. Most IDF programs will never need
to call this API directly.)
Header File
• components/heap/include/multi_heap.h
Functions
void *multi_heap_aligned_alloc(multi_heap_handle_t heap, size_t size, size_t alignment)
allocate a chunk of memory with specific alignment
Return pointer to the memory allocated, NULL on failure
Parameters
• heap: Handle to a registered heap.
• size: size in bytes of memory chunk
• alignment: how the memory must be aligned
void *multi_heap_malloc(multi_heap_handle_t heap, size_t size)
malloc() a buffer in a given heap
Semantics are the same as standard malloc(), only the returned buffer will be allocated in the specified heap.
Return Pointer to new memory, or NULL if allocation fails.
Parameters
• heap: Handle to a registered heap.
• size: Size of desired buffer.
Espressif Systems 980
Submit Document Feedback
Release v4.4
To Next Page
Loading...
Need help?
General