General DMA (GDMA)

Overview

RTL8721F provides a GDMA0 controller with 8 independent channels for memory-to-memory and memory-to-peripheral transfers. The Rust driver ameba_hal::dma wraps the PAC register block directly — no raw bit-masking or C FFI is involved.

Features

  • 8 independent channels via DmaChannel<CH, MODE>, each with its own NVIC interrupt and per-channel state

  • Memory-to-memory transfer via mem_to_mem_blocking / mem_to_mem, 4-byte aligned source and destination, length a multiple of 4

  • Hardware auto-reload multi-block transfer via mem_to_mem_reload_start, reloading the source and/or destination address at every block boundary via ReloadConfig without CPU intervention between blocks

  • Memory-to-peripheral and peripheral-to-memory transfer via periph_tx / periph_rx, used internally by UART/SPI DMA modes with caller-selected TrWidth and Msize per peripheral frame size

  • Raw ISR callback registration per channel via register_irq / GdmaIrqHandler, coexisting with the async Future path since both are driven from the same interrupt entry point

  • Operation mode:

    • Blocking: poll-driven, mem_to_mem_blocking busy-waits on channel completion

    • Async: interrupt-driven via an embassy waker, returns a DmaFuture

Note

periph_tx / periph_rx are pub(crate) and only reachable through a peripheral’s own DMA API, such as UART’s into_dma_async or SPI’s into_dma_async.

Operating Modes

GDMA supports two operating modes: Basic Transfer and Multi-block Transfer.

Basic Transfer

A single-block memory-to-memory copy, obtained by calling mem_to_mem_blocking on a Blocking channel or mem_to_mem on an Async channel converted with into_async. The whole transfer completes once, either by busy-waiting or by awaiting the returned DmaFuture.

use ameba_hal::dma::{Async, Blocking, DmaChannel};
...
let mut ch: DmaChannel<0, Async> = unsafe {
    DmaChannel::<0, Blocking>::steal().into_async()
};
...
unsafe {
    ch.mem_to_mem(
        core::ptr::addr_of!(SRC.0) as *const u8,
        core::ptr::addr_of_mut!(DST.0) as *mut u8,
        64,
    ).await;
}

Full example: examples/gdma/basic/src/main.rs.

Multi-block Transfer

A continuous auto-reload transfer, started with mem_to_mem_reload_start on an Async channel. The source and/or destination address automatically reloads to its initial value at every block boundary via ReloadConfig, so the channel keeps streaming blocks without CPU intervention. Since a continuously-reloading channel never reaches a self-evident “done”, progress is observed entirely through a GdmaIrqHandler registered beforehand via register_irq, and the handler calls clean_auto_reload before the last block completes so that block’s completion fires transfer_done instead of reloading again.

use ameba_hal::dma::{Async, Blocking, DmaChannel, GdmaIrqEvent, GdmaIrqHandler, ReloadConfig};
...
struct MultiblockHandler {
    block_count: AtomicUsize,
    done: AtomicBool,
    ok: AtomicBool,
}

impl GdmaIrqHandler for MultiblockHandler {
    fn on_irq(&mut self, event: GdmaIrqEvent) {
        if event.error {
            println!("[GDMA-IRQ] error isr=0x{:08X} (from ISR)", event.isr);
            self.ok.store(false, Ordering::Relaxed);
            self.done.store(true, Ordering::Release);
            return;
        }
        if !event.block_done && !event.transfer_done {
            return;
        }

        let idx = self.block_count.load(Ordering::Relaxed);
        ...
        if idx + 2 == MAX_BLOCKS {
            let mut ch = unsafe { DmaChannel::<0, Async>::steal() };
            ch.clean_auto_reload(ReloadConfig { reload_src: false, reload_dst: true });
        }
        ...
        self.block_count.store(idx + 1, Ordering::Relaxed);

        if event.transfer_done {
            self.done.store(true, Ordering::Release);
        }
    }
}
...
let mut ch: DmaChannel<0, Async> = unsafe { DmaChannel::<0, Blocking>::steal().into_async() };

let handler = unsafe { &mut *addr_of_mut!(HANDLER) };
ch.register_irq(handler);

unsafe {
    ch.mem_to_mem_reload_start(
        addr_of!(SRC.0) as *const u8,
        addr_of_mut!(DST.0) as *mut u8,
        BLOCK_SIZE,
        ReloadConfig { reload_src: false, reload_dst: true },
    );
}

Full example: examples/gdma/multiblock/src/main.rs.

Application Examples

The Rust SDK provides two example projects under examples/gdma/:

  • gdma/basic

    GDMA channel 0, async mem-to-mem copy of 64 bytes, comparing the source and destination buffers once complete.

    Wiring: none required.

    [GDMA] start
    [GDMA] async done in Nms
    [PASS] GDMA: mem-to-mem 64 bytes OK
    
  • gdma/multiblock

    GDMA channel 0, hardware auto-reload transfer. A 128-byte source buffer is streamed through a single reused 32-byte destination window in 4 blocks, with a raw ISR callback validating and clearing the destination window after every block.

    Wiring: none required.

    [GDMA multiblock] start
    [GDMA-IRQ] block 0 done isr=0x02 (from ISR)
    [GDMA-IRQ] block 1 done isr=0x02 (from ISR)
    [GDMA-IRQ] block 2 done isr=0x02 (from ISR)
    [GDMA-IRQ] block 3 done isr=0x03 (from ISR)
    [PASS] GDMA multiblock: 4 blocks of 32 bytes streamed via per-block ISR OK
    

Note

Compile any example with cargo xtask build example --name gdma/<demo>.

API Reference

Quick Usage

use ameba_hal::dma::{Async, Blocking, DmaChannel};

let mut ch: DmaChannel<0, Async> = unsafe { DmaChannel::<0, Blocking>::steal().into_async() };

unsafe {
    ch.mem_to_mem(src_ptr, dst_ptr, 64).await;
}

DmaChannel also exposes mem_to_mem_blocking for the blocking path and mem_to_mem_reload_start for auto-reload multi-block transfers — see the Operating Modes section above.