DMA HAL

DMA Hardware Abstraction Layer API Reference. More...

Functions list
void	hal_dma_configure_default (hal_dma_config_t *config)
	Configure DMA HAL configuration structure.
err_t	hal_dma_open (hal_dma_t *obj, hal_dma_config_t *config)
	Open the DMA HAL object.
void	hal_dma_get_channels (hal_dma_channel_t *channels)
	Get DMA modules/streams/channels.
err_t	hal_dma_set_mode (hal_dma_t *obj, hal_dma_mode_t mode)
	Set the DMA mode.
err_t	hal_dma_set_direction (hal_dma_t *obj, hal_dma_direction_t direction)
	Set the DMA direction.
err_t	hal_dma_set_priority (hal_dma_t *obj, hal_dma_priority_t priority)
	Set the DMA priority.
err_t	hal_dma_set_transfer_config (hal_dma_t *obj, uint32_t addr_src, uint32_t addr_dst, size_t transfer_size, hal_dma_source_memory_region_t src_mem_type)
	Configure the DMA transfer.
err_t	hal_dma_transfer_start (hal_dma_t *obj)
	Initializes the DMA transfer.
err_t	hal_dma_transfer_stop (hal_dma_t *obj)
	Stops the DMA transfer.
err_t	hal_dma_transfer_abort (hal_dma_t *obj)
	Aborts a DMA transfer.
err_t	hal_dma_close (hal_dma_t *obj)
	Close DMA HAL object.

Function Documentation

hal_dma_close()

err_t hal_dma_close

(

hal_dma_t *

obj

)

Closes DMA HAL object, aborts any ongoing transfers, disables the stream, deinitializes the module, clears all buffers used by object and disables module clock for lower power consumption.

Parameters

[in,out]

obj

DMA HAL object. See hal_dma_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by err_t, which is dependant on the architecture and ported low level layer.

Example

// DMA HAL context structure.
static hal_dma_t hal_dma;
 
// DMA HAL configuration structure.
static hal_dma_config_t hal_dma_cfg;
 
// Fill structure with default values.
hal_dma_configure_default( &hal_dma_cfg );
 
// Initialize and allocate resources for DMA module.
if ( HAL_DMA_ERROR == hal_dma_open( &hal_dma, &hal_dma_cfg ) )
{
    // Error handling strategy.
}
 
// Close previously initialized DMA module object handler.
if ( HAL_DMA_SUCCESS == hal_dma_close( &hal_dma ) {
    // No error.
} else {
    // Handle the error.
}

hal_dma_configure_default()

void hal_dma_configure_default

(

hal_dma_config_t *

config

)

Configures hal_dma_config_t structure to default initialization values. Take into consideration that this is just structure variable initial values setting. Values need to be redefined by user.

Parameters

[in,out]

config

configure DMA HAL configuration structure. See hal_dma_config_t structure definition for detailed explanation.

Default values:

Function	Default value
Module	0xFF
Stream	0xFF
Channel	0xFF
Direction	HAL_DMA_DIRECTION_DEFAULT
Mode	HAL_DMA_MODE_DEFAULT
Priority	HAL_DMA_PRIORITY_DEFAULT
Memory increment	false
Memory data alignment	HAL_DMA_DATA_ALIGN_DEFAULT
Memory burst size	HAL_DMA_BURST_SIZE_INCREMENT_DEFAULT
Peripheral increment	false
Peripheral data alignment	HAL_DMA_DATA_ALIGN_DEFAULT
Peripheral burst size	HAL_DMA_BURST_SIZE_INCREMENT_DEFAULT
Source address	0
Destination address	0
Transfer length	0

Returns

Nothing.

Example

// DMA HAL configuration structure.
static hal_dma_config_t hal_dma_cfg;
 
// Fill structure with default values.
hal_dma_configure_default( &hal_dma_cfg );

hal_dma_get_channels()

void hal_dma_get_channels

(

hal_dma_channel_t *

channels

)

Checks current MCU for available number of modules, streams and channels.

Parameters

[in,out]

channels

DMA channel context array. See hal_dma_channel_t definition for detailed explanation.

Returns

Nothing.

Precondition

Make sure that channels array has been adequately instantiated before calling this API.

Note

It is recommended to use this API in order to check available resources and see which ones are free to use.

Example

// DMA HAL channel context structure.
static hal_dma_channel_t hal_dma_channels;
 
// Get list of available channels per stream per module.
hal_dma_get_channels( &hal_dma_channels );
 
// Lets say we want to use DMA module 0, stream 3 and channel 4.
if ( DMA_STATE_FREE == hal_dma_channels[0][3][4] )
{
    // Module 0, stream 3, channel 4 is free for use.
}

hal_dma_open()

err_t hal_dma_open	(	hal_dma_t *	obj,
		hal_dma_config_t *	config )

Opens the DMA HAL object on selected module, stream and channel. Allocates memory for specified object. Additionally, initializes the DMA module.

Parameters

[in,out]	obj	DMA HAL object. See hal_dma_t structure definition for detailed explanation.
[in]	config	configure DMA HAL configuration settings. See hal_dma_config_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by err_t, which is dependant on the architecture and ported low level layer.

Precondition

Make sure that configuration structure has been adequately populated beforehand. See hal_dma_configure_default definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// DMA HAL context structure.
static hal_dma_t hal_dma;
 
// DMA HAL configuration structure.
static hal_dma_config_t hal_dma_cfg;
 
// Fill structure with default values.
hal_dma_configure_default( &hal_dma_cfg );
 
// Specify desired DMA module.
hal_dma_cfg.module = 0; // First module (DMA0 or DMA1 based on MCU).
 
// Specify desired DMA stream number.
hal_dma_cfg.stream = 5;
 
// Specify desired DMA channel number.
hal_dma_cfg.channel = 3;
 
// Initialize and allocate resources for DMA module.
if ( HAL_DMA_ERROR == hal_dma_open( &dma, &hal_dma_cfg ) )
{
    // Error handling strategy.
}

hal_dma_set_direction()

err_t hal_dma_set_direction	(	hal_dma_t *	obj,
		hal_dma_direction_t	direction )

Sets DMA direction to be used by the DMA HAL.

Parameters

[in,out]	obj	DMA HAL object. See hal_dma_t structure definition for detailed explanation.
[in]	direction	DMA direction. See hal_dma_direction_t for valid values.

Returns

The function can return one of the values defined by err_t, which is dependant on the architecture and ported low level layer.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_dma_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// DMA HAL context structure.
static hal_dma_t hal_dma;
 
// DMA HAL configuration structure.
static hal_dma_config_t hal_dma_cfg;
 
// Fill structure with default values.
hal_dma_configure_default( &hal_dma_cfg );
 
// Initialize and allocate resources for DMA module.
if ( HAL_DMA_ERROR == hal_dma_open( &hal_dma, &hal_dma_cfg ) )
{
    // Error handling strategy.
}
 
// Set desired DMA mode.
if ( HAL_DMA_ERROR == hal_dma_set_direction( &hal_dma, HAL_DMA_DIRECTION_MEMORY_TO_MEMORY ) )
{
    // Error handling strategy.
}

hal_dma_set_mode()

err_t hal_dma_set_mode	(	hal_dma_t *	obj,
		hal_dma_mode_t	mode )

Sets DMA mode to be used by the DMA HAL.

Parameters

[in,out]	obj	DMA HAL object. See hal_dma_t structure definition for detailed explanation.
[in]	mode	DMA mode. See hal_dma_mode_t for valid values.

Returns

The function can return one of the values defined by err_t, which is dependant on the architecture and ported low level layer.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_dma_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// DMA HAL context structure.
static hal_dma_t hal_dma;
 
// DMA HAL configuration structure.
static hal_dma_config_t hal_dma_cfg;
 
// Fill structure with default values.
hal_dma_configure_default( &hal_dma_cfg );
 
// Initialize and allocate resources for DMA module.
if ( HAL_DMA_ERROR == hal_dma_open( &hal_dma, &hal_dma_cfg ) )
{
    // Error handling strategy.
}
 
// Set desired DMA mode.
if ( HAL_DMA_ERROR == hal_dma_set_mode( &hal_dma, HAL_DMA_MODE_NORMAL ) )
{
    // Error handling strategy.
}

hal_dma_set_priority()

err_t hal_dma_set_priority	(	hal_dma_t *	obj,
		hal_dma_priority_t	priority )

Sets DMA priority level to be used by the DMA HAL.

Parameters

[in,out]	obj	DMA HAL object. See hal_dma_t structure definition for detailed explanation.
[in]	priority	DMA priority level. See hal_dma_priority_t for valid values.

Returns

The function can return one of the values defined by err_t, which is dependant on the architecture and ported low level layer.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_dma_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// DMA HAL context structure.
static hal_dma_t hal_dma;
 
// DMA HAL configuration structure.
static hal_dma_config_t hal_dma_cfg;
 
// Fill structure with default values.
hal_dma_configure_default( &hal_dma_cfg );
 
// Initialize and allocate resources for DMA module.
if ( HAL_DMA_ERROR == hal_dma_open( &hal_dma, &hal_dma_cfg ) )
{
    // Error handling strategy.
}
 
// Set desired DMA mode.
if ( HAL_DMA_ERROR == hal_dma_set_priority( &hal_dma, HAL_DMA_PRIORITY_MEDIUM ) )
{
    // Error handling strategy.
}

hal_dma_set_transfer_config()

err_t hal_dma_set_transfer_config	(	hal_dma_t *	obj,
		uint32_t	addr_src,
		uint32_t	addr_dst,
		size_t	transfer_size,
		hal_dma_source_memory_region_t	src_mem_type )

Configures initialized DMA stream for transfer.

Parameters

[in,out]	obj	DMA HAL object. See hal_dma_t structure definition for detailed explanation.
[in]	addr_src	Source address for transfer.
[in]	addr_dst	Destination address for transfer.
[in]	transfer_size	Number of bytes to transfer.
[in]	src_mem_type	Source address memory region.

Returns

The function can return one of the values defined by err_t, which is dependant on the architecture and ported low level layer.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_dma_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// DMA HAL context structure.
static hal_dma_t hal_dma;
 
// DMA HAL configuration structure.
static hal_dma_config_t hal_dma_cfg;
 
// Source buffer in flash.
static const uint8_t buffer_src[2] = {0xCa, 0xfe};
 
// Destination buffer in RAM.
static uint8_t buffer_dst[2];
 
// Fill structure with default values.
hal_dma_configure_default( &hal_dma_cfg );
 
// Set data alignment to BYTE(8-bit) because
// arrays are byte size.
hal_dma_cfg.data_align_memory = HAL_DMA_DATA_ALIGN_BYTES_1;
hal_dma_cfg.data_align_peripheral = HAL_DMA_DATA_ALIGN_BYTES_1;
 
// Set memory addresses to be incremented
// for both memory and peripheral.
hal_dma_cfg.mem_inc = true;
hal_dma_cfg.periph_inc = true;
 
// Initialize and allocate resources for DMA module.
if ( HAL_DMA_ERROR == hal_dma_open( &hal_dma, &hal_dma_cfg ) )
{
    // Error handling strategy.
}
 
// Configure transfer to copy 2 bytes from buffer_src to buffer_dst.
if ( HAL_DMA_ERROR == hal_dma_set_transfer_config( &hal_dma, (uint32_t)buffer_src, (uint32_t)buffer_dst, 2,  HAL_DMA_SOURCE_MEMORY_REGION_PFM ) )
{
    // Error handling strategy.
}
 
// Transfer is now configured and can be started.

hal_dma_transfer_abort()

err_t hal_dma_transfer_abort

(

hal_dma_t *

obj

)

Aborts any ongoing DMA transfers and disables stream.

Parameters

[in,out]

obj

DMA HAL object. See hal_dma_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by err_t, which is dependant on the architecture and ported low level layer.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_dma_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// DMA HAL context structure.
static hal_dma_t hal_dma;
 
// DMA HAL configuration structure.
static hal_dma_config_t hal_dma_cfg;
 
// Source buffer in flash.
static const uint8_t buffer_src[2] = {0xCa, 0xfe};
 
// Destination buffer in RAM.
static uint8_t buffer_dst[2];
 
// Fill structure with default values.
hal_dma_configure_default( &hal_dma_cfg );
 
// Set data alignment to BYTE(8-bit) because
// arrays are byte size.
hal_dma_cfg.data_align_memory = HAL_DMA_DATA_ALIGN_BYTES_1;
hal_dma_cfg.data_align_peripheral = HAL_DMA_DATA_ALIGN_BYTES_1;
 
// Set memory addresses to be incremented
// for both memory and peripheral.
hal_dma_cfg.mem_inc = true;
hal_dma_cfg.periph_inc = true;
 
// Initialize and allocate resources for DMA module.
if ( HAL_DMA_ERROR == hal_dma_open( &hal_dma, &hal_dma_cfg ) )
{
    // Error handling strategy.
}
 
// Configure transfer to copy 2 bytes from buffer_src to buffer_dst.
if ( HAL_DMA_ERROR == hal_dma_set_transfer_config( &hal_dma, (uint32_t)buffer_src, (uint32_t)buffer_dst, 2 ) )
{
    // Error handling strategy.
}
 
// Start the transfer and check the destination buffer.
if ( HAL_DMA_ERROR == hal_dma_transfer_start( &hal_dma ) )
{
    // Error handling strategy.
}
 
// Compare buffers now.
if ( !memcmp(buffer_src_flash, buffer_dst, sizeof(buffer_src)) )
{
    // Successful comparison.
}
 
// Abort any further ongoing transfers.
if ( HAL_DMA_ERROR == hal_dma_transfer_abort( &hal_dma ) )
{
    // Error handling strategy.
}

hal_dma_transfer_start()

err_t hal_dma_transfer_start

(

hal_dma_t *

obj

)

Starts previously configured DMA transfer by enabling stream.

Parameters

[in,out]

obj

DMA HAL object. See hal_dma_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by err_t, which is dependant on the architecture and ported low level layer.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_dma_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// DMA HAL context structure.
static hal_dma_t hal_dma;
 
// DMA HAL configuration structure.
static hal_dma_config_t hal_dma_cfg;
 
// Source buffer in flash.
static const uint8_t buffer_src[2] = {0xCa, 0xfe};
 
// Destination buffer in RAM.
static uint8_t buffer_dst[2];
 
// Fill structure with default values.
hal_dma_configure_default( &hal_dma_cfg );
 
// Set data alignment to BYTE(8-bit) because
// arrays are byte size.
hal_dma_cfg.data_align_memory = HAL_DMA_DATA_ALIGN_BYTES_1;
hal_dma_cfg.data_align_peripheral = HAL_DMA_DATA_ALIGN_BYTES_1;
 
// Set memory addresses to be incremented
// for both memory and peripheral.
hal_dma_cfg.mem_inc = true;
hal_dma_cfg.periph_inc = true;
 
// Initialize and allocate resources for DMA module.
if ( HAL_DMA_ERROR == hal_dma_open( &hal_dma, &hal_dma_cfg ) )
{
    // Error handling strategy.
}
 
// Configure transfer to copy 2 bytes from buffer_src to buffer_dst.
if ( HAL_DMA_ERROR == hal_dma_set_transfer_config( &hal_dma, (uint32_t)buffer_src, (uint32_t)buffer_dst, 2 ) )
{
    // Error handling strategy.
}
 
// Start the transfer and check the destination buffer.
if ( HAL_DMA_ERROR == hal_dma_transfer_start( &hal_dma ) )
{
    // Error handling strategy.
}
 
// Compare buffers now.
if ( !memcmp(buffer_src_flash, buffer_dst, sizeof(buffer_src)) )
{
    // Successful comparison.
}

hal_dma_transfer_stop()

err_t hal_dma_transfer_stop

(

hal_dma_t *

obj

)

Stops an active DMA transfer by disabling stream.

Parameters

[in,out]

obj

DMA HAL object. See hal_dma_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by err_t, which is dependant on the architecture and ported low level layer.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_dma_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// DMA HAL context structure.
static hal_dma_t hal_dma;
 
// DMA HAL configuration structure.
static hal_dma_config_t hal_dma_cfg;
 
// Source buffer in flash.
static const uint8_t buffer_src[2] = {0xCa, 0xfe};
 
// Destination buffer in RAM.
static uint8_t buffer_dst[2];
 
// Fill structure with default values.
hal_dma_configure_default( &hal_dma_cfg );
 
// Set data alignment to BYTE(8-bit) because
// arrays are byte size.
hal_dma_cfg.data_align_memory = HAL_DMA_DATA_ALIGN_BYTES_1;
hal_dma_cfg.data_align_peripheral = HAL_DMA_DATA_ALIGN_BYTES_1;
 
// Set memory addresses to be incremented
// for both memory and peripheral.
hal_dma_cfg.mem_inc = true;
hal_dma_cfg.periph_inc = true;
 
// Initialize and allocate resources for DMA module.
if ( HAL_DMA_ERROR == hal_dma_open( &hal_dma, &hal_dma_cfg ) )
{
    // Error handling strategy.
}
 
// Configure transfer to copy 2 bytes from buffer_src to buffer_dst.
if ( HAL_DMA_ERROR == hal_dma_set_transfer_config( &hal_dma, (uint32_t)buffer_src, (uint32_t)buffer_dst, 2 ) )
{
    // Error handling strategy.
}
 
// Start the transfer and check the destination buffer.
if ( HAL_DMA_ERROR == hal_dma_transfer_start( &hal_dma ) )
{
    // Error handling strategy.
}
 
// Compare buffers now.
if ( !memcmp(buffer_src_flash, buffer_dst, sizeof(buffer_src)) )
{
    // Successful comparison. Stop the stream now.
    if ( HAL_DMA_ERROR == hal_dma_transfer_stop( &hal_dma ) )
    {
        // Error handling strategy.
    }
}