Direct Memory Access (DMA)

Modules
	DMA_Registers

Data Structures
struct	mxc_dma_config_t
struct	mxc_dma_srcdst_t
struct	mxc_dma_adv_config_t

Typedefs
typedef void(*	mxc_dma_complete_cb_t) (void *dest)
typedef mxc_dma_srcdst_t(*	mxc_dma_trans_chain_t) (mxc_dma_srcdst_t dest)

Enumerations
enum	mxc_dma_priority_t
enum	mxc_dma_reqsel_t
enum	mxc_dma_prescale_t
enum	mxc_dma_timeout_t
enum	mxc_dma_width_t

Functions
int	MXC_DMA_Init (void)
void	MXC_DMA_DeInit (void)
int	MXC_DMA_AcquireChannel (void)
int	MXC_DMA_ReleaseChannel (int ch)
int	MXC_DMA_ConfigChannel (mxc_dma_config_t config, mxc_dma_srcdst_t srcdst)
int	MXC_DMA_AdvConfigChannel (mxc_dma_adv_config_t advConfig)
int	MXC_DMA_SetSrcDst (mxc_dma_srcdst_t srcdst)
int	MXC_DMA_GetSrcDst (mxc_dma_srcdst_t *srcdst)
int	MXC_DMA_SetSrcReload (mxc_dma_srcdst_t srcdstReload)
int	MXC_DMA_GetSrcReload (mxc_dma_srcdst_t *srcdstReload)
int	MXC_DMA_SetCallback (int ch, void(*callback)(int, int))
int	MXC_DMA_SetChannelInterruptEn (int ch, bool chdis, bool ctz)
int	MXC_DMA_ChannelEnableInt (int ch, int flags)
int	MXC_DMA_ChannelDisableInt (int ch, int flags)
int	MXC_DMA_ChannelGetFlags (int ch)
int	MXC_DMA_ChannelClearFlags (int ch, int flags)
int	MXC_DMA_EnableInt (int ch)
int	MXC_DMA_DisableInt (int ch)
int	MXC_DMA_Start (int ch)
int	MXC_DMA_Stop (int ch)
mxc_dma_ch_regs_t *	MXC_DMA_GetCHRegs (int ch)
void	MXC_DMA_Handler (void)
int	MXC_DMA_MemCpy (void *dest, void *src, int len, mxc_dma_complete_cb_t callback)
int	MXC_DMA_DoTransfer (mxc_dma_config_t config, mxc_dma_srcdst_t firstSrcDst, mxc_dma_trans_chain_t callback)

Detailed Description

---

Data Structure Documentation

mxc_dma_config_t

struct mxc_dma_config_t

The basic configuration information to set up a DMA channel and prepare it for transfers.

Data Fields
int	ch
mxc_dma_reqsel_t	reqsel
mxc_dma_width_t	srcwd
mxc_dma_width_t	dstwd
int	srcinc_en
int	dstinc_en

mxc_dma_srcdst_t

struct mxc_dma_srcdst_t

The information needed to complete a DMA transfer.

Data Fields
int	ch
void *	source
void *	dest
int	len

mxc_dma_adv_config_t

struct mxc_dma_adv_config_t

The advanced configuration options, these are optional but could be needed in cases where multiple DMA channels are running concurrently or DMA is being used with low bandwidth peripherals.

Data Fields
int	ch
mxc_dma_priority_t	prio
unsigned int	reqwait_en
mxc_dma_timeout_t	tosel
mxc_dma_prescale_t	pssel
unsigned int	burst_size

Typedef Documentation

mxc_dma_complete_cb_t

typedef void(* mxc_dma_complete_cb_t) (void *dest)

The callback called on completion of a DMA_MemCpy() transfer.

Parameters

dest	Pointer to the destination of the copy

mxc_dma_trans_chain_t

typedef mxc_dma_srcdst_t(* mxc_dma_trans_chain_t) (mxc_dma_srcdst_t dest)

The callback called on completion of a transfer,.

Note

This callback is used with MXC_DMA_DoTransfer() to allow the user to chain an unlimited number of DMA Transfers.

Parameters

trans

Struct of the completed transfer

Returns

Returns the next transfer to be completed, or NULL if no more transfers will be done

Enumeration Type Documentation

mxc_dma_prescale_t

enum mxc_dma_prescale_t

Enumeration for the DMA prescaler.

Enumerator
MXC_DMA_PRESCALE_DISABLE	Prescaler disabled.
MXC_DMA_PRESCALE_DIV256	Divide by 256.
MXC_DMA_PRESCALE_DIV64K	Divide by 65,536.
MXC_DMA_PRESCALE_DIV16M	Divide by 16,777,216.

mxc_dma_priority_t

enum mxc_dma_priority_t

Enumeration for the DMA Channel's priority level.

Enumerator
MXC_DMA_PRIO_HIGH	High Priority.
MXC_DMA_PRIO_MEDHIGH	Medium High Priority.
MXC_DMA_PRIO_MEDLOW	Medium Low Priority.
MXC_DMA_PRIO_LOW	Low Priority.

mxc_dma_reqsel_t

enum mxc_dma_reqsel_t

DMA request select.

Enumerator
MXC_DMA_REQUEST_MEMTOMEM	Memory to Memory DMA Request Selection.
MXC_DMA_REQUEST_SPI0RX	SPI0 Receive DMA Request Selection.
MXC_DMA_REQUEST_SPI1RX	SPI1 Receive DMA Request Selection.
MXC_DMA_REQUEST_SPI2RX	SPI2 Receive DMA Request Selection.
MXC_DMA_REQUEST_SPI3RX	SPI3 Receive DMA Request Selection.
MXC_DMA_REQUEST_SPI4RX	SPI4 Receive DMA Request Selection.
MXC_DMA_REQUEST_UART0RX	UART0 Receive DMA Request Selection.
MXC_DMA_REQUEST_UART1RX	UART1 Receive DMA Request Selection.
MXC_DMA_REQUEST_UART2RX	UART2 Receive DMA Request Selection.
MXC_DMA_REQUEST_UART3RX	UART3 Receive DMA Request Selection.
MXC_DMA_REQUEST_I2C0RX	I2C0 Receive DMA Request Selection.
MXC_DMA_REQUEST_I2C1RX	I2C1 Receive DMA Request Selection.
MXC_DMA_REQUEST_I2C2RX	I2C2 Receive DMA Request Selection.
MXC_DMA_REQUEST_ADC	ADC Receive DMA Request Selection.
MXC_DMA_REQUEST_I2SRX	I2S Receive DMA Request Selection.
MXC_DMA_REQUEST_CAN0RX	CAN0 Receive DMA Request Selection.
MXC_DMA_REQUEST_CAN1RX	CAN1 Receive DMA Request Selection.
MXC_DMA_REQUEST_SPI0TX	SPI0 Transmit DMA Request Selection.
MXC_DMA_REQUEST_SPI1TX	SPI1 Transmit DMA Request Selection.
MXC_DMA_REQUEST_SPI2TX	SPI2 Transmit DMA Request Selection.
MXC_DMA_REQUEST_SPI3TX	SPI3 Transmit DMA Request Selection.
MXC_DMA_REQUEST_SPI4TX	SPI4 Transmit DMA Request Selection.
MXC_DMA_REQUEST_UART0TX	UART0 Transmit DMA Request Selection.
MXC_DMA_REQUEST_UART1TX	UART1 Transmit DMA Request Selection.
MXC_DMA_REQUEST_UART2TX	UART2 Transmit DMA Request Selection.
MXC_DMA_REQUEST_UART3TX	UART3 Receive DMA Request Selection.
MXC_DMA_REQUEST_I2C0TX	I2C0 Transmit DMA Request Selection.
MXC_DMA_REQUEST_I2C1TX	I2C1 Transmit DMA Request Selection.
MXC_DMA_REQUEST_I2C2TX	I2C2 Transmit DMA Request Selection.
MXC_DMA_REQUEST_I2STX	I2S Transmit DMA Request Selection.
MXC_DMA_REQUEST_CAN0TX	CAN0 Transmit DMA Request Selection.
MXC_DMA_REQUEST_CAN1TX	CAN1 Transmit DMA Request Selection.

mxc_dma_timeout_t

enum mxc_dma_timeout_t

Enumeration for the DMA timeout value.

Enumerator
MXC_DMA_TIMEOUT_4_CLK	DMA timeout of 4 clocks.
MXC_DMA_TIMEOUT_8_CLK	DMA timeout of 8 clocks.
MXC_DMA_TIMEOUT_16_CLK	DMA timeout of 16 clocks.
MXC_DMA_TIMEOUT_32_CLK	DMA timeout of 32 clocks.
MXC_DMA_TIMEOUT_64_CLK	DMA timeout of 64 clocks.
MXC_DMA_TIMEOUT_128_CLK	DMA timeout of 128 clocks.
MXC_DMA_TIMEOUT_256_CLK	DMA timeout of 256 clocks.
MXC_DMA_TIMEOUT_512_CLK	DMA timeout of 512 clocks.

mxc_dma_width_t

enum mxc_dma_width_t

DMA transfer data width.

Enumerator
MXC_DMA_WIDTH_BYTE	DMA transfer in bytes.
MXC_DMA_WIDTH_HALFWORD	DMA transfer in 16-bit half-words.
MXC_DMA_WIDTH_WORD	DMA transfer in 32-bit words.

Function Documentation

MXC_DMA_AcquireChannel()

int MXC_DMA_AcquireChannel

(

void

)

Request DMA channel.

Returns a handle to the first free DMA channel, which can be used via API calls or direct access to channel registers using the MXC_DMA_GetCHRegs(int ch) function.

Returns

Non-negative channel handle (inclusive of zero).

E_NONE_AVAIL All channels in use.

E_BAD_STATE DMA is not initialized, call MXC_DMA_Init() first.

E_BUSY DMA is currently busy (locked), try again later.

MXC_DMA_AdvConfigChannel()

int MXC_DMA_AdvConfigChannel

(

mxc_dma_adv_config_t

advConfig

)

Configure the DMA channel with more advanced parameters.

Parameters

advConfig

Struct containing advanced DMA parameters

Returns

E_BAD_PARAM if an unused or invalid channel handle, E_NO_ERROR otherwise

MXC_DMA_ChannelClearFlags()

int MXC_DMA_ChannelClearFlags	(	int	ch,
		int	flags
	)

Clear channel interrupt flags.

Parameters

ch	channel handle
flags	The flags to clear

Returns

E_BAD_PARAM if an unused or invalid channel handle, E_NO_ERROR otherwise, Error Codes

MXC_DMA_ChannelDisableInt()

int MXC_DMA_ChannelDisableInt	(	int	ch,
		int	flags
	)

Disable channel interrupt.

Parameters

ch	channel handle
flags	The flags to disable

Returns

E_BAD_PARAM if an unused or invalid channel handle, E_NO_ERROR otherwise, Error Codes

MXC_DMA_ChannelEnableInt()

int MXC_DMA_ChannelEnableInt	(	int	ch,
		int	flags
	)

Enable channel interrupt.

Note

Each channel has two interrupts (complete, and count to zero) which must also be enabled with MXC_DMA_SetChannelInterruptEn()

Parameters

ch	channel handle
flags	The flags to enable

Returns

E_BAD_PARAM if an unused or invalid channel handle, E_NO_ERROR otherwise, Error Codes

MXC_DMA_ChannelGetFlags()

int MXC_DMA_ChannelGetFlags

(

int

ch

)

Read channel interrupt flags.

Parameters

ch	channel handle

Returns

E_BAD_PARAM if an unused or invalid channel handle, flags otherwise, Error Codes

MXC_DMA_ConfigChannel()

int MXC_DMA_ConfigChannel	(	mxc_dma_config_t	config,
		mxc_dma_srcdst_t	srcdst
	)

Configure the DMA channel.

Configures the channel, which was previously requested by MXC_DMA_Getchannel()

Parameters

config	Struct containing DMA configuration parameters
srcdst	Struct containing pointers and length of DMA operation

Returns

E_BAD_PARAM if an unused or invalid channel handle, E_NO_ERROR otherwise

MXC_DMA_DisableInt()

int MXC_DMA_DisableInt

(

int

ch

)

Disable channel interrupt.

Parameters

ch	channel handle

Returns

E_BAD_PARAM if an unused or invalid channel handle, E_NO_ERROR otherwise, Error Codes

MXC_DMA_DoTransfer()

int MXC_DMA_DoTransfer	(	mxc_dma_config_t	config,
		mxc_dma_srcdst_t	firstSrcDst,
		mxc_dma_trans_chain_t	callback
	)

Performs a memcpy, using DMA, optionally asynchronous.

Note

The user must have the DMA interrupt enabled and call MXC_DMA_Handler() from the ISR.

Parameters

config	The channel config struct
firstSrcDst	The source, destination, and count for the first transfer
callback	function is called when transfer is complete

Returns

see Error Codes

MXC_DMA_EnableInt()

int MXC_DMA_EnableInt

(

int

ch

)

Enable channel interrupt.

Note

Each channel has two interrupts (complete, and count to zero) which must also be enabled with MXC_DMA_SetChannelInterruptEn()

Parameters

ch	channel handle

Returns

E_BAD_PARAM if an unused or invalid channel handle, E_NO_ERROR otherwise, Error Codes

MXC_DMA_GetCHRegs()

mxc_dma_ch_regs_t * MXC_DMA_GetCHRegs

(

int

ch

)

Get a pointer to the DMA channel registers.

Parameters

ch	channel handle

If direct access to DMA channel registers is required, this function can be used on a channel handle returned by MXC_DMA_AcquireChannel().

Returns

NULL if an unused or invalid channel handle, or a valid pointer otherwise

MXC_DMA_GetSrcDst()

int MXC_DMA_GetSrcDst

(

mxc_dma_srcdst_t *

srcdst

)

Get channel source, destination, and count for transfer.

Parameters

srcdst

Pointer to struct with the correct channel number

Returns

See Error Codes for a list of return values

MXC_DMA_GetSrcReload()

int MXC_DMA_GetSrcReload

(

mxc_dma_srcdst_t *

srcdstReload

)

Get channel reload source, destination, and count for transfer.

Parameters

srcdstReload

Pointer to struct with the correct channel number

Returns

See Error Codes for a list of return values

MXC_DMA_Handler()

void MXC_DMA_Handler

(

void

)

Interrupt handler function.

Call this function as the ISR for each DMA channel under driver control. Interrupt flags for channel ch will be automatically cleared before return.

MXC_DMA_Init()

int MXC_DMA_Init

(

void

)

Initialize DMA resources.

This initialization is required before using the DMA driver functions.

Note

On default this function enables DMA peripheral clock. if you wish to manage clock and gpio related things in upper level instead of here. Define MSDK_NO_GPIO_CLK_INIT flag in project.mk file. By this flag this function will remove clock and gpio related codes from file.

Returns

E_NO_ERROR if successful

MXC_DMA_MemCpy()

int MXC_DMA_MemCpy	(	void *	dest,
		void *	src,
		int	len,
		mxc_dma_complete_cb_t	callback
	)

Performs a memcpy, using DMA, optionally asynchronous.

Note

The user must have the DMA interrupt enabled and call MXC_DMA_Handler() from the ISR.

Parameters

dest	pointer to destination memory
src	pointer to source memory
len	number of bytes to copy
callback	function to call when transfer is complete

Returns

see Error Codes

MXC_DMA_ReleaseChannel()

int MXC_DMA_ReleaseChannel

(

int

ch

)

Release DMA channel.

Stops any DMA operation on the channel and returns it to the pool of free channels.

Parameters

ch	channel handle to release

Returns

E_BAD_PARAM if an unused or invalid channel handle, E_NO_ERROR otherwise

MXC_DMA_SetCallback()

int MXC_DMA_SetCallback	(	int	ch,
		void(*)(int, int)	callback
	)

Set channel interrupt callback.

Parameters

ch	channel handle
callback	Pointer to a function to call when the channel interrupt flag is set and interrupts are enabled or when DMA is shutdown by the driver.

Configures the channel interrupt callback. The callback function is called for two conditions:

1. When the channel's interrupt flag is set and DMA interrupts are enabled.
2. If the driver calls the MXC_DMA_Shutdown() function. The callback function prototype is:

   void callback_fn(int ch, int reason);

   ch indicates the channel that generated the callback, reason is either E_NO_ERROR for a DMA interrupt or E_SHUTDOWN if the DMA is being shutdown.

Returns

E_BAD_PARAM if an unused or invalid channel handle, E_NO_ERROR otherwise, Error Codes

MXC_DMA_SetChannelInterruptEn()

int MXC_DMA_SetChannelInterruptEn	(	int	ch,
		bool	chdis,
		bool	ctz
	)

Set channel interrupt.

Note

Each channel has two interrupts (complete, and count to zero). To enable complete, pass true for chdis. To enable count to zero, pass true for ctz.

Parameters

ch	Channel Handle
chdis	Enable channel complete interrupt
ctz	Enable channel count to zero interrupt.

Returns

E_BAD_PARAM if an unused or invalid channel handle, E_NO_ERROR otherwise

MXC_DMA_SetSrcDst()

int MXC_DMA_SetSrcDst

(

mxc_dma_srcdst_t

srcdst

)

Set channel source, destination, and count for the transfer.

Parameters

srcdst

Struct containing the channel, source, destination, and count for the channel

Note

Unless the channel request select is mxc_dma_srcdst_t = MXC_DMA_REQUEST_MEMTOMEM, either src_addr or dst_addr will be ignored by the DMA engine. In these cases, the address is a don't-care. See the User's Guide for more information.

Returns

E_BAD_PARAM if an unused or invalid channel handle, E_NO_ERROR otherwise

MXC_DMA_SetSrcReload()

int MXC_DMA_SetSrcReload

(

mxc_dma_srcdst_t

srcdstReload

)

Set channel reload source, destination, and count for the transfer.

Parameters

srcdstReload

Struct containing the channel, source, destination, and count for the channel

Note

Unless the channel request select is mxc_dma_srcdst_t = MXC_DMA_REQUEST_MEMTOMEM, either src_addr or dst_addr will be ignored by the DMA engine. In these cases, the address is a don't-care. See the User's Guide for more information.

Returns

E_BAD_PARAM if an unused or invalid channel handle, E_NO_ERROR otherwise

MXC_DMA_Start()

int MXC_DMA_Start

(

int

ch

)

Start transfer.

Parameters

ch	channel handle

Start the DMA channel transfer, assumes that MXC_DMA_SetSrcDstCnt() has been called beforehand.

Returns

E_BAD_PARAM if an unused or invalid channel handle, E_NO_ERROR otherwise, Error Codes

MXC_DMA_Stop()

int MXC_DMA_Stop

(

int

ch

)

Stop DMA transfer, irrespective of status (complete or in-progress)

Parameters

ch	channel handle

Returns

E_BAD_PARAM if an unused or invalid channel handle, E_NO_ERROR otherwise, Error Codes