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 stateMemory-to-memory transfer via
mem_to_mem_blocking/mem_to_mem, 4-byte aligned source and destination, length a multiple of 4Hardware auto-reload multi-block transfer via
mem_to_mem_reload_start, reloading the source and/or destination address at every block boundary viaReloadConfigwithout CPU intervention between blocksMemory-to-peripheral and peripheral-to-memory transfer via
periph_tx/periph_rx, used internally by UART/SPI DMA modes with caller-selectedTrWidthandMsizeper peripheral frame sizeRaw ISR callback registration per channel via
register_irq/GdmaIrqHandler, coexisting with the asyncFuturepath since both are driven from the same interrupt entry pointOperation mode:
Blocking: poll-driven,
mem_to_mem_blockingbusy-waits on channel completionAsync: interrupt-driven via an
embassywaker, returns aDmaFuture
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 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 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.