diff --git a/components/heap/internals.md b/components/heap/internals.md new file mode 100644 index 0000000000..d007f1d4c8 --- /dev/null +++ b/components/heap/internals.md @@ -0,0 +1,9 @@ +# Function placement in IRAM section + +The heap component is compiled and linked in a way that minimizes the utilization of the IRAM section of memory without impacting the performance of its core functionalities. For this reason, the heap component API provided through [esp_heap_caps.h](./include/esp_heap_caps.h) and [esp_heap_caps_init.h](./include/esp_heap_caps_init.h) can be sorted into two sets of functions. + +1. The performance related functions placed into the IRAM by using the `IRAM_ATTR` defined in [esp_attr.h](./../../components/esp_common/include/esp_attr.h) (e.g., `heap_caps_malloc`, `heap_caps_free`, `heap_caps_realloc`, etc.) + +2. The functions that does not require the best of performance placed in the flash (e.g., `heap_caps_print_heap_info`, `heap_caps_dump`, `heap_caps_dump_all`, etc.) + +With that in mind, all the functions defined in [multi_heap.c](./multi_heap.c), [multi_heap_poisoning.c](./multi_heap_poisoning.c) and [tlsf.c](./tlsf/tlsf.c) that are directly or indirectly called from one of the heap component API functions placed in IRAM have to also be placed in IRAM. Symmetrically, the functions directly or indirectly called from one of the heap component API functions placed in flash will also be placed in flash. \ No newline at end of file diff --git a/docs/en/api-reference/system/mem_alloc.rst b/docs/en/api-reference/system/mem_alloc.rst index 8ee2bcb808..7aa5a2635f 100644 --- a/docs/en/api-reference/system/mem_alloc.rst +++ b/docs/en/api-reference/system/mem_alloc.rst @@ -129,7 +129,28 @@ 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. +It is technically possible to call ``malloc``, ``free``, and related functions from interrupt handler (ISR) context (see :ref:`calling-heap-related-functions-from-isr`). 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. + +.. _calling-heap-related-functions-from-isr: + +Calling heap related functions from ISR +--------------------------------------- + +The following functions from the heap component can be called form interrupt handler (ISR): + +* :cpp:func:`heap_caps_malloc` +* :cpp:func:`heap_caps_malloc_default` +* :cpp:func:`heap_caps_realloc_default` +* :cpp:func:`heap_caps_malloc_prefer` +* :cpp:func:`heap_caps_realloc_prefer` +* :cpp:func:`heap_caps_calloc_prefer` +* :cpp:func:`heap_caps_free` +* :cpp:func:`heap_caps_realloc` +* :cpp:func:`heap_caps_calloc` +* :cpp:func:`heap_caps_aligned_alloc` +* :cpp:func:`heap_caps_aligned_free` + +Note however this practice is strongly discouraged. Heap Tracing & Debugging ------------------------