uDMA Library

The mikroC PRO for ARM provides a library for working with uDMA module.

The TM4C129xxxxx series microcontroller includes a Direct Memory Access (DMA) controller, known as micro-DMA (uDMA). The uDMA controller provides a way to offload data transfer tasks from the
processor, allowing for more efficient use of the processor and the available bus bandwidth.

The uDMA controller can perform transfers between memory and peripherals. It has dedicated channels for each supported on-chip module and can be programmed to automatically perform transfers between peripherals and memory as the peripheral is ready to transfer more data.

Library Routines

uDMA_Enable
uDMA_Disable
uDMA_ErrorStatusGet
uDMA_ErrorStatusClear
uDMA_ChannelEnable
uDMA_ChannelDisable
uDMA_ChannelIsEnabled
uDMA_ControlBaseSet
uDMA_ControlBaseGet
uDMA_ControlAlternateBaseGet
uDMA_ChannelRequest
uDMA_ChannelAttributeEnable
uDMA_ChannelAttributeDisable
uDMA_ChannelAttributeGet
uDMA_ChannelControlSet
uDMA_ChannelTransferSet
uDMA_ChannelSizeGet
uDMA_ChannelModeGet
uDMA_ChannelAssign
uDMA_Init

uDMA_Enable

Prototype	void uDMA_Enable();
Description	This function enables the uDMA controller. The uDMA controller must be enabled before it can be configured and used.
Parameters	None.
Returns	none.
Requires	Nothing.
Notes	None.

uDMA_Disable

Prototype	void uDMA_Disable();
Description	This function disables the uDMA controller. Once disabled, the uDMA controller cannot operate until re-enabled with uDMA_Enable.
Parameters	None.
Returns	none.
Requires	Nothing.
Notes	None.

uDMA_ErrorStatusGet

Prototype	unsigned long uDMA_ErrorStatusGet();
Description	This function returns the uDMA error status. It should be called from within the uDMA error interrupt handler to determine if a uDMA error occurred.
Parameters	None.
Returns	Returns non-zero if a uDMA error is pending.
Requires	Nothing.
Notes	None.

uDMA_ErrorStatusClear

Prototype	void uDMA_ErrorStatusClear();
Description	This function clears a pending uDMA error interrupt. This function should be called from within the uDMA error interrupt handler to clear the interrupt.
Parameters	None.
Returns	Nothing.
Requires	Nothing.
Notes	None.

uDMA_ChannelEnable

Prototype	unsigned short uDMA_ChannelEnable(unsigned long channelNum);
Description	This function enables a specific uDMA channel for use. This function must be used to enable a channel before it can be used to perform a uDMA transfer. When a uDMA transfer is completed, the channel is automatically disabled by the uDMA controller. Therefore, this function should be called prior to starting up any new transfer.
Parameters	`channelNum:` channel number to enable.
Returns	`1` - if parameter `channelNum` is greater or equal to 32. `0` - if successful.
Requires	Nothing.
Notes	None.

uDMA_ChannelDisable

Prototype	unsigned short uDMA_ChannelDisable(unsigned long channelNum);
Description	This function disables a specific uDMA channel. Once disabled, a channel cannot respond to uDMA transfer requests until re-enabled via uDMA_ChannelEnable.
Parameters	`channelNum:` channel number to disable.
Returns	`1` - if parameter `channelNum` is greater or equal to 32. `0` - if successful.
Requires	Nothing.
Notes	None.

uDMA_ChannelIsEnabled

Prototype	unsigned short uDMA_ChannelIsEnabled(unsigned long channelNum);
Description	his function checks to see if a specific uDMA channel is enabled. This function can be used to check the status of a transfer, as the channel is automatically disabled at the end of a transfer.
Parameters	`channelNum:` channel number to check.
Returns	`1` - if parameter `channelNum` is greater or equal to 32. `0` - if successful.
Requires	Nothing.
Notes	None.

uDMA_ControlBaseSet

Prototype	unsigned short uDMA_ControlBaseSet(unsigned long psControlTable);
Description	This function configures the base address of the channel control table. This table resides in system memory and holds control information for each uDMA channel. The table must be aligned on a 1024-byte boundary. The base address must be configured before any of the channel functions can be used. The size of the channel control table depends on the number of uDMA channels and the transfer modes that are used. Refer to the introductory text and the microcontroller datasheet for more information about the channel control table.
Parameters	`psControlTable:` pointer to the 1024-byte-aligned base address of the uDMA channel control table.
Returns	`1` - if an error occurred. `0` - if successful.
Requires	Nothing.
Notes	None.

uDMA_ControlBaseGet

Prototype	unsigned long uDMA_ControlBaseGet();
Description	This function gets the base address of the channel control table. This table resides in system memory and holds control information for each uDMA channel.
Parameters	None.
Returns	Returns a pointer to the base address of the channel control table.
Requires	Nothing.
Notes	None.

uDMA_ControlAlternateBaseGet

Prototype	unsigned long uDMA_ControlAlternateBaseGet();
Description	This function gets the base address of the second half of the channel control table that holds the alternate control structures for each channel.
Parameters	None.
Returns	Returns a pointer to the base address of the second half of the channel control table.
Requires	Nothing.
Notes	None.

uDMA_ChannelRequest

Prototype	unsigned short uDMA_ChannelRequest(unsigned long channelNum);
Description	This function allows software to request a uDMA channel to begin a transfer. This function could be used for performing a memory-to-memory transfer, or if for some reason a transfer needs to be initiated by software instead of the peripheral associated with that channel.
Parameters	`channelNum:` channel number on which to request a uDMA transfer.
Returns	`1` - if parameter `channelNum` is greater or equal to 32. `0` - if successful.
Requires	Nothing.
Notes	If the channel is `UDMA_CHANNEL_SW` and interrupts are used, then the completion is signaled on the uDMA dedicated interrupt. If a peripheral channel is used, then the completion is signaled on the peripheral's interrupt.

uDMA_ChannelAttributeEnable

Prototype

unsigned short uDMA_ChannelAttributeEnable(unsigned long channelNum, unsigned long attr);

Description

This function is used to disable attributes of a uDMA channel.

Parameters

channelNum: channel to configure.

attr: combination of attributes for the channel. Valid values can be formed by OR-ing the following constants :

Symbolic name	Value	Description
_UDMA_ATTR_USEBURST	0x00000001	Restrict transfers to use only burst mode.
_UDMA_ATTR_ALTSELECT	0x00000002	Select the alternate control structure for the channel.
_UDMA_ATTR_HIGH_PRIORITY	0x00000004	Set the channel to high priority.
_UDMA_ATTR_REQMASK	0x00000008	Mask the hardware request signal from the peripheral for the channel.
_UDMA_ATTR_ALL	0x0000000F	Combination of all values.

Returns

1 - if parameter channelNum is greater or equal to 32.
2 - if parameter attr is greater or equal to OR-ed value of the attribute constants.
0 - if successful.

Requires

Nothing.

Notes

None.

uDMA_ChannelAttributeDisable

Prototype

unsigned short uDMA_ChannelAttributeDisable(unsigned long channelNum, unsigned long attr);

Description

This function is used to enable attributes of a uDMA channel.

Parameters

channelNum: channel to configure.

attr: combination of attributes for the channel. Valid values can be formed by OR-ing the following constants :

Symbolic name	Value	Description
_UDMA_ATTR_USEBURST	0x00000001	Restrict transfers to use only burst mode.
_UDMA_ATTR_ALTSELECT	0x00000002	Select the alternate control structure for the channel.
_UDMA_ATTR_HIGH_PRIORITY	0x00000004	Set the channel to high priority.
_UDMA_ATTR_REQMASK	0x00000008	Mask the hardware request signal from the peripheral for the channel.
_UDMA_ATTR_ALL	0x0000000F	Combination of all values.

Returns

1 - if parameter channelNum is greater or equal to 32.
2 - if parameter attr is greater or equal to OR-ed value of the attribute constants.
0 - if successful.

Requires

Nothing.

Notes

None.

uDMA_ChannelAttributeGet

Prototype

unsigned long uDMA_ChannelAttributeGet(unsigned long channelNum);

Description

This function returns a combination of flags representing the attributes of the uDMA channel.

Parameters

channelNum: channel to configure.

Returns

Resulting combination of flags that represent the attributes of the uDMA channel :

Symbolic name	Value	Description
_UDMA_ATTR_USEBURST	0x00000001	Restrict transfers to use only burst mode.
_UDMA_ATTR_ALTSELECT	0x00000002	Select the alternate control structure for the channel.
_UDMA_ATTR_HIGH_PRIORITY	0x00000004	Set the channel to high priority.
_UDMA_ATTR_REQMASK	0x00000008	Mask the hardware request signal from the peripheral for the channel.
_UDMA_ATTR_ALL	0x0000000F	Combination of all values.

1 - if parameter channelNum is greater or equal to 32.

Requires

Nothing.

Notes

None.

uDMA_ChannelControlSet

Prototype

unsigned short uDMA_ChannelControlSet(unsigned long channelStructIndex, unsigned long control);

Description

This function is used to set control parameters for a uDMA transfer. These parameters are typically not changed often.

Parameters

channelStructIndex: this parameter should be the logical OR of the channel number with one of _UDMA_PRI_SELECT or UDMA_ALT_SELECT to choose whether the primary or alternate data structure is used.

control: this parameter should be the logical OR of five values:

data size valid values :

Symbolic name Description

_UDMA_SIZE_8 8 bits data size.

_UDMA_SIZE_16 16 bits data size.

_UDMA_SIZE_32 32 bits data size.

source address increment valid values :

Symbolic name	Description
_UDMA_SRC_INC_8	address increment of 8-bit (byte).
_UDMA_SRC_INC_16	address increment of 16-bit (half-word).
_UDMA_SRC_INC_32	address increment of 32-bit (word).
_UDMA_SRC_INC_NONE	address non-incrementing.

destination address increment valid values :

Symbolic name	Description
_UDMA_DST_INC_8	address increment of 8-bit (byte).
_UDMA_DST_INC_16	address increment of 16-bit (half-word).
_UDMA_DST_INC_32	address increment of 32-bit (word).
_UDMA_DST_INC_NONE	address non-incrementing.

arbitration size determines how many items (in powers of two) are transferred before the uDMA controller re-arbitrates for the bus. valid values :

Symbolic name	Description
_UDMA_ARB_1	1 item.
_UDMA_ARB_2	2 items.
_UDMA_ARB_4	4 items.
_UDMA_ARB_8	8 items.
_UDMA_ARB_16	16 items.
_UDMA_ARB_32	32 items.
_UDMA_ARB_64	64 items.
_UDMA_ARB_128	128 items.
_UDMA_ARB_256	256 items.
_UDMA_ARB_512	512 items.
_UDMA_ARB_1024	1024 items.

The value _UDMA_NEXT_USEBURST is used to force the channel to only respond to burst requests at the tail end of a scatter-gather transfer.

Returns

2 - if control base register is equal to zero.
1 - if
0 - if successful.

Requires

Nothing.

Notes

The address increment cannot be smaller than the data size.

uDMA_ChannelTransferSet

Prototype

unsigned short uDMA_ChannelTransferSet(unsigned long channelStructIndex, unsigned long mode, void *pvSrcAddr, void *pvDstAddr, unsigned long transferSize);

Description

This function is used to configure the parameters for a uDMA transfer. These parameters are typically changed often.
The function uDMA_ChannelControlSet MUST be called at least once for this channel prior to calling this function.

Parameters

channelStructIndex: this parameter should be the logical OR of the channel number with one of _UDMA_PRI_SELECT or UDMA_ALT_SELECT to choose whether the primary or alternate data structure is used.

mode: this parameter should be one of the following values:

Symbolic name	Description
_UDMA_MODE_STOP	Stops the uDMA transfer. The controller sets the mode this value at the end of a transfer.
_UDMA_MODE_BASIC	Perform a basic transfer based on request.
_UDMA_MODE_AUTO	Perform a transfer that always completes once started even if the request is removed.
_UDMA_MODE_PINGPONG	Set up a transfer that switches between the primary and alternate control structures for the channel. This mode allows use of ping-pong buffering for uDMA transfers.
_UDMA_MODE_MEM_SCATTER_GATHER	Set up a memory scatter-gather transfer.
_UDMA_MODE_PER_SCATTER_GATHER	Set up a peripheral scatter-gather transfer.

pvSrcAddr: pointer to the first location of the data to be transferred. This address should be aligned according to the item size.
The compiler takes care of this alignment if the pointer is pointing to storage of the appropriate data type.
pvDstAddr: pointer to the first location of the data to be transferred. This address should be aligned according to the item size.
The compiler takes care of this alignment if the pointer is pointing to storage of the appropriate data type.
transferSize: number of data items (not the number of bytes).

Returns

1, 2, 3, 5 - if an error occurred.
0 - if successful.

Requires

Nothing.

Notes

Great care must be taken to not modify a channel control structure that is in use or else the results are unpredictable, including the possibility of undesired data transfers to or from memory or peripherals.
For BASIC and AUTO modes, it is safe to make changes when the channel is disabled, or the uDMA_ChannelModeGet returns zero.

For PINGPONG or one of the SCATTER_GATHER modes, it is safe to modify the primary or alternate control structure only when the other is being used.
The uDMA_ChannelModeGet function returns zero when a channel control structure is inactive and safe to modify.

The two scatter-gather modes, memory and peripheral, are actually different depending on whether the primary or alternate control structure is selected.
This function looks for the _UDMA_PRI_SELECT and UDMA_ALT_SELECT flag along with the channel number and sets the scatter-gather mode as appropriate for the primary or alternate control structure.

The channel must also be enabled using uDMA_ChannelEnable after calling this function. The transfer does not begin until the channel has been configured and enabled.
Note that the channel is automatically disabled after the transfer is completed, meaning that uDMA_ChannelEnable must be called again after setting up the next transfer.

uDMA_ChannelSizeGet

Prototype	unsigned long uDMA_ChannelSizeGet(unsigned long channelStructIndex);
Description	This function is used to get the uDMA transfer size for a channel. The transfer size is the number of items to transfer, where the size of an item might be 8, 16, or 32 bits.
Parameters	`channelStructIndex:` this parameter should be the logical OR of the channel number with one of `_UDMA_PRI_SELECT` or `UDMA_ALT_SELECT` to choose whether the primary or alternate data structure is used.
Returns	`1`, `2` - if an error occurred. If a partial transfer has already occurred, then the number of remaining items is returned. If the transfer is complete, then 0 is returned.
Requires	Nothing.
Notes	None.

uDMA_ChannelModeGet

Prototype	unsigned long uDMA_ChannelModeGet(unsigned long channelStructIndex);
Description	This function is used to get the transfer mode for the uDMA channel and to query the status of a transfer on a channel. When the transfer is complete the mode is `_UDMA_MODE_STOP`.
Parameters	`channelStructIndex:` this parameter should be the logical OR of the channel number with one of `_UDMA_PRI_SELECT` or `UDMA_ALT_SELECT` to choose whether the primary or alternate data structure is used.
Returns	`1`, `2` - if an error occurred. If a partial transfer has already occurred, then the number of remaining items is returned. If the transfer is complete, then 0 is returned.
Requires	Nothing.
Notes	None.

uDMA_ChannelAssign

Prototype	void uDMA_ChannelAssign(unsigned long mapping);
Description	This function assigns a peripheral mapping to a uDMA channel. It is used to select which peripheral is used for a uDMA channel.
Parameters	`mapping:`macro specifying the peripheral assignment for a channel. Please consult the data sheet for a table showing all the possible peripheral assignments for the uDMA channels for a particular device.
Returns	None.
Requires	Nothing.
Notes	None.

uDMA_Init

Prototype	void uDMA_Init();
Description	This function initializes uDMA controller.
Parameters	None.
Returns	None.
Requires	Nothing.
Notes	This function is only available on devices that have the DMA Channel Map Select registers (DMACHMAP0-3). Please consult the data sheet for your part.

Want more examples and libraries?
Find them on