rt-thread/bsp/phytium/libraries/standalone/doc/reference/driver/fddma.md

FDDMA 驱动程序

1. 概述

DDMA(Device Direct Memory Access)是E2000提供的一个通用DMA控制模块，支持典型的DMA操作，提供多个DMA通道，多个通道可以同时工作，独立配置给不同外设使用

2. 功能

FDDMA 驱动程序主要完成 DDMA 模块的初始化，DDMA通道的分配与释放， 相关源文件为：

fddma
    .
    ├── fddma.c
    ├── fddma.h
    ├── fddma_g.c
    ├── fddma_hw.c
    ├── fddma_hw.h
    ├── fddma_intr.c
    ├── fddma_selftest.c
    └── fddma_sinit.c

3. 配置方法

以下部分将指导您完成 FDDMA 驱动的软件配置:

• 初始化 DDMA 控制器
• 配置 DDMA 通道，与外设完成绑定
• 启动 DDMA 通道

4 应用示例

通过DDMA搬运SPI数据完成回环测试

5. API参考

5.1. 用户数据结构

FDdmaConfig

• DDMA 实例配置

typedef struct
{
    u32 id;                     /* DDMA ctrl id */
    uintptr base_addr;          /* DDMA ctrl base address */
    u32 irq_num;                /* DDMA ctrl interrupt id */
    u32 irq_prority;            /* DDMA ctrl interrupt priority */
} FDdmaConfig; /* DDMA instance configuration */

FDdmaChanConfig

• DDMA 通道配置

typedef struct
{
    FDdmaChanIndex id;          /* DMA channel index */
    u32 slave_id;               /* Perpherial slave id for DDMA */
    FDdmaChanRequst req_mode;   /* DMA transfer direction */
    uintptr ddr_addr;           /* DMA channel DDR address, could be source or destination */
    u32 dev_addr;               /* DMA channel Perpherial, could be source or destination */
    u32 trans_len;              /* DMA channel transfer length */
#define FDDMA_MIN_TRANSFER_LEN      4  /* min bytes in transfer */
    u32 timeout;                /* timeout = 0 means no use DMA timeout */
} FDdmaChanConfig;  /* DDMA channel instance */

FDdmaChan

• DDMA 通道实例

typedef struct FDdmaChan_
{
    FDdmaChanConfig config; /* DDMA channel configuration */
    boolean is_used;        /* TRUE means channel is in use */
    FDdma *dma;             /* DMA instance of this channel */
    FDdmaChanEvtHandler evt_handler[FDDMA_NUM_OF_CHAN_EVT]; /* interrupt evt */
    void *evt_handler_args[FDDMA_NUM_OF_CHAN_EVT]; /* interrupt evt args */
} FDdmaChan; /* DDMA channel instance */

FDdma

• DDMA 控制器实例

typedef struct FDdma_
{
    FDdmaConfig config;  /* DDMA instance configuration */
    FDdmaChan   *chan[FDDMA_NUM_OF_CHAN];  /* DDMA channel instance, NULL means channel not yet allocate */
    u32 is_ready;        /* TRUE means DDMA init ok */
    u32 bind_status;     /* channel bind status, BIT(n) = 1 means channel n is allocated */
} FDdma; /* DDMA instance */

5.2 错误码定义

• FDDMA_SUCCESS : 成功
• FDDMA_ERR_NOT_INIT ：驱动未初始化
• FDDMA_ERR_CHAN_BINDED ：通道已经绑定无法分配
• FDDMA_ERR_CHAN_RUNNING : 通道正在工作无法分配
• FDDMA_ERR_INVALID_TRANS_SIZE : DMA传输字节数不合法
• FDDMA_ERR_WAIT_TIMEOUT : DMA等待超时
• FDDMA_ERR_INVALID_DDR_ADDR : DMA传输地址不合法

5.3. 用户API接口

FDdmaLookupConfig

const FDdmaConfig *FDdmaLookupConfig(u32 instance_id);

Note:

• 获取DDMA实例默认配置

Input:

• {u32} instance_id, DDMA实例号

Return:

• {const FDdmaConfig *} DDMA控制器默认配置

FDdmaCfgInitialization

FError FDdmaCfgInitialization(FDdma *const instance, const FDdmaConfig *input_config);

Note:

• 初始化DDMA控制器

Input:

• {FDdma} *instance, DDMA控制器实例
• {FDdmaConfig} *input_config, DDMA控制器配置

Return:

• {FError} FDDMA_SUCCESS表示初始化成功，其它返回值表示初始化失败

FDdmaDeInitialization

void FDdmaDeInitialization(FDdma *const instance);

Note:

• 去初始化DDMA控制器

Input:

• {FDdma} *instance, DDMA控制器实例

Return:

• 无

FDdmaAllocateChan

FError FDdmaAllocateChan(FDdma *const instance, FDdmaChan *const dma_chan, const FDdmaChanConfig *dma_chan_config);

Note:

• 按照配置分配并使能DDMA通道

Input:

• {FDdma} *instance, DDMA控制器实例
• {FDdmaChan} *dma_chan, DDMA通道实例
• {FDdmaChanConfig} *dma_chan_config, DDMA通道配置

Return:

• {FError} FDDMA_SUCCESS表示分配成功，其它返回值表示分配失败

FDdmaDellocateChan

FError FDdmaDellocateChan(FDdmaChan *const dma_chan);

Note:

• 释放之前分配的DDMA通道

Input:

• {FDdmaChan} *dma_chan, DDMA控制器实例

Return:

• {FError} FDDMA_SUCCESS表示释放成功，其它返回值表示释放失败

FDdmaStart

FError FDdmaStart(FDdma *const instance);

Note:

• 启动DDMA控制器，开始传输

Input:

• {FDdma} *instance, DDMA控制器实例

Return:

• {FError} FDDMA_SUCCESS表示启动成功，其它返回值表示启动失败

FDdmaStop

FError FDdmaStop(FDdma *const instance);

Note:

• 停止DDMA控制器

Input:

• {FDdma} *instance, DDMA控制器实例

Return:

• {FError} FDDMA_SUCCESS表示停止成功，其它返回值表示停止失败

FDdmaIrqHandler

void FDdmaIrqHandler(s32 vector, void *args)

Note:

• DDMA中断处理函数

Input:

• {s32} vector
• {void} *param, 输入参数

Return:

• 无

FDdmaRegisterChanEvtHandler

void FDdmaRegisterChanEvtHandler(FDdmaChan *const dma_chan,
                                 FDdmaChanEvt evt, 
                                 FDdmaChanEvtHandler handler, 
                                 void *handler_arg);

Note:

• 注册DDMA通道中断响应事件函数

Input:

• {FDdmaChan} *dma_chan, DDMA通道
• {FDdmaChanEvt} evt, 中断事件
• {FDdmaChanEvtHandler} handler, 中断响应事件函数
• {void} *handler_arg, 中断响应事件函数输入参数

Return:

• 无