Merge branch 'docs/freertos_doc_organization' into 'master'

Docs: Update FreeRTOS documentation organization for IDF and Amazon SMP FreeRTOS See merge request espressif/esp-idf!22264
espressif · Feb 15, 2023 · c94e0a9 · c94e0a9
2 parents beb1c08 + 3b638b1
commit c94e0a9
Show file tree

Hide file tree

Showing 10 changed files with 153 additions and 128 deletions.
diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst
@@ -17,7 +17,6 @@ API Guides
    :SOC_USB_OTG_SUPPORTED: dfu
    error-handling
    :SOC_BLE_MESH_SUPPORTED: esp-ble-mesh/ble-mesh-index
-   freertos-smp
    :SOC_WIFI_MESH_SUPPORT: esp-wifi-mesh
    event-handling
    :SOC_SPIRAM_SUPPORTED: external-ram

diff --git a/docs/en/api-reference/system/freertos.rst b/docs/en/api-reference/system/freertos.rst
@@ -1,127 +1,117 @@
-FreeRTOS
-========
+FreeRTOS (Overview)
+===================
 
 Overview
 --------
 
-This section contains documentation of FreeRTOS types, functions, and macros. It is automatically generated from FreeRTOS header files.
+FreeRTOS is an open source real-time operating system kernel that acts as the operating system for ESP-IDF applications and is integrated into ESP-IDF as a component. The FreeRTOS component in ESP-IDF contains ports of the FreeRTOS kernel for all the CPU architectures used by ESP targets (i.e., Xtensa and RISC-V). Furthermore, ESP-IDF provides different implementations of FreeRTOS in order to support SMP (Symmetric Multiprocessing) on multi-core ESP targets. This document provides an overview of the FreeRTOS component, the FreeRTOS implementations offered by ESP-IDF, and the common aspects across all implementations.
 
-.. note::
-    ESP-IDF FreeRTOS is based on Vanilla FreeRTOS v10.4.3
+Implementations
+---------------
 
-- For more information about the SMP changes of ESP-IDF FreeRTOS, see :doc:`/api-guides/freertos-smp`
-- For more information about the features added to ESP-IDF FreeRTOS, see :doc:`/api-reference/system/freertos_additions`.
+The `official FreeRTOS <https://www.freertos.org/index.html>`_ (henceforth referred to as Vanilla FreeRTOS) is a single-core RTOS. In order to support the various multi-core ESP targets, ESP-IDF supports different FreeRTOS implementations, namely **ESP-IDF FreeRTOS** and **Amazon SMP FreeRTOS**.
 
-Configuration
--------------
+ESP-IDF FreeRTOS
+^^^^^^^^^^^^^^^^
 
-Vanilla FreeRTOS allows ports and applications to configure the kernel by adding various ``#define config...`` macros to ``FreeRTOSConfig.h``. Through these macros, the kernel's scheduling behavior and various kernel features can be enabled or disabled. **However, in ESP-IDF FreeRTOS, the ``FreeRTOSConfig.h`` file is considered a private and must not be modified by users**. Any FreeRTOS configuration that is exposed to the user will be done so via menuconfig.
+ESP-IDF FreeRTOS is a FreeRTOS implementation based on Vanilla FreeRTOS v10.4.3, but contains significant modifications to support SMP. ESP-IDF FreeRTOS only supports two cores at most (i.e., dual core SMP), but is more optimized for this scenario by design. For more details regarding ESP-IDF FreeRTOS and its modifications, please refer to the :doc:`freertos_idf` document.
 
-ESP-IDF FreeRTOS can be configured in the project configuration menu (``idf.py menuconfig``) under ``Component Config/FreeRTOS``. The following section highlights some of the ESP-IDF FreeRTOS configuration options. For a full list of ESP-IDF FreeRTOS configurations, see :doc:`/api-reference/kconfig`
+.. note::
+    ESP-IDF FreeRTOS is currently the default FreeRTOS implementation for ESP-IDF.
 
-- :ref:`CONFIG_FREERTOS_UNICORE` will run ESP-IDF FreeRTOS only on CPU0. Note that this is **not equivalent to running Vanilla FreeRTOS**. Furthermore, this option may affect behavior of components other than :component:`freertos`. For more details regarding the effects of running ESP-IDF FreeRTOS on a single core, refer to :ref:`freertos-smp-single-core`. Alternatively, users can also search for occurrences of ``CONFIG_FREERTOS_UNICORE`` in the ESP-IDF components.
+Amazon SMP FreeRTOS
+^^^^^^^^^^^^^^^^^^^
 
-- :ref:`CONFIG_FREERTOS_TASK_FUNCTION_WRAPPER` will enclose all task functions within a wrapper function. In the case that a task function mistakenly returns (i.e. does not call :cpp:func:`vTaskDelete`), the call flow will return to the wrapper function. The wrapper function will then log an error and abort the application, as illustrated below::
+Amazon SMP FreeRTOS is an SMP implementation of FreeRTOS that is officially supported by Amazon. Amazon SMP FreeRTOS is able to support N-cores (i.e., more than two cores). Amazon SMP FreeRTOS can be enabled via the :ref:`CONFIG_FREERTOS_SMP` option. For more details regarding Amazon SMP FreeRTOS, please refer to the `official Amazon SMP FreeRTOS documentation <https://freertos.org/symmetric-multiprocessing-introduction.html>`_.
 
-    E (25) FreeRTOS: FreeRTOS task should not return. Aborting now!
-    abort() was called at PC 0x40085c53 on core 0
+.. warning::
+    The Amazon SMP FreeRTOS implementation (and its port in ESP-IDF) are currently in experimental/beta state. Therefore, significant behavioral changes and breaking API changes can occur.
 
-.. only:: CONFIG_FREERTOS_UNICORE
-
-    .. note::
-        As {IDF_TARGET_NAME} is a single core SoC, the :ref:`CONFIG_FREERTOS_UNICORE` configuration is always set.
+Configuration
+-------------
 
+Kernel Configuration
+^^^^^^^^^^^^^^^^^^^^
 
-.. _freertos-applications:
+Vanilla FreeRTOS requires that ports and applications configure the kernel by adding various ``#define config...`` macros to ``FreeRTOSConfig.h``. Vanilla FreeRTOS supports a list of kernel configuration options which allow various kernel behaviors and features to be enabled or disabled.
 
-ESP-IDF FreeRTOS Applications
------------------------------
+**However, for all FreeRTOS ports in ESP-IDF, the ``FreeRTOSConfig.h`` file is considered private and must not be modified by users**. A large number of kernel configuration options in ``FreeRTOSConfig.h`` are hard coded as they are either required or not supported in ESP-IDF. All kernel configuration options that are configurable by the user will be exposed via menuconfig under ``Component Config/FreeRTOS/Kernel``.
 
-Unlike Vanilla FreeRTOS, users must not call :cpp:func:`vTaskStartScheduler`. Instead, ESP-IDF FreeRTOS is started automatically. The entry point is a user defined ``void app_main(void)`` function.
+For the full list of user configurable kernel options, see :doc:`/api-reference/kconfig`. The list below highlights some commonly used kernel configuration options:
 
-- Typically, users would spawn the rest of their applications task from ``app_main``.
-- The ``app_main`` function is allowed to return at any point (i.e., before the application terminates).
-- The ``app_main`` function is called from the ``main`` task. 
-
-The ``main`` task is one of multiple tasks that are automatically spawned by ESP-IDF during startup. These tasks are:
-
-.. only:: not CONFIG_FREERTOS_UNICORE
-
-    .. list-table:: List of Tasks Created During Startup
-        :widths: 25 25 5 50
-        :header-rows: 1
-
-        * - Task Name
-          - Affinity
-          - Priority
-          - Description
-        * - Main Task (``main``)
-          - CPU0
-          - 1
-          - Task that simply calls ``app_main``. This task will self delete when ``app_main`` returns
-        * - Idle Tasks (``IDLEx``)
-          - CPU0 and CPU1
-          - 0
-          - Idle tasks created for (and pinned to) each CPU
-        * - IPC Tasks (``ipcx``)
-          - CPU0 and CPU1
-          - 24
-          - IPC tasks created for (and pinned to) each CPU. IPC tasks are used to implement the Inter-processor Call (IPC) feature. See :doc:`/api-reference/system/ipc` for more details.
+- :ref:`CONFIG_FREERTOS_UNICORE` will run FreeRTOS only on CPU0. Note that this is **not equivalent to running Vanilla FreeRTOS**. Furthermore, this option may affect behavior of components other than :component:`freertos`. For more details regarding the effects of running FreeRTOS on a single core, refer to :ref:`freertos-smp-single-core` (if using ESP-IDF FreeRTOS) or the official Amazon SMP FreeRTOS documentation. Alternatively, users can also search for occurrences of ``CONFIG_FREERTOS_UNICORE`` in the ESP-IDF components.
 
 .. only:: CONFIG_FREERTOS_UNICORE
 
-    .. list-table:: List of Tasks Created During Startup
-        :widths: 25 25 5 50
-        :header-rows: 1
-
-        * - Task Name
-          - Affinity
-          - Priority
-          - Description
-        * - Main Task (``main``)
-          - CPU0
-          - 1
-          - Task that simply calls ``app_main``. This task will self delete when ``app_main`` returns
-        * - Idle Tasks (``IDLE``)
-          - CPU0
-          - 0
-          - Idle task created for CPU0
-
     .. note::
+        As {IDF_TARGET_NAME} is a single core SoC, the :ref:`CONFIG_FREERTOS_UNICORE` configuration is always set.
 
-        Low priority numbers denote low priority tasks.
-
-Task API
---------
-
-.. include-build-file:: inc/task.inc
-
-Queue API
----------
-
-.. include-build-file:: inc/queue.inc
+- :ref:`CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY` enables backward compatibility with some FreeRTOS macros/types/functions that were deprecated from v8.0 onwards.
 
-Semaphore API
--------------
+Port Configuration
+^^^^^^^^^^^^^^^^^^
 
-.. include-build-file:: inc/semphr.inc
+All other FreeRTOS related configuration options that are not part of the kernel configuration are exposed via menuconfig under ``Component Config/FreeRTOS/Port``. These options configure aspects such as:
 
-Timer API
----------
+- The FreeRTOS ports themselves (e.g., tick timer selection, ISR stack size)
+- Additional features added to the FreeRTOS implementation or ports
 
-.. include-build-file:: inc/timers.inc
+Using FreeRTOS
+--------------
 
-Event Group API
----------------
+Application Entry Point
+^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include-build-file:: inc/event_groups.inc
+Unlike Vanilla FreeRTOS, users of FreeRTOS in ESP-IDF **must never call** :cpp:func:`vTaskStartScheduler` and :cpp:func:`vTaskEndScheduler`. Instead, ESP-IDF will start FreeRTOS automatically. Users must define a ``void app_main(void)`` function which acts as the entry point for user's application and is automatically called on ESP-IDF startup.
 
-Stream Buffer API
------------------
+- Typically, users would spawn the rest of their application's task from ``app_main``.
+- The ``app_main`` function is allowed to return at any point (i.e., before the application terminates).
+- The ``app_main`` function is called from the ``main`` task.
+
+Background Tasks
+^^^^^^^^^^^^^^^^
+
+During startup, ESP-IDF and FreeRTOS will automatically create multiple tasks that run in the background (listed in the the table below).
+
+.. list-table:: List of Tasks Created During Startup
+    :widths: 10 75 5 5 5
+    :header-rows: 1
+
+    * - Task Name
+      - Description
+      - Stack Size
+      - Affinity
+      - Priority
+    * - Idle Tasks (``IDLEx``)
+      - An idle task (``IDLEx``) is created for (and pinned to) each CPU, where ``x`` is the CPU's number.
+      - :ref:`CONFIG_FREERTOS_IDLE_TASK_STACKSIZE`
+      - CPUx
+      - ``0``
+    * - FreeRTOS Timer Task (``Tmr Svc``)
+      - FreeRTOS will create the Timer Service/Daemon Task if any FreeRTOS Timer APIs are called by the application.
+      - :ref:`CONFIG_FREERTOS_TIMER_TASK_STACK_DEPTH`
+      - CPU0
+      - :ref:`CONFIG_FREERTOS_TIMER_TASK_PRIORITY`
+    * - Main Task (``main``)
+      - Task that simply calls ``app_main``. This task will self delete when ``app_main`` returns
+      - :ref:`CONFIG_ESP_MAIN_TASK_STACK_SIZE`
+      - :ref:`CONFIG_ESP_MAIN_TASK_AFFINITY`
+      - ``1``
+    * - IPC Tasks (``ipcx``)
+      - When :ref:`CONFIG_FREERTOS_UNICORE` is false, an IPC task (``ipcx``) is created for (and pinned to) each CPU. IPC tasks are used to implement the Inter-processor Call (IPC) feature.
+      - :ref:`CONFIG_ESP_IPC_TASK_STACK_SIZE`
+      - CPUx
+      - ``24``
+    * - ESP Timer Task (``esp_timer``)
+      - ESP-IDF will create the ESP Timer Task used to process ESP Timer callbacks.
+      - :ref:`CONFIG_ESP_TIMER_TASK_STACK_SIZE`
+      - CPU0
+      - ``22``
 
-.. include-build-file:: inc/stream_buffer.inc
+.. note::
+    Note that if an application uses other ESP-IDF features (e.g., WiFi or Bluetooth), those features may create their own background tasks in addition to the tasks listed in the table above.
 
-Message Buffer API
+FreeRTOS Additions
 ------------------
 
-.. include-build-file:: inc/message_buffer.inc
+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.
diff --git a/docs/en/api-reference/system/freertos_additions.rst b/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.