uDMA Library

The mikroPascal 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

Prototype

procedure 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

procedure 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

function uDMA_ErrorStatusGet() : dword;
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

procedure 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

function uDMA_ChannelEnable(channelNum : dword) : byte;
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

function uDMA_ChannelDisable(channelNum : dword) : byte;
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

function uDMA_ChannelIsEnabled(channelNum : dword) : byte;
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

function uDMA_ControlBaseSet(psControlTable : dword) : byte;
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

function uDMA_ControlBaseGet() : dword;
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

function uDMA_ControlAlternateBaseGet() : dword;
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

function uDMA_ChannelRequest(channelNum : dword) : byte;
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

function uDMA_ChannelAttributeEnable(channelNum : dword; attr : dword) : byte;
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

function uDMA_ChannelAttributeDisable(channelNum : dword; attr : dword) : byte;
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

function uDMA_ChannelAttributeGet(channelNum : dword) : dword;
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

function uDMA_ChannelControlSet(channelStructIndex : dword; control : dword) : byte;
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:
    1. 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.

    2. 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.

    3. 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.

    4. 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.

    5. 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

function uDMA_ChannelTransferSet(channelStructIndex : dword; mode : dword; pvSrcAddr : ^dword; pvDstAddr : ^dword; transferSize : dword) : byte;
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

function uDMA_ChannelSizeGet(channelStructIndex : dword) : dword;
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

function uDMA_ChannelModeGet(channelStructIndex : dword) : dword;
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

procedure uDMA_ChannelAssign(mapping : dword);
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

procedure 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.