GDMA

概述

RTL8721F 提供一个 GDMA0 控制器,含 8 个独立通道,支持内存到内存和内存到外设的传输。Rust 驱动 ameba_hal::dma 直接封装 PAC 寄存器块,不涉及裸位操作或 C FFI 调用。

功能特性

  • 8 个独立通道,通过 DmaChannel<CH, MODE> 访问,每个通道都有各自的 NVIC 中断和通道状态

  • 内存到内存传输通过 mem_to_mem_blocking / mem_to_mem 实现,源和目标地址需 4 字节对齐,长度需为 4 的倍数

  • 硬件自动重载多块传输通过 mem_to_mem_reload_start 实现,按 ReloadConfig 在每个 block 边界自动重载源和/或目标地址,block 之间无需 CPU 干预

  • 内存到外设及外设到内存传输通过 periph_tx / periph_rx 实现,供 UART/SPI 的 DMA 模式内部调用,调用方需按外设帧大小选择 TrWidth 和 Msize

  • 每个通道均可通过 register_irq / GdmaIrqHandler 注册裸 ISR 回调,与 async Future 路径共存,两者由同一个中断入口驱动

  • 操作模式:

    • Blocking:轮询驱动,mem_to_mem_blocking 忙等通道完成

    • Async:中断驱动,基于 embassy waker,返回一个 DmaFuture

备注

periph_tx / periph_rx 为 pub(crate),只能通过外设自身的 DMA API 间接调用,例如 UART 的 into_dma_async 或 SPI 的 into_dma_async。

工作模式

GDMA 支持两种工作模式:Basic Transfer 和 Multi-block Transfer。

Basic Transfer

单块内存到内存拷贝,在 Blocking 通道上调用 mem_to_mem_blocking,或在通过 into_async 转换得到的 Async 通道上调用 mem_to_mem 获得。整个传输一次性完成,可以忙等,也可以 await 返回的 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;
}

完整示例见 examples/gdma/basic/src/main.rs。

Multi-block Transfer

在 Async 通道上调用 mem_to_mem_reload_start 启动的连续自动重载传输。源和/或目标地址会按 ReloadConfig 在每个 block 边界自动重载回初始值,通道无需 CPU 干预即可持续传输后续 block。由于持续重载的通道没有明确的"完成"时刻,进度完全通过提前经 register_irq 注册的 GdmaIrqHandler 观察,该回调需要在最后一个 block 完成前调用 clean_auto_reload,这样该 block 完成时触发的是 transfer_done 而不是继续重载。

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 },
    );
}

完整示例见 examples/gdma/multiblock/src/main.rs。

应用示例

Rust SDK 在 examples/gdma/ 下提供两个示例项目:

  • gdma/basic

    GDMA 通道 0,异步 mem-to-mem 拷贝 64 字节,完成后比对源与目标缓冲区。

    接线:无需外部接线。

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

    GDMA 通道 0,硬件自动重载传输。128 字节源缓冲区分 4 个 block 流经同一个复用的 32 字节目标窗口,每个 block 结束后由裸 ISR 回调完成校验并清空该窗口。

    接线:无需外部接线。

    [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
    

备注

编译任意示例:cargo xtask build example --name gdma/<demo>。

API 参考

快速用法

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 还提供 mem_to_mem_blocking 用于 blocking 路径,以及 mem_to_mem_reload_start 用于自动重载多块传输,参见上文工作模式一节。