diff --git a/components/freertos/FreeRTOS-Kernel/include/freertos/queue.h b/components/freertos/FreeRTOS-Kernel/include/freertos/queue.h index c16faf1046..cf4d49665c 100644 --- a/components/freertos/FreeRTOS-Kernel/include/freertos/queue.h +++ b/components/freertos/FreeRTOS-Kernel/include/freertos/queue.h @@ -1351,9 +1351,6 @@ void vQueueDelete( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; #define xQueueSendFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) \ xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK ) -/** @cond !DOC_EXCLUDE_HEADER_SECTION */ -/**@{*/ - /** * @cond !DOC_EXCLUDE_HEADER_SECTION * queue. h diff --git a/docs/docs_not_updated/esp32p4.txt b/docs/docs_not_updated/esp32p4.txt index 4b08c0fe4e..eaaa425d44 100644 --- a/docs/docs_not_updated/esp32p4.txt +++ b/docs/docs_not_updated/esp32p4.txt @@ -173,13 +173,11 @@ api-reference/system/async_memcpy.rst api-reference/system/random.rst api-reference/system/esp_timer.rst api-reference/system/esp_event.rst -api-reference/system/freertos.rst api-reference/system/system_time.rst api-reference/system/log.rst api-reference/system/soc_caps.rst api-reference/system/internal-unstable.rst api-reference/system/app_image_format.rst -api-reference/system/freertos_additions.rst api-reference/system/himem.rst api-reference/system/power_management.rst api-reference/system/mem_alloc.rst @@ -196,7 +194,6 @@ api-reference/system/ipc.rst api-reference/system/esp_https_ota.rst api-reference/system/ulp-risc-v.rst api-reference/system/esp_err.rst -api-reference/system/freertos_idf.rst api-reference/system/console.rst api-reference/system/intr_alloc.rst api-reference/system/index.rst diff --git a/docs/en/api-guides/host-apps.rst b/docs/en/api-guides/host-apps.rst index defe1acfde..2a39be3e10 100644 --- a/docs/en/api-guides/host-apps.rst +++ b/docs/en/api-guides/host-apps.rst @@ -44,9 +44,11 @@ POSIX/Linux Simulator Approach The `FreeRTOS POSIX/Linux simulator `_ is available on ESP-IDF as a preview target already. This simulator allows ESP-IDF components to be implemented on the host, making them accessible to ESP-IDF applications when running on host. Currently, only a limited number of components are ready to be built on Linux. Furthermore, the functionality of each component ported to Linux may also be limited or different compared to the functionality when building that component for a chip target. For more information about whether the desired components are supported on Linux, please refer to :ref:`component-linux-mock-support`. -.. note:: +.. only:: not esp32p4 - The FreeRTOS POSIX/Linux simulator allows configuring the :ref:`amazon_smp_freertos` version. However, the simulation still runs in single-core mode. The main reason allowing Amazon SMP FreeRTOS is to provide API compatibility with ESP-IDF applications written for Amazon SMP FreeRTOS. + .. note:: + + The FreeRTOS POSIX/Linux simulator allows configuring the :ref:`amazon_smp_freertos` version. However, the simulation still runs in single-core mode. The main reason allowing Amazon SMP FreeRTOS is to provide API compatibility with ESP-IDF applications written for Amazon SMP FreeRTOS. Requirements for Using Mocks ---------------------------- diff --git a/docs/en/api-reference/system/freertos.rst b/docs/en/api-reference/system/freertos.rst index ff236a0aa7..526507bb26 100644 --- a/docs/en/api-reference/system/freertos.rst +++ b/docs/en/api-reference/system/freertos.rst @@ -9,27 +9,29 @@ FreeRTOS is an open source real-time operating system kernel that acts as the op 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**. +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 as listed below: 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. + 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:: + .. note:: - ESP-IDF FreeRTOS is currently the default FreeRTOS implementation for ESP-IDF. + ESP-IDF FreeRTOS is currently the default FreeRTOS implementation for ESP-IDF. -.. _amazon_smp_freertos: +.. only:: not esp32p4 -Amazon SMP FreeRTOS -^^^^^^^^^^^^^^^^^^^ + .. _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 `_. + Amazon SMP FreeRTOS + ^^^^^^^^^^^^^^^^^^^ -.. 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. + 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 ------------- @@ -77,7 +79,7 @@ Unlike Vanilla FreeRTOS, users of FreeRTOS in ESP-IDF **must never call** :cpp:f Background Tasks ^^^^^^^^^^^^^^^^ -During startup, ESP-IDF and FreeRTOS automatically creates multiple tasks that run in the background (listed in the the table below). +During startup, ESP-IDF and the FreeRTOS kernel 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 @@ -115,7 +117,7 @@ During startup, ESP-IDF and FreeRTOS automatically creates multiple tasks that r - ``22`` .. 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. + Note that if an application uses other ESP-IDF features (e.g., Wi-Fi or Bluetooth), those features may create their own background tasks in addition to the tasks listed in the table above. FreeRTOS Additions ------------------ diff --git a/docs/en/api-reference/system/freertos_idf.rst b/docs/en/api-reference/system/freertos_idf.rst index 1da7603188..1e304d7eed 100644 --- a/docs/en/api-reference/system/freertos_idf.rst +++ b/docs/en/api-reference/system/freertos_idf.rst @@ -6,7 +6,7 @@ FreeRTOS (ESP-IDF) 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, 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). +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, ESP32-S3 and ESP32-P4), ESP-IDF provides a dual core SMP (Symmetric Multiprocessing) capable implementation of FreeRTOS, (hereinafter referred to as ESP-IDF FreeRTOS). 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. @@ -50,9 +50,9 @@ Although an SMP system allows threads to switch cores, there are scenarios where SMP on an ESP Target ^^^^^^^^^^^^^^^^^^^^ -ESP targets (such as the ESP32, ESP32-S3) are dual core SMP SoCs. These targets have the following hardware features that make them SMP capable: +ESP targets (such as the ESP32, ESP32-S3 and ESP32-P4) are dual core SMP SoCs. These targets have the following hardware features that make them SMP capable: -- Two identical cores known as CPU0 (i.e., Protocol CPU or PRO_CPU) and CPU1 (i.e., Application CPU or APP_CPU). This means that the execution of a piece of code is identical regardless of which core it runs on. +- Two identical cores known as CPU0 and CPU1. This means that the execution of a piece of code is identical regardless of which core it runs on. - Symmetric memory (with some small exceptions). - If multiple cores access the same memory address, their access will be serialized at the memory bus level. @@ -60,9 +60,12 @@ ESP targets (such as the ESP32, ESP32-S3) are dual core SMP SoCs. These targets - Cross-core interrupts that allow one CPU to trigger and interrupt on another CPU. This allows cores to signal each other. -.. note:: - The ``PRO_CPU`` and ``APP_CPU`` aliases for CPU0 and CPU1 exist in ESP-IDF as they reflect how typical ESP-IDF applications utilize the two CPUs. Typically, the tasks responsible for handling wireless networking (e.g., Wi-Fi or Bluetooth) are pinned to CPU0 (thus the name PRO_CPU), whereas the tasks handling the remainder of the application are pinned to CPU1 (thus the name APP_CPU). +.. only:: not esp32p4 + + .. note:: + + CPU0 is also known as Protocol CPU or ``PRO_CPU`` and CPU1 is also known as Application CPU or ``APP_CPU``. The ``PRO_CPU`` and ``APP_CPU`` aliases for CPU0 and CPU1 exist in ESP-IDF as they reflect how typical ESP-IDF applications utilize the two CPUs. Typically, the tasks responsible for handling wireless networking (e.g., Wi-Fi or Bluetooth) are pinned to CPU0 (thus the name PRO_CPU), whereas the tasks handling the remainder of the application are pinned to CPU1 (thus the name APP_CPU). .. ------------------------------------------------------ Tasks -------------------------------------------------------- @@ -112,7 +115,7 @@ Task deletion in Vanilla FreeRTOS is called via :cpp:func:`vTaskDelete`. The fun ESP-IDF FreeRTOS provides the same :cpp:func:`vTaskDelete` function. However, due to the dual core nature, there are some behavioral differences when calling :cpp:func:`vTaskDelete` in ESP-IDF FreeRTOS: - When deleting a task that is pinned to the other core, that task's memory is always freed by the idle task of the other core (due to the need to clear FPU registers). -- When deleting a task that is currently running on the other core, a yield is triggered on the other core and the task's memory is freed by one of the idle tasks (depending on the task's core affinity) +- When deleting a task that is currently running on the other core, an yield is triggered on the other core and the task's memory is freed by one of the idle tasks (depending on the task's core affinity) - A deleted task's memory is freed immediately if... - The tasks is currently running on this core and is also pinned to this core @@ -419,32 +422,34 @@ Given that interrupts (or interrupt nesting) are disabled during a critical sect Misc ---- -Floating Point Usage -^^^^^^^^^^^^^^^^^^^^ +.. only:: SOC_CPU_HAS_FPU -Usually, when a context switch occurs: + Floating Point Usage + ^^^^^^^^^^^^^^^^^^^^ -- the current state of a CPU's registers are saved to the stack of task being switch out -- the previously saved state of the CPU's registers are loaded from the stack of the task being switched in + Usually, when a context switch occurs: -However, ESP-IDF FreeRTOS implements Lazy Context Switching for the FPU (Floating Point Unit) registers of a CPU. In other words, when a context switch occurs on a particular core (e.g., CPU0), the state of the core's FPU registers are not immediately saved to the stack of the task getting switched out (e.g., Task A). The FPU's registers are left untouched until: + - the current state of a CPU's registers are saved to the stack of task being switch out + - the previously saved state of the CPU's registers are loaded from the stack of the task being switched in -- A different task (e.g., Task B) runs on the same core and uses the FPU. This will trigger an exception that saves the FPU registers to Task A's stack. -- Task A get's scheduled to the same core and continues execution. Saving and restoring the FPU's registers is not necessary in this case. + However, ESP-IDF FreeRTOS implements Lazy Context Switching for the FPU (Floating Point Unit) registers of a CPU. In other words, when a context switch occurs on a particular core (e.g., CPU0), the state of the core's FPU registers are not immediately saved to the stack of the task getting switched out (e.g., Task A). The FPU's registers are left untouched until: -However, given that tasks can be unpinned thus can be scheduled on different cores (e.g., Task A switches to CPU1), it is unfeasible to copy and restore the FPU's registers across cores. Therefore, when a task utilizes the FPU (by using a ``float`` type in its call flow), ESP-IDF FreeRTOS will automatically pin the task to the current core it is running on. This ensures that all tasks that uses the FPU are always pinned to a particular core. + - A different task (e.g., Task B) runs on the same core and uses the FPU. This will trigger an exception that saves the FPU registers to Task A's stack. + - Task A get's scheduled to the same core and continues execution. Saving and restoring the FPU's registers is not necessary in this case. -Furthermore, ESP-IDF FreeRTOS by default does not support the usage of the FPU within an interrupt context given that the FPU's register state is tied to a particular task. + However, given that tasks can be unpinned thus can be scheduled on different cores (e.g., Task A switches to CPU1), it is unfeasible to copy and restore the FPU's registers across cores. Therefore, when a task utilizes the FPU (by using a ``float`` type in its call flow), ESP-IDF FreeRTOS will automatically pin the task to the current core it is running on. This ensures that all tasks that uses the FPU are always pinned to a particular core. -.. only: esp32 + Furthermore, ESP-IDF FreeRTOS by default does not support the usage of the FPU within an interrupt context given that the FPU's register state is tied to a particular task. - .. note:: + .. only: esp32 - Users that require the use of the ``float`` type in an ISR routine should refer to the :ref:`CONFIG_FREERTOS_FPU_IN_ISR` configuration option. + .. note:: -.. note:: + Users that require the use of the ``float`` type in an ISR routine should refer to the :ref:`CONFIG_FREERTOS_FPU_IN_ISR` configuration option. - 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``. + .. note:: + + 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``. .. -------------------------------------------------- Single Core ----------------------------------------------------- diff --git a/docs/zh_CN/api-guides/host-apps.rst b/docs/zh_CN/api-guides/host-apps.rst index bcf916a0b5..54a770f6a8 100644 --- a/docs/zh_CN/api-guides/host-apps.rst +++ b/docs/zh_CN/api-guides/host-apps.rst @@ -44,9 +44,11 @@ POSIX/Linux 模拟器的模拟 ESP-IDF 已支持使用 `FreeRTOS POSIX/Linux 模拟器 `_ 预览应用程序在目标芯片上的运行效果。使用该模拟器可以在主机上运行 ESP-IDF 组件，并使这类组件可用于在主机上运行的 ESP-IDF 应用程序。目前，只有一部分组件可以在 Linux 上构建。此外，各组件移植到 Linux 上后，其功能可能也会受到限制，或与在芯片目标上构建该组件的功能有所不同。有关所需组件在 Linux 上是否受支持的更多信息，请参阅 :ref:`component-linux-mock-support`。 -.. note:: +.. only:: not esp32p4 - FreeRTOS POSIX/Linux 模拟器支持配置 :ref:`amazon_smp_freertos` 版本，但模拟仍在单核模式下运行。支持 Amazon SMP FreeRTOS 主要是为给 Amazon SMP FreeRTOS 编写的 ESP-IDF 应用程序提供 API 兼容性。 + .. note:: + + FreeRTOS POSIX/Linux 模拟器支持配置 :ref:`amazon_smp_freertos` 版本，但模拟仍在单核模式下运行。支持 Amazon SMP FreeRTOS 主要是为给 Amazon SMP FreeRTOS 编写的 ESP-IDF 应用程序提供 API 兼容性。 使用模拟器的前提 -----------------