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, FREERTOS_LEGACY_HOOKS must be enabled in make menuconfig. FREERTOS_LEGACY_IDLE_HOOK and 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

Header File

• esp32/include/esp_freertos_hooks.h

Functions

esp_err_t esp_register_freertos_idle_hook_for_cpu(esp_freertos_idle_cb_t new_idle_cb, UBaseType_t cpuid)

Register a callback to be called from the specified core’s idle hook. The callback should return true if it should be called by the idle hook once per interrupt (or FreeRTOS tick), and return false if it should be called repeatedly as fast as possible by the idle hook.

Warning

Idle callbacks MUST NOT, UNDER ANY CIRCUMSTANCES, CALL A FUNCTION THAT MIGHT BLOCK.

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

Parameters

• new_idle_cb: Callback to be called
• cpuid: id of the core

esp_err_t esp_register_freertos_idle_hook(esp_freertos_idle_cb_t new_idle_cb)

Register a callback to the idle hook of the core that calls this function. The callback should return true if it should be called by the idle hook once per interrupt (or FreeRTOS tick), and return false if it should be called repeatedly as fast as possible by the idle hook.

Warning

Idle callbacks MUST NOT, UNDER ANY CIRCUMSTANCES, CALL A FUNCTION THAT MIGHT BLOCK.

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

Parameters

• new_idle_cb: Callback to be called

esp_err_t esp_register_freertos_tick_hook_for_cpu(esp_freertos_tick_cb_t new_tick_cb, UBaseType_t cpuid)

Register a callback to be called from the specified core’s tick hook.

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

Parameters

• new_tick_cb: Callback to be called
• cpuid: id of the core

esp_err_t esp_register_freertos_tick_hook(esp_freertos_tick_cb_t new_tick_cb)

Register a callback to be called from the calling core’s tick hook.

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

Parameters

• new_tick_cb: Callback to be called

void esp_deregister_freertos_idle_hook_for_cpu(esp_freertos_idle_cb_t old_idle_cb, UBaseType_t cpuid)

Unregister an idle callback from the idle hook of the specified core.

Parameters

• old_idle_cb: Callback to be unregistered
• cpuid: id of the core

void esp_deregister_freertos_idle_hook(esp_freertos_idle_cb_t old_idle_cb)

Unregister an idle callback. If the idle callback is registered to the idle hooks of both cores, the idle hook will be unregistered from both cores.

Parameters

• old_idle_cb: Callback to be unregistered

void esp_deregister_freertos_tick_hook_for_cpu(esp_freertos_tick_cb_t old_tick_cb, UBaseType_t cpuid)

Unregister a tick callback from the tick hook of the specified core.

Parameters

• old_tick_cb: Callback to be unregistered
• cpuid: id of the core

void esp_deregister_freertos_tick_hook(esp_freertos_tick_cb_t old_tick_cb)

Unregister a tick callback. If the tick callback is registered to the tick hooks of both cores, the tick hook will be unregistered from both cores.

Parameters

• old_tick_cb: Callback to be unregistered

Type Definitions

typedef bool (*esp_freertos_idle_cb_t)()

typedef void (*esp_freertos_tick_cb_t)()