Stack overflow detection (method 1 and 2) in FreeRTOS

Introduction

Stack overflow detection helps catch when a program uses more memory than allowed for its stack. This prevents crashes and bugs.

When running tasks in FreeRTOS that have limited stack size.

When debugging unexpected crashes or freezes in embedded systems.

When developing safety-critical applications that must avoid memory corruption.

When optimizing memory usage to ensure tasks have enough stack but not too much.

When testing new tasks or code changes that might increase stack usage.

Syntax

FreeRTOS

/* Method 1: Using configCHECK_FOR_STACK_OVERFLOW = 1 or 2 in FreeRTOSConfig.h */

// Enable stack overflow checking in FreeRTOSConfig.h
#define configCHECK_FOR_STACK_OVERFLOW 1

// Implement the hook function in your application code
void vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName) {
    // This function is called when a stack overflow is detected
    // You can log, halt, or reset the system here
    for(;;); // Loop forever to halt
}

/* Method 2: Using pxTaskGetStackStart and manual checking */

// Example function to check stack overflow manually
void CheckTaskStackOverflow(TaskHandle_t xTask) {
    // Get stack start address
    StackType_t *stack_start = pxTaskGetStackStart(xTask);
    // Get current stack pointer
    StackType_t *stack_pointer = pxTaskGetStackPointer(xTask);
    // Compare pointers to detect overflow
    if(stack_pointer < stack_start) {
        // Stack overflow detected
    }
}

Method 1 uses FreeRTOS built-in hook and config option for automatic detection.

Method 2 requires manual checking and is less common but useful for custom needs.

Examples

This example shows method 1 with config 1, which checks overflow on task switch.

FreeRTOS

#define configCHECK_FOR_STACK_OVERFLOW 1

void vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName) {
    // Called on overflow
    printf("Stack overflow in task: %s\n", pcTaskName);
    for(;;); // Stop here
}

Method 1 with config 2 does more thorough checking on each context switch.

FreeRTOS

#define configCHECK_FOR_STACK_OVERFLOW 2

void vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName) {
    // Called on overflow
    printf("Stack overflow detected in task: %s\n", pcTaskName);
    for(;;); // Halt
}

Method 2 manually compares stack pointers to detect overflow.

FreeRTOS

void CheckTaskStackOverflow(TaskHandle_t xTask) {
    StackType_t *stack_start = pxTaskGetStackStart(xTask);
    StackType_t *stack_pointer = pxTaskGetStackPointer(xTask);
    if(stack_pointer < stack_start) {
        printf("Manual stack overflow detected\n");
    }
}

Always check if task handle is valid before checking stack.

FreeRTOS

// Edge case: Empty task handle
void CheckTaskStackOverflow(TaskHandle_t xTask) {
    if(xTask == NULL) {
        printf("Invalid task handle\n");
        return;
    }
    // Proceed with checking
}

Sample Program

This program enables method 1 stack overflow detection. It creates a task with a small stack and large local array to cause overflow. When overflow happens, the hook prints a message and halts.

FreeRTOS

#define configCHECK_FOR_STACK_OVERFLOW 1

#include "FreeRTOS.h"
#include "task.h"
#include <stdio.h>

void vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName) {
    printf("Stack overflow detected in task: %s\n", pcTaskName);
    for(;;); // Halt system
}

void vTaskFunction(void *pvParameters) {
    volatile int array[1000]; // Large array to cause overflow
    (void)array;
    while(1) {
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

int main(void) {
    TaskHandle_t xTaskHandle = NULL;
    xTaskCreate(vTaskFunction, "OverflowTask", 100, NULL, 1, &xTaskHandle);
    vTaskStartScheduler();
    // Should never reach here
    return 0;
}

Important Notes

Stack overflow detection adds some overhead but helps catch serious bugs early.

Method 1 is recommended for most users because it integrates with FreeRTOS scheduler.

Common mistake: Not enabling configCHECK_FOR_STACK_OVERFLOW or not implementing the hook.

Use stack overflow detection during development and testing to avoid crashes in production.

Time complexity: O(1) per context switch for method 1; manual checks depend on implementation.

Space complexity: Slightly increased stack size due to checking variables.

Summary

Stack overflow detection prevents tasks from corrupting memory by using too much stack.

Method 1 uses FreeRTOS config and hook for automatic detection on context switches.

Method 2 allows manual checking by comparing stack pointers but is less common.