Stack Usage and Stack Overflow Checking
Each task maintains its own stack. The memory used by the task stack is allocated automatically when the task is created, and dimensioned by a parameter
passed to the xTaskCreate() API function.
Stack overflow is a very common cause of application instability. FreeRTOS therefore provides two optional mechanisms that can be used to assist
in the detection and correction of just such an occurrence. The option used is configured using the
configCHECK_FOR_STACK_OVERFLOW configuration constant.
Note that these options are only available on architectures where the memory map is not segmented.
Also, some processors could generate a fault or exception in response to a stack corruption before the RTOS kernel overflow check can occur.
The application must provide a stack overflow hook function if configCHECK_FOR_STACK_OVERFLOW is not set to 0. The hook function must
be called vApplicationStackOverflowHook(), and have the prototype below:
void vApplicationStackOverflowHook( xTaskHandle xTask,
signed portCHAR *pcTaskName );
The xTask and pcTaskName parameters pass to the hook function the handle and name of the offending task respectively.
Note however, depending on the severity of the overflow, these parameters could themselves be corrupted, in which case the
pxCurrentTCB variable can be inspected directly.
Stack overflow checking introduces a context switch overhead so its use is only recommended during the development or testing phases.
Stack Overflow Detection - Method 1
It is likely that the stack will reach its greatest (deepest) value after the RTOS kernel has swapped the task out of the Running
state because this is when the stack will contain the task context. At this point the RTOS kernel can check that the processor stack pointer remains
within the valid stack space. The stack overflow hook function is called if the stack pointer contain a value that is outside of the
valid stack range.
This method is quick but not guaranteed to catch all stack overflows.
Set configCHECK_FOR_STACK_OVERFLOW to 1 to use this method only.
Stack Overflow Detection - Method 2
When a task is first created its stack is filled with a known value. When swapping a task out of the Running state the RTOS kernel can
check the last 16 bytes within the valid stack range to ensure that these known values have not been overwritten by the task or
interrupt activity. The stack overflow hook function is called should any of these 16 bytes not remain at their initial value.
This method is less efficient than method one, but still fairly fast. It is very likely to catch stack overflows but is still
not guaranteed to catch all overflows.
To use this method in combination with method 1 set configCHECK_FOR_STACK_OVERFLOW to 2. It is not possible to use only this method.
Copyright (C) 2004-2010 Richard Barry. Copyright (C) 2010-2013 Real Time Engineers Ltd.
Any and all data, files, source code, html content and documentation included in the FreeRTOSTM distribution or available on this site are the exclusive property of Real Time Engineers Ltd..
See the files license.txt (included in the distribution) and this copyright notice for more information. FreeRTOSTM and FreeRTOS.orgTM are trade marks of Real Time Engineers Ltd.