Merge branch 'feature/freertos_add_create_task_with_caps' into 'master'

FreeRTOS: Add xTaskCreateWithCaps()

Closes IDFGH-9922

See merge request espressif/esp-idf!23191

docs/en/api-reference/system/freertos.rst

@@ -118,10 +118,15 @@ FreeRTOS Additions
 
 ESP-IDF provides some supplemental features to FreeRTOS such as Ring Buffers, ESP-IDF style Tick and Idle Hooks, and TLSP deletion callbacks. See :doc:`freertos_additions` for more details.
 
+.. _freertos-heap:
+
 FreeRTOS Heap
 -------------
 
 Vanilla FreeRTOS provides its own `selection of heap implementations <https://www.freertos.org/a00111.html>`_. However, ESP-IDF already implements its own heap (see :doc:`/api-reference/system/mem_alloc`), thus ESP-IDF does not make use of the heap implementations provided by Vanilla FreeRTOS. All FreeRTOS ports in ESP-IDF map FreeRTOS memory allocation/free calls (e.g., ``pvPortMalloc()`` and ``pvPortFree()``) to ESP-IDF heap API (i.e., :cpp:func:`heap_caps_malloc` and :cpp:func:`heap_caps_free`). However, the FreeRTOS ports ensure that all dynamic memory allocated by FreeRTOS is placed in internal memory.
 
 .. note::
-    If users wish to place FreeRTOS objects in external memory, users should allocate those objects manually using :cpp:func:`heap_caps_malloc`, then create the object using the object's ``...CreateStatic()`` function.
+    If users wish to place FreeRTOS tasks/objects in external memory, users can use the following methods:
+
+    - Allocate the task/object using one of the ``...CreateWithCaps()`` API such as :cpp:func:`xTaskCreateWithCaps` and :cpp:func:`xQueueCreateWithCaps` (see :ref:`freertos-idf-additional-api` for more details).
+    - Manually allocate external memory for those objects using :cpp:func:`heap_caps_malloc`, then create the objects from the allocated memory using on of the ``...CreateStatic()`` FreeRTOS functions.

docs/en/api-reference/system/freertos_additions.rst

@@ -432,6 +432,8 @@ When implementing TLSP callbacks, users should note the following:
 
 .. ----------------------------------------------- IDF Additional API --------------------------------------------------
 
+.. _freertos-idf-additional-api:
+
 IDF Additional API
 ------------------
 

docs/en/migration-guides/release-5.x/5.1/system.rst

@@ -3,6 +3,31 @@ System
 
 :link_to_translation:`zh_CN:[中文]`
 
+FreeRTOS
+--------
+
+.. only:: SOC_SPIRAM_SUPPORTED
+
+    Dynamic Memory Allocation
+    ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    Previously, most FreeRTOS dynamic allocation would eventually call to ``malloc()``. Thus, if an application was configured to allow ``malloc()`` to allocate from external RAM (i.e., :ref:`CONFIG_SPIRAM_USE` was set ``CONFIG_SPIRAM_USE_MALLOC``), then there was a possibility that FreeRTOS could allocate dynamic memory from external RAM, with the exact placement being decided by the heap allocator.
+
+    .. note::
+        Dynamic memory allocation for tasks (which are likely to consume the most memory) were an exception to the scenario above. FreeRTOS would use a separate memory allocation function to guarantee that dynamic memory allocate for a task was always placed in internal RAM.
+
+    Allowing FreeRTOS objects (such as queues and semaphores) to be placed in external RAM becomes an issue if those objects are accessed while the cache is disabled (such as during SPI Flash write operations) and would lead to a cache access errors (see :doc:`Fatal Errors </api-guides/fatal-errors>` for more details).
+
+    Therefore, FreeRTOS has been updated to always use internal memory (i.e., DRAM) for dynamic memory allocation. Calling FreeRTOS creation functions (e.g., :cpp:func:`xTaskCreate`, :cpp:func:`xQueueCreate`) will guarantee that the memory allocated for those tasks/objects is from internal memory (see :ref:`freertos-heap` for more details).
+
+    .. warning::
+        For users that previously relied on :ref:`CONFIG_SPIRAM_USE` to place FreeRTOS objects into external memory, this change will lead to increased usage of internal memory due the FreeRTOS objects now being allocated there.
+
+    Users that want to place a FreeRTOS task/object into external memory will now need to do so explicitly. Users can use one of the following methods:
+
+    - Allocate the task/object using one of the ``...CreateWithCaps()`` API such as :cpp:func:`xTaskCreateWithCaps` and :cpp:func:`xQueueCreateWithCaps` (see :ref:`freertos-idf-additional-api` for more details).
+    - Manually allocate external memory for those objects using :cpp:func:`heap_caps_malloc`, then create the objects from the allocated memory using one of the ``...CreateStatic()`` FreeRTOS functions.
+
 Power Management
 -----------------------