Chapter 2. API Reference
Thread Safety Heap functions are thread safe, meaning they can be called from different tasks simultaneously
without any limitations.
It is technically possible to call malloc, free, and related functions from interrupt handler (ISR) context. However
this is not recommended, as heap function calls may delay other interrupts. It is strongly recommended to refactor
applications so that any buffers used by an ISR are pre-allocated outside of the ISR. Support for calling heap functions
from ISRs may be removed in a future update.
Heap Tracing & Debugging
The following features are documented on the Heap Memory Debugging page:
• Heap Information (free space, etc.)
• Heap Corruption Detection
• Heap Tracing (memory leak detection, monitoring, etc.)
API Reference - Initialisation
Header File
• components/heap/include/esp_heap_caps_init.h
Functions
void heap_caps_init(void)
Initialize the capability-aware heap allocator.
This is called once in the IDF startup code. Do not call it at other times.
void heap_caps_enable_nonos_stack_heaps(void)
Enable heap(s) in memory regions where the startup stacks are located.
On startup, the pro/app CPUs have a certain memory region they use as stack, so we cannot do allocations
in the regions these stack frames are. When FreeRTOS is completely started, they do not use that memory
anymore and heap(s) there can be enabled.
esp_err_t heap_caps_add_region(intptr_t start, intptr_t end)
Add a region of memory to the collection of heaps at runtime.
Most memory regions are defined in soc_memory_layout.c for the SoC, and are registered via heap_caps_init().
Some regions can’t be used immediately and are later enabled via heap_caps_enable_nonos_stack_heaps().
Call this function to add a region of memory to the heap at some later time.
This function does not consider any of the “reserved”regions or other data in soc_memory_layout, caller
needs to consider this themselves.
All memory within the region specified by start & end parameters must be otherwise unused.
The capabilities of the newly registered memory will be determined by the start address, as looked up in the
regions specified in soc_memory_layout.c.
Use heap_caps_add_region_with_caps() to register a region with custom capabilities.
Return ESP_OK on success, ESP_ERR_INVALID_ARG if a parameter is invalid,
ESP_ERR_NOT_FOUND if the specified start address doesn’t reside in a known region, or
any error returned by heap_caps_add_region_with_caps().
Parameters
• start: Start address of new region.
• end: End address of new region.
esp_err_t heap_caps_add_region_with_caps(const uint32_t caps[], intptr_t start, intptr_t end)
Add a region of memory to the collection of heaps at runtime, with custom capabilities.
Similar to heap_caps_add_region(), only custom memory capabilities are specified by the caller.
Espressif Systems 979
Submit Document Feedback
Release v4.4
To Next Page
Loading...