From 461f8da7048e0ef6f337afa5eeb15d3612ea7dd1 Mon Sep 17 00:00:00 2001 From: Darian Leung Date: Tue, 17 Oct 2017 18:57:31 +0800 Subject: [PATCH] docs/Added documentation about esp32 hooks This commit adds documentation about the esp32 Idle and Tick Hooks --- components/esp32/include/esp_freertos_hooks.h | 44 ++++++++-------- docs/Doxyfile | 2 + docs/api-guides/freertos-smp.rst | 4 ++ docs/api-reference/system/hooks.rst | 51 +++++++++++++++++++ docs/api-reference/system/index.rst | 1 + 5 files changed, 80 insertions(+), 22 deletions(-) create mode 100644 docs/api-reference/system/hooks.rst diff --git a/components/esp32/include/esp_freertos_hooks.h b/components/esp32/include/esp_freertos_hooks.h index 42176cb1b..3d2111926 100644 --- a/components/esp32/include/esp_freertos_hooks.h +++ b/components/esp32/include/esp_freertos_hooks.h @@ -38,12 +38,13 @@ typedef void (*esp_freertos_tick_cb_t)(); * @warning Idle callbacks MUST NOT, UNDER ANY CIRCUMSTANCES, CALL * A FUNCTION THAT MIGHT BLOCK. * - * @param esp_freertos_idle_cb_t new_idle_cb : Callback to be called - * @param UBaseType_t cpuid : id of the core + * @param[in] new_idle_cb Callback to be called + * @param[in] cpuid id of the core * - * @return ESP_OK : Callback registered to the specified core's idle hook - * @return ESP_ERR_NO_MEM : No more space on the specified core's idle hook to register callback - * @return ESP_ERR_INVALID_ARG : cpuid is invalid + * @return + * - ESP_OK: Callback registered to the specified core's idle hook + * - ESP_ERR_NO_MEM: No more space on the specified core's idle hook to register callback + * - ESP_ERR_INVALID_ARG: cpuid is invalid */ esp_err_t esp_register_freertos_idle_hook_for_cpu(esp_freertos_idle_cb_t new_idle_cb, UBaseType_t cpuid); @@ -56,32 +57,35 @@ esp_err_t esp_register_freertos_idle_hook_for_cpu(esp_freertos_idle_cb_t new_idl * @warning Idle callbacks MUST NOT, UNDER ANY CIRCUMSTANCES, CALL * A FUNCTION THAT MIGHT BLOCK. * - * @param esp_freertos_idle_cb_t new_idle_cb : Callback to be called + * @param[in] new_idle_cb Callback to be called * - * @return ESP_OK : Callback registered to the calling core's idle hook - * @return ESP_ERR_NO_MEM : No more space the calling core's idle hook to register callback + * @return + * - ESP_OK: Callback registered to the calling core's idle hook + * - ESP_ERR_NO_MEM: No more space on the calling core's idle hook to register callback */ esp_err_t esp_register_freertos_idle_hook(esp_freertos_idle_cb_t new_idle_cb); /** * @brief Register a callback to be called from the specified core's tick hook. * - * @param esp_freertos_tick_cb_t new_tick_cb : Callback to be called - * @param UBaseType_t cpuid : id of the core + * @param[in] new_tick_cb Callback to be called + * @param[in] cpuid id of the core * - * @return ESP_OK : Callback registered - * @return ESP_ERR_NO_MEM : No more space on the specified core's tick hook to register the callback - * @return ESP_ERR_INVALID_ARG : cpuid is invalid + * @return + * - ESP_OK: Callback registered to specified core's tick hook + * - ESP_ERR_NO_MEM: No more space on the specified core's tick hook to register the callback + * - ESP_ERR_INVALID_ARG: cpuid is invalid */ esp_err_t esp_register_freertos_tick_hook_for_cpu(esp_freertos_tick_cb_t new_tick_cb, UBaseType_t cpuid); /** * @brief Register a callback to be called from the calling core's tick hook. * - * @param esp_freertos_tick_cb_t new_tick_cb : Callback to be called + * @param[in] new_tick_cb Callback to be called * - * @return ESP_OK : Callback registered - * @return ESP_ERR_NO_MEM : No more space on the calling core's tick hook to register the callback + * @return + * - ESP_OK: Callback registered to the calling core's tick hook + * - ESP_ERR_NO_MEM: No more space on the calling core's tick hook to register the callback */ esp_err_t esp_register_freertos_tick_hook(esp_freertos_tick_cb_t new_tick_cb); @@ -91,9 +95,7 @@ esp_err_t esp_register_freertos_tick_hook(esp_freertos_tick_cb_t new_tick_cb); * the idle hooks of both cores, the idle hook will be unregistered from * both cores * - * @param esp_freertos_idle_cb_t new_idle_cb : Callback to be unregistered - * - * @return void + * @param[in] old_idle_cb Callback to be unregistered */ void esp_deregister_freertos_idle_hook(esp_freertos_idle_cb_t old_idle_cb); @@ -103,9 +105,7 @@ void esp_deregister_freertos_idle_hook(esp_freertos_idle_cb_t old_idle_cb); * tick hooks of both cores, the tick hook will be unregistered from * both cores * - * @param esp_freertos_idle_cb_t new_idle_cb : Callback to be unregistered - * - * @return void + * @param[in] old_tick_cb Callback to be unregistered */ void esp_deregister_freertos_tick_hook(esp_freertos_tick_cb_t old_tick_cb); diff --git a/docs/Doxyfile b/docs/Doxyfile index dee628ef4..0a3aa6687 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -126,6 +126,8 @@ INPUT = \ ## NOTE: for two lines below header_file.inc is not used ../components/esp32/include/esp_int_wdt.h \ ../components/esp32/include/esp_task_wdt.h \ + ## Hooks + ../components/esp32/include/esp_freertos_hooks.h \ ## Over The Air Updates (OTA) ../components/app_update/include/esp_ota_ops.h \ ## Sleep diff --git a/docs/api-guides/freertos-smp.rst b/docs/api-guides/freertos-smp.rst index a706320d8..87e04d664 100644 --- a/docs/api-guides/freertos-smp.rst +++ b/docs/api-guides/freertos-smp.rst @@ -55,6 +55,10 @@ automatically free memory used by Thread Local Storage Pointers during the task deletion. Call ``vTaskSetThreadLocalStoragePointerAndDelCallback()`` to set Thread Local Storage Pointers and deletion callbacks. +:ref:`FreeRTOS Hooks`: Vanilla FreeRTOS Hooks were not designed for SMP. +ESP-IDF provides its own Idle and Tick Hooks in addition to the Vanilla FreeRTOS +hooks. For full details, see the ESP-IDF Hooks API Reference. + :ref:`esp-idf-freertos-configuration`: Several aspects of ESP-IDF FreeRTOS can be configured using ``make meunconfig`` such as running ESP-IDF in Unicore Mode, or configuring the number of Thread Local Storage Pointers each task will have. diff --git a/docs/api-reference/system/hooks.rst b/docs/api-reference/system/hooks.rst new file mode 100644 index 000000000..78ac708a2 --- /dev/null +++ b/docs/api-reference/system/hooks.rst @@ -0,0 +1,51 @@ +.. _hooks_api_reference: + +ESP-IDF FreeRTOS Hooks +====================== + +Overview +-------- + +FreeRTOS consists of Idle Hooks and Tick Hooks which allow for application +specific funtiionality to be added to the Idle Task and Tick Interrupt. The +ESP32 is dual core in nature, hence the ESP-IDF provides its own Idle and Tick +Hooks that are dual core compatible in addition to the hooks provided by Vanilla +FreeRTOS. + +Vanilla FreeRTOS Hooks +---------------------- + +Idle and Tick Hooks in vanilla FreeRTOS are implemented by defining +implementations for the functions ``vApplicationIdleHook`` and +``vApplicationTickHook`` respectively somewhere in the application. Vanilla +FreeRTOS will run the user defined Idle Hook every iteration of the Idle Task, +whereas the user defined Tick Hook will run once per tick interrupt (given that +there are no pended ticks). + +Due to vanilla FreeRTOS being designed for single core, ``vApplicationIdleHook`` +and ``vApplicationTickHook`` will be run in both cores on the ESP32. In +other words, the same Idle Hook and Tick Hook are used for both cores. + +To enable the vanilla FreeRTOS hooks in ESP-IDF, :ref:`CONFIG_FREERTOS_LEGACY_HOOKS` +must be enabled in ``make menuconfig``. :ref:`CONFIG_FREERTOS_LEGACY_IDLE_HOOK` +and :ref:`CONFIG_FREERTOS_LEGACY_TICK_HOOK` should also be enabled. + +ESP-IDF Idle and Tick Hooks +--------------------------- + +Due to the dual core nature of the ESP32, it may be necessary for some +applications to have seperate Idle Hooks for each core. Furthermore, it may +be necessary for Idle and Tick Hooks to have execute multiple functionalities +that are configurable at run time. Therefore the ESP-IDF provides it's own Idle +and Tick Hooks in addition to the hooks provided by Vanilla FreeRTOS. + +The ESP-IDF Hooks do not operate in the same way as Vanilla FreeRTOS Hooks +where users provide a definition for each of the hooks. Instead, the ESP-IDF +Hooks are predefined to call a list of user registered callbacks specific to +each core. Users can register and deregister callbacks which are run on the +Idle or Tick Hook of a specific core. + +API Reference +------------- + +.. include:: /_build/inc/esp_freertos_hooks.inc \ No newline at end of file diff --git a/docs/api-reference/system/index.rst b/docs/api-reference/system/index.rst index e86cd1262..e5f457f61 100644 --- a/docs/api-reference/system/index.rst +++ b/docs/api-reference/system/index.rst @@ -8,6 +8,7 @@ System API Heap Memory Debugging Interrupt Allocation Watchdogs + Hooks Over The Air Updates (OTA) Sleep Modes Logging