This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the device's Direct Memory Access DMA Controller (DMAC) functionality.

The DMAC is an AHB-central DMA controller core that transfers data from a source peripheral to a destination peripheral over one or more AMBA buses. This is a driver for the configuration, enabling, disabling, and use of the DMAC peripheral.

Devices from the following series can use this module:

Atmel | SMART SAM3A
Atmel | SMART SAM3U
Atmel | SMART SAM3X
Atmel | SMART SAM4E

The outline of this documentation is as follows:

Prerequisites

There are no prerequisites for this module.

Module Overview

The DMA Controller (DMAC) is an AHB-central DMA controller core that transfers data from a source peripheral to a destination peripheral over one or more AMBA buses. One channel is required for each source/destination pair. In the most basic configuration, the DMAC has one master interface and one channel. The master interface reads the data from a source and writes it to a destination. Two AMBA transfers are required for each DMAC data transfer. This is also known as a dual-access transfer.

Special Considerations

There are no special considerations for this module.

Extra Information

For extra information, see Extra Information for Direct Memory Access Controller Driver. This includes:

Examples

For a list of examples related to this driver, see Examples for Direct Memory Access Controller Driver.

API Overview

Data Structures
struct	dma_transfer_descriptor_t
	DMA transfer descriptor structure, otherwise known as a Linked List Item (LLI). More...

Enumerations
enum	dmac_priority_mode_t { DMAC_PRIORITY_FIXED = 0, DMAC_PRIORITY_ROUND_ROBIN = DMAC_GCFG_ARB_CFG }
	DMAC priority mode. More...

Functions
void	dmac_channel_disable (Dmac *p_dmac, uint32_t ul_num)
	Disable the specified DMA Channel. More...

void	dmac_channel_enable (Dmac *p_dmac, uint32_t ul_num)
	Enable the specified DMA Channel. More...

uint32_t	dmac_channel_get_status (Dmac *p_dmac)
	Get the DMAC Channel handler status. More...

uint32_t	dmac_channel_is_enable (Dmac *p_dmac, uint32_t ul_num)
	Check if the specified DMA Channel is enabled. More...

uint32_t	dmac_channel_is_transfer_done (Dmac *p_dmac, uint32_t ul_num)
	Check if the data transfer occurring on the specified DMA Channel is complete. More...

void	dmac_channel_keep (Dmac *p_dmac, uint32_t ul_num)
	Resume the specified DMA Channel from an automatic stall state. More...

void	dmac_channel_multi_buf_transfer_init (Dmac p_dmac, uint32_t ul_num, dma_transfer_descriptor_t p_desc)
	Initialize the DMA Channel for a multiple buffer transfer. More...

void	dmac_channel_resume (Dmac *p_dmac, uint32_t ul_num)
	Resume the specified DMA Channel transfer (restoring its context). More...

void	dmac_channel_set_configuration (Dmac *p_dmac, uint32_t ul_num, uint32_t ul_cfg)
	Set the DMAC configuration register of the specified DMA Channel. More...

void	dmac_channel_set_ctrlA (Dmac *p_dmac, uint32_t ul_num, uint32_t ul_ctrlA)
	Set the DMA control A of the specified DMA Channel. More...

void	dmac_channel_set_ctrlB (Dmac *p_dmac, uint32_t ul_num, uint32_t ul_ctrlB)
	Set the DMA control B of the specified DMA Channel. More...

void	dmac_channel_set_descriptor_addr (Dmac *p_dmac, uint32_t ul_num, uint32_t ul_desc)
	Set the DMA descriptor address of the specified DMA Channel. More...

void	dmac_channel_set_destination_addr (Dmac *p_dmac, uint32_t ul_num, uint32_t ul_addr)
	Set the DMA destination address of the specified DMA Channel. More...

void	dmac_channel_set_source_addr (Dmac *p_dmac, uint32_t ul_num, uint32_t ul_addr)
	Set the DMA source address of the specified DMA Channel. More...

void	dmac_channel_single_buf_transfer_init (Dmac p_dmac, uint32_t ul_num, dma_transfer_descriptor_t p_desc)
	Initialize the DMA Channel for a single buffer transfer. More...

void	dmac_channel_stop_transfer (Dmac *p_dmac, uint32_t ul_num)
	Stop a DMA transfer occurring on the specified DMA Channel. More...

void	dmac_channel_suspend (Dmac *p_dmac, uint32_t ul_num)
	Suspend the specified DMA Channel and its current context. More...

void	dmac_disable (Dmac *p_dmac)
	Disable the DMA Controller. More...

void	dmac_disable_interrupt (Dmac *p_dmac, uint32_t ul_mask)
	Disable DMAC interrupts. More...

void	dmac_enable (Dmac *p_dmac)
	Enable the DMA Controller. More...

void	dmac_enable_interrupt (Dmac *p_dmac, uint32_t ul_mask)
	Enable DMAC interrupts. More...

uint32_t	dmac_get_interrupt_mask (Dmac *p_dmac)
	Get the DMAC Interrupt Mask. More...

uint32_t	dmac_get_status (Dmac *p_dmac)
	Get the DMAC transfer status. More...

void	dmac_init (Dmac *p_dmac)
	Initialize the DMA controller and disable it. More...

void	dmac_set_priority_mode (Dmac *p_dmac, dmac_priority_mode_t mode)
	Set the DMA priority mode. More...

void	dmac_soft_chunk_transfer_request (Dmac *p_dmac, uint32_t ul_num, uint32_t ul_src_req, uint32_t ul_dst_req)
	DMA Channel software chunk request. More...

void	dmac_soft_set_last_transfer_flag (Dmac *p_dmac, uint32_t ul_num, uint32_t ul_src_flag, uint32_t ul_dst_flag)
	Set the DMA Channel's last transfer flag. More...

void	dmac_soft_single_transfer_request (Dmac *p_dmac, uint32_t ul_num, uint32_t ul_src_req, uint32_t ul_dst_req)
	DMA Channel software single request. More...

enum dmac_priority_mode_t

DMAC priority mode.

Enumerator
DMAC_PRIORITY_FIXED	Fixed priority arbiter.
DMAC_PRIORITY_ROUND_ROBIN	Modified round robin arbiter.

void dmac_channel_disable	(	Dmac *	p_dmac,
		uint32_t	ul_num
	)

Disable the specified DMA Channel.

Parameters

[out]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)

References Assert.

Referenced by dmac_channel_stop_transfer(), spi_master_initialize(), spi_master_transfer(), spi_slave_initialize(), and spi_slave_transfer().

void dmac_channel_enable	(	Dmac *	p_dmac,
		uint32_t	ul_num
	)

Enable the specified DMA Channel.

Parameters

[out]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)

References Assert.

Referenced by spi_master_transfer(), and spi_slave_transfer().

uint32_t dmac_channel_get_status ( Dmac * p_dmac )

Get the DMAC Channel handler status.

Parameters

[in] p_dmac Module hardware register base address pointer

Returns: DMAC Channel handler status register. Refer to the section called "DMAC Channel Handler Status Register" in the device-specific datasheet for more information.

References Assert.

Referenced by dmac_channel_is_transfer_done(), and dmac_channel_stop_transfer().

uint32_t dmac_channel_is_enable	(	Dmac *	p_dmac,
		uint32_t	ul_num
	)

Check if the specified DMA Channel is enabled.

Parameters

[in]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)

Returns: The DMA Channel's enable/disable status.

Return values

0	DMA Channel is disabled
1	DMA Channel is enabled

References Assert.

uint32_t dmac_channel_is_transfer_done	(	Dmac *	p_dmac,
		uint32_t	ul_num
	)

Check if the data transfer occurring on the specified DMA Channel is complete.

Note: This function is used in polling mode.

Parameters

[in]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)

Returns: The data transfer status.

Return values

0	Data is transferring
1	Data transfer complete

References Assert, and dmac_channel_get_status().

void dmac_channel_keep	(	Dmac *	p_dmac,
		uint32_t	ul_num
	)

Resume the specified DMA Channel from an automatic stall state.

Parameters

[out]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)

References Assert.

void dmac_channel_multi_buf_transfer_init	(	Dmac *	p_dmac,
		uint32_t	ul_num,
		dma_transfer_descriptor_t *	p_desc
	)

Initialize the DMA Channel for a multiple buffer transfer.

Parameters

[in,out]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)
[in]	p_desc	Pointer to a transfer descriptor

References Assert, dmac_channel_set_ctrlB(), and dmac_channel_set_descriptor_addr().

void dmac_channel_resume	(	Dmac *	p_dmac,
		uint32_t	ul_num
	)

Resume the specified DMA Channel transfer (restoring its context).

Parameters

[out]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)

References Assert.

Referenced by dmac_channel_stop_transfer().

void dmac_channel_set_configuration	(	Dmac *	p_dmac,
		uint32_t	ul_num,
		uint32_t	ul_cfg
	)

Set the DMAC configuration register of the specified DMA Channel.

Parameters

[out]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)
[in]	ul_cfg	Configuration of CFG register

References Assert.

Referenced by configure_dmac().

void dmac_channel_set_ctrlA	(	Dmac *	p_dmac,
		uint32_t	ul_num,
		uint32_t	ul_ctrlA
	)

Set the DMA control A of the specified DMA Channel.

Parameters

[out]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)
[in]	ul_ctrlA	Configuration of control A register

References Assert.

Referenced by dmac_channel_single_buf_transfer_init().

void dmac_channel_set_ctrlB	(	Dmac *	p_dmac,
		uint32_t	ul_num,
		uint32_t	ul_ctrlB
	)

Set the DMA control B of the specified DMA Channel.

Parameters

[out]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)
[in]	ul_ctrlB	Configuration of control B register

References Assert.

Referenced by dmac_channel_multi_buf_transfer_init(), and dmac_channel_single_buf_transfer_init().

void dmac_channel_set_descriptor_addr	(	Dmac *	p_dmac,
		uint32_t	ul_num,
		uint32_t	ul_desc
	)

Set the DMA descriptor address of the specified DMA Channel.

Parameters

[out]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)
[in]	ul_desc	Descriptor address

References Assert.

Referenced by dmac_channel_multi_buf_transfer_init(), and dmac_channel_single_buf_transfer_init().

void dmac_channel_set_destination_addr	(	Dmac *	p_dmac,
		uint32_t	ul_num,
		uint32_t	ul_addr
	)

Set the DMA destination address of the specified DMA Channel.

Parameters

[out]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)
[in]	ul_addr	Destination address

Note: This register must be aligned with the source transfer width.

References Assert.

Referenced by dmac_channel_single_buf_transfer_init().

void dmac_channel_set_source_addr	(	Dmac *	p_dmac,
		uint32_t	ul_num,
		uint32_t	ul_addr
	)

Set the DMA source address of the specified DMA Channel.

Parameters

[out]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)
[in]	ul_addr	Source address

Note: This register must be aligned with the source transfer width.

References Assert.

Referenced by dmac_channel_single_buf_transfer_init().

void dmac_channel_single_buf_transfer_init	(	Dmac *	p_dmac,
		uint32_t	ul_num,
		dma_transfer_descriptor_t *	p_desc
	)

Initialize the DMA Channel for a single buffer transfer.

Parameters

[in,out]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)
[in]	p_desc	Pointer to a transfer descriptor

References Assert, dmac_channel_set_ctrlA(), dmac_channel_set_ctrlB(), dmac_channel_set_descriptor_addr(), dmac_channel_set_destination_addr(), dmac_channel_set_source_addr(), dma_transfer_descriptor_t::ul_ctrlA, dma_transfer_descriptor_t::ul_ctrlB, dma_transfer_descriptor_t::ul_destination_addr, and dma_transfer_descriptor_t::ul_source_addr.

Referenced by spi_master_transfer(), and spi_slave_transfer().

void dmac_channel_stop_transfer	(	Dmac *	p_dmac,
		uint32_t	ul_num
	)

Stop a DMA transfer occurring on the specified DMA Channel.

Note: Under normal operation, the hardware disables a channel on transfer completion by clearing the DMAC_CHSR.ENAx register bit. The recommended way for software to disable a channel without losing data is to use the SUSPx bit in conjunction with the EMPTx bit in the Channel Handler Status Register.

Parameters

[in,out]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)

References Assert, dmac_channel_disable(), dmac_channel_get_status(), dmac_channel_resume(), and dmac_channel_suspend().

void dmac_channel_suspend	(	Dmac *	p_dmac,
		uint32_t	ul_num
	)

Suspend the specified DMA Channel and its current context.

Parameters

[out]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)

References Assert.

Referenced by dmac_channel_stop_transfer().

void dmac_disable ( Dmac * p_dmac )

Disable the DMA Controller.

Parameters

[in,out] p_dmac Module hardware register base address pointer

References Assert.

Referenced by dmac_init().

void dmac_disable_interrupt	(	Dmac *	p_dmac,
		uint32_t	ul_mask
	)

Disable DMAC interrupts.

Parameters

[out]	p_dmac	Module hardware register base address pointer
[in]	ul_mask	A bitmask of interrupts to be disabled

Where input parameter ul_mask is a bitmask containing one or more of the following:

Parameter Value	Description
DMAC_EBCIDR_BTC0	Channel 0 Buffer Transfer Completed
DMAC_EBCIDR_BTC1	Channel 1 Buffer Transfer Completed
DMAC_EBCIDR_BTC2	Channel 2 Buffer Transfer Completed
DMAC_EBCIDR_BTC3	Channel 3 Buffer Transfer Completed
DMAC_EBCIDR_CBTC0	Channel 0 Chained Buffer Transfer Completed
DMAC_EBCIDR_CBTC1	Channel 1 Chained Buffer Transfer Completed
DMAC_EBCIDR_CBTC2	Channel 2 Chained Buffer Transfer Completed
DMAC_EBCIDR_CBTC3	Channel 3 Chained Buffer Transfer Completed
DMAC_EBCIDR_ERR0	Channel 0 Access Error
DMAC_EBCIDR_ERR1	Channel 1 Access Error
DMAC_EBCIDR_ERR2	Channel 2 Access Error
DMAC_EBCIDR_ERR3	Channel 3 Access Error

References Assert.

void dmac_enable ( Dmac * p_dmac )

Enable the DMA Controller.

Parameters

[out] p_dmac Module hardware register base address pointer

References Assert.

Referenced by configure_dmac().

void dmac_enable_interrupt	(	Dmac *	p_dmac,
		uint32_t	ul_mask
	)

Enable DMAC interrupts.

Parameters

[out]	p_dmac	Module hardware register base address pointer
[in]	ul_mask	A bitmask of interrupts to be enabled

Where input parameter ul_mask is a bitmask containing one or more of the following:

Parameter Value	Description
DMAC_EBCIER_BTC0	Channel 0 Buffer Transfer Completed
DMAC_EBCIER_BTC1	Channel 1 Buffer Transfer Completed
DMAC_EBCIER_BTC2	Channel 2 Buffer Transfer Completed
DMAC_EBCIER_BTC3	Channel 3 Buffer Transfer Completed
DMAC_EBCIER_CBTC0	Channel 0 Chained Buffer Transfer Completed
DMAC_EBCIER_CBTC1	Channel 1 Chained Buffer Transfer Completed
DMAC_EBCIER_CBTC2	Channel 2 Chained Buffer Transfer Completed
DMAC_EBCIER_CBTC3	Channel 3 Chained Buffer Transfer Completed
DMAC_EBCIER_ERR0	Channel 0 Access Error
DMAC_EBCIER_ERR1	Channel 1 Access Error
DMAC_EBCIER_ERR2	Channel 2 Access Error
DMAC_EBCIER_ERR3	Channel 3 Access Error

References Assert.

Referenced by configure_dmac().

uint32_t dmac_get_interrupt_mask ( Dmac * p_dmac )

Get the DMAC Interrupt Mask.

Parameters

[in] p_dmac Module hardware register base address pointer

Returns: DMAC Interrupt mask.

References Assert.

uint32_t dmac_get_status ( Dmac * p_dmac )

Get the DMAC transfer status.

Parameters

[in] p_dmac Module hardware register base address pointer

Returns: DMAC transfer status. Refer to section called "DMAC Error, Buffer Transfer and Chained Buffer Transfer Status Register" in the device-specific datasheet for more information.

References Assert.

Referenced by DMAC_Handler().

void dmac_init ( Dmac * p_dmac )

Initialize the DMA controller and disable it.

Parameters

[in,out] p_dmac Module hardware register base address pointer

References dmac_disable().

Referenced by configure_dmac().

void dmac_set_priority_mode	(	Dmac *	p_dmac,
		dmac_priority_mode_t	mode
	)

Set the DMA priority mode.

Parameters

[in,out]	p_dmac	Module hardware register base address pointer
[in]	mode	Priority mode

References Assert.

Referenced by configure_dmac().

void dmac_soft_chunk_transfer_request	(	Dmac *	p_dmac,
		uint32_t	ul_num,
		uint32_t	ul_src_req,
		uint32_t	ul_dst_req
	)

DMA Channel software chunk request.

Parameters

[in,out]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)
[in]	ul_src_req	Request a source transfer
[in]	ul_dst_req	Request a destination transfer

References Assert.

void dmac_soft_set_last_transfer_flag	(	Dmac *	p_dmac,
		uint32_t	ul_num,
		uint32_t	ul_src_flag,
		uint32_t	ul_dst_flag
	)

Set the DMA Channel's last transfer flag.

Parameters

[in,out]	p_dmac	Module hardware register base address pointer
[in]	ul_num	Channel number
[in]	ul_src_flag	Last source transfer flag
[in]	ul_dst_flag	Last destination transfer flag

References Assert.

void dmac_soft_single_transfer_request	(	Dmac *	p_dmac,
		uint32_t	ul_num,
		uint32_t	ul_src_req,
		uint32_t	ul_dst_req
	)

DMA Channel software single request.

Parameters

[in,out]	p_dmac	Module hardware register base address pointer
[in]	ul_num	DMA Channel number (range 0 to 3)
[in]	ul_src_req	Request a source transfer
[in]	ul_dst_req	Request a destination transfer

References Assert.

Microchip® Advanced Software Framework

Prerequisites

Module Overview

Special Considerations

Extra Information

Examples

API Overview

Data Structures

Enumerations

Functions