vsf_template_dma.h

Go to the documentation of this file.

/*****************************************************************************
 *   Copyright(C)2009-2022 by VSF Team                                       *
 *                                                                           *
 *  Licensed under the Apache License, Version 2.0 (the "License");          *
 *  you may not use this file except in compliance with the License.         *
 *  You may obtain a copy of the License at                                  *
 *                                                                           *
 *     http://www.apache.org/licenses/LICENSE-2.0                            *
 *                                                                           *
 *  Unless required by applicable law or agreed to in writing, software      *
 *  distributed under the License is distributed on an "AS IS" BASIS,        *
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
 *  See the License for the specific language governing permissions and      *
 *  limitations under the License.                                           *
 *                                                                           *
 ****************************************************************************/
 
#ifndef __VSF_TEMPLATE_DMA_H__
#define __VSF_TEMPLATE_DMA_H__
 
/*============================ INCLUDES ======================================*/
 
#include "./vsf_template_hal_driver.h"
#include "hal/arch/vsf_arch.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*============================ MACROS ========================================*/
 
#ifndef VSF_DMA_CFG_MULTI_CLASS
#   define VSF_DMA_CFG_MULTI_CLASS                        ENABLED
#endif
 
#ifndef VSF_DMA_CFG_PREFIX
#   if VSF_DMA_CFG_MULTI_CLASS == ENABLED
#       define VSF_DMA_CFG_PREFIX                         vsf
#   elif defined(VSF_HW_DMA_COUNT) && (VSF_HW_DMA_COUNT != 0)
#       define VSF_DMA_CFG_PREFIX                         vsf_hw
#   else
#       define VSF_DMA_CFG_PREFIX                         vsf
#   endif
#endif
 
#ifndef VSF_DMA_CFG_FUNCTION_RENAME
#   define VSF_DMA_CFG_FUNCTION_RENAME                  ENABLED
#endif
 
#ifndef VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_MODE
#   define VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_MODE    DISABLED
#endif
 
#ifndef VSF_DMA_CFG_REIMPLEMENT_TYPE_IRQ_MASK
#   define VSF_DMA_CFG_REIMPLEMENT_TYPE_IRQ_MASK        DISABLED
#endif
 
#ifndef VSF_DMA_CFG_REIMPLEMENT_TYPE_ADDR
#   define VSF_DMA_CFG_REIMPLEMENT_TYPE_ADDR            DISABLED
#endif
 
#ifndef VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_HINT
#   define VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_HINT    DISABLED
#endif
 
#ifndef VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_CFG
#   define VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_CFG     DISABLED
#endif
 
#ifndef VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_SG_CFG
#   define VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_SG_CFG  \
                                                        DISABLED
#endif
 
#ifndef VSF_DMA_CFG_REIMPLEMENT_TYPE_CFG
#   define VSF_DMA_CFG_REIMPLEMENT_TYPE_CFG             DISABLED
#endif
 
#ifndef VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_STATUS
#   define VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_STATUS  DISABLED
#endif
 
#ifndef VSF_DMA_CFG_REIMPLEMENT_TYPE_CAPABILITY
#   define VSF_DMA_CFG_REIMPLEMENT_TYPE_CAPABILITY      DISABLED
#endif
 
#ifndef VSF_DMA_CFG_INHERIT_HAL_CAPABILITY
#   define VSF_DMA_CFG_INHERIT_HAL_CAPABILITY           ENABLED
#endif
 
#ifndef VSF_DMA_CHANNEL_SG_ARRAY
#   define VSF_DMA_CHANNEL_SG_ARRAY(__NAME, __COUNT, ...)                       \
    vsf_dma_channel_sg_desc_t __NAME[__COUNT] = {                               \
        __VA_ARGS__                                                             \
    };
#endif
 
#ifndef VSF_DMA_CHANNEL_SG_ITEM
#   define VSF_DMA_CHANNEL_SG_ITEM(__MODE, __SRC_ADDR, __DST_ADDR, __CNT, ...)  \
    {                                                                           \
        .mode = __MODE,                                                         \
        .src_address = __SRC_ADDR,                                              \
        .dst_address = __DST_ADDR,                                              \
        .count = __CNT,                                                         \
        __VA_ARGS__                                                             \
    }
#endif
 
/*============================ MACROFIED FUNCTIONS ===========================*/
 
#define VSF_DMA_APIS(__prefix_name) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,                dma, init,                               VSF_MCONNECT(__prefix_name, _t) *dma_ptr, vsf_dma_cfg_t *cfg_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, void,                     dma, fini,                               VSF_MCONNECT(__prefix_name, _t) *dma_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,                dma, get_configuration,                  VSF_MCONNECT(__prefix_name, _t) *dma_ptr, vsf_dma_cfg_t *cfg_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_dma_capability_t,     dma, capability,                         VSF_MCONNECT(__prefix_name, _t) *dma_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,                dma, channel_acquire,                    VSF_MCONNECT(__prefix_name, _t) *dma_ptr, vsf_dma_channel_hint_t *channel_hint_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, void,                     dma, channel_release,                    VSF_MCONNECT(__prefix_name, _t) *dma_ptr, uint8_t channel) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,                dma, channel_config,                     VSF_MCONNECT(__prefix_name, _t) *dma_ptr, uint8_t channel, vsf_dma_channel_cfg_t *cfg_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,                dma, channel_get_configuration,          VSF_MCONNECT(__prefix_name, _t) *dma_ptr, uint8_t channel, vsf_dma_channel_cfg_t *cfg_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,                dma, channel_start,                      VSF_MCONNECT(__prefix_name, _t) *dma_ptr, uint8_t channel, vsf_dma_addr_t src_address, vsf_dma_addr_t dst_address, uint32_t count) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,                dma, channel_cancel,                     VSF_MCONNECT(__prefix_name, _t) *dma_ptr, uint8_t channel) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,                dma, channel_sg_config_desc,             VSF_MCONNECT(__prefix_name, _t) *dma_ptr, uint8_t channel, vsf_dma_isr_t isr, vsf_dma_channel_sg_desc_t *scatter_gather_cfg, uint32_t sg_count) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,                dma, channel_sg_start,                   VSF_MCONNECT(__prefix_name, _t) *dma_ptr, uint8_t channel) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, uint32_t,                 dma, channel_get_transferred_count,      VSF_MCONNECT(__prefix_name, _t) *dma_ptr, uint8_t channel) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_dma_channel_status_t, dma, channel_status,                     VSF_MCONNECT(__prefix_name, _t) *dma_ptr, uint8_t channel)
 
/*============================ TYPES =========================================*/
 
#if VSF_DMA_CFG_REIMPLEMENT_TYPE_ADDR == DISABLED
typedef uintptr_t vsf_dma_addr_t;
#endif
 
#if VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_MODE == DISABLED
typedef enum vsf_dma_channel_mode_t {
    VSF_DMA_MEMORY_TO_MEMORY        = (0x00 << 0),
    VSF_DMA_MEMORY_TO_PERIPHERAL    = (0x01 << 0),
    VSF_DMA_PERIPHERAL_TO_MEMORY    = (0x02 << 0),
    VSF_DMA_PERIPHERAL_TO_PERIPHERAL= (0x03 << 0),
 
    VSF_DMA_SRC_ADDR_INCREMENT      = (0x00 << 2),
    VSF_DMA_SRC_ADDR_DECREMENT      = (0x01 << 2),
    VSF_DMA_SRC_ADDR_NO_CHANGE      = (0x02 << 2),
 
    VSF_DMA_DST_ADDR_INCREMENT      = (0x00 << 4),
    VSF_DMA_DST_ADDR_DECREMENT      = (0x01 << 4),
    VSF_DMA_DST_ADDR_NO_CHANGE      = (0x02 << 4),
 
    VSF_DMA_SRC_WIDTH_BYTE_1        = (0x00 << 6),
    VSF_DMA_SRC_WIDTH_BYTES_2       = (0x01 << 6),
    VSF_DMA_SRC_WIDTH_BYTES_4       = (0x02 << 6),
    VSF_DMA_SRC_WIDTH_BYTES_8       = (0x03 << 6),
    VSF_DMA_SRC_WIDTH_BYTES_16      = (0x04 << 6),
    VSF_DMA_SRC_WIDTH_BYTES_32      = (0x05 << 6),
 
    VSF_DMA_DST_WIDTH_BYTE_1        = (0x00 << 10),
    VSF_DMA_DST_WIDTH_BYTES_2       = (0x01 << 10),
    VSF_DMA_DST_WIDTH_BYTES_4       = (0x02 << 10),
    VSF_DMA_DST_WIDTH_BYTES_8       = (0x03 << 10),
    VSF_DMA_DST_WIDTH_BYTES_16      = (0x04 << 10),
    VSF_DMA_DST_WIDTH_BYTES_32      = (0x05 << 10),
 
    VSF_DMA_SRC_BURST_LENGTH_1       = (0x00 << 14),
    VSF_DMA_SRC_BURST_LENGTH_2       = (0x01 << 14),
    VSF_DMA_SRC_BURST_LENGTH_4       = (0x02 << 14),
    VSF_DMA_SRC_BURST_LENGTH_8       = (0x03 << 14),
    VSF_DMA_SRC_BURST_LENGTH_16      = (0x04 << 14),
    VSF_DMA_SRC_BURST_LENGTH_32      = (0x05 << 14),
    VSF_DMA_SRC_BURST_LENGTH_64      = (0x06 << 14),
    VSF_DMA_SRC_BURST_LENGTH_128     = (0x07 << 14),
 
    VSF_DMA_DST_BURST_LENGTH_1       = (0x00 << 18),
    VSF_DMA_DST_BURST_LENGTH_2       = (0x01 << 18),
    VSF_DMA_DST_BURST_LENGTH_4       = (0x02 << 18),
    VSF_DMA_DST_BURST_LENGTH_8       = (0x03 << 18),
    VSF_DMA_DST_BURST_LENGTH_16      = (0x04 << 18),
    VSF_DMA_DST_BURST_LENGTH_32      = (0x05 << 18),
    VSF_DMA_DST_BURST_LENGTH_64      = (0x06 << 18),
    VSF_DMA_DST_BURST_LENGTH_128     = (0x07 << 18),
 
    //prio
    VSF_DMA_PRIORITY_LOW             = (0x00 << 22),
    VSF_DMA_PRIORITY_MEDIUM          = (0x01 << 22),
    VSF_DMA_PRIORITY_HIGH            = (0x02 << 22),
    VSF_DMA_PRIORITY_VERY_HIGH       = (0x03 << 22),
 
} vsf_dma_channel_mode_t;
#endif
 
enum {
    VSF_DMA_DIRECTION_COUNT           = 4,
    VSF_DMA_DIRECTION_MASK            = VSF_DMA_MEMORY_TO_MEMORY        |
                                        VSF_DMA_MEMORY_TO_PERIPHERAL    |
                                        VSF_DMA_PERIPHERAL_TO_MEMORY    |
                                        VSF_DMA_PERIPHERAL_TO_PERIPHERAL,
 
    VSF_DMA_SRC_ADDR_COUNT            = 3,
    VSF_DMA_SRC_ADDR_MASK             = VSF_DMA_SRC_ADDR_INCREMENT |
                                        VSF_DMA_SRC_ADDR_DECREMENT |
                                        VSF_DMA_SRC_ADDR_NO_CHANGE,
 
    VSF_DMA_DST_ADDR_COUNT            = 3,
    VSF_DMA_DST_ADDR_MASK             = VSF_DMA_DST_ADDR_INCREMENT |
                                        VSF_DMA_DST_ADDR_DECREMENT |
                                        VSF_DMA_DST_ADDR_NO_CHANGE,
 
    VSF_DMA_SRC_WIDTH_COUNT           = 6,
    VSF_DMA_SRC_WIDTH_MASK            = VSF_DMA_SRC_WIDTH_BYTE_1   |
                                        VSF_DMA_SRC_WIDTH_BYTES_2  |
                                        VSF_DMA_SRC_WIDTH_BYTES_4  |
                                        VSF_DMA_SRC_WIDTH_BYTES_8  |
                                        VSF_DMA_SRC_WIDTH_BYTES_16 |
                                        VSF_DMA_SRC_WIDTH_BYTES_32,
 
    VSF_DMA_DST_WIDTH_COUNT           = 6,
    VSF_DMA_DST_WIDTH_MASK            = VSF_DMA_DST_WIDTH_BYTE_1   |
                                        VSF_DMA_DST_WIDTH_BYTES_2  |
                                        VSF_DMA_DST_WIDTH_BYTES_4  |
                                        VSF_DMA_DST_WIDTH_BYTES_8  |
                                        VSF_DMA_DST_WIDTH_BYTES_16 |
                                        VSF_DMA_DST_WIDTH_BYTES_32,
 
    VSF_DMA_SRC_BURST_COUNT           = 8,
    VSF_DMA_SRC_BURST_MASK            = VSF_DMA_SRC_BURST_LENGTH_1   |
                                        VSF_DMA_SRC_BURST_LENGTH_2   |
                                        VSF_DMA_SRC_BURST_LENGTH_4   |
                                        VSF_DMA_SRC_BURST_LENGTH_8   |
                                        VSF_DMA_SRC_BURST_LENGTH_16  |
                                        VSF_DMA_SRC_BURST_LENGTH_32  |
                                        VSF_DMA_SRC_BURST_LENGTH_64  |
                                        VSF_DMA_SRC_BURST_LENGTH_128,
 
    VSF_DMA_DST_BURST_COUNT           = 8,
    VSF_DMA_DST_BURST_MASK            = VSF_DMA_DST_BURST_LENGTH_1   |
                                        VSF_DMA_DST_BURST_LENGTH_2   |
                                        VSF_DMA_DST_BURST_LENGTH_4   |
                                        VSF_DMA_DST_BURST_LENGTH_8   |
                                        VSF_DMA_DST_BURST_LENGTH_16  |
                                        VSF_DMA_DST_BURST_LENGTH_32  |
                                        VSF_DMA_DST_BURST_LENGTH_64  |
                                        VSF_DMA_DST_BURST_LENGTH_128,
 
    VSF_DMA_PRIORITY_COUNT            = 4,
    VSF_DMA_PRIORITY_MASK             = VSF_DMA_PRIORITY_LOW       |
                                        VSF_DMA_PRIORITY_MEDIUM    |
                                        VSF_DMA_PRIORITY_HIGH      |
                                        VSF_DMA_PRIORITY_VERY_HIGH,
 
    VSF_DMA_MODE_MASK_COUNT           = 8,
    VSF_DMA_MODE_ALL_BITS_MASK        = VSF_DMA_DIRECTION_MASK  |
                                        VSF_DMA_SRC_ADDR_MASK   |
                                        VSF_DMA_DST_ADDR_MASK   |
                                        VSF_DMA_SRC_WIDTH_MASK  |
                                        VSF_DMA_DST_WIDTH_MASK  |
                                        VSF_DMA_SRC_BURST_MASK  |
                                        VSF_DMA_DST_BURST_MASK  |
                                        VSF_DMA_PRIORITY_MASK,
 
};
 
#if VSF_DMA_CFG_REIMPLEMENT_TYPE_IRQ_MASK == DISABLED
typedef enum vsf_dma_irq_mask_t {
    VSF_DMA_IRQ_MASK_CPL        = (0x1ul << 0),
    VSF_DMA_IRQ_MASK_HALF_CPL   = (0x1ul << 1),
    VSF_DMA_IRQ_MASK_ERROR      = (0x1ul << 2),
} vsf_dma_irq_mask_t;
#endif
 
enum {
    VSF_DMA_IRQ_COUNT               = 3,
    VSF_DMA_IRQ_ALL_BITS_MASK       = VSF_DMA_IRQ_MASK_CPL      |
                                      VSF_DMA_IRQ_MASK_HALF_CPL |
                                      VSF_DMA_IRQ_MASK_ERROR,
};
 
 
#if VSF_DMA_CFG_REIMPLEMENT_TYPE_CFG == DISABLED
typedef struct vsf_dma_cfg_t {
    vsf_arch_prio_t         prio;   
} vsf_dma_cfg_t;
#endif
 
#if VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_HINT == DISABLED
typedef struct vsf_dma_channel_hint_t {
    int8_t                  channel;
    uint8_t                 request_line;
    vsf_arch_prio_t         prio;
} vsf_dma_channel_hint_t;
#endif
 
#if VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_CFG == DISABLED
typedef struct vsf_dma_t vsf_dma_t;
 
typedef void vsf_dma_isr_handler_t(void *target_ptr, vsf_dma_t *dma_ptr, int8_t channel, vsf_dma_irq_mask_t irq_mask);
 
typedef struct vsf_dma_isr_t {
    vsf_dma_isr_handler_t *handler_fn;
    void                  *target_ptr;
} vsf_dma_isr_t;
 
 
typedef struct vsf_dma_channel_cfg_t {
    vsf_dma_channel_mode_t  mode;
    vsf_dma_isr_t           isr;
    vsf_dma_irq_mask_t      irq_mask;
    vsf_arch_prio_t         prio;
    uint8_t                 src_request_idx;
    uint8_t                 dst_request_idx;
} vsf_dma_channel_cfg_t;
#endif
 
/*============================ INITIALIZATION MACROS =========================*/
 
// Helper macro for optional argument with default value
#ifndef __VSF_DMA_GET_ARG_OR_DEFAULT
#   define __VSF_DMA_GET_ARG_OR_DEFAULT(__DEFAULT, __ARG, ...) (__ARG)
#endif
 
#ifndef VSF_DMA_CHANNEL_HINT_INIT
#   define VSF_DMA_CHANNEL_HINT_INIT(__CHANNEL, __REQUEST_LINE, ...) \
    { \
        .channel = (__CHANNEL), \
        .request_line = (__REQUEST_LINE), \
        .prio = __VSF_DMA_GET_ARG_OR_DEFAULT(,##__VA_ARGS__, vsf_arch_prio_invalid, vsf_arch_prio_invalid), \
    }
#endif
 
#ifndef VSF_DMA_CHANNEL_CFG_INIT
#   define VSF_DMA_CHANNEL_CFG_INIT(__MODE, __ISR, __IRQ_MASK, __SRC_REQ_IDX, __DST_REQ_IDX, ...) \
    { \
        .mode = (__MODE), \
        .isr = (__ISR), \
        .irq_mask = (__IRQ_MASK), \
        .prio = __VSF_DMA_GET_ARG_OR_DEFAULT(,##__VA_ARGS__, vsf_arch_prio_invalid, vsf_arch_prio_invalid), \
        .src_request_idx = (__SRC_REQ_IDX), \
        .dst_request_idx = (__DST_REQ_IDX), \
    }
#endif
 
#if VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_SG_CFG == DISABLED
typedef struct vsf_dma_channel_sg_desc_t {
    vsf_dma_channel_mode_t mode;    
    vsf_dma_addr_t src_address;     
    vsf_dma_addr_t dst_address;     
    uint32_t count;                 
    vsf_dma_addr_t next;
} vsf_dma_channel_sg_desc_t;
#endif
 
#if VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_STATUS == DISABLED
typedef struct vsf_dma_channel_status_t {
    union {
        inherit(vsf_peripheral_status_t)
            struct {
            uint32_t is_busy : 1;
        };
    };
} vsf_dma_channel_status_t;
#endif
 
#if VSF_DMA_CFG_REIMPLEMENT_TYPE_CAPABILITY == DISABLED
typedef struct vsf_dma_capability_t {
#if VSF_DMA_CFG_INHERIT_HAL_CAPABILITY == ENABLED
    inherit(vsf_peripheral_capability_t)
#endif
 
    vsf_dma_irq_mask_t irq_mask;               
 
    uint8_t channel_count;                     
 
    uint8_t irq_count;
 
    vsf_dma_channel_mode_t supported_modes;
 
    uint32_t max_transfer_count;               
    uint8_t addr_alignment;                    
 
    uint8_t support_scatter_gather : 1;        
} vsf_dma_capability_t;
#endif
 
typedef struct vsf_dma_op_t {
#undef  __VSF_HAL_TEMPLATE_API
#define __VSF_HAL_TEMPLATE_API VSF_HAL_TEMPLATE_API_FP
 
    VSF_DMA_APIS(vsf_dma)
} vsf_dma_op_t;
 
#if VSF_DMA_CFG_MULTI_CLASS == ENABLED
struct vsf_dma_t  {
    const vsf_dma_op_t * op;
};
#endif
 
/*============================ PROTOTYPES ====================================*/
 
extern vsf_err_t vsf_dma_init(vsf_dma_t *dma_ptr, vsf_dma_cfg_t *cfg_ptr);
 
extern void vsf_dma_fini(vsf_dma_t *dma_ptr);
 
extern vsf_err_t vsf_dma_get_configuration(vsf_dma_t *dma_ptr, vsf_dma_cfg_t *cfg_ptr);
 
extern vsf_dma_capability_t vsf_dma_capability(vsf_dma_t *dma_ptr);
 
extern vsf_err_t vsf_dma_channel_acquire(vsf_dma_t *dma_ptr, vsf_dma_channel_hint_t *channel_hint_ptr);
 
extern void vsf_dma_channel_release(vsf_dma_t *dma_ptr, uint8_t channel);
 
extern vsf_err_t vsf_dma_channel_config(vsf_dma_t *dma_ptr, uint8_t channel, vsf_dma_channel_cfg_t *cfg_ptr);
 
extern vsf_err_t vsf_dma_channel_get_configuration(vsf_dma_t *dma_ptr, uint8_t channel, vsf_dma_channel_cfg_t *cfg_ptr);
 
extern vsf_err_t vsf_dma_channel_start(vsf_dma_t *dma_ptr, uint8_t channel, vsf_dma_addr_t src_address, vsf_dma_addr_t dst_address, uint32_t count);
 
extern vsf_err_t vsf_dma_channel_cancel(vsf_dma_t *dma_ptr, uint8_t channel);
 
extern vsf_err_t vsf_dma_channel_sg_config_desc(vsf_dma_t *dma_ptr, uint8_t channel, vsf_dma_isr_t isr,
            vsf_dma_channel_sg_desc_t *sg_desc_ptr, uint32_t sg_count);
 
extern vsf_err_t vsf_dma_channel_sg_start(vsf_dma_t *dma_ptr, uint8_t channel);
 
extern uint32_t vsf_dma_channel_get_transferred_count(vsf_dma_t *dma_ptr, uint8_t channel);
 
extern vsf_dma_channel_status_t vsf_dma_channel_status(vsf_dma_t *dma_ptr, uint8_t channel);
 
// \~english
// @brief Acquire a DMA channel from all available DMA instances
// @param[in,out] channel_hint_ptr: a pointer to DMA channel hint. User should provide appropriate hint information based on actual requirements. If the actually allocated channel or other configuration differs from user's expectation, the function may modify channel_hint_ptr to notify the user of the actual allocation. The allocated channel number will be stored in channel_hint_ptr->channel.
// @return vsf_dma_t *: pointer to the DMA instance that successfully allocated the channel, or NULL if allocation failed
// @note Prerequisites: All DMA instances must be homogeneous (isomorphic). Peripherals can acquire channels from any DMA instance, and channels acquired from any DMA instance can be assigned to any peripheral. This function iterates through all available DMA instances and attempts to acquire a channel from each one. It returns the first DMA instance that successfully allocates a channel.
// @note The VSF_PREFIX prefix of this can be replaced with the actual prefix, e.g. vsf_hw
//
// \~chinese
// @brief 从所有可用的 DMA 实例中获取一个 DMA 通道
// @param[in,out] channel_hint_ptr: 指向 DMA 通道提示的指针。用户应根据实际情况提供合适的提示信息。如果实际分配的通道或其他配置与用户预期不一致，函数可能会修改 channel_hint_ptr 来通知用户实际分配的结果。分配的通道号将存储在 channel_hint_ptr->channel 中。
// @return vsf_dma_t *: 成功分配通道的 DMA 实例指针，如果分配失败则返回 NULL
// @note 前提条件：所有 DMA 实例必须是同构的（功能相同）。外设可以从任意一个 DMA 实例申请通道，并且从任意一个 DMA 实例获取的通道都可以分配给任意一个外设使用。此函数遍历所有可用的 DMA 实例，并尝试从每个实例中获取通道。它返回第一个成功分配通道的 DMA 实例。
// @note VSF_PREFIX 前缀可以替换成实际的前缀，例如 vsf_hw
// */
//extern vsf_dma_t * VSF_PREFIX_dma_channel_acquire_from_all(vsf_dma_channel_hint_t *channel_hint_ptr);
//
 
/*============================ MACROFIED FUNCTIONS ===========================*/
 
#if VSF_DMA_CFG_FUNCTION_RENAME == ENABLED
#   define __vsf_dma_t                                              VSF_MCONNECT(VSF_DMA_CFG_PREFIX, _dma_t)
#   define vsf_dma_init(__DMA, ...)                                 VSF_MCONNECT(VSF_DMA_CFG_PREFIX, _dma_init)((__vsf_dma_t *)(__DMA), ##__VA_ARGS__)
#   define vsf_dma_fini(__DMA)                                      VSF_MCONNECT(VSF_DMA_CFG_PREFIX, _dma_fini)((__vsf_dma_t *)(__DMA))
#   define vsf_dma_get_configuration(__DMA, ...)                    VSF_MCONNECT(VSF_DMA_CFG_PREFIX, _dma_get_configuration)((__vsf_dma_t *)(__DMA), ##__VA_ARGS__)
#   define vsf_dma_capability(__DMA)                                VSF_MCONNECT(VSF_DMA_CFG_PREFIX, _dma_capability)((__vsf_dma_t *)(__DMA))
#   define vsf_dma_channel_acquire(__DMA, ...)                      VSF_MCONNECT(VSF_DMA_CFG_PREFIX, _dma_channel_acquire)((__vsf_dma_t *)(__DMA), ##__VA_ARGS__)
#   define vsf_dma_channel_release(__DMA, ...)                      VSF_MCONNECT(VSF_DMA_CFG_PREFIX, _dma_channel_release)((__vsf_dma_t *)(__DMA), ##__VA_ARGS__)
#   define vsf_dma_channel_config(__DMA, ...)                       VSF_MCONNECT(VSF_DMA_CFG_PREFIX, _dma_channel_config)((__vsf_dma_t *)(__DMA), ##__VA_ARGS__)
#   define vsf_dma_channel_get_configuration(__DMA, ...)            VSF_MCONNECT(VSF_DMA_CFG_PREFIX, _dma_channel_get_configuration)((__vsf_dma_t *)(__DMA), ##__VA_ARGS__)
#   define vsf_dma_channel_start(__DMA, ...)                        VSF_MCONNECT(VSF_DMA_CFG_PREFIX, _dma_channel_start)((__vsf_dma_t *)(__DMA), ##__VA_ARGS__)
#   define vsf_dma_channel_sg_config_desc(__DMA, ...)               VSF_MCONNECT(VSF_DMA_CFG_PREFIX, _dma_channel_sg_config_desc)((__vsf_dma_t *)(__DMA), ##__VA_ARGS__)
#   define vsf_dma_channel_sg_start(__DMA, ...)                     VSF_MCONNECT(VSF_DMA_CFG_PREFIX, _dma_channel_sg_start)((__vsf_dma_t *)(__DMA), ##__VA_ARGS__)
#   define vsf_dma_channel_cancel(__DMA, ...)                       VSF_MCONNECT(VSF_DMA_CFG_PREFIX, _dma_channel_cancel)((__vsf_dma_t *)(__DMA), ##__VA_ARGS__)
#   define vsf_dma_channel_get_transferred_count(__DMA, ...)        VSF_MCONNECT(VSF_DMA_CFG_PREFIX, _dma_channel_get_transferred_count)((__vsf_dma_t *)(__DMA), ##__VA_ARGS__)
#   define vsf_dma_channel_status(__DMA, ...)                       VSF_MCONNECT(VSF_DMA_CFG_PREFIX, _dma_channel_status)((__vsf_dma_t *)(__DMA), ##__VA_ARGS__)
#endif
 
#ifdef __cplusplus
}
#endif
 
#endif  /*__VSF_TEMPLATE_DMA_H__*/