5.2 Checking for Stack Overflow

A stack overflow is a very common source of support requests, but FreeRTOS provides some features to help debug such issues.

Stack overflow occurs when a task tries to push more elements on the stack than there is room for. The stack size is specified when a task is created. To find out how close a task is to overflowing its stack, the uxTaskGetStackHighWaterMark(TaskHandle_t xTask) function can be used. It returns the minimum of unused stack in words. If an 8-bit MCU is used, a return value of 1 will mean 1 byte. For a 32-bit MCU, 1 word means 4 bytes. To use this function, the INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in the configuration file.

It is also possible to check for stack overflow during run-time. By setting the configCHECK_FOR_STACK_OVERFLOW to 1, the kernel checks that the stack pointer remains within the valid stack space. If not, the stack overflow hook function is called. A hook function is a function that allows the application to react when something happens and provide different behavior. For example, an LED can be turned on when a stack has overflowed. Another option might be to print an error message and reboot the system. The vApplicationStackOverflowHook() function must be provided by the application.

See www.freertos.org/Stacks-and-stack-overflow-checking.html for more information about FreeRTOS and stack overflow.