freertos: Update ESP-IDF FreeRTOS and FreeRTOS Additions documentation

This commit updates the ESP-IDF FreeRTOS and FreeRTOS Additions to account for
the fact that there are now two implementations of SMP FreeRTOS (i.e., IDF SMP
vs Amazon SMP).

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

@@ -1,9 +1,7 @@
-FreeRTOS Supplemental Features
-==============================
+FreeRTOS (Supplemental Features)
+================================
 
-ESP-IDF uses a modified version of FreeRTOS v10.4.3 that contains significant changes for SMP compatibility (see :doc:`ESP-IDF FreeRTOS SMP Changes<../../api-guides/freertos-smp>`). However, in addition to ESP-IDF FreeRTOS, various features are also provided by ESP-IDF to supplement the features offered by FreeRTOS.
-
-This document describes these supplemental features added to ESP-IDF. This document is split into the following sections:
+ESP-IDF provides multiple features to supplement the features offered by FreeRTOS. These supplemental features are available on all FreeRTOS implementations supported by ESP-IDF (i.e., ESP-IDF FreeRTOS and Amazon SMP FreeRTOS). This document describes these supplemental features and is split into the following sections:
 
 .. contents:: Contents
     :depth: 2
@@ -13,7 +11,7 @@ This document describes these supplemental features added to ESP-IDF. This docum
 Overview
 --------
 
-ESP-IDF adds various new features to supplement the capabilities of ESP-IDF FreeRTOS as follows:
+ESP-IDF adds various new features to supplement the capabilities of FreeRTOS as follows:
 
 - **Ring buffers**: Ring buffers provide a FIFO buffer that can accept entries of arbitrary lengths.
 - **ESP-IDF Tick and Idle Hooks**: ESP-IDF provides multiple custom tick interrupt hooks and idle task hooks that are more numerous and more flexible when compared to FreeRTOS tick and idle hooks.
@@ -26,7 +24,13 @@ ESP-IDF adds various new features to supplement the capabilities of ESP-IDF Free
 Ring Buffers
 ------------
 
-The ESP-IDF FreeRTOS ring buffer is a strictly FIFO buffer that supports arbitrarily sized items. Ring buffers are a more memory efficient alternative to FreeRTOS queues in situations where the size of items is variable. The capacity of a ring buffer is not measured by the number of items it can store, but rather by the amount of memory used for storing items. The ring buffer provides APIs to send an item, or to allocate space for an item in the ring buffer to be filled manually by the user. For efficiency reasons, **items are always retrieved from the ring buffer by reference**. As a result, all retrieved items *must also be returned* to the ring buffer by using :cpp:func:`vRingbufferReturnItem` or :cpp:func:`vRingbufferReturnItemFromISR`, in order for them to be removed from the ring buffer completely. The ring buffers are split into the three following types:
+FreeRTOS provides stream buffers and message buffers as the primary mechanisms to send arbitrarily sized data between tasks and ISRs. However, FreeRTOS stream buffers and message buffers have the following limitations:
+
+- Strictly single sender and single receiver
+- Data is passed by copy
+- Unable to reserve buffer space for a deferred send (i.e., send acquire)
+
+Therefore, ESP-IDF provides a separate ring buffer implementation to address the issues above. ESP-IDF ring buffers are strictly FIFO buffers that supports arbitrarily sized items. Ring buffers are a more memory efficient alternative to FreeRTOS queues in situations where the size of items is variable. The capacity of a ring buffer is not measured by the number of items it can store, but rather by the amount of memory used for storing items. The ring buffer provides APIs to send an item, or to allocate space for an item in the ring buffer to be filled manually by the user. For efficiency reasons, **items are always retrieved from the ring buffer by reference**. As a result, all retrieved items *must also be returned* to the ring buffer by using :cpp:func:`vRingbufferReturnItem` or :cpp:func:`vRingbufferReturnItemFromISR`, in order for them to be removed from the ring buffer completely. The ring buffers are split into the three following types:
 
 **No-Split buffers** will guarantee that an item is stored in contiguous memory and will not attempt to split an item under any circumstances. Use No-Split buffers when items must occupy contiguous memory. *Only this buffer type allows you to get the data item address and write to the item by yourself.* Refer the documentation of the functions :cpp:func:`xRingbufferSendAcquire` and :cpp:func:`xRingbufferSendComplete` for more details.
 
@@ -425,7 +429,7 @@ Vanilla FreeRTOS provides a Thread Local Storage Pointers (TLSP) feature. These
 - get a task's TLSPs by calling :cpp:func:`pvTaskGetThreadLocalStoragePointer` during the task's lifetime.
 - free the memory pointed to by the TLSPs before the task is deleted.
 
-However, there can be instances where users may want the freeing of TLSP memory to be automatic. Therefore, ESP-IDF FreeRTOS provides the additional feature of TLSP deletion callbacks. These user provided deletion callbacks are called automatically when a task is deleted, thus allowing the TLSP memory to be cleaned up without needing to add the cleanup logic explicitly to the code of every task.
+However, there can be instances where users may want the freeing of TLSP memory to be automatic. Therefore, ESP-IDF provides the additional feature of TLSP deletion callbacks. These user provided deletion callbacks are called automatically when a task is deleted, thus allowing the TLSP memory to be cleaned up without needing to add the cleanup logic explicitly to the code of every task.
 
 The TLSP deletion callbacks are set in a similar fashion to the TLSPs themselves.
 

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

@@ -1,30 +1,25 @@
-ESP-IDF FreeRTOS (SMP)
-======================
-
-.. note::
-  This document assumes that the reader has a requisite understanding of Vanilla FreeRTOS (its features, behavior, and API usage). Refer to the `Vanilla FreeRTOS documentation <https://www.freertos.org/index.html>`_ for more details.
-
-This document describes the API and behavioral differences between Vanilla FreeRTOS and ESP-IDF FreeRTOS that were made in order to support Symmetric Multiprocessing (SMP). This document is split into the following parts.
-
-.. contents:: Contents
-  :depth: 3
-
+FreeRTOS (ESP-IDF)
+==================
 
 .. ---------------------------------------------------- Overview -------------------------------------------------------
 
 Overview
 --------
 
-The original FreeRTOS (hereinafter referred to as Vanilla FreeRTOS) is a small and efficient Real Time Operating System supported on many single-core MCUs and SoCs. However, numerous ESP targets (such as the ESP32 and ESP32-S3) are capable of dual core symmetric multiprocessing (SMP). Therefore, the version of FreeRTOS used in ESP-IDF (hereinafter referred to as ESP-IDF FreeRTOS) is a modified version of Vanilla FreeRTOS v10.4.3. Theses modifications allow ESP-IDF FreeRTOS to utilize the dual core SMP capabilities of ESP SoCs.
+The original FreeRTOS (hereinafter referred to as Vanilla FreeRTOS) is a small and efficient Real Time Operating System supported on many single-core MCUs and SoCs. However, to support numerous dual core ESP targets (such as the ESP32 and ESP32-S3), ESP-IDF provides a dual core SMP (Symmetric Multiprocessing) capable implementation of FreeRTOS, (hereinafter referred to as ESP-IDF FreeRTOS).
 
-.. only:: CONFIG_FREERTOS_UNICORE
+ESP-IDF FreeRTOS is based on Vanilla FreeRTOS v10.4.3, but contains significant modifications to both API and kernel behavior in order to support dual core SMP. This document describes the API and behavioral differences between Vanilla FreeRTOS and ESP-IDF FreeRTOS.
 
-  .. note::
-    Some ESP targets (such as the ESP32-S2 and ESP32-C3) are single core SoCs. ESP-IDF applications built for these targets will be built with **ESP-IDF FreeRTOS instead of Vanilla FreeRTOS**. However, the builds for these single core targets will always have the :ref:`CONFIG_FREERTOS_UNICORE` configuration enabled. See :ref:`freertos-smp-single-core` for more details.
+.. note::
+  This document assumes that the reader has a requisite understanding of Vanilla FreeRTOS (its features, behavior, and API usage). Refer to the `Vanilla FreeRTOS documentation <https://www.freertos.org/index.html>`_ for more details.
 
 .. note::
-  - For information regarding features that have been added to ESP-IDF FreeRTOS, see :doc:`ESP-IDF FreeRTOS Additions</api-reference/system/freertos_additions>`.
-  - For a detailed ESP-IDF FreeRTOS API Reference, see :doc:`FreeRTOS API reference<../api-reference/system/freertos>`.
+  ESP-IDF FreeRTOS can be built for single core by enabling the :ref:`CONFIG_FREERTOS_UNICORE` configuration option. ESP targets that are single core will always have the :ref:`CONFIG_FREERTOS_UNICORE` option enabled. However, note that building with :ref:`CONFIG_FREERTOS_UNICORE` enabled does not equate to building with Vanilla FreeRTOS (i.e., some of the behavioral and API changes of ESP-IDF will still be present). For more details, see :ref:`freertos-smp-single-core` for more details.
+
+This document is split into the following parts.
+
+.. contents:: Contents
+  :depth: 2
 
 
 .. -------------------------------------------- Symmetric Multiprocessing ----------------------------------------------
@@ -321,13 +316,6 @@ ESP-IDF FreeRTOS provides the same API, however interrupts will only disabled or
 .. warning::
   Disabling interrupts is a valid method of achieve mutual exclusion in Vanilla FreeRTOS (and single core systems in general). However, in an SMP system, disabling interrupts  is **NOT** a valid method ensuring mutual exclusion. Refer to Critical Sections for more details.
 
-Startup and Termination
-^^^^^^^^^^^^^^^^^^^^^^^
-
-ESP-IDF FreeRTOS **does not** require users to call :cpp:func:`vTaskStartScheduler` to start the scheduler. The startup flow of an ESP-IDF application will already call this automatically. The entry point for user code is a user defined ``void app_main(void)`` function. For more details regarding the startup of ESP-IDF FreeRTOS applications, see :ref:`freertos-applications`.
-
-ESP-IDF FreeRTOS **does not** support scheduler termination. Calling :cpp:func:`vTaskEndScheduler` will simply cause the application to abort.
-
 
 .. ------------------------------------------------ Critical Sections --------------------------------------------------
 
@@ -461,3 +449,45 @@ For multicore targets (such as the ESP32 and ESP32-S3), :ref:`CONFIG_FREERTOS_UN
 
 .. note::
   Users should bear in mind that enabling :ref:`CONFIG_FREERTOS_UNICORE` **is NOT equivalent to running Vanilla FreeRTOS**. The additional API of ESP-IDF FreeRTOS can still be called, and the behavior changes of ESP-IDF FreeRTOS will incur a small amount of overhead even when compiled for only a single core.
+
+.. ------------------------------------------------- API References ----------------------------------------------------
+
+API Reference
+-------------
+
+This section contains documentation of FreeRTOS types, functions, and macros. It is automatically generated from FreeRTOS header files.
+
+Task API
+^^^^^^^^
+
+.. include-build-file:: inc/task.inc
+
+Queue API
+^^^^^^^^^
+
+.. include-build-file:: inc/queue.inc
+
+Semaphore API
+^^^^^^^^^^^^^
+
+.. include-build-file:: inc/semphr.inc
+
+Timer API
+^^^^^^^^^
+
+.. include-build-file:: inc/timers.inc
+
+Event Group API
+^^^^^^^^^^^^^^^
+
+.. include-build-file:: inc/event_groups.inc
+
+Stream Buffer API
+^^^^^^^^^^^^^^^^^
+
+.. include-build-file:: inc/stream_buffer.inc
+
+Message Buffer API
+^^^^^^^^^^^^^^^^^^
+
+.. include-build-file:: inc/message_buffer.inc