heap: add documentation about the function placement in IRAM and its usage in ISR

This commits adds a internal.md file in the heap directory to clarify the idea behind
which functions is placed in IRAM or in flash.

A section in mem_alloc.rst documentation is added to specify which functions from the
heap component API can be used in interrupt handlers.

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.

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
 ------------------------