Homepage  

Stack Usage and Stack Overflow Checking
[Configuration]

---

---

Stack Usage

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.org 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 and the stack grows down from high memory. Also, some processors could generate a fault or exception in response to a stack corruption before the 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 *pxTask, signed portCHAR *pcTaskName );

The pxTask 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.

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 kernel has swapped the task out of the Running state (when the stack contains the task context). At this point the kernel can check that the processor stack pointer remains within the valid stack space. The stack overflow hook function is called should the stack pointer contain an invalid value.

This method is quick but not guaranteed to catch all stack overflows. To use this method only set configCHECK_FOR_STACK_OVERFLOW to 1.

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 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) 2003 - 2008 Richard Barry
Any and all data, files, source code, html content and documentation included in the FreeRTOS distribution or available on this site are the exclusive property of Richard Barry. See the files license.txt (included in the distribution) and this copyright notice for more information. FreeRTOS^TM and FreeRTOS.org^TM are trade marks of Richard Barry.