#include "./vsf_template_hal_driver.h"
#include "hal/arch/vsf_arch.h"

Data Structures
struct	vsf_dma_cfg_t
	Configuration structure for DMA. More...

struct	vsf_dma_channel_hint_t
	DMA channel hint structure for channel allocation. More...

struct	vsf_dma_isr_t

struct	vsf_dma_channel_cfg_t
	dma configuration More...

struct	vsf_dma_channel_sg_desc_t
	DMA scatter-gather descriptor structure. More...

struct	vsf_dma_channel_status_t

struct	vsf_dma_capability_t
	DMA capability structure that can be reimplemented in specific HAL drivers. More...

struct	vsf_dma_op_t

struct	vsf_dma_t

Macros
#define	VSF_DMA_CFG_MULTI_CLASS ENABLED
	Enable multi-class support by default for maximum availability.

#define	VSF_DMA_CFG_PREFIX vsf
	We can redefine macro VSF_DMA_CFG_PREFIX to specify a prefix to call a specific driver directly in the application code.

#define	VSF_DMA_CFG_FUNCTION_RENAME ENABLED
	Disable VSF_DMA_CFG_FUNCTION_RENAME to use the original function names (e.g., vsf_dma_init()).

#define	VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_MODE DISABLED
	Enable the option to reimplement channel mode type in specific hardware drivers.

#define	VSF_DMA_CFG_REIMPLEMENT_TYPE_IRQ_MASK DISABLED
	Enable the option to reimplement interrupt mask type in specific hardware drivers.

#define	VSF_DMA_CFG_REIMPLEMENT_TYPE_ADDR DISABLED
	Enable the option to reimplement DMA address type in specific hardware drivers.

#define	VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_HINT DISABLED
	Enable the option to reimplement Channel Hint type configuration in specific hardware drivers.

#define	VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_CFG DISABLED
	Enable the option to reimplement channel configuration type. For compatibility, do not delete members when redefining vsf_dma_channel_cfg_t The vsf_dma_isr_handler_t and vsf_dma_isr_t types also need to be redefined.

#define	VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_SG_CFG DISABLED
	Enable the option to reimplement DMA channel scatter-gather configuration type.

#define	__VSF_DMA_CFG_SUPPORT_STANDARD_OPTIONAL DISABLED
	Enable standard optional features support.

#define	VSF_DMA_CFG_REIMPLEMENT_TYPE_CFG DISABLED
	Enable the option to reimplement DMA configuration type. For compatibility, do not delete members when redefining vsf_dma_cfg_t.

#define	VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_STATUS DISABLED
	Enable the option to reimplement DMA channel status type.

#define	VSF_DMA_CFG_REIMPLEMENT_TYPE_CTRL DISABLED
	In specific hardware driver, enable macro VSF_DMA_CFG_REIMPLEMENT_TYPE_CTRL to redefine enum vsf_dma_ctrl_t.

#define	VSF_DMA_CFG_REIMPLEMENT_TYPE_CAPABILITY DISABLED
	Enable the option to reimplement capability type. For compatibility, do not delete members when redefining vsf_dma_capability_t.

#define	VSF_DMA_CFG_INHERIT_HAL_CAPABILITY ENABLED
	Enable inheriting HAL capability to reuse common capability definitions.

#define	VSF_DMA_CHANNEL_SG_ARRAY(__NAME, __COUNT, ...)
	DMA scatter-gather configuration macro.

#define	VSF_DMA_CHANNEL_SG_ITEM(__MODE, __SRC_ADDR, __DST_ADDR, __CNT, ...)
	DMA scatter-gather item configuration macro.

#define	VSF_DMA_APIS(__prefix_name)
	DMA API template, used to generate DMA type, specific prefix function declarations, etc.

#define	__VSF_DMA_GET_ARG_OR_DEFAULT(__DEFAULT, __ARG, ...) (__ARG)

#define	VSF_DMA_CHANNEL_HINT_INIT(__CHANNEL, __REQUEST_LINE, ...)

#define	VSF_DMA_CHANNEL_CFG_INIT(__MODE, __ISR, __IRQ_MASK, __SRC_REQ_IDX, __DST_REQ_IDX, ...)
	Initialize vsf_dma_channel_cfg_t structure with default values.

Typedefs
typedef uintptr_t	vsf_dma_addr_t
	DMA address type, used for source address, destination address and scatter-gather descriptor address.

typedef enum vsf_dma_channel_mode_t	vsf_dma_channel_mode_t

typedef enum vsf_dma_irq_mask_t	vsf_dma_irq_mask_t

typedef struct vsf_dma_cfg_t	vsf_dma_cfg_t
	Configuration structure for DMA.

typedef struct vsf_dma_channel_hint_t	vsf_dma_channel_hint_t
	DMA channel hint structure for channel allocation.

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_t

typedef struct vsf_dma_channel_cfg_t	vsf_dma_channel_cfg_t
	dma configuration

typedef struct vsf_dma_channel_sg_desc_t	vsf_dma_channel_sg_desc_t
	DMA scatter-gather descriptor structure.

typedef struct vsf_dma_channel_status_t	vsf_dma_channel_status_t

typedef enum vsf_dma_ctrl_t	vsf_dma_ctrl_t
	Predefined VSF DMA control commands that can be reimplemented in specific HAL drivers.

typedef struct vsf_dma_capability_t	vsf_dma_capability_t
	DMA capability structure that can be reimplemented in specific HAL drivers.

typedef struct vsf_dma_op_t	vsf_dma_op_t

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

enum	{ VSF_DMA_DIRECTION_COUNT = 4 , VSF_DMA_DIRECTION_MASK , VSF_DMA_SRC_ADDR_COUNT = 3 , VSF_DMA_SRC_ADDR_MASK , VSF_DMA_DST_ADDR_COUNT = 3 , VSF_DMA_DST_ADDR_MASK , VSF_DMA_SRC_WIDTH_COUNT = 6 , VSF_DMA_SRC_WIDTH_MASK , VSF_DMA_DST_WIDTH_COUNT = 6 , VSF_DMA_DST_WIDTH_MASK , VSF_DMA_SRC_BURST_COUNT = 8 , VSF_DMA_SRC_BURST_MASK , VSF_DMA_DST_BURST_COUNT = 8 , VSF_DMA_DST_BURST_MASK , VSF_DMA_PRIORITY_COUNT = 4 , VSF_DMA_PRIORITY_MASK , VSF_DMA_MODE_MASK_COUNT = 8 , VSF_DMA_MODE_ALL_BITS_MASK }

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

enum	{ VSF_DMA_IRQ_COUNT = 3 , VSF_DMA_IRQ_ALL_BITS_MASK }

enum	vsf_dma_ctrl_t { __VSF_DMA_CTRL_DUMMY = 0 }
	Predefined VSF DMA control commands that can be reimplemented in specific HAL drivers. More...

Functions
vsf_err_t	vsf_dma_init (vsf_dma_t dma_ptr, vsf_dma_cfg_t cfg_ptr)
	Initialize a DMA instance.

void	vsf_dma_fini (vsf_dma_t *dma_ptr)
	Finalize a DMA instance.

vsf_err_t	vsf_dma_get_configuration (vsf_dma_t dma_ptr, vsf_dma_cfg_t cfg_ptr)
	Get the current configuration of DMA instance.

vsf_dma_capability_t	vsf_dma_capability (vsf_dma_t *dma_ptr)
	Get the capabilities of DMA instance.

vsf_err_t	vsf_dma_channel_acquire (vsf_dma_t dma_ptr, vsf_dma_channel_hint_t channel_hint_ptr)
	DMA acquire a new channel.

void	vsf_dma_channel_release (vsf_dma_t *dma_ptr, uint8_t channel)
	Release a DMA channel.

vsf_err_t	vsf_dma_channel_config (vsf_dma_t dma_ptr, uint8_t channel, vsf_dma_channel_cfg_t cfg_ptr)
	Configure a DMA channel.

vsf_err_t	vsf_dma_channel_get_configuration (vsf_dma_t dma_ptr, uint8_t channel, vsf_dma_channel_cfg_t cfg_ptr)
	Get the current configuration of a DMA channel.

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)
	Start a DMA channel transfer.

vsf_err_t	vsf_dma_channel_cancel (vsf_dma_t *dma_ptr, uint8_t channel)
	Cancel the transmission of a specific DMA channel.

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)
	Configure a DMA channel for scatter-gather transfer.

vsf_err_t	vsf_dma_channel_sg_start (vsf_dma_t *dma_ptr, uint8_t channel)
	Start a DMA scatter-gather transfer.

uint32_t	vsf_dma_channel_get_transferred_count (vsf_dma_t *dma_ptr, uint8_t channel)
	Get the count of data items transferred for a specific DMA channel.

vsf_dma_channel_status_t	vsf_dma_channel_status (vsf_dma_t *dma_ptr, uint8_t channel)
	Get status of a DMA channel.

vsf_err_t	vsf_dma_ctrl (vsf_dma_t dma_ptr, vsf_dma_ctrl_t ctrl, void param)
	Execute a control command on a DMA instance.

Macro Definition Documentation

◆ VSF_DMA_CFG_MULTI_CLASS

#define VSF_DMA_CFG_MULTI_CLASS ENABLED

Enable multi-class support by default for maximum availability.

◆ VSF_DMA_CFG_PREFIX

#define VSF_DMA_CFG_PREFIX vsf

We can redefine macro VSF_DMA_CFG_PREFIX to specify a prefix to call a specific driver directly in the application code.

◆ VSF_DMA_CFG_FUNCTION_RENAME

#define VSF_DMA_CFG_FUNCTION_RENAME ENABLED

Disable VSF_DMA_CFG_FUNCTION_RENAME to use the original function names (e.g., vsf_dma_init()).

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_MODE

#define VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_MODE DISABLED

Enable the option to reimplement channel mode type in specific hardware drivers.

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_IRQ_MASK

#define VSF_DMA_CFG_REIMPLEMENT_TYPE_IRQ_MASK DISABLED

Enable the option to reimplement interrupt mask type in specific hardware drivers.

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_ADDR

#define VSF_DMA_CFG_REIMPLEMENT_TYPE_ADDR DISABLED

Enable the option to reimplement DMA address type in specific hardware drivers.

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_HINT

#define VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_HINT DISABLED

Enable the option to reimplement Channel Hint type configuration in specific hardware drivers.

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_CFG

#define VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_CFG DISABLED

Enable the option to reimplement channel configuration type. For compatibility, do not delete members when redefining vsf_dma_channel_cfg_t The vsf_dma_isr_handler_t and vsf_dma_isr_t types also need to be redefined.

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_SG_CFG

#define VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_SG_CFG DISABLED

Enable the option to reimplement DMA channel scatter-gather configuration type.

◆ __VSF_DMA_CFG_SUPPORT_STANDARD_OPTIONAL

#define __VSF_DMA_CFG_SUPPORT_STANDARD_OPTIONAL DISABLED

Enable standard optional features support.

This macro controls the availability of standard optional features in the template. Standard optional features include:

Channel acquire from all DMA controllers (vsf_dma_channel_acquire_from_all)

Note: This macro is for testing purposes only. Users should NOT enable this macro. Standard optional features should be implemented directly in hardware drivers if the hardware supports them, rather than enabling this macro in the template. Enabling this macro may cause compilation errors or unexpected behavior.

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_CFG

#define VSF_DMA_CFG_REIMPLEMENT_TYPE_CFG DISABLED

Enable the option to reimplement DMA configuration type. For compatibility, do not delete members when redefining vsf_dma_cfg_t.

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_STATUS

#define VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_STATUS DISABLED

Enable the option to reimplement DMA channel status type.

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_CTRL

#define VSF_DMA_CFG_REIMPLEMENT_TYPE_CTRL DISABLED

In specific hardware driver, enable macro VSF_DMA_CFG_REIMPLEMENT_TYPE_CTRL to redefine enum vsf_dma_ctrl_t.

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_CAPABILITY

#define VSF_DMA_CFG_REIMPLEMENT_TYPE_CAPABILITY DISABLED

Enable the option to reimplement capability type. For compatibility, do not delete members when redefining vsf_dma_capability_t.

◆ VSF_DMA_CFG_INHERIT_HAL_CAPABILITY

#define VSF_DMA_CFG_INHERIT_HAL_CAPABILITY ENABLED

Enable inheriting HAL capability to reuse common capability definitions.

◆ VSF_DMA_CHANNEL_SG_ARRAY

#define VSF_DMA_CHANNEL_SG_ARRAY	(	__NAME,
		__COUNT,
		...
	)

Value:

    vsf_dma_channel_sg_desc_t __NAME[__COUNT] = {                               \
        __VA_ARGS__                                                             \
    };

DMA scatter-gather configuration macro.

Note: Use macro VSF_DMA_CHANNEL_SG_ARRAY to initialize the vsf_dma_channel_sg_desc_t structure array for better compatibility.; In specific hardware drivers, the actual array size may be redefined based on the passed __COUNT, e.g., actual array size may be __COUNT+1 (for list termination).

Warning: Do NOT use sizeof(array)/sizeof(array[0]) to calculate sg_count. Always use the __COUNT value that was passed to this macro, as the actual array size may differ from __COUNT in driver-specific implementations.

◆ VSF_DMA_CHANNEL_SG_ITEM

#define VSF_DMA_CHANNEL_SG_ITEM	(	__MODE,
		__SRC_ADDR,
		__DST_ADDR,
		__CNT,
		...
	)

Value:

    {                                                                           \
        .mode = __MODE,                                                         \
        .src_address = __SRC_ADDR,                                              \
        .dst_address = __DST_ADDR,                                              \
        .count = __CNT,                                                         \
        __VA_ARGS__                                                             \
    }

DMA scatter-gather item configuration macro.

Note: Use macro VSF_DMA_CHANNEL_SG_ITEM to initialize the vsf_dma_channel_sg_desc_t structure for better compatibility.; The 'next' field is intentionally NOT initialized by this macro - it is reserved for driver use and will be set up by the driver in vsf_dma_channel_sg_config_desc().

◆ VSF_DMA_APIS

#define VSF_DMA_APIS ( __prefix_name )

Value:

    __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) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,                dma, ctrl,                               VSF_MCONNECT(__prefix_name, _t) *dma_ptr, vsf_dma_ctrl_t ctrl, void* param)

DMA API template, used to generate DMA type, specific prefix function declarations, etc.

Parameters

[in] __prefix_name The prefix used for generating DMA functions.

Examples: /github/workspace/source/hal/driver/common/template/vsf_template_dma.h.

◆ __VSF_DMA_GET_ARG_OR_DEFAULT

#define __VSF_DMA_GET_ARG_OR_DEFAULT	(	__DEFAULT,
		__ARG,
		...
	)	(__ARG)

◆ VSF_DMA_CHANNEL_HINT_INIT

#define VSF_DMA_CHANNEL_HINT_INIT	(	__CHANNEL,
		__REQUEST_LINE,
		...
	)

Value:

    { \
        .channel = (__CHANNEL), \
        .request_line = (__REQUEST_LINE), \
        .prio = __VSF_DMA_GET_ARG_OR_DEFAULT(,##__VA_ARGS__, vsf_arch_prio_invalid, vsf_arch_prio_invalid), \
    }

◆ VSF_DMA_CHANNEL_CFG_INIT

#define VSF_DMA_CHANNEL_CFG_INIT	(	__MODE,
		__ISR,
		__IRQ_MASK,
		__SRC_REQ_IDX,
		__DST_REQ_IDX,
		...
	)

Value:

    { \
        .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), \
    }

Initialize vsf_dma_channel_cfg_t structure with default values.

Parameters

[in]	__MODE	DMA channel mode
[in]	__ISR	Interrupt service routine configuration
[in]	__IRQ_MASK	Interrupt mask
[in]	__SRC_REQ_IDX	Source request index
[in]	__DST_REQ_IDX	Destination request index
[in]	...	Optional interrupt priority. If not provided, defaults to vsf_arch_prio_invalid.

Note: Use this macro to ensure proper initialization, especially for vsf_arch_prio_t which may have non-zero invalid value (vsf_arch_prio_invalid = -1).; If priority is not specified, it will default to vsf_arch_prio_invalid.

Typedef Documentation

◆ vsf_dma_addr_t

typedef uintptr_t vsf_dma_addr_t

DMA address type, used for source address, destination address and scatter-gather descriptor address.

Note: The default type is uintptr_t.

◆ vsf_dma_channel_mode_t

typedef enum vsf_dma_channel_mode_t vsf_dma_channel_mode_t

◆ vsf_dma_irq_mask_t

typedef enum vsf_dma_irq_mask_t vsf_dma_irq_mask_t

◆ vsf_dma_cfg_t

typedef struct vsf_dma_cfg_t vsf_dma_cfg_t

Configuration structure for DMA.

Note: The prio field specifies the default interrupt priority for all DMA channels. This default priority will be used when channel-specific priority is not specified or when channels share the same interrupt.

◆ vsf_dma_channel_hint_t

typedef struct vsf_dma_channel_hint_t vsf_dma_channel_hint_t

DMA channel hint structure for channel allocation.

Note: This structure is used only during channel acquire phase to provide hints for channel allocation. It contains only information needed for channel selection.

◆ vsf_dma_t

typedef struct vsf_dma_t vsf_dma_t

◆ vsf_dma_isr_handler_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)

◆ vsf_dma_isr_t

typedef struct vsf_dma_isr_t vsf_dma_isr_t

◆ vsf_dma_channel_cfg_t

typedef struct vsf_dma_channel_cfg_t vsf_dma_channel_cfg_t

dma configuration

DMA channel configuration structure for transfer setup

Note: This structure contains all configuration needed for DMA transfer operations, including transfer mode, interrupt settings, and peripheral indices.

◆ vsf_dma_channel_sg_desc_t

typedef struct vsf_dma_channel_sg_desc_t vsf_dma_channel_sg_desc_t

DMA scatter-gather descriptor structure.

Note: : The vsf_dma_channel_sg_desc_t structure can be redefined according to the descriptor structure required by DMA Scatter-Gather in specific hardware drivers.

◆ vsf_dma_channel_status_t

typedef struct vsf_dma_channel_status_t vsf_dma_channel_status_t

◆ vsf_dma_ctrl_t

typedef enum vsf_dma_ctrl_t vsf_dma_ctrl_t

Predefined VSF DMA control commands that can be reimplemented in specific HAL drivers.

Note: Used as the 'ctrl' parameter (second parameter) in vsf_dma_ctrl(vsf_dma_t *dma_ptr, vsf_dma_ctrl_t ctrl, void *param) function; The 'param' parameter (third parameter) type depends on the specific control command

Optional control commands require one or more enumeration options and a macro with the same name to determine if they are supported at runtime. If the feature supports more than one option, it is recommended to provide the corresponding MASK option, so that the user can check for supported features at compile-time.

Feature Classification:

Mandatory: None (only __VSF_DMA_CTRL_DUMMY is defined by default)
Standard Optional: None (no standard optional features defined)

◆ vsf_dma_capability_t

typedef struct vsf_dma_capability_t vsf_dma_capability_t

DMA capability structure that can be reimplemented in specific HAL drivers.

Note: This structure defines the features supported by the DMA hardware. When reimplementing, all existing members must be preserved for compatibility.

◆ vsf_dma_op_t

typedef struct vsf_dma_op_t vsf_dma_op_t

Enumeration Type Documentation

◆ vsf_dma_channel_mode_t

enum vsf_dma_channel_mode_t

Enumerator
VSF_DMA_MEMORY_TO_MEMORY
VSF_DMA_MEMORY_TO_PERIPHERAL
VSF_DMA_PERIPHERAL_TO_MEMORY
VSF_DMA_PERIPHERAL_TO_PERIPHERAL
VSF_DMA_SRC_ADDR_INCREMENT
VSF_DMA_SRC_ADDR_DECREMENT
VSF_DMA_SRC_ADDR_NO_CHANGE
VSF_DMA_DST_ADDR_INCREMENT
VSF_DMA_DST_ADDR_DECREMENT
VSF_DMA_DST_ADDR_NO_CHANGE
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_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_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_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_LOW
VSF_DMA_PRIORITY_MEDIUM
VSF_DMA_PRIORITY_HIGH
VSF_DMA_PRIORITY_VERY_HIGH

◆ anonymous enum

anonymous enum

Enumerator
VSF_DMA_DIRECTION_COUNT
VSF_DMA_DIRECTION_MASK
VSF_DMA_SRC_ADDR_COUNT
VSF_DMA_SRC_ADDR_MASK
VSF_DMA_DST_ADDR_COUNT
VSF_DMA_DST_ADDR_MASK
VSF_DMA_SRC_WIDTH_COUNT
VSF_DMA_SRC_WIDTH_MASK
VSF_DMA_DST_WIDTH_COUNT
VSF_DMA_DST_WIDTH_MASK
VSF_DMA_SRC_BURST_COUNT
VSF_DMA_SRC_BURST_MASK
VSF_DMA_DST_BURST_COUNT
VSF_DMA_DST_BURST_MASK
VSF_DMA_PRIORITY_COUNT
VSF_DMA_PRIORITY_MASK
VSF_DMA_MODE_MASK_COUNT
VSF_DMA_MODE_ALL_BITS_MASK

◆ vsf_dma_irq_mask_t

enum vsf_dma_irq_mask_t

Enumerator
VSF_DMA_IRQ_MASK_CPL
VSF_DMA_IRQ_MASK_HALF_CPL
VSF_DMA_IRQ_MASK_ERROR

◆ anonymous enum

anonymous enum

Enumerator
VSF_DMA_IRQ_COUNT
VSF_DMA_IRQ_ALL_BITS_MASK

◆ vsf_dma_ctrl_t

enum vsf_dma_ctrl_t

Predefined VSF DMA control commands that can be reimplemented in specific HAL drivers.

Note: Used as the 'ctrl' parameter (second parameter) in vsf_dma_ctrl(vsf_dma_t *dma_ptr, vsf_dma_ctrl_t ctrl, void *param) function; The 'param' parameter (third parameter) type depends on the specific control command

Optional control commands require one or more enumeration options and a macro with the same name to determine if they are supported at runtime. If the feature supports more than one option, it is recommended to provide the corresponding MASK option, so that the user can check for supported features at compile-time.

Feature Classification:

Mandatory: None (only __VSF_DMA_CTRL_DUMMY is defined by default)
Standard Optional: None (no standard optional features defined)

Enumerator

__VSF_DMA_CTRL_DUMMY

Dummy value for compilation, required when no actual control commands are defined.

Note: This value is needed only when using the template default enum definition (VSF_DMA_CFG_REIMPLEMENT_TYPE_CTRL == DISABLED) and all optional control commands are commented out. It ensures the enum has at least one member to avoid compilation errors with some C compilers that don't allow empty enums.; If you enable any control commands below (uncomment them), or if you redefine the enum in a specific hardware driver (VSF_DMA_CFG_REIMPLEMENT_TYPE_CTRL == ENABLED), you can remove this DUMMY value as long as at least one actual command is defined.

Examples: /github/workspace/source/hal/driver/common/template/vsf_template_dma.h.

Function Documentation

◆ vsf_dma_init()

vsf_err_t vsf_dma_init	(	vsf_dma_t *	dma_ptr,
		vsf_dma_cfg_t *	cfg_ptr
	)

extern

Initialize a DMA instance.

Parameters

[in]	dma_ptr	a pointer to structure vsf_dma_t
[in]	cfg_ptr	a pointer to structure vsf_dma_cfg_t

Returns: vsf_err_t: VSF_ERR_NONE if initialization successful, otherwise returns error code

Note: It is not necessary to call vsf_dma_fini() to deinitialization. vsf_dma_init() should be called before any other DMA API except vsf_dma_capability().

◆ vsf_dma_fini()

void vsf_dma_fini ( vsf_dma_t * dma_ptr )

extern

Finalize a DMA instance.

Parameters

[in] dma_ptr a pointer to structure vsf_dma_t

Returns: none

◆ vsf_dma_get_configuration()

vsf_err_t vsf_dma_get_configuration	(	vsf_dma_t *	dma_ptr,
		vsf_dma_cfg_t *	cfg_ptr
	)

extern

Get the current configuration of DMA instance.

Parameters

[in]	dma_ptr	a pointer to structure vsf_dma_t
[out]	cfg_ptr	a pointer to structure vsf_dma_cfg_t to store the current configuration

Returns: vsf_err_t: VSF_ERR_NONE if successful, otherwise returns error code

◆ vsf_dma_capability()

vsf_dma_capability_t vsf_dma_capability ( vsf_dma_t * dma_ptr )

extern

Get the capabilities of DMA instance.

Parameters

[in] dma_ptr a pointer to structure vsf_dma_t

Returns: vsf_dma_capability_t: All capabilities of current DMA vsf_dma_capability_t

◆ vsf_dma_channel_acquire()

vsf_err_t vsf_dma_channel_acquire	(	vsf_dma_t *	dma_ptr,
		vsf_dma_channel_hint_t *	channel_hint_ptr
	)

extern

DMA acquire a new channel.

Parameters

[in]	dma_ptr	a pointer to structure vsf_dma_t
[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.

Returns: vsf_err_t: VSF_ERR_NONE if the acquire was successful, otherwise returns error code

Note: For priority handling details, refer to vsf_dma_channel_hint_t documentation.

◆ vsf_dma_channel_release()

void vsf_dma_channel_release	(	vsf_dma_t *	dma_ptr,
		uint8_t	channel
	)

extern

Release a DMA channel.

Parameters

[in]	dma_ptr	a pointer to structure vsf_dma_t
[in]	channel	channel number

Returns: none

◆ vsf_dma_channel_config()

vsf_err_t vsf_dma_channel_config	(	vsf_dma_t *	dma_ptr,
		uint8_t	channel,
		vsf_dma_channel_cfg_t *	cfg_ptr
	)

extern

Configure a DMA channel.

Parameters

[in]	dma_ptr	a pointer to structure vsf_dma_t
[in]	channel	channel number
[in]	cfg_ptr	a pointer to DMA channel configuration

Returns: vsf_err_t: VSF_ERR_NONE if the configuration was successful, otherwise returns error code

Note

Priority handling:

The cfg_ptr->prio field is only effective when hardware supports per-channel independent interrupt priority configuration.
If cfg_ptr->prio is vsf_arch_prio_invalid, the default priority from vsf_dma_cfg_t (or the priority set during channel_acquire) will be used.
For chips where multiple channels share the same interrupt, modifying priority in channel_config may affect other channels sharing the same interrupt. The behavior in this case is implementation-defined (driver-specific).
For per-channel independent interrupt scenarios, this allows dynamic priority adjustment at runtime.
For static allocation (channels fixed to peripherals): a) Priority can be configured via channel_config() at runtime (if hardware supports dynamic priority adjustment). b) If priority is not configured via channel_config(), the default priority from vsf_dma_cfg_t will be used.
Priority override order (from highest to lowest priority):
1. Priority specified in channel_config() (overrides all previous settings)
2. Priority specified in channel_acquire() (preserved if config uses vsf_arch_prio_invalid)
3. Default priority from vsf_dma_cfg_t (used as fallback)

◆ vsf_dma_channel_get_configuration()

vsf_err_t vsf_dma_channel_get_configuration	(	vsf_dma_t *	dma_ptr,
		uint8_t	channel,
		vsf_dma_channel_cfg_t *	cfg_ptr
	)

extern

Get the current configuration of a DMA channel.

Parameters

[in]	dma_ptr	a pointer to structure vsf_dma_t
[in]	channel	channel number
[out]	cfg_ptr	a pointer to structure vsf_dma_channel_cfg_t to store the current configuration

Returns: vsf_err_t: VSF_ERR_NONE if successful, otherwise returns error code

◆ vsf_dma_channel_start()

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

Start a DMA channel transfer.

Parameters

[in]	dma_ptr	a pointer to structure vsf_dma_t
[in]	channel	channel number
[in]	src_address	source address
[in]	dst_address	destination address
[in]	count	number of data items to be transferred

Returns

vsf_err_t:

VSF_ERR_NONE if the start request was successful
VSF_ERR_BUSY if the channel is currently busy with another transfer
Other error codes for other failures

◆ vsf_dma_channel_cancel()

vsf_err_t vsf_dma_channel_cancel	(	vsf_dma_t *	dma_ptr,
		uint8_t	channel
	)

extern

Cancel the transmission of a specific DMA channel.

Parameters

[in]	dma_ptr	a pointer to structure vsf_dma_t
[in]	channel	channel number

Returns: vsf_err_t: VSF_ERR_NONE if the cancel request was successful, otherwise returns error code

◆ vsf_dma_channel_sg_config_desc()

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

Configure a DMA channel for scatter-gather transfer.

Parameters

[in]	dma_ptr	a pointer to structure vsf_dma_t
[in]	channel	channel number
[in]	isr	DMA interrupt handler
[in]	cfg_ptr	a pointer to DMA channel scatter-gather configuration
[in]	sg_count	number of scatter-gather configurations

Returns: vsf_err_t: VSF_ERR_NONE if the configuration was successful, otherwise returns error code

Note

The scatter_gather_cfg array should be initialized using the VSF_DMA_CHANNEL_SG_ARRAY macro for better compatibility.

The scatter_gather_cfg must point to DMA-accessible memory region.

The caller must ensure scatter_gather_cfg remains valid until the DMA transfer completes.

The contents of scatter_gather_cfg may be modified by the driver to match the actual hardware descriptor format required by the DMA controller.

The driver will handle linked list construction internally, including:

Setting up the 'next' pointer for each descriptor
Terminating the list with NULL or hardware-specific end marker Users only need to provide a valid descriptor array with sg_count elements.

For a specific channel, API vsf_dma_channel_sg_config_desc() and vsf_dma_channel_sg_start() must be used together. API vsf_dma_channel_config() and vsf_dma_channel_start() are paired for use. These two groups of APIs cannot be mixed. Only after the current DMA transfer is completely finished, can you switch to the other group of APIs.

◆ vsf_dma_channel_sg_start()

vsf_err_t vsf_dma_channel_sg_start	(	vsf_dma_t *	dma_ptr,
		uint8_t	channel
	)

extern

Start a DMA scatter-gather transfer.

Parameters

[in]	dma_ptr	a pointer to structure vsf_dma_t
[in]	channel	channel number

Returns

vsf_err_t:

VSF_ERR_NONE if the start request was successful
VSF_ERR_BUSY if the channel is currently busy with another transfer
Other error codes for other failures

Note

: For a specific channel, API vsf_dma_channel_sg_config_desc() and vsf_dma_channel_sg_start() must be used together. API vsf_dma_channel_config() and vsf_dma_channel_start() are paired for use. These two groups of APIs cannot be mixed. Only after the current DMA transfer is completely finished, can you switch to the other group of APIs.

: If the channel is busy, this function returns VSF_ERR_BUSY immediately without modifying the ongoing transfer. To wait for the current transfer to complete, applications can:

Poll vsf_dma_channel_status() to check if the channel is no longer busy (is_busy == 0)
Wait for the transfer completion interrupt (VSF_DMA_IRQ_MASK_CPL) if interrupt is enabled

◆ vsf_dma_channel_get_transferred_count()

uint32_t vsf_dma_channel_get_transferred_count	(	vsf_dma_t *	dma_ptr,
		uint8_t	channel
	)

extern

Get the count of data items transferred for a specific DMA channel.

Parameters

[in]	dma_ptr	a pointer to structure vsf_dma_t
[in]	channel	channel number

Returns: uint32_t: Number of data items transferred

Note

Behavior after completion:

For normal transfer: Returns 0 after VSF_DMA_IRQ_MASK_CPL interrupt.
For scatter-gather transfer: Returns 0 after the entire SG chain completes.

Usage after cancel: This function is typically called after vsf_dma_channel_cancel() to get the number of data items that were successfully transferred before cancellation.

Scatter-Gather semantics:

Returns the cumulative total of data items transferred across all descriptors in the SG chain, including completed descriptors plus the partial transfer of the current (interrupted) descriptor.
If cancel occurs exactly at a descriptor boundary, the return value includes all data items from completed descriptors (the current descriptor's transfer count would be 0).

◆ vsf_dma_channel_status()

vsf_dma_channel_status_t vsf_dma_channel_status	(	vsf_dma_t *	dma_ptr,
		uint8_t	channel
	)

extern

Get status of a DMA channel.

Parameters

[in]	dma_ptr	a pointer to structure vsf_dma_t
[in]	channel	channel number

Returns: vsf_dma_channel_status_t: Status of the DMA channel

◆ vsf_dma_ctrl()

vsf_err_t vsf_dma_ctrl	(	vsf_dma_t *	dma_ptr,
		vsf_dma_ctrl_t	ctrl,
		void *	param
	)

extern

Execute a control command on a DMA instance.

Parameters

[in,out]	dma_ptr	pointer to DMA instance structure vsf_dma_t
[in]	ctrl	Control command from vsf_dma_ctrl_t enumeration
[in]	param	Command-specific parameter (can be NULL depending on command)

Returns: vsf_err_t: VSF_ERR_NONE if command executed successfully, VSF_ERR_NOT_SUPPORT if command is not supported, other error codes defined by vsf_err_t for specific failures

Note: Available commands and their parameters are hardware-dependent; Some commands may not be supported on all hardware platforms

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ VSF_DMA_CFG_MULTI_CLASS

◆ VSF_DMA_CFG_PREFIX

◆ VSF_DMA_CFG_FUNCTION_RENAME

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_MODE

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_IRQ_MASK

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_ADDR

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_HINT

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_CFG

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_SG_CFG

◆ __VSF_DMA_CFG_SUPPORT_STANDARD_OPTIONAL

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_CFG

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_STATUS

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_CTRL

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_CAPABILITY

◆ VSF_DMA_CFG_INHERIT_HAL_CAPABILITY

◆ VSF_DMA_CHANNEL_SG_ARRAY

◆ VSF_DMA_CHANNEL_SG_ITEM

◆ VSF_DMA_APIS

◆ __VSF_DMA_GET_ARG_OR_DEFAULT

◆ VSF_DMA_CHANNEL_HINT_INIT

◆ VSF_DMA_CHANNEL_CFG_INIT

Typedef Documentation

◆ vsf_dma_addr_t

◆ vsf_dma_channel_mode_t

◆ vsf_dma_irq_mask_t

◆ vsf_dma_cfg_t

◆ vsf_dma_channel_hint_t

◆ vsf_dma_t

◆ vsf_dma_isr_handler_t

◆ vsf_dma_isr_t

◆ vsf_dma_channel_cfg_t

◆ vsf_dma_channel_sg_desc_t

◆ vsf_dma_channel_status_t

◆ vsf_dma_ctrl_t

◆ vsf_dma_capability_t

◆ vsf_dma_op_t

Enumeration Type Documentation

◆ vsf_dma_channel_mode_t

◆ anonymous enum

◆ vsf_dma_irq_mask_t

◆ anonymous enum

◆ vsf_dma_ctrl_t

Function Documentation

◆ vsf_dma_init()

◆ vsf_dma_fini()

◆ vsf_dma_get_configuration()

◆ vsf_dma_capability()

◆ vsf_dma_channel_acquire()

◆ vsf_dma_channel_release()

◆ vsf_dma_channel_config()

◆ vsf_dma_channel_get_configuration()

◆ vsf_dma_channel_start()

◆ vsf_dma_channel_cancel()

◆ vsf_dma_channel_sg_config_desc()

◆ vsf_dma_channel_sg_start()

◆ vsf_dma_channel_get_transferred_count()

◆ vsf_dma_channel_status()

◆ vsf_dma_ctrl()