Functions

Functions for DMA driver. More...

Functions
dma_status_en	dma_init (dma_instance_en instance)
dma_status_en	dma_deinit (dma_instance_en instance)
dma_status_en	dma_channel_request (dma_instance_en instance, uint32_t *channel, dma_channel_attr_t *attr)
dma_status_en	dma_request_specific_channel (dma_instance_en instance, uint32_t channel)
dma_status_en	dma_free_channel (dma_instance_en instance, uint32_t channel)
dma_status_en	dma_prepare_transfer (dma_instance_en instance, uint32_t channel, dma_channel_config_t *config)
dma_status_en	dma_start_transfer (dma_instance_en instance, uint32_t channel)
dma_status_en	dma_sw_trig_config (dma_instance_en instance, uint32_t channel, const dma_sw_trigger_config_t *config)
dma_status_en	dma_sw_trig (dma_instance_en instance, uint32_t channel, dma_trigger_target_en trigger_target)
dma_status_en	dma_get_status (dma_instance_en instance, uint32_t channel, uint32_t *status)
dma_status_en	dma_clear_status (dma_instance_en instance, uint32_t channel, uint32_t mask)
dma_status_en	dma_enable_ints (dma_instance_en instance, uint32_t channel, uint32_t mask)
dma_status_en	dma_disable_ints (dma_instance_en instance, uint32_t channel, uint32_t mask)
dma_status_en	dma_get_error (dma_instance_en instance, uint32_t channel, uint32_t *error)
dma_status_en	dma_pause_transfer (dma_instance_en instance, uint32_t channel)
dma_status_en	dma_resume_transfer (dma_instance_en instance, uint32_t channel)
dma_status_en	dma_stop_transfer (dma_instance_en instance, uint32_t channel)
dma_status_en	dma_abort_transfer (dma_instance_en instance, uint32_t channel)
dma_status_en	dma_get_remaining_bytes (dma_instance_en instance, uint32_t channel, uint32_t *remaining)
dma_status_en	dma_channel_is_active (dma_instance_en instance, uint32_t channel, bool *active)
dma_status_en	dma_create_descriptor (dma_instance_en instance, uint32_t channel, const dma_channel_config_t *config, dma_descriptor_handle_t *descriptor_out)
dma_status_en	dma_link_descriptors (dma_descriptor_handle_t first_desc, dma_descriptor_handle_t second_desc)
dma_status_en	dma_start_descriptor_chain (dma_instance_en instance, uint32_t channel, dma_descriptor_handle_t *first_desc)
dma_status_en	dma_free_descriptor (dma_descriptor_handle_t descriptor)

Detailed Description

Functions for DMA driver.

General functions for DMA driver. These functions provide basic functionality on top of DMA hardware registers.

Function Documentation

dma_init()

dma_status_en dma_init

(

dma_instance_en

instance

)

Initializes the DMA controller instance and internal driver state.

Parameters

[in]

instance

DMA controller instance identifier.

Returns

dma_status_en Error code indicating success or the reason for failure.

Precondition

None - this is the first function that must be called.

Postcondition

DMA controller instance is initialized and ready for channel requests.

Note

This function must be called before any other DMA API is used. Multiple calls to this function for the same instance are safe.

dma_deinit()

dma_status_en dma_deinit

(

dma_instance_en

instance

)

Deinitializes the DMA controller instance and resets internal driver state.

Parameters

[in]

instance

DMA controller instance identifier.

Returns

dma_status_en Error code indicating success or the reason for failure.

dma_channel_request()

dma_status_en dma_channel_request	(	dma_instance_en	instance,
		uint32_t *	channel,
		dma_channel_attr_t *	attr )

Requests and reserves a free DMA channel for use based on requirements.

Parameters

[in]	instance	DMA controller instance identifier.
[out]	channel	Pointer to variable that receives the allocated channel number.
[in]	attr	Pointer to channel requirements structure specifying desired channel attributes.

Returns

dma_status_en Error code indicating success or the reason for failure.

Precondition

DMA controller instance must be initialized using dma_init.

Postcondition

If successful, a channel is allocated and ready for configuration.

Note

The allocated channel number is returned via the channel parameter. Channel attributes specify requirements like 2D support, template support, etc.

dma_request_specific_channel()

dma_status_en dma_request_specific_channel	(	dma_instance_en	instance,
		uint32_t	channel )

Requests and reserves a specific DMA channel by channel number.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used (0 to max channels - 1).

Returns

dma_status_en Error code indicating success or the reason for failure.

dma_free_channel()

dma_status_en dma_free_channel	(	dma_instance_en	instance,
		uint32_t	channel )

Releases a previously requested DMA channel, making it available for reuse.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used (0 to max channels - 1).

Returns

dma_status_en Error code indicating success or the reason for failure.

dma_prepare_transfer()

dma_status_en dma_prepare_transfer	(	dma_instance_en	instance,
		uint32_t	channel,
		dma_channel_config_t *	config )

Prepares and configures a DMA transfer, making it ready to start. This function validates parameters, configures hardware registers, and prepares the channel for execution.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used (0 to max channels - 1).
[in]	config	Pointer to the complete DMA channel configuration structure containing transfer parameters, source/destination addresses, and callback settings.

Returns

dma_status_en Error code indicating success or the reason for failure.

Precondition

• DMA controller instance must be initialized using dma_init.
• Channel must be allocated using dma_channel_request or dma_request_specific_channel.
• Configuration structure must be properly initialized with valid parameters.

Postcondition

• If successful, channel is configured and ready to start transfer.
• Hardware registers are programmed with transfer parameters.
• Callback function is registered if provided in configuration.

Note

This function validates all parameters before configuring the hardware. Any previous configuration on this channel will be overwritten.

dma_start_transfer()

dma_status_en dma_start_transfer	(	dma_instance_en	instance,
		uint32_t	channel )

Starts the DMA transfer on the specified channel.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used (0 to max channels - 1).

Returns

dma_status_en Error code indicating success or the reason for failure.

dma_sw_trig_config()

dma_status_en dma_sw_trig_config	(	dma_instance_en	instance,
		uint32_t	channel,
		const dma_sw_trigger_config_t *	config )

Configures software trigger settings for the specified DMA channel.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used (0 to max channels - 1).
[in]	config	Pointer to software trigger configuration structure.

Returns

dma_status_en Error code indicating success or the reason for failure.

dma_sw_trig()

dma_status_en dma_sw_trig	(	dma_instance_en	instance,
		uint32_t	channel,
		dma_trigger_target_en	trigger_target )

Issues a software trigger to the specified DMA channel.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used (0 to max channels - 1).
[in]	trigger_target	Source or destination trigger target (dma_trigger_target_en).

Returns

dma_status_en Error code indicating success or the reason for failure.

dma_get_status()

dma_status_en dma_get_status	(	dma_instance_en	instance,
		uint32_t	channel,
		uint32_t *	status )

Returns the current status flags of the specified DMA channel.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used (0 to max channels - 1).
[out]	status	Pointer to store the current status flags (combination of dma_status_flags_en).

Returns

dma_status_en Error code indicating success or the reason for failure.

dma_clear_status()

dma_status_en dma_clear_status	(	dma_instance_en	instance,
		uint32_t	channel,
		uint32_t	mask )

Clears the specified status flags for the DMA channel.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used (0 to max channels - 1).
[in]	mask	Status mask specifying which flags to clear (combination of dma_status_flags_en).

Returns

dma_status_en Error code indicating success or the reason for failure.

dma_enable_ints()

dma_status_en dma_enable_ints	(	dma_instance_en	instance,
		uint32_t	channel,
		uint32_t	mask )

Enables interrupts for the specified DMA channel.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used (0 to max channels - 1).
[in]	mask	Interrupt mask specifying which interrupts to enable (combination of dma_interrupt_flags_en).

Returns

dma_status_en Error code indicating success or the reason for failure.

dma_disable_ints()

dma_status_en dma_disable_ints	(	dma_instance_en	instance,
		uint32_t	channel,
		uint32_t	mask )

Disables the specified interrupt sources for the given DMA channel.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel for which interrupts need to be disabled (0 to max channels - 1).
[in]	mask	Interrupt mask specifying which interrupts to disable (combination of dma_ch_interrupt_en flags).

Returns

dma_status_en Error code indicating success or the reason for failure.

dma_get_error()

dma_status_en dma_get_error	(	dma_instance_en	instance,
		uint32_t	channel,
		uint32_t *	error )

Retrieves error information for the specified DMA channel.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used (0 to max channels - 1).
[out]	error	Pointer to store the error information and error codes.

Returns

dma_status_en Error code indicating success or the reason for failure.

dma_pause_transfer()

dma_status_en dma_pause_transfer	(	dma_instance_en	instance,
		uint32_t	channel )

Pauses the active DMA transfer on the specified channel.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used (0 to max channels - 1).

Returns

dma_status_en Error code indicating success or the reason for failure.

dma_resume_transfer()

dma_status_en dma_resume_transfer	(	dma_instance_en	instance,
		uint32_t	channel )

Resumes a previously paused DMA transfer on the specified channel.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used (0 to max channels - 1).

Returns

dma_status_en Error code indicating success or the reason for failure.

dma_stop_transfer()

dma_status_en dma_stop_transfer	(	dma_instance_en	instance,
		uint32_t	channel )

Stops the DMA transfer on the specified channel and resets channel state.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used (0 to max channels - 1).

Returns

dma_status_en Error code indicating success or the reason for failure.

dma_abort_transfer()

dma_status_en dma_abort_transfer	(	dma_instance_en	instance,
		uint32_t	channel )

Aborts an ongoing DMA transfer on the specified channel.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used (0 to max channels - 1).

Returns

dma_status_en Error code indicating success or the reason for failure.

dma_get_remaining_bytes()

dma_status_en dma_get_remaining_bytes	(	dma_instance_en	instance,
		uint32_t	channel,
		uint32_t *	remaining )

Retrieves the number of bytes remaining in the current DMA transfer.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used (0 to max channels - 1).
[out]	remaining	Pointer to store the remaining byte count for the current transfer.

Returns

dma_status_en Error code indicating success or the reason for failure.

dma_channel_is_active()

dma_status_en dma_channel_is_active	(	dma_instance_en	instance,
		uint32_t	channel,
		bool *	active )

Checks if the specified DMA channel is currently active.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used (0 to max channels - 1).
[out]	active	Pointer to store the channel active status (true if active, false if idle).

Returns

dma_status_en Error code indicating success or the reason for failure.

dma_create_descriptor()

dma_status_en dma_create_descriptor	(	dma_instance_en	instance,
		uint32_t	channel,
		const dma_channel_config_t *	config,
		dma_descriptor_handle_t *	descriptor_out )

Creates a DMA command descriptor based on the provided configuration. Automatically generates the header and includes only the relevant fields required for the DMA transfer.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used.
[in]	config	Pointer to the DMA channel configuration structure.
[out]	descriptor_out	Pointer to a variable that receives the created descriptor handle. The descriptor memory must be pre-allocated by the caller and aligned as per hardware requirements (typically 32-byte alignment). The caller is responsible for memory management.

Returns

dma_status_en - Error code indicating success or reason for failure.

Note

• The descriptor format includes a header followed by optional register fields based on the provided configuration.
• Descriptor linking must be performed using dma_link_descriptors before chain execution.
• This function does NOT allocate memory for the descriptor. The caller must provide pre-allocated, properly aligned memory via descriptor_out parameter.

dma_link_descriptors()

dma_status_en dma_link_descriptors	(	dma_descriptor_handle_t	first_desc,
		dma_descriptor_handle_t	second_desc )

Links two descriptors together to form a command chain.

Parameters

[in]	first_desc	Handle to the first descriptor in the chain.
[in]	second_desc	Handle to the second descriptor to link to the first descriptor.

Returns

dma_status_en Error code indicating success or the reason for failure.

Precondition

Both descriptors must be created using dma_create_descriptor.

Postcondition

If successful, first_desc will point to second_desc in the chain.

Note

This function modifies the first descriptor to link to the second descriptor. Multiple descriptors can be chained by calling this function repeatedly.

dma_start_descriptor_chain()

dma_status_en dma_start_descriptor_chain	(	dma_instance_en	instance,
		uint32_t	channel,
		dma_descriptor_handle_t *	first_desc )

Starts execution of a descriptor chain by setting the initial command and linking to the first descriptor.

Parameters

[in]	instance	DMA controller instance identifier.
[in]	channel	Number of the channel being used (0 to max channels - 1).
[in]	first_desc	Pointer to handle of the first descriptor in the chain to execute.

Returns

dma_status_en Error code indicating success or the reason for failure.

Precondition

• DMA controller instance must be initialized using dma_init.
• Channel must be allocated and configured.
• Descriptor chain must be properly created and linked.

Postcondition

• If successful, descriptor chain execution begins on the specified channel.

Note

The first_desc parameter is a pointer to the descriptor handle, not the handle itself.

dma_free_descriptor()

dma_status_en dma_free_descriptor

(

dma_descriptor_handle_t

descriptor

)

Frees a descriptor handle and releases associated resources. This function only releases internal driver resources associated with the descriptor. It does NOT free the descriptor memory itself, as that memory was provided by the caller.

Parameters

[in]

descriptor

Descriptor handle to free and release associated driver resources.

Returns

dma_status_en Error code indicating success or the reason for failure.

Note

This function does NOT free the descriptor memory. The caller is responsible for freeing the descriptor memory that was originally provided to dma_create_descriptor. Only internal driver resources and associations are released.