From 89466c649e816a59296b6cf38d48c9aab2e6659b Mon Sep 17 00:00:00 2001 From: Mahavir Jain Date: Tue, 26 Oct 2021 17:26:59 +0530 Subject: [PATCH] docs: freertos: add note about tick hooks placement requirement Closes https://github.com/espressif/esp-idf/issues/7740 Closes IDFGH-6056 --- docs/en/api-guides/freertos-smp.rst | 2 +- .../system/freertos_additions.rst | 29 ++++++++++++------- 2 files changed, 19 insertions(+), 12 deletions(-) diff --git a/docs/en/api-guides/freertos-smp.rst b/docs/en/api-guides/freertos-smp.rst index 388cdde9f5..7b8585ab2b 100644 --- a/docs/en/api-guides/freertos-smp.rst +++ b/docs/en/api-guides/freertos-smp.rst @@ -6,7 +6,7 @@ Overview .. only:: not CONFIG_FREERTOS_UNICORE - The vanilla FreeRTOS is designed to run on a single core. However the ESP32 is + The vanilla FreeRTOS is designed to run on a single core. However the {IDF_TARGET_NAME} is dual core containing a Protocol CPU (known as **CPU 0** or **PRO_CPU**) and an Application CPU (known as **CPU 1** or **APP_CPU**). The two cores are identical in practice and share the same memory. This allows the two cores to diff --git a/docs/en/api-reference/system/freertos_additions.rst b/docs/en/api-reference/system/freertos_additions.rst index df312052fd..df6783137e 100644 --- a/docs/en/api-reference/system/freertos_additions.rst +++ b/docs/en/api-reference/system/freertos_additions.rst @@ -498,27 +498,34 @@ Vanilla FreeRTOS hooks are referred to as **Legacy Hooks** in ESP-IDF FreeRTOS. To enable legacy hooks, :ref:`CONFIG_FREERTOS_LEGACY_HOOKS` should be enabled in :doc:`project configuration menu `. -Due to vanilla FreeRTOS being designed for single core, ``vApplicationIdleHook()`` -and ``vApplicationTickHook()`` can only be defined once. However, the ESP32 is dual core -in nature, therefore same Idle Hook and Tick Hook are used for both cores (in other words, -the hooks are symmetrical for both cores). +.. only:: not CONFIG_FREERTOS_UNICORE -In a dual core system, ``vApplicationTickHook()`` must be located in IRAM (for example -by adding the IRAM_ATTR attribute). + Due to vanilla FreeRTOS being designed for single core, ``vApplicationIdleHook()`` + and ``vApplicationTickHook()`` can only be defined once. However, the {IDF_TARGET_NAME} is dual core + in nature, therefore same Idle Hook and Tick Hook are used for both cores (in other words, + the hooks are symmetrical for both cores). ESP-IDF Idle and Tick Hooks ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Due to the the dual core nature of the ESP32, it may be necessary for some -applications to have separate hooks for each core. Furthermore, it may -be necessary for the Idle Tasks or Tick Interrupts to execute multiple hooks -that are configurable at run time. Therefore the ESP-IDF provides it's own hooks -API in addition to the legacy hooks provided by Vanilla FreeRTOS. + +For some use-cases it may be necessary for the Idle Tasks or Tick Interrupts to execute multiple hooks +that are configurable at run time. + +.. only:: not CONFIG_FREERTOS_UNICORE + + Furthermore, due to the the dual core nature of the {IDF_TARGET_NAME}, it may be necessary for some + applications to have separate hooks for each core. + +Therefore the ESP-IDF provides it's own hooks API in addition to the legacy hooks provided +by Vanilla FreeRTOS. The ESP-IDF tick/idle hooks are registered at run time, and each tick/idle hook must be registered to a specific CPU. When the idle task runs/tick Interrupt occurs on a particular CPU, the CPU will run each of its registered idle/tick hooks in turn. +.. note:: Tick interrupt stays active whilst cache is disabled and hence ``vApplicationTickHook()`` (legacy case) or ESP-IDF tick hooks must be placed in internal RAM. Please refer to the :ref:`SPI flash API documentation ` for more details. + Hooks API Reference -------------------