430 lines
16 KiB
C
430 lines
16 KiB
C
/**
|
||
* Copyright (c) @CompanyNameMagicTag 2022-2022. All rights reserved. \n
|
||
*
|
||
* Description: Provides DMA driver api \n
|
||
* Author: @CompanyNameTag \n
|
||
* History: \n
|
||
* 2022-10-16， Create file. \n
|
||
*/
|
||
|
||
#ifndef DMA_H
|
||
#define DMA_H
|
||
|
||
#include <stdint.h>
|
||
#include "errcode.h"
|
||
|
||
#ifdef __cplusplus
|
||
#if __cplusplus
|
||
extern "C" {
|
||
#endif /* __cplusplus */
|
||
#endif /* __cplusplus */
|
||
|
||
/**
|
||
* @defgroup drivers_driver_dma DMA
|
||
* @ingroup drivers_driver
|
||
* @{
|
||
*/
|
||
|
||
/**
|
||
* @if Eng
|
||
* @brief Memory-to-memory type of DMA channel user configuration.
|
||
* @else
|
||
* @brief 内存到内存类型的DMA通道用户配置。
|
||
* @endif
|
||
*/
|
||
typedef struct dma_ch_user_memory_config {
|
||
/** @if Eng The source address of this transfer.
|
||
* @else 传输源地址。
|
||
* @endif */
|
||
uint32_t src;
|
||
/** @if Eng The destination address of this transfer.
|
||
* @else 传输目的地址。
|
||
* @endif */
|
||
uint32_t dest;
|
||
/** @if Eng Transfer number.
|
||
* @else 传输数据量。
|
||
* @endif */
|
||
uint16_t transfer_num;
|
||
/** @if Eng Transfer priority of channel(Lowest: 0 and Highest: 3).
|
||
* @else 传输通道优先级(最低为0以及最高为3)。
|
||
* @endif */
|
||
uint8_t priority;
|
||
/** @if Eng Transfer data width:
|
||
* - 0: 1byte
|
||
* - 1: 2byte
|
||
* - 2: 4byte
|
||
* @else 传输数据宽度：
|
||
* - 0: 1字节
|
||
* - 1: 2字节
|
||
* - 2: 4字节
|
||
* @endif */
|
||
uint8_t width;
|
||
} dma_ch_user_memory_config_t;
|
||
|
||
/**
|
||
* @if Eng
|
||
* @brief Memory-to-periph or periph-to-memory type of DMA channel user configuration.
|
||
* @else
|
||
* @brief 内存到外设或外设到内存类型的DMA通道用户配置。
|
||
* @endif
|
||
*/
|
||
typedef struct dma_ch_user_peripheral_config {
|
||
/** @if Eng The source address of this transfer.
|
||
* @else 传输源地址。
|
||
* @endif */
|
||
uint32_t src;
|
||
/** @if Eng The destination address of this transfer.
|
||
* @else 传输目的地址。
|
||
* @endif */
|
||
uint32_t dest;
|
||
/** @if Eng Transfer number.
|
||
* @else 传输数据量。
|
||
* @endif */
|
||
uint16_t transfer_num;
|
||
/** @if Eng Hardware handshaking ID of the source. see @ref hal_dma_handshaking_source_t.
|
||
* @else 源端硬件握手号。 参考 @ref hal_dma_handshaking_source_t 。
|
||
* @endif */
|
||
uint16_t src_handshaking;
|
||
/** @if Eng Hardware handshaking ID of the destination. see @ref hal_dma_handshaking_source_t.
|
||
* @else 目的端硬件握手号。 参考 @ref hal_dma_handshaking_source_t 。
|
||
* @endif */
|
||
uint16_t dest_handshaking;
|
||
/** @if Eng Transfer type:
|
||
* - 0: memory to memory and DMA is flow controller
|
||
* - 1: memory to periph and DMA is flow controller
|
||
* - 2: periph to memory and DMA is flow controller
|
||
* - 3: periph to periph and DMA is flow controller
|
||
* - 4: periph to memory and periph is flow controller
|
||
* - 5: periph to periph and source periph is flow controller
|
||
* - 6: memory to periph and periph is flow controller
|
||
* - 7: periph to periph and destination periph is flow controller
|
||
* @else 传输类型：
|
||
* - 0: 内存到内存并且由DMA流控
|
||
* - 1: 内存到外设并且由DMA流控
|
||
* - 2: 外设到内存并且由DMA流控
|
||
* - 3: 外设到外设并且由DMA流控
|
||
* - 4: 外设到内存并且由外设流控
|
||
* - 5: 外设到外设并且由源端外设流控
|
||
* - 6: 内存到外设并且由外设流控
|
||
* - 7: 外设到外设并且由目的端外设流控
|
||
* @endif */
|
||
uint8_t trans_type;
|
||
/** @if Eng Transfer direction:
|
||
* - 0: memory to periph
|
||
* - 1: periph to memory
|
||
* - 2: periph to periph
|
||
* @else 传输方向：
|
||
* - 0: 内存到外设
|
||
* - 1: 外设到内存
|
||
* - 2: 外设到外设
|
||
* @endif */
|
||
uint8_t trans_dir;
|
||
/** @if Eng Transfer priority of channel(Lowest: 0 and Highest: 3).
|
||
* @else 传输通道优先级(最低为0以及最高为3)。
|
||
* @endif */
|
||
uint8_t priority;
|
||
/** @if Eng Transfer data width of the source:
|
||
* - 0: 1byte
|
||
* - 1: 2byte
|
||
* - 2: 4byte
|
||
* @else 源端传输数据宽度：
|
||
* - 0: 1字节
|
||
* - 1: 2字节
|
||
* - 2: 4字节
|
||
* @endif */
|
||
uint8_t src_width;
|
||
/** @if Eng Transfer data width of the destination:
|
||
* - 0: 1byte
|
||
* - 1: 2byte
|
||
* - 2: 4byte
|
||
* @else 目的端传输数据宽度：
|
||
* - 0: 1字节
|
||
* - 1: 2字节
|
||
* - 2: 4字节
|
||
* @endif */
|
||
uint8_t dest_width;
|
||
/** @if Eng Transfer burst length:
|
||
* - 0: burst length is 1
|
||
* - 1: burst length is 4
|
||
* - 2: burst length is 8
|
||
* - 3: burst length is 16
|
||
* @else 传输burst长度：
|
||
* - 0: burst长度是1
|
||
* - 1: burst长度是4
|
||
* - 2: burst长度是8
|
||
* - 3: burst长度是16
|
||
* @endif */
|
||
uint8_t burst_length;
|
||
/** @if Eng Source address incremental mode：
|
||
* - 0: increment
|
||
* - 1: decrement
|
||
* - 2: no change
|
||
* @else 源端地址增量模式：
|
||
* - 0: 递增
|
||
* - 1: 递减
|
||
* - 2: 不变
|
||
* @endif */
|
||
uint8_t src_increment;
|
||
/** @if Eng Destination address incremental mode:
|
||
* - 0: increment
|
||
* - 1: decrement
|
||
* - 2: no change
|
||
* @else 目的端地址增量模式：
|
||
* - 0: 递增
|
||
* - 1: 递减
|
||
* - 2: 不变
|
||
* @endif */
|
||
uint8_t dest_increment;
|
||
/** @if Eng DMA protection control bits used to drive the AHB HPROT[3:1] bus:
|
||
* - 0: HPROT[1]
|
||
* - 1: HPROT[2]
|
||
* - 2: HPROT[3]
|
||
* @else 保护控制位，用于驱动AHB HPRO[3:1]总线：
|
||
* - 0: HPROT[1]
|
||
* - 1: HPROT[2]
|
||
* - 2: HPROT[3]
|
||
* @endif */
|
||
uint8_t protection;
|
||
} dma_ch_user_peripheral_config_t;
|
||
|
||
/**
|
||
* @if Eng
|
||
* @brief Pointer to the DMA channel transfer done/error callback function.
|
||
* @param [in] intr DMA interrupt type.
|
||
* @param [in] channel DMA channel.
|
||
* @param [in] arg DMA private param pointer passed by DMA caller.
|
||
* @else
|
||
* @brief DMA通道传输完成/错误所触发的回调函数指针。
|
||
* @param [in] intr DMA中断类型。
|
||
* @param [in] channel DMA通道。
|
||
* @param [in] arg 调用DMA传输时传递的私有参数指针。
|
||
* @endif
|
||
*/
|
||
typedef void (*dma_transfer_cb_t)(uint8_t intr, uint8_t channel, uintptr_t arg);
|
||
|
||
/**
|
||
* @if Eng
|
||
* @brief Initialize the DMA module.
|
||
* @retval ERRCODE_SUCC Success.
|
||
* @retval Other Failure. For details, see @ref errcode_t.
|
||
* @else
|
||
* @brief 初始化DMA模块。
|
||
* @retval ERRCODE_SUCC 成功。
|
||
* @retval Other 失败 参考 @ref errcode_t 。
|
||
* @endif
|
||
*/
|
||
errcode_t uapi_dma_init(void);
|
||
|
||
/**
|
||
* @if Eng
|
||
* @brief Deinitialize the DMA module.
|
||
* @retval ERRCODE_SUCC Success.
|
||
* @retval Other Failure. For details, see @ref errcode_t.
|
||
* @else
|
||
* @brief 去初始化DMA模块。
|
||
* @retval ERRCODE_SUCC 成功。
|
||
* @retval Other 失败 参考 @ref errcode_t 。
|
||
* @endif
|
||
*/
|
||
void uapi_dma_deinit(void);
|
||
|
||
/**
|
||
* @if Eng
|
||
* @brief Open the DMA module.
|
||
* @retval ERRCODE_SUCC Success.
|
||
* @retval Other Failure. For details, see @ref errcode_t.
|
||
* @else
|
||
* @brief 开启DMA模块。
|
||
* @retval ERRCODE_SUCC 成功。
|
||
* @retval Other 失败 参考 @ref errcode_t 。
|
||
* @endif
|
||
*/
|
||
errcode_t uapi_dma_open(void);
|
||
|
||
/**
|
||
* @if Eng
|
||
* @brief Close the DMA module.
|
||
* @else
|
||
* @brief 关闭DMA模块。
|
||
* @endif
|
||
*/
|
||
void uapi_dma_close(void);
|
||
|
||
/**
|
||
* @if Eng
|
||
* @brief Start DMA transfer of specific Channel.
|
||
* @param [in] channel DMA channel.
|
||
* @retval ERRCODE_SUCC Success.
|
||
* @retval Other Failure. For details, see @ref errcode_t.
|
||
* @else
|
||
* @brief 启动指定通道的DMA传输。
|
||
* @param [in] channel DMA通道。
|
||
* @retval ERRCODE_SUCC 成功。
|
||
* @retval Other 失败 参考 @ref errcode_t 。
|
||
* @endif
|
||
*/
|
||
errcode_t uapi_dma_start_transfer(uint8_t channel);
|
||
|
||
/**
|
||
* @if Eng
|
||
* @brief Stop DMA transfer of specific Channel.
|
||
* @param [in] channel DMA channel.
|
||
* @retval ERRCODE_SUCC Success.
|
||
* @retval Other Failure. For details, see @ref errcode_t.
|
||
* @else
|
||
* @brief 停止指定通道的DMA传输。
|
||
* @param [in] channel DMA通道。
|
||
* @retval ERRCODE_SUCC 成功。
|
||
* @retval Other 失败 参考 @ref errcode_t 。
|
||
* @endif
|
||
*/
|
||
errcode_t uapi_dma_end_transfer(uint8_t channel);
|
||
|
||
/**
|
||
* @if Eng
|
||
* @brief Get the number of data transferred by the DMA.
|
||
* @param [in] channel DMA channel.
|
||
* @retval The number of data transferred by the DMA.
|
||
* @else
|
||
* @brief 获取DMA传输的数据量。
|
||
* @param [in] channel DMA通道。
|
||
* @retval 获取DMA传输的数据量。
|
||
* @endif
|
||
*/
|
||
uint32_t uapi_dma_get_block_ts(uint8_t channel);
|
||
|
||
/**
|
||
* @if Eng
|
||
* @brief Transfer type memory-to-memory through DMA channel.
|
||
* @param [in] user_cfg DMA channel transfer configuration of user. For details, see @ref dma_ch_user_memory_config_t.
|
||
* @param [in] callback Channel transfer done/error callback function. For details, see @ref dma_transfer_cb_t.
|
||
* @param [in] arg Private param pointer for storing self information, which can be passed to DMA callback
|
||
* @ref dma_transfer_cb_t when transfer completed.
|
||
* @retval ERRCODE_SUCC Success.
|
||
* @retval Other Failure. For details, see @ref errcode_t.
|
||
* @else
|
||
* @brief 通过DMA通道传输类型为内存到内存的数据。
|
||
* @param [in] user_cfg 用户的DMA通道传输配置 For details, see @ref dma_ch_user_memory_config_t 。
|
||
* @param [in] callback 通道传输完成/错误回调函数 For details, see @ref dma_transfer_cb_t 。
|
||
* @param [in] arg 用于存储自定义信息的私有参数指针，传输完成时回传给dma回调函数 @ref dma_transfer_cb_t 。
|
||
* @retval ERRCODE_SUCC 成功。
|
||
* @retval Other 失败 参考 @ref errcode_t 。
|
||
* @endif
|
||
*/
|
||
errcode_t uapi_dma_transfer_memory_single(const dma_ch_user_memory_config_t *user_cfg,
|
||
dma_transfer_cb_t callback, uintptr_t arg);
|
||
|
||
/**
|
||
* @if Eng
|
||
* @brief Transfer type memory-periph or periph-memory through DMA channel.
|
||
* @param [in] user_cfg DMA channel transfer configuration of user.
|
||
* For details, see @ref dma_ch_user_peripheral_config_t.
|
||
* @param [out] channel DMA channel selected.
|
||
* @param [in] callback Channel transfer done/error callback function. For details, see @ref dma_transfer_cb_t.
|
||
* @param [in] arg Private param pointer for storing self information, which can be passed to DMA callback
|
||
* @ref dma_transfer_cb_t when transfer completed.
|
||
* @retval ERRCODE_SUCC Success.
|
||
* @retval Other Failure. For details, see @ref errcode_t.
|
||
* @else
|
||
* @brief 通过DMA通道传输类型为内存到外设或外设到内存的数据。
|
||
* @param [in] user_cfg 用户的DMA通道传输配置 For details, see @ref dma_ch_user_peripheral_config_t 。
|
||
* @param [out] channel 获取被选择的通道。
|
||
* @param [in] callback 通道传输完成/错误回调函数 For details, see @ref dma_transfer_cb_t 。
|
||
* @param [in] arg 用于存储自定义信息的私有参数指针，传输完成时回传给DMA回调函数 @ref dma_transfer_cb_t 。
|
||
* @retval ERRCODE_SUCC 成功。
|
||
* @retval Other 失败 参考 @ref errcode_t 。
|
||
* @endif
|
||
*/
|
||
errcode_t uapi_dma_configure_peripheral_transfer_single(const dma_ch_user_peripheral_config_t *user_cfg,
|
||
uint8_t *channel, dma_transfer_cb_t callback, uintptr_t arg);
|
||
|
||
#if defined(CONFIG_DMA_SUPPORT_LLI)
|
||
/**
|
||
* @if Eng
|
||
* @brief Get DMA linked list channel.
|
||
* @param [in] burst_length Dma burst transfer length.
|
||
* @param [in] handshaking Dma Transfer periph.
|
||
* @retval ERRCODE_SUCC Success.
|
||
* @retval The DMA channel.
|
||
* @else
|
||
* @brief 获取DMA链表传输通道。
|
||
* @param [in] burst_length DMA的burst传输长度。
|
||
* @param [in] handshaking DMA传输外设种类。
|
||
* @retval DMA通道
|
||
* @endif
|
||
*/
|
||
uint8_t uapi_dma_get_lli_channel(uint8_t burst_length, uint8_t handshaking);
|
||
|
||
/**
|
||
* @if Eng
|
||
* @brief Transfer type memory-to-memory in linked list mode through DMA channel.
|
||
* @param [in] channel DMA channel.
|
||
* @param [in] user_cfg DMA channel transfer configuration of user. For details, see @ref dma_ch_user_memory_config_t.
|
||
* @param [in] callback Channel transfer done/error callback function. For details, see @ref dma_transfer_cb_t.
|
||
* @retval ERRCODE_SUCC Success.
|
||
* @retval Other Failure. For details, see @ref errcode_t.
|
||
* @else
|
||
* @brief 通过DMA通道以链表模式传输类型为内存到内存的数据。
|
||
* @param [in] channel DMA通道。
|
||
* @param [in] user_cfg 用户的DMA通道传输配置 For details, see @ref dma_ch_user_memory_config_t 。
|
||
* @param [in] callback 通道传输完成/错误回调函数 For details, see @ref dma_transfer_cb_t 。
|
||
* @retval ERRCODE_SUCC 成功。
|
||
* @retval Other 失败 参考 @ref errcode_t 。
|
||
* @endif
|
||
*/
|
||
errcode_t uapi_dma_transfer_memory_lli(uint8_t channel, const dma_ch_user_memory_config_t *user_cfg,
|
||
dma_transfer_cb_t callback);
|
||
|
||
/**
|
||
* @if Eng
|
||
* @brief Transfer type memory-periph or periph-memory in linked list mode through DMA channel.
|
||
* @param [in] channel DMA channel.
|
||
* @param [in] user_cfg DMA channel transfer configuration of user.
|
||
* For details, see @ref dma_ch_user_peripheral_config_t.
|
||
* @param [in] callback Channel transfer done/error callback function. For details, see @ref dma_transfer_cb_t.
|
||
* @retval ERRCODE_SUCC Success.
|
||
* @retval Other Failure. For details, see @ref errcode_t.
|
||
* @else
|
||
* @brief 通过DMA通道以链表模式传输类型为内存到外设或外设到内存的数据。
|
||
* @param [in] channel DMA通道。
|
||
* @param [in] user_cfg 用户的DMA通道传输配置 For details, see @ref dma_ch_user_peripheral_config_t 。
|
||
* @param [in] callback 通道传输完成/错误回调函数 For details, see @ref dma_transfer_cb_t 。
|
||
* @retval ERRCODE_SUCC 成功。
|
||
* @retval Other 失败 参考 @ref errcode_t 。
|
||
* @endif
|
||
*/
|
||
errcode_t uapi_dma_configure_peripheral_transfer_lli(uint8_t channel, const dma_ch_user_peripheral_config_t *user_cfg,
|
||
dma_transfer_cb_t callback);
|
||
|
||
/**
|
||
* @if Eng
|
||
* @brief Enable DMA linked list transfer.
|
||
* @param [in] channel DMA channel.
|
||
* @param [in] callback Channel transfer done/error callback function. For details, see @ref dma_transfer_cb_t.
|
||
* @param [in] arg Private param pointer for storing self information, which can be passed to DMA callback
|
||
* @ref dma_transfer_cb_t when transfer completed.
|
||
* @retval ERRCODE_SUCC Success.
|
||
* @retval Other Failure. For details, see @ref errcode_t.
|
||
* @else
|
||
* @brief 启用DMA链表传输。
|
||
* @param [in] channel DMA通道。
|
||
* @param [in] callback 通道传输完成/错误回调函数 For details, see @ref dma_transfer_cb_t 。
|
||
* @param [in] arg 用于存储自定义信息的私有参数指针，传输完成时回传给dma回调函数 @ref dma_transfer_cb_t 。
|
||
* @retval ERRCODE_SUCC 成功。
|
||
* @retval Other 失败 参考 @ref errcode_t 。
|
||
* @endif
|
||
*/
|
||
errcode_t uapi_dma_enable_lli(uint8_t channel, dma_transfer_cb_t callback, uintptr_t arg);
|
||
#endif /* CONFIG_DMA_SUPPORT_LLI */
|
||
/**
|
||
* @}
|
||
*/
|
||
|
||
#ifdef __cplusplus
|
||
#if __cplusplus
|
||
}
|
||
#endif /* __cplusplus */
|
||
#endif /* __cplusplus */
|
||
|
||
#endif
|