Merge branch 'docs/esp32_hooks' into 'master'

docs/Added documentation about esp32 hooks

See merge request !1417

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);
 

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

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<hooks_api_reference>`: 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.

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

docs/api-reference/system/index.rst

@@ -8,6 +8,7 @@ System API
    Heap Memory Debugging <heap_debug>
    Interrupt Allocation <intr_alloc>
    Watchdogs <wdts>
+   Hooks <hooks>
    Over The Air Updates (OTA) <ota>
    Sleep Modes <sleep_modes>
    Logging <log>