| Hook API Function | Description |
|---|---|
| vApplicationIdleHook() | Runs user-defined background or low-power code during Idle task execution |
| vApplicationTickHook() | Runs from the RTOS tick interrupt |
| vApplicationMallocFailedHook() | Called when pvPortMalloc() cannot allocate memory |
| vApplicationStackOverflowHook() | Called when a task stack overflow is detected |
| vApplicationDaemonTaskStartupHook() | Runs once when the Timer Service/Daemon task starts |
The idle task hook is a user-defined callback function that FreeRTOS executes repeatedly whenever no other task is ready to run. It is implemented as vApplicationIdleHook() and enabled by setting configUSE_IDLE_HOOK to 1 in FreeRTOSConfig.h. The hook can be used for low-priority background operations, such as entering a low-power mode, collecting system statistics, or performing simple maintenance tasks. It must never block, call functions that may block, or perform lengthy processing, because doing so prevents the idle task from running normally and may delay the cleanup of deleted tasks.
void vApplicationIdleHook(void)
// ---------------------- Example ----------------------
#define configUSE_TICKLESS_IDLE 0
#define configUSE_IDLE_HOOK 1
#define configIDLE_SHOULD_YIELD 1
void BeforeEnterSleep(void)
{
__HAL_RCC_GPIOB_CLK_SLEEP_DISABLE();
__HAL_RCC_GPIOC_CLK_SLEEP_DISABLE();
__HAL_RCC_GPIOD_CLK_SLEEP_DISABLE();
__HAL_RCC_GPIOE_CLK_SLEEP_DISABLE();
__HAL_RCC_GPIOF_CLK_SLEEP_DISABLE();
__HAL_RCC_GPIOG_CLK_SLEEP_DISABLE();
__HAL_RCC_GPIOH_CLK_SLEEP_DISABLE();
}
void AfterExitSleep(void)
{
__HAL_RCC_GPIOB_CLK_SLEEP_ENABLE();
__HAL_RCC_GPIOC_CLK_SLEEP_ENABLE();
__HAL_RCC_GPIOD_CLK_SLEEP_ENABLE();
__HAL_RCC_GPIOE_CLK_SLEEP_ENABLE();
__HAL_RCC_GPIOF_CLK_SLEEP_ENABLE();
__HAL_RCC_GPIOG_CLK_SLEEP_ENABLE();
__HAL_RCC_GPIOH_CLK_SLEEP_ENABLE();
}
void vApplicationIdleHook(void)
{
BeforeEnterSleep();
__DSB();
__WFI();
__ISB();
AfterExitSleep();
}vApplicationMallocFailedHook() is a user-defined FreeRTOS hook function that is called whenever a dynamic memory allocation request fails, such as when pvPortMalloc(), xTaskCreate(), or another kernel object creation function cannot obtain enough heap memory. To enable it, set configUSE_MALLOC_FAILED_HOOK to 1 in FreeRTOSConfig.h. The hook is commonly used to record diagnostic information, trigger an assertion, illuminate an error indicator, or halt execution for debugging. Because the system may have very little memory remaining, the hook should avoid performing additional dynamic memory allocations.
void vApplicationMallocFailedHook(void)
// ---------------------- Example ----------------------
#define configUSE_MALLOC_FAILED_HOOK 1
void vApplicationMallocFailedHook(void)
{
taskDISABLE_INTERRUPTS();
for (;;) {}
}vApplicationStackOverflowHook() is a user-defined FreeRTOS hook function that is called when the kernel detects that a task has exceeded its allocated stack space. To enable stack-overflow checking, set configCHECK_FOR_STACK_OVERFLOW to 1 or 2 in FreeRTOSConfig.h, with 2 providing more thorough checking. The hook receives the handle and name of the affected task, allowing the application to record diagnostic information, trigger an assertion, illuminate an error LED, or halt execution for debugging. Because stack corruption may already have occurred, the hook should avoid complex operations and should normally stop the system so the cause can be investigated.
void vApplicationStackOverflowHook(TaskHandle_t xTask,
char *pcTaskName)
// ---------------------- Example ----------------------
#define INCLUDE_uxTaskGetStackHighWaterMark 1
#define configCHECK_FOR_STACK_OVERFLOW 2
volatile const char *g_overflow_task_name = NULL;
volatile TaskHandle_t g_overflow_task_handle = NULL;
void vApplicationStackOverflowHook(TaskHandle_t xTask,
char *pcTaskName)
{
g_overflow_task_handle = xTask;
g_overflow_task_name = pcTaskName; // points to the task name string
taskDISABLE_INTERRUPTS();
for (;;) {
__NOP(); // set breakpoint here and inspect g_overflow_task_name
// LED may also be turned on or toggled here
}
}Back to top of the page