DMA Driver

DMA Driver API Reference. More...

Functions list
void	dma_configure_default (dma_config_t *config)
	Configure DMA Driver configuration structure. More...
err_t	dma_open (dma_t *obj, dma_config_t *config)
	Open the DMA Driver object. More...
void	dma_get_channels (dma_channel_t *channels)
	Get DMA modules/streams/channels. More...
err_t	dma_set_mode (dma_t *obj, dma_mode_t mode)
	Set the DMA mode. More...
err_t	dma_set_direction (dma_t *obj, dma_direction_t direction)
	Set the DMA direction. More...
err_t	dma_set_priority (dma_t *obj, dma_priority_t priority)
	Set the DMA priority. More...
err_t	dma_set_transfer_config (dma_t *obj, uint32_t addr_src, uint32_t addr_dst, size_t transfer_size, dma_source_memory_region_t src_mem_type)
	Configure the DMA transfer. More...
err_t	dma_transfer_start (dma_t *obj)
	Initializes the DMA transfer. More...
err_t	dma_transfer_stop (dma_t *obj)
	Stops the DMA transfer. More...
err_t	dma_transfer_abort (dma_t *obj)
	Aborts a DMA transfer. More...
err_t	dma_close (dma_t *obj)
	Close DMA Driver object. More...

Detailed Description

DMA DRV API layer header. Contains all enums, structures and function declarations available for DMA module.

Function Documentation

dma_configure_default()

void dma_configure_default

(

dma_config_t *

config

)

Configures 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 driver configuration structure. See dma_config_t structure definition for detailed explanation.

Default values:

Function	Default value
Module	0xFF
Stream	0xFF
Channel	0xFF
Direction	DMA_DIRECTION_DEFAULT
Mode	DMA_MODE_DEFAULT
Priority	DMA_PRIORITY_DEFAULT
Memory increment	false
Memory data alignment	DMA_DATA_ALIGN_DEFAULT
Memory burst size	DMA_BURST_SIZE_INCREMENT_DEFAULT
Peripheral increment	false
Peripheral data alignment	DMA_DATA_ALIGN_DEFAULT
Peripheral burst size	DMA_BURST_SIZE_INCREMENT_DEFAULT
Source address	0
Destination address	0
Transfer length	0

Returns

Nothing.

Example

// DMA driver configuration structure.
static dma_config_t dma_cfg;
 
// Fill structure with default values.
dma_configure_default( &dma_cfg );

dma_open()

err_t dma_open	(	dma_t *	obj,
		dma_config_t *	config
	)

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

Parameters

[in,out]	obj	DMA driver object. See dma_t structure definition for detailed explanation.
[in]	config	configure DMA driver configuration settings. See 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 dma_configure_default definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// DMA driver context structure.
static dma_t dma;
 
// DMA driver configuration structure.
static dma_config_t dma_cfg;
 
// Fill structure with default values.
dma_configure_default( &dma_cfg );
 
// Specify desired DMA module.
dma_cfg.module = 0; // First module (DMA0 or DMA1 based on MCU).
 
// Specify desired DMA stream number.
dma_cfg.stream = 5;
 
// Specify desired DMA channel number.
dma_cfg.channel = 3;
 
// Initialize and allocate resources for DMA module.
if ( DMA_ERROR == dma_open( &dma, &dma_cfg ) )
{
 // Error handling strategy.
}

dma_get_channels()

void dma_get_channels

(

dma_channel_t *

channels

)

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

Parameters

[in,out]

channels

DMA channel context array. See 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 channel context structure.
static dma_channel_t dma_channels;
 
// Get list of available channels per stream per module.
dma_get_channels( &dma_channels );
 
// Lets say we want to use DMA module 0, stream 3 and channel 4.
if ( DMA_STATE_FREE == dma_channels[0][3][4] )
{
 // Module 0, stream 3, channel 4 is free for use.
}

dma_set_mode()

err_t dma_set_mode	(	dma_t *	obj,
		dma_mode_t	mode
	)

Sets DMA mode to be used by the DMA driver.

Parameters

[in,out]	obj	DMA driver object. See dma_t structure definition for detailed explanation.
[in]	mode	DMA mode. See 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 dma_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// DMA driver context structure.
static dma_t dma;
 
// DMA driver configuration structure.
static dma_config_t dma_cfg;
 
// Fill structure with default values.
dma_configure_default( &dma_cfg );
 
// Initialize and allocate resources for DMA module.
if ( DMA_ERROR == dma_open( &dma, &dma_cfg ) )
{
 // Error handling strategy.
}
 
// Set desired DMA mode.
if ( DMA_ERROR == dma_set_mode( &dma, DMA_MODE_NORMAL ) )
{
 // Error handling strategy.
}

dma_set_direction()

err_t dma_set_direction	(	dma_t *	obj,
		dma_direction_t	direction
	)

Sets DMA direction to be used by the DMA driver.

Parameters

[in,out]	obj	DMA driver object. See dma_t structure definition for detailed explanation.
[in]	direction	DMA direction. See 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 dma_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// DMA driver context structure.
static dma_t dma;
 
// DMA driver configuration structure.
static dma_config_t dma_cfg;
 
// Fill structure with default values.
dma_configure_default( &dma_cfg );
 
// Initialize and allocate resources for DMA module.
if ( DMA_ERROR == dma_open( &dma, &dma_cfg ) )
{
 // Error handling strategy.
}
 
// Set desired DMA mode.
if ( DMA_ERROR == dma_set_direction( &dma, DMA_DIRECTION_MEMORY_TO_MEMORY ) )
{
 // Error handling strategy.
}

dma_set_priority()

err_t dma_set_priority	(	dma_t *	obj,
		dma_priority_t	priority
	)

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

Parameters

[in,out]	obj	DMA driver object. See dma_t structure definition for detailed explanation.
[in]	priority	DMA priority level. See 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 dma_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// DMA driver context structure.
static dma_t dma;
 
// DMA driver configuration structure.
static dma_config_t dma_cfg;
 
// Fill structure with default values.
dma_configure_default( &dma_cfg );
 
// Initialize and allocate resources for DMA module.
if ( DMA_ERROR == dma_open( &dma, &dma_cfg ) )
{
 // Error handling strategy.
}
 
// Set desired DMA mode.
if ( DMA_ERROR == dma_set_priority( &dma, DMA_PRIORITY_MEDIUM ) )
{
 // Error handling strategy.
}

dma_set_transfer_config()

err_t dma_set_transfer_config	(	dma_t *	obj,
		uint32_t	addr_src,
		uint32_t	addr_dst,
		size_t	transfer_size,
		dma_source_memory_region_t	src_mem_type
	)

Configures initialized DMA stream for transfer.

Parameters

[in,out]	obj	DMA driver object. See 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 dma_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// DMA driver context structure.
static dma_t dma;
 
// DMA driver configuration structure.
static dma_config_t 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.
dma_configure_default( &dma_cfg );
 
// Set data alignment to BYTE(8-bit) because
// arrays are byte size.
dma_cfg.data_align_memory = DMA_DATA_ALIGN_BYTES_1;
dma_cfg.data_align_peripheral = DMA_DATA_ALIGN_BYTES_1;
 
// Set memory addresses to be incremented
// for both memory and peripheral.
dma_cfg.mem_inc = true;
dma_cfg.periph_inc = true;
 
// Initialize and allocate resources for DMA module.
if ( DMA_ERROR == dma_open( &dma, &dma_cfg ) )
{
 // Error handling strategy.
}
 
// Configure transfer to copy 2 bytes from buffer_src to buffer_dst.
if ( DMA_ERROR == dma_set_transfer_config( &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.

dma_transfer_start()

err_t dma_transfer_start

(

dma_t *

obj

)

Starts previously configured DMA transfer by enabling stream.

Parameters

[in,out]

obj

DMA driver object. See 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 dma_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// DMA driver context structure.
static dma_t dma;
 
// DMA driver configuration structure.
static dma_config_t 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.
dma_configure_default( &dma_cfg );
 
// Set data alignment to BYTE(8-bit) because
// arrays are byte size.
dma_cfg.data_align_memory = DMA_DATA_ALIGN_BYTES_1;
dma_cfg.data_align_peripheral = DMA_DATA_ALIGN_BYTES_1;
 
// Set memory addresses to be incremented
// for both memory and peripheral.
dma_cfg.mem_inc = true;
dma_cfg.periph_inc = true;
 
// Initialize and allocate resources for DMA module.
if ( DMA_ERROR == dma_open( &dma, &dma_cfg ) )
{
 // Error handling strategy.
}
 
// Configure transfer to copy 2 bytes from buffer_src to buffer_dst.
if ( DMA_ERROR == dma_set_transfer_config( &dma, (uint32_t)buffer_src, (uint32_t)buffer_dst, 2 ) )
{
 // Error handling strategy.
}
 
// Start the transfer and check the destination buffer.
if ( DMA_ERROR == dma_transfer_start( &dma ) )
{
 // Error handling strategy.
}
 
// Compare buffers now.
if ( !memcmp(buffer_src_flash, buffer_dst, sizeof(buffer_src)) )
{
 // Successful comparison.
}

dma_transfer_stop()

err_t dma_transfer_stop

(

dma_t *

obj

)

Stops an active DMA transfer by disabling stream.

Parameters

[in,out]

obj

DMA driver object. See 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 dma_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// DMA driver context structure.
static dma_t dma;
 
// DMA driver configuration structure.
static dma_config_t 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.
dma_configure_default( &dma_cfg );
 
// Set data alignment to BYTE(8-bit) because
// arrays are byte size.
dma_cfg.data_align_memory = DMA_DATA_ALIGN_BYTES_1;
dma_cfg.data_align_peripheral = DMA_DATA_ALIGN_BYTES_1;
 
// Set memory addresses to be incremented
// for both memory and peripheral.
dma_cfg.mem_inc = true;
dma_cfg.periph_inc = true;
 
// Initialize and allocate resources for DMA module.
if ( DMA_ERROR == dma_open( &dma, &dma_cfg ) )
{
 // Error handling strategy.
}
 
// Configure transfer to copy 2 bytes from buffer_src to buffer_dst.
if ( DMA_ERROR == dma_set_transfer_config( &dma, (uint32_t)buffer_src, (uint32_t)buffer_dst, 2 ) )
{
 // Error handling strategy.
}
 
// Start the transfer and check the destination buffer.
if ( DMA_ERROR == dma_transfer_start( &dma ) )
{
 // Error handling strategy.
}
 
// Compare buffers now.
if ( !memcmp(buffer_src_flash, buffer_dst, sizeof(buffer_src)) )
{
 // Successful comparison. Stop the stream now.
 if ( DMA_ERROR == dma_transfer_stop( &dma ) )
 {
 // Error handling strategy.
 }
}

dma_transfer_abort()

err_t dma_transfer_abort

(

dma_t *

obj

)

Aborts any ongoing DMA transfers and disables stream.

Parameters

[in,out]

obj

DMA driver object. See 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 dma_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// DMA driver context structure.
static dma_t dma;
 
// DMA driver configuration structure.
static dma_config_t 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.
dma_configure_default( &dma_cfg );
 
// Set data alignment to BYTE(8-bit) because
// arrays are byte size.
dma_cfg.data_align_memory = DMA_DATA_ALIGN_BYTES_1;
dma_cfg.data_align_peripheral = DMA_DATA_ALIGN_BYTES_1;
 
// Set memory addresses to be incremented
// for both memory and peripheral.
dma_cfg.mem_inc = true;
dma_cfg.periph_inc = true;
 
// Initialize and allocate resources for DMA module.
if ( DMA_ERROR == dma_open( &dma, &dma_cfg ) )
{
 // Error handling strategy.
}
 
// Configure transfer to copy 2 bytes from buffer_src to buffer_dst.
if ( DMA_ERROR == dma_set_transfer_config( &dma, (uint32_t)buffer_src, (uint32_t)buffer_dst, 2 ) )
{
 // Error handling strategy.
}
 
// Start the transfer and check the destination buffer.
if ( DMA_ERROR == dma_transfer_start( &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 ( DMA_ERROR == dma_transfer_abort( &dma ) )
{
 // Error handling strategy.
}

dma_close()

err_t dma_close

(

dma_t *

obj

)

Closes DMA driver 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 driver object. See 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 driver context structure.
static dma_t dma;
 
// DMA driver configuration structure.
static dma_config_t dma_cfg;
 
// Fill structure with default values.
dma_configure_default( &dma_cfg );
 
// Initialize and allocate resources for DMA module.
if ( DMA_ERROR == dma_open( &dma, &dma_cfg ) )
{
 // Error handling strategy.
}
 
// Close previously initialized DMA module object handler.
if ( DMA_SUCCESS == dma_close( &dma ) {
 // No error.
} else {
 // Handle the error.
}