OVMS3-idf/docs/en/api-reference/system/hooks.rst

.. _hooks_api_reference:

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/Added documentation about esp32 hooks This commit adds documentation about the esp32 Idle and Tick Hooks 2017-10-17 10:57:31 +00:00			`.. _hooks_api_reference:`

docs: add FreeRTOS API docs - Use `code` tags instead of a mix of `<pre></pre>` and `@verbatim .. @endverbatim` - Remove manually added function prototypes from comment blocks - Remove of grouping (`\defgroup`) — some extra work is needed to make groups compatible with the way we auto-generate API reference from Doxygen XML files. It's pretty easy to add the grouping directives back if/when we implement support for Doxygen groups in the later stages of documentation build process. - Hide private APIs under `@cond .. @endcond` - Convert some comments into Doxygen-compatible ones - Fix various documentation issues: missing documentation for some parameters, mismatch between parameter names in comment block and in function prototype. - Add doxygen comments for functions which didn't have them (thread local storage). - Add [out] param tags where necessary - Redefine `xTaskCreate` and `xTaskCreateStatic` as inline functions instead of macros. 2017-12-01 04:50:45 +00:00			`FreeRTOS Hooks`
			`==============`
docs/Added documentation about esp32 hooks This commit adds documentation about the esp32 Idle and Tick Hooks 2017-10-17 10:57:31 +00:00
			`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`