#include "hal/driver/driver.h"

Macros
#define	VSF_DMA_CFG_FUNCTION_RENAME DISABLED

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

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

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_FUNCTION_RENAME

#define VSF_DMA_CFG_FUNCTION_RENAME DISABLED

Function Documentation

◆ vsf_dma_init()

vsf_err_t vsf_dma_init	(	vsf_dma_t *	dma_ptr,
		vsf_dma_cfg_t *	cfg_ptr
	)

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 )

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
	)

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 )

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
	)

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
	)

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
	)

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
	)

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
	)

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

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
	)

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

vsf_err_t vsf_dma_channel_cancel	(	vsf_dma_t *	dma_ptr,
		uint8_t	channel
	)

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

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.

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
	)

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

Macros

Functions

Macro Definition Documentation

◆ VSF_DMA_CFG_FUNCTION_RENAME

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

◆ vsf_dma_channel_sg_start()

◆ vsf_dma_channel_cancel()

◆ vsf_dma_channel_get_transferred_count()

◆ vsf_dma_channel_status()