#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_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_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.

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

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.

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

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

Parameters

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

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.

◆ 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_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

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

◆ 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

◆ 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

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_REIMPLEMENT_TYPE_CFG

◆ VSF_DMA_CFG_REIMPLEMENT_TYPE_CHANNEL_STATUS

◆ 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

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_capability_t

◆ vsf_dma_op_t

Enumeration Type Documentation

◆ vsf_dma_channel_mode_t

◆ anonymous enum

◆ vsf_dma_irq_mask_t

◆ anonymous enum

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