docs/Added documentation about esp32 hooks

This commit adds documentation about the esp32 Idle and Tick Hooks
This commit is contained in:
Darian Leung 2017-10-17 18:57:31 +08:00
parent 90bf40587e
commit 461f8da704
5 changed files with 80 additions and 22 deletions

View file

@ -38,12 +38,13 @@ typedef void (*esp_freertos_tick_cb_t)();
* @warning Idle callbacks MUST NOT, UNDER ANY CIRCUMSTANCES, CALL * @warning Idle callbacks MUST NOT, UNDER ANY CIRCUMSTANCES, CALL
* A FUNCTION THAT MIGHT BLOCK. * 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
* @param UBaseType_t cpuid : id of the core * @param[in] cpuid id of the core
* *
* @return ESP_OK : Callback registered to the specified core's idle hook * @return
* @return ESP_ERR_NO_MEM : No more space on the specified core's idle hook to register callback * - ESP_OK: Callback registered to the specified core's idle hook
* @return ESP_ERR_INVALID_ARG : cpuid is invalid * - 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); 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 * @warning Idle callbacks MUST NOT, UNDER ANY CIRCUMSTANCES, CALL
* A FUNCTION THAT MIGHT BLOCK. * 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
* @return ESP_ERR_NO_MEM : No more space the calling core's idle hook to register callback * - 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); 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. * @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[in] new_tick_cb Callback to be called
* @param UBaseType_t cpuid : id of the core * @param[in] cpuid id of the core
* *
* @return ESP_OK : Callback registered * @return
* @return ESP_ERR_NO_MEM : No more space on the specified core's tick hook to register the callback * - ESP_OK: Callback registered to specified core's tick hook
* @return ESP_ERR_INVALID_ARG : cpuid is invalid * - 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); 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. * @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
* @return ESP_ERR_NO_MEM : No more space on the calling core's tick hook to register the callback * - 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); 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 * the idle hooks of both cores, the idle hook will be unregistered from
* both cores * both cores
* *
* @param esp_freertos_idle_cb_t new_idle_cb : Callback to be unregistered * @param[in] old_idle_cb Callback to be unregistered
*
* @return void
*/ */
void esp_deregister_freertos_idle_hook(esp_freertos_idle_cb_t old_idle_cb); 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 * tick hooks of both cores, the tick hook will be unregistered from
* both cores * both cores
* *
* @param esp_freertos_idle_cb_t new_idle_cb : Callback to be unregistered * @param[in] old_tick_cb Callback to be unregistered
*
* @return void
*/ */
void esp_deregister_freertos_tick_hook(esp_freertos_tick_cb_t old_tick_cb); void esp_deregister_freertos_tick_hook(esp_freertos_tick_cb_t old_tick_cb);

View file

@ -126,6 +126,8 @@ INPUT = \
## NOTE: for two lines below header_file.inc is not used ## NOTE: for two lines below header_file.inc is not used
../components/esp32/include/esp_int_wdt.h \ ../components/esp32/include/esp_int_wdt.h \
../components/esp32/include/esp_task_wdt.h \ ../components/esp32/include/esp_task_wdt.h \
## Hooks
../components/esp32/include/esp_freertos_hooks.h \
## Over The Air Updates (OTA) ## Over The Air Updates (OTA)
../components/app_update/include/esp_ota_ops.h \ ../components/app_update/include/esp_ota_ops.h \
## Sleep ## Sleep

View file

@ -55,6 +55,10 @@ automatically free memory used by Thread Local Storage Pointers during the task
deletion. Call ``vTaskSetThreadLocalStoragePointerAndDelCallback()`` deletion. Call ``vTaskSetThreadLocalStoragePointerAndDelCallback()``
to set Thread Local Storage Pointers and deletion callbacks. 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 :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, 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. or configuring the number of Thread Local Storage Pointers each task will have.

View file

@ -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

View file

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