Module dma

Direct Memory Access Commons

Overview

The DMA driver provides an interface to efficiently transfer data between different memory regions within the ESP microcontroller without involving the CPU. The Direct Memory Access (DMA) controller is a hardware block responsible for managing these data transfers.

The driver is organized into several components and traits, each responsible for handling specific functionalities of the DMA controller. Below is an overview of the main components and their functionalities:

• Tx and Rx traits:
  • These traits define the behaviors and functionalities required for DMA transmit and receive operations.
    The Tx trait includes functions to start, stop, and check the completion status of an outbound DMA transfer.
    On the other hand, the Rx trait provides similar functionalities for inbound DMA transfers.
• DmaTransfer and DmaTransferRxTx traits:
  • The DmaTransfer trait and DmaTransferRxTx trait are used for in-progress DMA transfers.
    They allow waiting for the transfer to complete and checking its status. Additionally, the DmaTransferRxTx trait extends the functionalities to support both receive and transmit operations in a single trait.
• RegisterAccess trait:
  • This trait defines a set of methods that allow low-level access to the DMA controller’s registers.
    It provides functions to initialize DMA channels, configure burst mode, priority, and peripheral for both input and output data transfers.
    Additionally, it supports clearing interrupts, resetting channels, setting descriptor addresses, and checking for descriptor errors.

Notice, that this module is a common version of the DMA driver, ESP32 and ESP32-S2 are using older PDMA controller, whenever other chips are using newer GDMA controller.

Example

Initialize and utilize DMA controller in SPI

let dma = Gdma::new(peripherals.DMA);
let dma_channel = dma.channel0;

// For `ESP32` and `ESP32-S2` chips use `pdma::Dma` instead:
// let dma = Dma::new(system.dma);
// let dma_channel = dma.spi2channel;

let mut descriptors = [0u32; 8 * 3];
let mut rx_descriptors = [0u32; 8 * 3];

let mut spi = Spi::new(
    peripherals.SPI2,
    sclk,
    mosi,
    miso,
    cs,
    100u32.kHz(),
    SpiMode::Mode0,
    &clocks,
)
.with_dma(dma_channel.configure(
    false,
    &mut descriptors,
    &mut rx_descriptors,
    DmaPriority::Priority0,
));

⚠️ Note: Descriptors should be sized as ((CHUNK_SIZE + 4091) / 4092) * 3. I.e., to transfer buffers of size 1..=4092, you need 3 descriptors. The number of descriptors must be a multiple of 3.

Modules

gdma

Direct Memory Access

Structs

Channel

DMA Channel

ChannelRx

ChannelTx

DMA transmit channel

Enums

DmaError

DMA Errors

DmaPeripheral

DMA capable peripherals The values need to match the TRM

DmaPriority

DMA Priorities

Traits

AesPeripheral

Marks channels as useable for AES

ChannelTypes

DmaTransfer

Trait to be implemented for an in progress dma transfer.

DmaTransferRxTx

Trait to be implemented for an in progress dma transfer.

I2s0Peripheral

Marks channels as useable for I2S0

I2s1Peripheral

Marks channels as useable for I2S1

I2sPeripheral

Marks channels as useable for I2S

ParlIoPeripheral

Marks channels as useable for PARL_IO

PeripheralMarker

Marker trait

RegisterAccess

Rx

DMA Rx

RxChannel

RxPrivate

The functions here are not meant to be used outside the HAL

Spi2Peripheral

Marks channels as useable for SPI2

SpiPeripheral

Marks channels as useable for SPI

Tx

DMA Tx

TxChannel

TxPrivate

The functions here are not meant to be used outside the HAL