S32K144入门笔记（二十）：eDMA的API函数解读

---

1. SDK中的函数

在SDK中并没有转为PDB设置专门的PAL驱动，在基本的DRIVER库中一共有32个API函数，本文将解读这些函数的功能。

---

2. API函数的释义

status_t EDMA_DRV_Init(edma_state_t * edmaState,
                       const edma_user_config_t *userConfig,
                       edma_chn_state_t * const chnStateArray[],
                       const edma_channel_config_t * const chnConfigArray[],
                       uint32_t chnCount)

初始化运行时状态结构，以提供 eDMA 通道的分配、释放、保护功能，并跟踪通道的状态。该函数还会重置 eDMA 模块，将模块初始化为用户定义的设置和默认设置。

status_t EDMA_DRV_Deinit(void)

将 eDMA 模块重置为复位状态，并禁用对内核的中断。

status_t EDMA_DRV_ChannelInit(edma_chn_state_t *edmaChannelState,
                              const edma_channel_config_t *edmaChannelConfig)

根据用户配置为 eDMA 通道初始化运行时状态结构请求该通道，设置通道优先级并安装回调函数。

status_t EDMA_DRV_ReleaseChannel(uint8_t virtualChannel)

停止 eDMA 通道并禁用该通道的中断。在调用此函数后，可以释放通道状态结构。

void EDMA_DRV_PushConfigToReg(uint8_t virtualChannel,
                              const edma_transfer_config_t *tcd)

将通道配置复制到 TCD 寄存器中。

void EDMA_DRV_PushConfigToSTCD(const edma_transfer_config_t *config,
                               edma_software_tcd_t *stcd)

将属性从通道配置复制到软件 TCD 结构；软件 TCD 的地址可用于启用分散/聚集操作（指向下一个 TCD 的指针）。

status_t EDMA_DRV_ConfigSingleBlockTransfer(uint8_t virtualChannel,
                                            edma_transfer_type_t type,
                                            uint32_t srcAddr,
                                            uint32_t destAddr,
                                            edma_transfer_size_t transferSize,
                                            uint32_t dataBufferSize)

此函数为单个块传输配置描述符。
该函数考虑连续的内存块，因此它将 TCD 的源/目标偏移字段配置为无间隙地覆盖数据缓冲区，
根据“transferSize”参数（偏移量等于在源读取/目标写入中传输的字节数）。
注意：对于内存到外设或外设到内存的传输，确保传输大小等于所使用外设的数据缓冲区大小，否则可能只会传输被截断的数据块（例如，对于具有 8 位数据寄存器的通信 IP，传输大小应为 1B，而对于 32 位数据寄存器，传输大小应为 4B）。此约束的基本原理是，在外设端，地址偏移量设置为零，允许在单个源读取/目标写入操作中从/向外设读取/写入数据。

status_t EDMA_DRV_ConfigMultiBlockTransfer(uint8_t virtualChannel,
                                           edma_transfer_type_t type,
                                           uint32_t srcAddr,
                                           uint32_t destAddr,
                                           edma_transfer_size_t transferSize,
                                           uint32_t blockSize,
                                           uint32_t blockCount,
                                           bool disableReqOnCompletion)

此函数为多块传输配置描述符。该函数考虑连续的内存块，因此会根据“transferSize”参数配置 TCD 的源/目标偏移字段，以无间隙地覆盖数据缓冲区（偏移量等于在一次源读取/目标写入操作中传输的字节数）。缓冲区被划分为多个块，每个块在单个DMA 请求下进行传输。
注意：对于与外设之间的传输（到外设或从外设），请确保传输大小等于所使用外设的数据缓冲区大小，否则可能只会传输被截断的数据块（例如，对于具有 8 位数据寄存器的通信 IP，传输大小应为 1 字节，而对于 32 位数据寄存器，传输大小应为 4 字节）。此约束的原因是，在外设端，地址偏移量被设置为零，从而允许在单个源读取/目标写入操作中从外设读取或向外设写入数据。

status_t EDMA_DRV_ConfigLoopTransfer(uint8_t virtualChannel,
                                     const edma_transfer_config_t *transferConfig)

此函数以循环链的方式配置DMA传输。用户传递一块内存到此函数中，该函数配置循环传输属性（小循环/大循环计数、地址偏移、通道链接）。
只有当循环属性设置正确且eDMA模块启用了小循环映射时，DMA驱动程序才会将配置复制到TCD寄存器。

status_t EDMA_DRV_ConfigScatterGatherTransfer(uint8_t virtualChannel,
                                              edma_software_tcd_t *stcd,
                                              edma_transfer_size_t transferSize,
                                              uint32_t bytesOnEachRequest,
                                              const edma_scatter_gather_list_t *srcList,
                                              const edma_scatter_gather_list_t *destList,
                                              uint8_t tcdCount)

此函数将描述符配置为单端链。用户将内存块传递到此函数中。仅当最后一个内存块完成时才触发中断。内存块信息通过 edma_scatter_gather_list_t 数据结构传递，该结构可以告知内存地址和长度。
DMA 驱动程序为每个内存块配置描述符，从第一个描述符传输到最后一个描述符，然后停止。

void EDMA_DRV_CancelTransfer(bool error)

取消当前传输，可选择发出错误信号。

status_t EDMA_DRV_StartChannel(uint8_t virtualChannel)

启用 eDMA 通道的 DMA 请求。

status_t EDMA_DRV_StopChannel(uint8_t virtualChannel)

禁用 eDMA 通道的 DMA 请求。

status_t EDMA_DRV_SetChannelRequestAndTrigger(uint8_t virtualChannel,
                                              uint8_t request,
                                              bool enableTrigger)

选择将哪个 DMA 源路由到 DMA 通道。DMA 源在文件 * _Features.h 中定义。
为触发的 DMA 通道配置周期性触发功能。

void EDMA_DRV_ClearTCD(uint8_t virtualChannel)

将该通道的 TCD 中所有寄存器清零。

void EDMA_DRV_SetSrcAddr(uint8_t virtualChannel,
                         uint32_t address)

为 eDMA 通道配置源地址。

void EDMA_DRV_SetSrcOffset(uint8_t virtualChannel,
                           int16_t offset)

为 eDMA 通道配置源地址签名偏移量。当每个源读取完成时，将符号扩展的偏移量应用于当前源地址，以形成下一个状态值。

void EDMA_DRV_SetSrcReadChunkSize(uint8_t virtualChannel,
                                  edma_transfer_size_t size)

配置源数据块大小（按读取顺序传输）。源数据读取传输大小（1/2/4/16/32 字节）。

void EDMA_DRV_SetSrcLastAddrAdjustment(uint8_t virtualChannel,
                                       int32_t adjust)

配置源地址的最后一次调整。在主要迭代次数完成时添加到源地址的调整值。此值可用于将源地址恢复到初始值，或调整地址以引用下一个数据结构。

void EDMA_DRV_SetDestAddr(uint8_t virtualChannel,
                          uint32_t address)

配置 eDMA 通道的目标地址。

void EDMA_DRV_SetDestOffset(uint8_t virtualChannel,
                            int16_t offset)

为 eDMA 通道配置目标地址有符号偏移量。当每次完成目标写操作时，将有符号扩展偏移量应用于当前目标地址以形成下一个状态值。

void EDMA_DRV_SetDestWriteChunkSize(uint8_t virtualChannel,
                                    edma_transfer_size_t size)

配置目标数据块大小（在写入序列中传输），目标数据写入传输大小（1/2/4/16/32 字节）。

void EDMA_DRV_SetDestLastAddrAdjustment(uint8_t virtualChannel,
                                        int32_t adjust)

配置最后的目标地址调整。在主要迭代次数完成时添加到目标地址的调整值。此值可用于将目标地址恢复到初始值，或调整地址以引用下一个数据结构。

void EDMA_DRV_SetMinorLoopBlockSize(uint8_t virtualChannel,
                                    uint32_t nbytes)

配置通道的每个服务请求中要传输的字节数。设置每次收到请求时要传输的字节数（一个主要循环迭代）。此数字需要是源/目标传输大小的倍数，因为数据块将在多个读/写序列（次要循环）中传输。

void EDMA_DRV_SetMajorLoopIterationCount(uint8_t virtualChannel,
                                         uint32_t majorLoopCount)

配置主要循环迭代的次数。设置主要循环迭代的次数；对于当前通道的每个请求，每个主要循环迭代都会进行处理，传输为次要循环配置的数据块（NBYTES）。

uint32_t EDMA_DRV_GetRemainingMajorIterationsCount(uint8_t virtualChannel)

返回剩余的主要循环迭代计数。获取尚未触发的次要循环的数量（主要循环迭代）。

void EDMA_DRV_SetScatterGatherLink(uint8_t virtualChannel,
                                   uint32_t nextTCDAddr)

配置在分散/聚集模式下下一个TCD的内存地址。当启用分散/聚集功能时，此函数配置要从内存加载的下一个TCD的地址。该地址指向包含要加载到此通道的下一个传输TCD的起始位置，该位置为32字节取模为0的区域。通道重新加载是在主要迭代计数完成时执行的。分散/聚集地址必须是32字节取模为0。否则，将报告配置错误。

void EDMA_DRV_DisableRequestsOnTransferComplete(uint8_t virtualChannel,
                                                bool disable)

在 TCD 的主循环完成后禁用/启用 DMA 请求。果禁用，当当前主迭代计数达到零时，eDMA 硬件会自动清除相应的 DMA 请求。

void EDMA_DRV_ConfigureInterrupt(uint8_t virtualChannel,
                                 edma_channel_interrupt_t intSrc,
                                 bool enable)

禁用/启用通道中断请求。

void EDMA_DRV_TriggerSwRequest(uint8_t virtualChannel)

此函数为当前通道启用/禁用错误、半主循环和完整主循环中断。

status_t EDMA_DRV_InstallCallback(uint8_t virtualChannel,
                                  edma_callback_t callback,
                                  void *parameter)

此函数将回调函数和参数注册到eDMA通道状态结构中。
当通道完成或发生通道错误时，将调用回调函数。eDMA驱动程序将通道状态传递给此回调函数，以指示是由通道完成事件还是通道错误事件引起的。
要取消注册回调函数，请将回调函数设置为“NULL”并调用此函数。

edma_chn_status_t EDMA_DRV_GetChannelStatus(uint8_t virtualChannel)

获取通道状态。