Merge branch 'feature/esp32s31_pie_coproc_old_commit' into 'master'

feat: add support for PIE coprocessor on the ESP32-S31

Closes IDF-14867 and IDF-14661

See merge request espressif/esp-idf!45851

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

@@ -432,6 +432,40 @@ Misc
         ESP targets that contain an FPU do not support hardware acceleration for double precision floating point arithmetic (``double``). Instead, ``double`` is implemented via software, hence the behavioral restrictions regarding the ``float`` type do not apply to ``double``. Note that due to the lack of hardware acceleration, ``double`` operations may consume significantly more CPU time in comparison to ``float``.
 
 
+.. only:: SOC_CPU_HAS_PIE
+
+    PIE / AI Coprocessor Usage
+    ^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    Like the Floating Point Unit (FPU), IDF FreeRTOS implements **Lazy Context Switching** for the PIE coprocessor. On a context switch, PIE registers remain untouched until a task executes a PIE instruction. Once a task uses the PIE coprocessor, it is **pinned to the current core**.
+
+    .. only:: esp32s31
+
+        .. note::
+
+            On ESP32-S31, the PIE coprocessor is available **only on Core 1**. If a task executes a PIE instruction while running on Core 0, IDF FreeRTOS migrates the task to Core 1 and pins it there. This migration **overrides** any existing core affinity.
+            Because of this migration, tasks must **not** use the PIE coprocessor within a critical section or ISR, as doing so will cause a runtime abort.
+
+
+.. only:: SOC_CPU_HAS_HWLOOP
+
+    Hardware Loop (HWLP) Usage
+    ^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    In IDF FreeRTOS, the Hardware Loop (HWLP) unit is handled differently from other coprocessors: it does **not** use Lazy Context Switching.
+
+    When a task uses the HWLP and a context switch occurs, the HWLP registers are saved immediately during the interrupt entry path. Later, if the same task is switched back in, all HWLP registers are restored immediately.
+
+    In practice, this means that any task that has ever used the HWLP will always have an additional overhead on both context switch out and switch in.
+
+.. only:: SOC_CPU_HAS_DSP
+
+    DSP Coprocessor Usage
+    ^^^^^^^^^^^^^^^^^^^^^
+
+    On targets that feature the DSP coprocessor, context switching follows the same lazy scheme as the FPU: the coprocessor state is not saved until another task on the same core uses it or the task is switched to another core. When a task uses the DSP coprocessor, IDF FreeRTOS will automatically **pin the task to the current core** it is running on. The DSP coprocessor must not be used from within an interrupt context.
+
+
 .. -------------------------------------------------- Single Core  -----------------------------------------------------
 
 .. _freertos-idf-single-core: