Chapter 244: Advanced DMA Operations in ESP32

Chapter Objectives

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

• Explain the concept of Direct Memory Access (DMA) and its importance in high-performance embedded systems.
• Differentiate between CPU-driven data transfers and DMA-driven transfers.
• Understand the architecture of the General DMA (GDMA) controller found in modern ESP32 variants.
• Allocate DMA-capable memory buffers.
• Configure and use a DMA channel for a basic memory-to-memory transfer.
• Integrate DMA with peripherals like SPI for high-throughput communication.
• Use DMA completion callbacks to manage asynchronous transfers.
• Identify and troubleshoot common DMA-related issues.

Introduction

As embedded applications grow in complexity, handling large amounts of data becomes a significant challenge. Consider streaming audio, receiving data from a high-resolution camera, or writing to a graphical display. In these scenarios, the CPU could spend the majority of its time simply moving bytes from a peripheral to memory, or vice-versa. This process, known as Programmed I/O (PIO), is inefficient and leaves little time for the CPU to perform its primary tasks, such as running application logic, managing connectivity, or responding to user input.

This is where Direct Memory Access (DMA) provides an elegant and powerful solution. A DMA controller is a specialized hardware unit within the SoC designed to handle data transfers independently of the main CPU. By offloading this work, the DMA controller frees the CPU to focus on more complex computational tasks, dramatically improving overall system performance and efficiency.

Mastering DMA is a hallmark of an advanced embedded developer. It is the key to unlocking the full performance potential of the ESP32 for data-intensive applications.

Theory

The CPU Bottleneck: Programmed I/O (PIO)

Without DMA, the CPU is at the center of every data transfer. To read a block of data from a peripheral (like an SPI device), the CPU must execute a loop:

1. Read a byte/word from the peripheral’s data register.
2. Write that byte/word to a location in memory.
3. Increment the memory address pointer.
4. Repeat until all data is transferred.

During this entire process, the CPU is 100% occupied with the mundane task of byte-shuttling. It cannot run other tasks or respond to other events.

%%{ init: { 'theme': 'base', 'themeVariables': { 'fontFamily': 'Open Sans' } } }%%
graph TD
    subgraph System Bus
        direction TB
        CPU(<b>CPU</b><br><i>100% Occupied</i>)
        MEM([<b>Memory</b><br>e.g., RAM])
        PERI((<b>Peripheral</b><br>e.g., SPI Device))
    end

    PERI -- "1- Read Data Register" --> CPU
    CPU -- "2- Write to Memory" --> MEM
    CPU -- "3- Loop until done" --> CPU

    classDef cpu fill:#FEE2E2,stroke:#DC2626,stroke-width:2px,color:#991B1B
    classDef default fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF

    class CPU cpu
    class MEM,PERI default

The Solution: Direct Memory Access (DMA)

A DMA controller acts as a subordinate co-processor. The CPU initiates a transfer by configuring the DMA controller with four key pieces of information:

1. Source Address: Where to read the data from.
2. Destination Address: Where to write the data to.
3. Transfer Size: How much data to move.
4. Transfer Trigger: What event should start the transfer (e.g., a signal from a peripheral).

Once configured, the CPU can command the DMA controller to start. The DMA controller then takes over, accessing the system bus to move data directly from the source to the destination. While the DMA transfer is in progress, the CPU is completely free to execute other code. When the transfer is complete, the DMA controller can notify the CPU via an interrupt.

%%{ init: { 'theme': 'base', 'themeVariables': { 'fontFamily': 'Open Sans' } } }%%
graph TB
    subgraph System Components
        CPU(<b>CPU</b><br><i>Free for other tasks</i>)
        DMA(<b>DMA Controller</b>)
        MEM([<b>Memory</b>])
        PERI((<b>Peripheral</b>))
    end

    CPU -- "1- Configure Transfer<br>(Source, Dest, Size)" --> DMA;
    DMA -- "3- Interrupt<br>(Transfer Complete)" --> CPU;
    
    subgraph Data_Path [DMA Transfer - No CPU Involvement]
        direction LR
        PERI_path((Peripheral))
        DMA_path(DMA)
        MEM_path([Memory])
        PERI_path -- "<b>2- Data Bus</b>" --> DMA_path;
        DMA_path -- "<b>Direct Transfer</b>" --> MEM_path;
    end
    
    style Data_Path fill:none,stroke:#1E40AF,stroke-dasharray: 5 5

    classDef cpu_init fill:#EDE9FE,stroke:#5B21B6,stroke-width:2px,color:#5B21B6
    classDef cpu_done fill:#D1FAE5,stroke:#059669,stroke-width:2px,color:#065F46
    classDef dma fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF
    classDef path fill:#DBEAFE,stroke:#2563EB,stroke-width:2px,color:#1E40AF
    
    class CPU cpu_init
    class DMA,MEM,PERI dma
    class DMA_path,MEM_path,PERI_path path

Analogy: Imagine you are a busy office manager (the CPU). You need to make 1,000 copies of a report.

• PIO approach: You go to the photocopier yourself and stand there for an hour, feeding each page. During this time, you can’t answer emails or take phone calls.
• DMA approach: You ask an administrative assistant (the DMA controller) to make the copies for you. You give them the report (source), tell them where to put the copies (destination), and how many to make (size). You then go back to your desk and continue your important work. The assistant notifies you when the job is done.

DMA on ESP32: GDMA and Legacy DMA

ESP32 variants use different DMA architectures:

• Legacy DMA (ESP32): The original ESP32 has DMA capabilities, but they are tightly integrated into specific peripherals (e.g., SPI DMA, I2S DMA). There is no single, centralized DMA controller.
• General DMA (GDMA) (ESP32-S2, S3, C3, C6, H2): Newer variants feature a much more flexible General Purpose DMA controller. This is a pool of DMA channels that can be flexibly assigned to various peripherals as needed. ESP-IDF provides the GDMA driver to manage these resources.

For modern development, we will focus on the GDMA driver, as it is the standard for all current and future Espressif chips. High-level drivers like the SPI driver will use the GDMA driver under the hood on compatible chips.

DMA Descriptors and Linked Lists

For simple transfers, the DMA can be configured with a single source/destination pair. For more complex scenarios, GDMA uses descriptors. A descriptor is a small structure in memory that defines a single block of a transfer (buffer address, size, etc.).

The real power comes from chaining these descriptors together to form a linked list. This allows the DMA controller to perform complex, “scatter-gather” operations without any CPU intervention. For example, it can read data from a single peripheral buffer and scatter it into multiple, non-contiguous buffers in RAM, or gather data from various locations into a single stream.

%%{ init: { 'theme': 'base', 'themeVariables': { 'fontFamily': 'Open Sans' } } }%%
graph LR
    subgraph "DMA Controller Processing Chain"
        D1["<b>Descriptor 1</b><br><hr>Buffer Ptr: 0x3FFB1000<br>Size: 1024 bytes<br>Next Ptr: <i>Points to D2</i>"]
        D2["<b>Descriptor 2</b><br><hr>Buffer Ptr: 0x3FFB4000<br>Size: 512 bytes<br>Next Ptr: <i>Points to D3</i>"]
        D3["<b>Descriptor 3</b><br><hr>Buffer Ptr: 0x3FFB2800<br>Size: 1024 bytes<br>Next Ptr: <b>NULL</b>"]
        END((<b>End of Transfer</b><br><i>Generates Interrupt</i>))

        D1 --> D2 --> D3 --> END
    end

    subgraph "Data Buffers in RAM (Non-Contiguous)"
        B1[Buffer 1<br>1024 bytes @ 0x3FFB1000]
        B2[Buffer 2<br>512 bytes @ 0x3FFB4000]
        B3[Buffer 3<br>1024 bytes @ 0x3FFB2800]
    end

    D1 -.-> B1
    D2 -.-> B2
    D3 -.-> B3

    classDef desc fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF
    classDef buf fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#92400E
    classDef end_node fill:#D1FAE5,stroke:#059669,stroke-width:2px,color:#065F46

    class D1,D2,D3 desc
    class B1,B2,B3 buf
    class END end_node

Practical Examples

Let’s explore how to use the GDMA driver.

Warning: DMA buffers must be allocated in a specific region of RAM that the DMA controller can access. You cannot use standard malloc. You must use heap_caps_malloc with the MALLOC_CAP_DMA flag.

Example 1: Memory-to-Memory Transfer

This is the “Hello, World!” of DMA. We will use a DMA channel to copy data from one buffer to another, a task normally done with memcpy. This example isolates the DMA logic from any peripheral complexity.

1. Create a New Project

Create a new ESP-IDF project in VS Code. This example will work on any ESP32 variant that supports GDMA (S2, S3, C3, C6, H2).

2. Write the Application Code

Replace the contents of main/main.c with the following code.

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

static const char *TAG = "DMA_M2M_EXAMPLE";

#define BUFFER_SIZE 512

// Callback function, called by the ISR when a DMA transfer is complete
static bool IRAM_ATTR dma_transfer_done_callback(gdma_channel_handle_t dma_chan, gdma_event_data_t *event_data, void *user_data)
{
    // A semaphore would be used here in a real application to unblock a task.
    // For this simple example, we'll just log from the callback.
    // Note: Logging from an ISR is generally not recommended in production code.
    ets_printf("DMA transfer finished.\n");
    return true;
}

void app_main(void)
{
    ESP_LOGI(TAG, "Initializing DMA for memory-to-memory copy...");

    // 1. Allocate DMA-capable buffers
    char *src_buf = heap_caps_malloc(BUFFER_SIZE, MALLOC_CAP_DMA);
    if (!src_buf) {
        ESP_LOGE(TAG, "Failed to allocate source buffer");
        return;
    }
    char *dest_buf = heap_caps_malloc(BUFFER_SIZE, MALLOC_CAP_DMA);
    if (!dest_buf) {
        ESP_LOGE(TAG, "Failed to allocate destination buffer");
        free(src_buf);
        return;
    }

    // 2. Populate the source buffer
    for (int i = 0; i < BUFFER_SIZE; i++) {
        src_buf[i] = (i % 256);
    }
    // Clear destination buffer to ensure we see the copied data
    memset(dest_buf, 0, BUFFER_SIZE);

    // 3. Get a DMA channel
    gdma_channel_handle_t tx_channel = NULL;
    gdma_channel_alloc_config_t tx_chan_config = {
        .direction = GDMA_CHANNEL_DIRECTION_TX, // M2M transfers are considered TX
    };
    ESP_ERROR_CHECK(gdma_new_channel(&tx_chan_config, &tx_channel));
    ESP_LOGI(TAG, "DMA channel allocated");

    // 4. Register the completion callback
    gdma_event_callbacks_t cbs = {
        .on_trans_done = dma_transfer_done_callback,
    };
    ESP_ERROR_CHECK(gdma_register_event_callbacks(tx_channel, &cbs, NULL));

    // 5. Start the DMA transfer
    ESP_LOGI(TAG, "Starting DMA transfer...");
    ESP_ERROR_CHECK(gdma_start(tx_channel, (uint32_t)src_buf, (uint32_t)dest_buf, BUFFER_SIZE));

    // In a real app, a task would now block on a semaphore given by the callback.
    // Here, we'll just delay to allow the transfer to finish.
    vTaskDelay(pdMS_TO_TICKS(100));

    // 6. Verify the data
    if (memcmp(src_buf, dest_buf, BUFFER_SIZE) == 0) {
        ESP_LOGI(TAG, "Success! Data in destination buffer matches source buffer.");
    } else {
        ESP_LOGE(TAG, "Error! Data mismatch.");
    }

    // 7. Clean up
    ESP_ERROR_CHECK(gdma_del_channel(tx_channel));
    free(src_buf);
    free(dest_buf);
    ESP_LOGI(TAG, "Example finished.");
}

Code Explanation:

• heap_caps_malloc(..., MALLOC_CAP_DMA): We allocate our source and destination buffers in DMA-capable memory. This is non-negotiable.
• gdma_new_channel(): We request a GDMA channel from the driver. For M2M, the direction is always GDMA_CHANNEL_DIRECTION_TX.
• gdma_register_event_callbacks(): We register a callback function that the driver’s interrupt handler will call when our transfer is complete. This is the asynchronous way to know a DMA operation has finished. Note the IRAM_ATTR on the callback, which places it in IRAM for faster execution from an ISR.
• gdma_start(): This is the command that initiates the transfer. We provide the channel handle, source address, destination address, and size. This function returns immediately, and the transfer proceeds in the background.
• Verification: After a short delay to ensure completion, we use memcmp to prove that the data was copied correctly by the DMA controller, not the CPU.

3. Build, Flash, and Monitor

Run the “Build, Flash, and Monitor” task.

Observe the Output:

I (281) DMA_M2M_EXAMPLE: Initializing DMA for memory-to-memory copy...
I (291) DMA_M2M_EXAMPLE: DMA channel allocated
I (291) DMA_M2M_EXAMPLE: Starting DMA transfer...
DMA transfer finished.
I (301) DMA_M2M_EXAMPLE: Success! Data in destination buffer matches source buffer.
I (301) DMA_M2M_EXAMPLE: Example finished.

The output confirms that the DMA transfer was initiated and the callback was triggered upon completion, with the data successfully copied.

Variant Notes

DMA capabilities are one of the key areas of difference between ESP32 variants.

Tip: Even though the hardware differs, Espressif’s high-level drivers (SPI, I2S, etc.) provide a consistent experience. When you enable DMA mode in the SPI driver, for example, it will automatically use the correct underlying implementation (Legacy SPI-DMA on ESP32, GDMA on ESP32-S3). You only need to worry about the specific DMA API if you are doing advanced, low-level control.

Common Mistakes & Troubleshooting Tips

Exercises

1. ADC to RAM with DMA: Using your variant’s datasheet and the ESP-IDF examples, configure a continuous ADC conversion to write samples directly into a RAM buffer via DMA. Print the buffer contents periodically to verify the transfer. (Hint: Look for the ADC DMA controller documentation).
2. SPI DMA Performance Test: Write a program that transfers a large buffer (e.g., 4 KB) over the SPI bus. First, implement it without DMA, using spi_transaction_t and spi_device_transmit in a loop. Time how long it takes. Then, modify the code to perform the same transfer in a single transaction using DMA. Compare the transfer times and observe the CPU’s availability during the transfer.
3. Ping-Pong Buffering for DMA: Create a classic ping-pong buffer system. Allocate two DMA-capable buffers. Start a DMA transfer into the “ping” buffer. Once it’s full (signaled by the callback), immediately start a new DMA transfer into the “pong” buffer. While the pong buffer is filling, have your CPU task process the data in the ping buffer. When the pong transfer is complete, swap roles. This is the fundamental pattern for real-time data streaming.
4. RMT with DMA for NeoPixels: The RMT (Remote Control) peripheral can use DMA to generate the precise timings needed for WS2812 (NeoPixel) LEDs. Create an application that uses the RMT driver in DMA mode to drive a strip of at least 32 LEDs with a complex color pattern. This offloads the CPU from the demanding task of bit-banging the signal.

Summary

• DMA Offloads the CPU: DMA allows for high-speed data transfers between peripherals and memory without CPU intervention, freeing the CPU for other tasks.
• GDMA is the Modern Standard: Newer ESP32 variants (S2, S3, C-series, H-series) use the flexible General DMA (GDMA) controller, managed by the esp_gdma driver.
• MALLOC_CAP_DMA is Mandatory: Buffers used in DMA operations must be allocated from a special memory pool using heap_caps_malloc.
• Transfers are Asynchronous: DMA operations run in the background. Use callbacks and synchronization primitives like semaphores to know when a transfer is complete.
• Synchronization is Crucial: Do not access a memory buffer while the DMA controller is actively using it. This “race condition” will lead to data corruption.
• Drivers Abstract Complexity: High-level peripheral drivers in ESP-IDF often handle the underlying DMA configuration, simplifying its use in common applications like SPI or I2S communication.

Further Reading

• ESP-IDF Programming Guide: GDMA
  • https://docs.espressif.com/projects/esp-idf/en/v5.2.1/esp32s3/api-reference/peripherals/gdma.html (Example for ESP32-S3, but concepts apply to other GDMA-enabled chips).
• ESP-IDF SPI Master Driver with DMA
  • https://docs.espressif.com/projects/esp-idf/en/v5.2.1/esp32/api-reference/peripherals/spi_master.html
• ESP-IDF Peripheral Examples on GitHub
  • https://github.com/espressif/esp-idf/tree/master/examples/peripherals (Check for dma, gdma, spi, adc, and rmt examples).