From b56f66d28d32925e00e2f014919bb19dbe3e7a80 Mon Sep 17 00:00:00 2001 From: Darian Leung Date: Tue, 7 Feb 2023 17:07:52 +0800 Subject: [PATCH] freertos: Update FreeRTOS overview document This commit updates "freertos.rst" to act as an overview document of FreeRTOS in ESP-IDF, outlining the different FreeRTOS implementations (IDF vs Amazon) and various supplemental features. The details of each implementation will be separated to their own documents. --- docs/en/api-reference/system/freertos.rst | 180 ++++++++++------------ 1 file changed, 83 insertions(+), 97 deletions(-) diff --git a/docs/en/api-reference/system/freertos.rst b/docs/en/api-reference/system/freertos.rst index df349c57f5..0811b2b7e6 100644 --- a/docs/en/api-reference/system/freertos.rst +++ b/docs/en/api-reference/system/freertos.rst @@ -1,131 +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. + +Implementations +--------------- + +The `official FreeRTOS `_ (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**. + +ESP-IDF FreeRTOS +^^^^^^^^^^^^^^^^ + +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. .. note:: - ESP-IDF FreeRTOS is based on Vanilla FreeRTOS v10.4.3 + ESP-IDF FreeRTOS is currently the default FreeRTOS implementation for ESP-IDF. -- 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`. +Amazon SMP FreeRTOS +^^^^^^^^^^^^^^^^^^^ + +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 `_. + +.. 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. Configuration ------------- -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. +Kernel Configuration +^^^^^^^^^^^^^^^^^^^^ -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` +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. -- :ref:`CONFIG_FREERTOS_UNICORE` will run ESP-IDF FreeRTOS only on CPU0. Note that this is **not equivalent to running Vanilla FreeRTOS**. Futhermore, 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. +**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``. -- :ref:`CONFIG_FREERTOS_ASSERT_ON_UNTESTED_FUNCTION` will trigger a halt in functions in ESP-IDF FreeRTOS that have not been fully tested in an SMP context. +For the full list of user configurable kernel options, see :doc:`/api-reference/kconfig`. The list below highlights some commonly used kernel configuration options: -- :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:: - - E (25) FreeRTOS: FreeRTOS task should not return. Aborting now! - abort() was called at PC 0x40085c53 on core 0 +- :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 .. note:: As {IDF_TARGET_NAME} is a single core SoC, the :ref:`CONFIG_FREERTOS_UNICORE` configuration is always set. +- :ref:`CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY` enables backward compatibility with some FreeRTOS macros/types/functions that were deprecated from v8.0 onwards. -.. _freertos-applications: +Port Configuration +^^^^^^^^^^^^^^^^^^ -ESP-IDF FreeRTOS Applications ------------------------------ +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: -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. +- The FreeRTOS ports themselves (e.g., tick timer selection, ISR stack size) +- Additional features added to the FreeRTOS implementation or ports -- Typically, users would spawn the rest of their applications task from ``app_main``. +Using FreeRTOS +-------------- + +Application Entry Point +^^^^^^^^^^^^^^^^^^^^^^^ + +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. + +- 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. +- 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: +Background Tasks +^^^^^^^^^^^^^^^^ -.. only:: not CONFIG_FREERTOS_UNICORE +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: 25 25 5 50 - :header-rows: 1 +.. list-table:: List of Tasks Created During Startup + :widths: 10 75 5 5 5 + :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 IPC feature. See :doc:`/api-reference/system/ipc` for more details. + * - 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`` -.. only:: CONFIG_FREERTOS_UNICORE +.. 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. - .. 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 task created for (and pinned to) each CPU - - .. note:: - - Low priority numbers denote low priority tasks. - -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 +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.