Chapter 280: Memory Leak Detection and Prevention

Chapter Objectives

By the end of this chapter, you will be able to:

• Understand what memory leaks are and their critical impact on embedded system stability.
• Learn about ESP-IDF‘s built-in heap memory tracing and debugging features.
• Configure your project to enable heap tracing for leak detection.
• Use heap analysis functions to monitor memory usage and detect leaks at runtime.
• Analyze heap information to pinpoint the exact source of a memory leak in your code.
• Apply best practices for dynamic memory management to prevent leaks.

Introduction

In the resource-constrained world of embedded systems, every byte of RAM is precious. Unlike desktop applications that can rely on gigabytes of virtual memory, an ESP32 application has a finite and often small amount of heap memory to work with. Proper memory management is not just good practice; it is essential for long-term stability.

One of the most insidious bugs in C programming is the memory leak. This occurs when a program allocates a block of memory on the heap but fails to release it when it’s no longer needed. A small leak might go unnoticed at first, but over hours, days, or weeks of continuous operation, these lost bytes accumulate. Eventually, the system runs out of available memory, malloc calls begin to fail, and the device crashes.

Fortunately, ESP-IDF provides a powerful set of debugging tools designed specifically to help you find and fix these elusive bugs. This chapter will teach you how to become a memory detective, using heap tracing tools to hunt down leaks and ensure your application remains robust and reliable over its entire lifetime.

Theory

What is a Memory Leak?

A memory leak is a portion of memory that has been allocated from the heap but is no longer accessible or referenced by the program. Since there are no more pointers pointing to this memory block, the program has lost the ability to use or free it. From the system’s perspective, this memory is still “in use” and cannot be allocated to anyone else.

Analogy: The Library of Memory

Imagine the heap is a library, and memory blocks are books. When a task needs memory, it “borrows” a book (malloc). When it’s done, it’s supposed to “return” the book (free) so others can use it. A memory leak is like a task borrowing a book, taking it back to its desk, and then losing the library card that tracks the loan. The book is now stuck on the desk, unusable by anyone else, and the library has one fewer book on its shelves. If this happens repeatedly, the library eventually runs out of books.

graph LR
    subgraph "Heap Memory (The Library)"
        direction LR
        FreeBlocks[("Free Memory<br><b>(Books on Shelf)</b>")]
        AllocatedBlocks[("Allocated Memory<br><b>(Borrowed Books)</b>")]
    end

    subgraph "Application (The Borrower)"
        Task[("Task/Function")]
        Pointer[/"Pointer<br><b>(Library Card)</b>"/]
    end

    subgraph "Correct Usage"
    direction LR
        A[Start] --> B{"Task needs memory"};
        B -- "1- malloc()" --> C[Pointer points to<br>newly allocated block];
        C -- "2- Use memory" --> D{"Task is done<br>with memory"};
        D -- "3- free()" --> E[Memory block is returned<br>to the free list];
        E --> F((End));
    end
    
    subgraph "Memory Leak Scenario"
    direction LR
        LeakStart[Start] --> LeakA{"Task needs memory"};
        LeakA -- "1- malloc()" --> LeakB[Pointer points to<br>allocated block];
        LeakB -- "2- Pointer is lost<br>(overwritten, goes out of scope)" --> LeakC{"Orphaned Memory Block<br><b>(Lost Book)</b>"};
        LeakC --> LeakEnd((Leak! Memory is not freed));
    end

    classDef default fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF
    classDef startNode fill:#EDE9FE,stroke:#5B21B6,stroke-width:2px,color:#5B21B6
    classDef endNode fill:#D1FAE5,stroke:#059669,stroke-width:2px,color:#065F46
    classDef decisionNode fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#92400E
    classDef errorNode fill:#FEE2E2,stroke:#DC2626,stroke-width:1px,color:#991B1B
    
    class A,LeakStart startNode
    class F endNode
    class LeakEnd errorNode
    class B,D,LeakA decisionNode
    class C,E,LeakB,LeakC default

Memory leaks only occur with dynamically allocated memory from the heap (using functions like malloc, calloc, realloc). Memory allocated on the stack (local variables within functions) is managed automatically by the compiler and is not susceptible to leaks.

ESP-IDF Heap Memory Debugging

The ESP-IDF build system includes a sophisticated heap debugging framework that can be enabled via menuconfig. When activated, it intercepts calls to standard memory allocation functions. This allows it to record metadata about each allocation, a process known as heap tracing.

Depending on the configuration level, the heap tracer can:

• Add Canaries (Poisoning): It can write known patterns (called “canaries” or “poison”) into the areas just before and after an allocated block. If your code writes outside its allocated buffer (a buffer overflow or underflow), it will corrupt this canary. The system can then detect this corruption when the block is freed, immediately alerting you to the bug. This also helps detect “use-after-free” errors.
• Track Allocations: For leak detection, the tracer records information about every single memory block that is currently allocated. This metadata typically includes the size of the block and, most importantly, the address of the code that called malloc.

By periodically inspecting this list of active allocations, we can identify memory blocks that persist when they should have been freed, thereby detecting a leak.

Pinpointing the Source

Once we know a block of memory has been leaked, the heap tracer gives us the final clue we need: the address of the caller. This is just a raw memory address (e.g., 0x400d1234). To make it useful, we need to translate this address back to a human-readable file and line number. This is done using a command-line utility called addr2line, which uses the debug information stored in the project’s compiled .elf file to perform the translation.

Practical Example: Hunting Down a Leak

Let’s write a simple application with a deliberate memory leak and use the ESP-IDF tools to find it.

Step 1: Enable Heap Tracing in menuconfig

1. Run idf.py menuconfig.
2. Navigate to Component config -> Heap Memory Debugging.
3. Set “Heap newlib” to ([*]) Enable heap tracing.
4. Set the “Heap tracing mode” to (Basic (corruptions and leaks)) Enable basic heap tracing. This provides a good balance of features without excessive performance overhead for this example.
5. Save and exit.

Step 2: Write the Leaky Application

Create a new project and replace the contents of main.c. This code creates one task that leaks memory and a second task that monitors the heap.

main/main.c

#include <stdio.h>
#include <string.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_heap_caps.h"

#define LEAKY_BLOCK_SIZE 128

// This task allocates memory in a loop but never frees it.
void leaky_task(void *pvParameters)
{
    printf("Leaky task started. I will leak %d bytes every 2 seconds.\n", LEAKY_BLOCK_SIZE);
    while (1) {
        // Deliberately leak memory
        char *leaky_buffer = malloc(LEAKY_BLOCK_SIZE);

        if (leaky_buffer != NULL) {
            // Write something to the buffer to make it seem useful
            strcpy(leaky_buffer, "This is a memory leak!");
        } else {
            printf("Leaky task: malloc failed! We are out of memory.\n");
        }
        
        // We "forget" to call free(leaky_buffer);

        vTaskDelay(pdMS_TO_TICKS(2000));
    }
}

// This task periodically prints heap information.
void heap_monitoring_task(void *pvParameters)
{
    printf("Heap monitoring task started.\n");
    int iteration = 0;

    while (1) {
        vTaskDelay(pdMS_TO_TICKS(10000)); // Print info every 10 seconds
        iteration++;

        printf("\n--- Heap Status (Iteration %d) ---\n", iteration);
        printf("Free heap size: %d bytes\n", heap_caps_get_free_size(MALLOC_CAP_DEFAULT));
        printf("Largest free block: %d bytes\n", heap_caps_get_largest_free_block(MALLOC_CAP_DEFAULT));
        
        // For leak detection, we dump all allocated blocks.
        // This is the most important part for finding the source.
        printf("\nDumping all allocated heap blocks:\n");
        heap_caps_dump_all();
        printf("------------------------------------\n");
    }
}

void app_main(void)
{
    // Give the monitoring task a higher priority to ensure it can run
    xTaskCreate(&heap_monitoring_task, "monitor_task", 4096, NULL, 6, NULL);
    xTaskCreate(&leaky_task, "leaky_task", 2048, NULL, 5, NULL);
}

Step 3: Build, Flash, and Observe

1. Run idf.py build to compile the project. The output .elf file will be at build/memory_leak_example.elf. We will need this file later.
2. Run idf.py -p <PORT> flash monitor to flash the device and watch the output.

You will see the “Free heap size” decrease with every report from the monitoring task. More importantly, the output of heap_caps_dump_all() will grow longer.

Step 4: Analyze the Heap Dump

After a few iterations, the output from heap_caps_dump_all() will show multiple identical-looking blocks.

...
0x3ffb8a00    64 bytes (0x3ffb8a40)    alloc'd by task leaky_task @ 0x400d1a4c:0x400d15e2
0x3ffb8a50    128 bytes (0x3ffb8ad0)   alloc'd by task leaky_task @ 0x400d1a4c:0x400d15e2  <-- OUR LEAK
0x3ffb8ae0    128 bytes (0x3ffb8b60)   alloc'd by task leaky_task @ 0x400d1a4c:0x400d15e2  <-- OUR LEAK
0x3ffb8b70    128 bytes (0x3ffb8bf0)   alloc'd by task leaky_task @ 0x400d1a4c:0x400d15e2  <-- OUR LEAK
...

Notice the repeating lines: 128 bytes … alloc’d by task leaky_task @ 0x400d1a4c:0x400d15e2.

This is our leak. The system is telling us that the leaky_task allocated these blocks, and the call came from the code address 0x400d1a4c.

Step 5: Pinpoint the Source with addr2line

Now we translate that address into a file and line number.

1. Open a new terminal (do not close the monitor).
2. Source the ESP-IDF environment (get.sh or export.sh).
3. Run the addr2line command. The name depends on your chip’s architecture.
   • For Xtensa (ESP32, S2, S3): xtensa-esp32-elf-addr2line
   • For RISC-V (ESP32-C3, C6, H2): riscv32-esp-elf-addr2line
4. Execute the command with your .elf file and the address from the log:# For ESP32/S2/S3 xtensa-esp32-elf-addr2line -e build/your_project_name.elf 0x400d1a4c # Example output: # /path/to/your/project/main/main.c:20

The tool points directly to line 20 of main.c, which is exactly where our malloc call is. The leak has been found!

Variant Notes

The heap memory debugging framework is a core software component of ESP-IDF. Its functionality and API are identical across all ESP32 variants.

• API Consistency: Functions like heap_caps_dump_all() and heap_caps_get_free_size() work the same way regardless of the target.
• menuconfig Options: The configuration options under Heap Memory Debugging are the same for all chips.
• addr2line Tool: The only minor difference is the prefix for the addr2line utility, which changes based on the CPU architecture (xtensa-esp32-elf- for Xtensa cores, riscv32-esp-elf- for RISC-V cores).

The total amount of available heap will differ significantly between variants, but the tools you use to debug it remain constant.

Common Mistakes & Troubleshooting Tips

Exercises

1. The Leaky String Concatenator: Write a function char* create_greeting(const char *name) that should return a new string “Hello, [name]!”. Implement it by first allocating memory for “Hello, “, then allocating a new, larger buffer, copying “Hello, ” and the name into it, and returning the new buffer. “Forget” to free the initial “Hello, ” buffer. Use heap tracing to find this internal leak.
2. Fixing a Double Free: Enable “Comprehensive” heap poisoning in menuconfig. Write a function that allocates a pointer, frees it, and then accidentally tries to free it a second time. Observe the crash and the panic handler message, which should point you to the double-free error.
3. Fixing Use-After-Free: With heap poisoning still enabled, write a function that allocates a buffer, frees it, and then tries to write data into the freed buffer (e.g., strcpy(freed_buffer, "test")). Observe the crash caused by the corrupted heap canaries.
4. Creating a Resource Wrapper: To practice leak prevention, create a simple C struct that manages a dynamically allocated buffer. Write create_wrapper, destroy_wrapper, get_data, and set_data functions. This mimics how objects in higher-level languages prevent leaks through constructors and destructors. Test your wrapper to ensure it doesn’t leak.

Summary

• A memory leak is allocated heap memory that is no longer referenced and cannot be freed, causing a gradual loss of system RAM.
• Leaks are a primary cause of long-term instability and crashes in embedded systems.
• ESP-IDF provides powerful Heap Memory Debugging tools, configurable in menuconfig.
• Heap tracing records the source location of every memory allocation.
• The heap_caps_dump_all() function prints a list of all currently allocated blocks and their origins.
• The addr2line utility translates a memory address from the heap dump into a file and line number, pinpointing the leak’s source.
• Heap debugging adds overhead and must be disabled for production builds.

Further Reading

• ESP-IDF Heap Memory Debugging Documentation: https://docs.espressif.com/projects/esp-idf/en/v5.2.1/esp32/api-guides/heap-memory-debugging.html
• ESP-IDF Heap Memory Allocation API: https://docs.espressif.com/projects/esp-idf/en/v5.2.1/esp32/api-reference/system/mem_alloc.html
• Common C Memory Errors: A general guide to common pitfalls in C memory management. (Example: https://www.acodersjourney.com/top-5-c-memory-mistakes/)