Debugging Stack Overflow with Memory Analysis

1. What is a Stack Overflow?

As you know from our work with linker scripts, the stack is a region of RAM used for temporary data storage. Each time a function is called, a "stack frame" is pushed onto the stack to store:

• Local variables declared inside the function.
• The return address (where to go back to after the function finishes).
• Function arguments (depending on the calling convention).
• Saved CPU registers.

A stack overflow happens when the stack pointer (SP) moves beyond the memory region allocated for the stack. This can happen in two main ways:

1. Excessively Deep or Infinite Recursion: A function calls itself repeatedly without a proper exit condition, pushing a new stack frame each time until memory runs out.
2. Large Local Variables: A function declares a very large local variable (especially an array) that consumes all available stack space in one go.

The result is that the stack "overflows" into adjacent memory regions, corrupting whatever data was stored there—be it global variables, the heap, or another task's stack. This often leads to a HardFault when the CPU tries to use the corrupted data, such as a bogus return address.

Let's watch a video that brilliantly demonstrates these failure modes.

As you saw, a stack overflow doesn't always cause an immediate crash. It can lead to unpredictable behavior that is very difficult to debug. This is why we need specific tools to help us.

2. Static Analysis: Estimating Stack Usage

The first line of defense is to estimate how much stack your application might need before you even run it. STM32CubeIDE includes a Static Stack Analyzer for this purpose. It analyzes your compiled code and calculates the maximum stack depth for any given call chain.

Configuring the Analyzer

To use the analyzer, you first need to tell the GCC compiler to generate stack usage information.

1. In your project explorer, right-click the project and go to Properties.
2. Navigate to C/C++ Build > Settings > Tool Settings tab > MCU GCC Compiler > Miscellaneous.
3. In the "Other flags" field, add the flag: -fstack-usage.
4. Click Apply and Close.

After you rebuild your project, you can view the results.

The analyzer tells you the "local cost" of each function (how much stack it uses itself) and can show you the "maximum stack cost" for the entire call graph, giving you a good baseline for the required stack size.

Setting the Main Stack Size

The total size of the main stack is defined in your project's linker script. Based on the static analysis (and adding a healthy safety margin), you can adjust this value.

Remember that static analysis is an estimate. It can't account for interrupt nesting or other complex runtime behaviors, which is why we also need dynamic analysis.

3. Dynamic Analysis in a FreeRTOS Environment

In a FreeRTOS application, the situation is more complex and also more powerful. Each task has its own stack, allocated from the FreeRTOS heap. The main stack (defined in the linker script) is typically only used by interrupt service routines (ISRs).

FreeRTOS provides excellent tools for runtime stack overflow detection and analysis.

Enabling Stack Overflow Detection

FreeRTOS can automatically check for stack overflows on every context switch. You can enable this feature in FreeRTOSConfig.h.

For robust detection, Method 2 is strongly recommended. When an overflow is detected, the RTOS will call the vApplicationStackOverflowHook() function. This is where you can put your debugging code, such as printing an error message, blinking a "fault" LED, or resetting the device.

Practical Task:

1. Open your FreeRTOSConfig.h file (found under Middlewares/Third_Party/FreeRTOS/Source/include).
2. Set configCHECK_FOR_STACK_OVERFLOW to 2.
3. Add the following vApplicationStackOverflowHook function to your main.c:

/* In main.c, outside of any other function */

void vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName)
{
   /* This function will be called if a stack overflow is detected. */
   printf("!!! STACK OVERFLOW DETECTED IN TASK: %s !!!\r\n", pcTaskName);
   
   // Halt the system for debugging. In a real product, you might log
   // the error and reset.
   while(1)
   {
       // Toggle an LED rapidly to indicate a fatal error
       HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13);
       HAL_Delay(100);
   }
}

Measuring Stack Usage with High Water Mark

How do you know if a task's stack is almost full? FreeRTOS provides the uxTaskGetStackHighWaterMark() function. It returns the minimum amount of free stack space (in words) that a task has had since it was created. A low water mark is a strong warning sign that you need to increase that task's stack size.

4. Advanced Debugging: From HardFault to Root Cause

Sometimes, a stack overflow won't be caught by the FreeRTOS hook. A severe corruption can smash critical data so badly that the CPU triggers a HardFault before the RTOS scheduler can even run its check. When you halt the debugger, you'll find yourself inside the generic HardFault_Handler with a meaningless call stack.

This is where professional-grade debugging techniques are required to analyze the CPU's fault registers and manually reconstruct the state of the system at the moment of the crash.

This technique of analyzing fault registers is what separates a junior developer from a senior one. When your program ends up in HardFault_Handler, checking the CFSR for stacking error flags should be one of your first steps.

Conclusion

In this lesson, you've explored the dangerous world of stack overflows and armed yourself with a suite of tools to combat them.

Key Takeaways:

• Stack overflows are caused by deep recursion or large local variables and lead to data corruption and system crashes.
• Static Analysis (STM32CubeIDE's Static Stack Analyzer with -fstack-usage) helps you estimate stack requirements before runtime.
• In FreeRTOS, each task has its own stack. You can enable configCHECK_FOR_STACK_OVERFLOW and implement vApplicationStackOverflowHook for robust runtime detection.
• The uxTaskGetStackHighWaterMark() function is essential for monitoring and tuning the stack size of each task.
• When a HardFault occurs, analyzing the CPU's fault registers (CFSR) can reveal if a stacking error was the root cause, allowing you to begin a more focused investigation.

Properly sizing and monitoring your stack(s) is not optional; it is fundamental to building reliable and professional embedded firmware.

Preview of the Next Lesson:
With our system now more stable and robust against memory issues, we can turn our attention to efficiency. The next module, Power Management and Optimization, will begin by teaching you how to identify and use the MCU's different low-power modes to drastically reduce energy consumption—a critical requirement for battery-powered and automotive applications.