Data Structures
struct	tDMAControlTable

Macros
#define	uDMATaskStructEntry(ui32TransferCount, ui32ItemSize, ui32SrcIncrement, pvSrcAddr, ui32DstIncrement, pvDstAddr, ui32ArbSize, ui32Mode)

Functions
void	uDMAInit (void)

void	uDMAEnable (void)

void	uDMADisable (void)

uint32_t	uDMAErrorStatusGet (void)

void	uDMAErrorStatusClear (void)

void	uDMAChannelEnable (uint32_t ui32ChannelNum)

void	uDMAChannelDisable (uint32_t ui32ChannelNum)

bool	uDMAChannelIsEnabled (uint32_t ui32ChannelNum)

void	uDMAControlBaseSet (void *psControlTable)

void *	uDMAControlBaseGet (void)

void *	uDMAControlAlternateBaseGet (void)

void	uDMAChannelRequest (uint32_t ui32ChannelNum)

void	uDMAChannelAttributeEnable (uint32_t ui32ChannelNum, uint32_t ui32Attr)

void	uDMAChannelAttributeDisable (uint32_t ui32ChannelNum, uint32_t ui32Attr)

uint32_t	uDMAChannelAttributeGet (uint32_t ui32ChannelNum)

void	uDMAChannelControlSet (uint32_t ui32ChannelStructIndex, uint32_t ui32Control)

void	uDMAChannelTransferSet (uint32_t ui32ChannelStructIndex, uint32_t ui32Mode, void pvSrcAddr, void pvDstAddr, uint32_t ui32TransferSize)

void	uDMAChannelScatterGatherSet (uint32_t ui32ChannelNum, uint32_t ui32TaskCount, void *pvTaskList, uint32_t ui32IsPeriphSG)

uint32_t	uDMAChannelSizeGet (uint32_t ui32ChannelStructIndex)

uint32_t	uDMAChannelModeGet (uint32_t ui32ChannelStructIndex)

void	uDMAIntRegister (uint32_t ui32IntChannel, void(*pfnHandler)(void))

void	uDMAIntUnregister (uint32_t ui32IntChannel)

void	uDMAChannelAssign (uint32_t ui32Mapping)

Detailed Description

Introduction

The Micro Direct Memory Access (uDMA) API provides functions to configure the MSP432E4 uDMA controller. The uDMA controller is designed to work with the ARM Cortex-M processor and provides an efficient and low-overhead means of transferring blocks of data in the system.

The uDMA controller has the following features:

dedicated channels for supported peripherals
one channel each for receive and transmit for devices with receive and transmit paths
dedicated channel for software initiated data transfers
channels can be independently configured and operated
an arbitration scheme that is configurable per channel
two levels of priority
subordinate to Cortex-M processor bus usage
data sizes of 8, 16, or 32 bits
address increment of byte, half-word, word, or none
maskable device requests
optional software initiated transfers on any channel
interrupt on transfer completion

The uDMA controller supports several different transfer modes, allowing for complex transfer schemes. The following transfer modes are provided:

Basic mode performs a simple transfer when a request is asserted by a device. This mode is appropriate to use with peripherals where the peripheral asserts the request signal whenever data should be transferred. The transfer pauses if the request is de-asserted, even if the transfer is not complete.
Auto-request mode performs a simple transfer that is started by a request, but always completes the entire transfer, even if the request is de-asserted. This mode is appropriate to use with software-initiated transfers.
Ping-Pong mode is used to transfer data to or from two buffers, switching from one buffer to the other as each buffer fills. This mode is appropriate to use with peripherals as a way to ensure a continuous flow of data to or from the peripheral. However, it is more complex to set up and requires code to manage the ping-pong buffers in the interrupt handler.
Memory scatter-gather mode is a complex mode that provides a way to set up a list of transfer ``tasks'' for the uDMA controller. Blocks of data can be transferred to and from arbitrary locations in memory.
Peripheral scatter-gather mode is similar to memory scatter-gather mode except that it is controlled by a peripheral request.

Detailed explanation of the various transfer modes is beyond the scope of this document. Please refer to the device data sheet for more information on the operation of the uDMA controller.

The naming convention for the microDMA controller is to use the Greek letter mu'' to representmicro''. For the purposes of this document, and in the software library function names, a lower case u'' will be used in place of mu'' when the controller is referred to as ``uDMA''.

Note: When the GPIO_O_DATA register is the source or destination, the application code must use the bit banded address space instead of specifying the source or destination address as GPIO_O_DATA.

API Functions

The uDMA API functions provide a means to enable and configure the MSP432E4 uDMA controller to perform DMA transfers.

The general order of function calls to set up and perform a uDMA transfer is the following:

uDMAEnable() is called once to enable the controller.
uDMAControlBaseSet() is called once to set the channel control table.
uDMAChannelAttributeEnable() is called once or infrequently to configure the behavior of the channel.
uDMAChannelControlSet() is used to set up characteristics of the data transfer. It is only called once if the nature of the data transfer does not change.
uDMAChannelTransferSet() is used to set the buffer pointers and size for a transfer. It is called before each new transfer.
uDMAChannelEnable() enables a channel to perform data transfers.
uDMAChannelRequest() is used to initiate a software based transfer. This is normally not used for peripheral based transfers.

In order to use the uDMA controller, you must first enable it by calling uDMAEnable(). You can later disable it, if no longer needed, by calling uDMADisable().

Once the uDMA controller is enabled, you must tell it where to find the channel control structures in system memory by using the function uDMAControlBaseSet() and passing a pointer to the base of the channel control structure. The control structure must be allocated by the application. One way to do allocate the control structure is to declare an array of data type int8_t or uint8_t. In order to support all channels and transfer modes, the control table array should be 1024 bytes, but it can be fewer depending on transfer modes used and number of channels actually used.

Note: The control table must be aligned on a 1024-byte boundary.

The uDMA controller supports multiple channels. Each channel has a set of attribute flags to control certain uDMA features and channel behavior. The attribute flags are configured with the function uDMAChannelAttributeEnable() and cleared with uDMAChannelAttributeDisable(). The setting of the channel attribute flags can be queried using the function uDMAChannelAttributeGet().

Next, the control parameters of the DMA transfer must be configured. These parameters control the size and address increment of the data items to be transferred. The function uDMAChannelControlSet() is used to set up these control parameters.

All of the functions mentioned so far are used only once or infrequently to set up the uDMA channel and transfer. In order to configure the transfer addresses, transfer size, and transfer mode, use the function uDMAChannelTransferSet(). This function must be called for each new transfer. Once everything is set up, the channel is enabled by calling uDMAChannelEnable(), which must be done before each new transfer. The uDMA controller automatically disables the channel at the completion of a transfer. A channel can be manually disabled by using uDMAChannelDisable().

There are additional functions that can be used to query the status of a channel, either from an interrupt handler or in polling fashion. The function uDMAChannelSizeGet() is used to find the amount of data remaining to transfer on a channel. This value is zero when a transfer is complete. The function uDMAChannelModeGet() can be used to find the transfer mode of a uDMA channel. This function is usually used to see if the mode indicates stopped, meaning that a transfer has completed on a channel that was previously running. The function uDMAChannelIsEnabled() can be used to determine if a particular channel is enabled.

If the application is using run-time interrupt registration (see IntRegister()), then the function uDMAIntRegister() can be used to install an interrupt handler for the uDMA controller. This function also enables the interrupt on the system interrupt controller. If compile-time interrupt registration is used, then call the function IntEnable() to enable uDMA interrupts. When an interrupt handler has been installed with uDMAIntRegister(), it can be removed by calling uDMAIntUnregister().

This interrupt handler is only for software-initiated transfers or errors. uDMA interrupts for a peripheral occur on the peripheral's dedicated interrupt channel and should be handled by the peripheral interrupt handler. It is not necessary to acknowledge or clear uDMA interrupt sources. They are cleared automatically when they are serviced.

The uDMA interrupt handler should use the function uDMAErrorStatusGet() to test if a uDMA error occurred. If so, the interrupt must be cleared by calling uDMAErrorStatusClear().

Note: Many of the API functions take a channel parameter that includes the logical OR of one of the values UDMA_PRI_SELECT or UDMA_ALT_SELECT to choose the primary or alternate control structure. For Basic and Auto transfer modes, only the primary control structure is needed. The alternate control structure is only needed for complex transfer modes of Ping-pong or Scatter-gather. Refer to the device data sheet for detailed information about transfer modes.

Special considerations for using scatter-gather operations

In order to use the scatter-gather modes of the uDMA controller, you must prepare a ``task'' list in memory that describes the scatter-gather operations. There is a helper macro, uDMATaskStructEntry provided to help create the initialization values for the task list structure. Please see the documentation for this macro which includes a code snippet showing how it is used.

Once the task list is prepared, the appropriate uDMA channel must be configured for a scatter-gather operation. The best way to do this is to use the function uDMAChannelScatterGatherSet(). Alternatively, the functions uDMAChannelControlSet() followed by uDMAChannelTransferSet() can also be used.

Note: The scatter-gather task list must be resident in SRAM. The uDMA controller cannot read from flash memory.

About uDMA Channel Function Parameters

Many of the uDMA API functions require a channel number as a parameter. There are two different uses of the channel number. In some cases, it is the number of the uDMA channel and is used to read or write registers within the uDMA controller. In this case, it is simply the channel number with no additional qualifier.

However, in other cases the channel number that is supplied as a parameter is really an index into the uDMA channel control structure. Because every uDMA channel has a primary and an alternate channel control structure, this index must also be specified as part of the channel number. The index is specified by passing a value for the channel parameter that is the logical OR of the actual channel number and one of UDMA_PRI_SELECT or UDMA_ALT_SELECT. The default is the same as UDMA_PRI_SELECT so if you do not specify, the primary channel control structure is used, which is the right thing in most cases.

Note: When UDMA_ALT_SELECT is specified, what is really happening is that channel index 32-63 is being used, because the alternate channel control structures for channels 0-31 are located at index locations 32-63 in the channel control table.

Here is an example of the first case. In this example, a uDMA channel is enabled, and only the channel number is used because this is programming a register in the uDMA controller.

uDMAChannelEnable(UDMA_CHANNEL_UART0RX);

Here is an example of the second case. In this example, the channel control structure is to be modified to configure some transfer parameters. Therefore in addition to specifying the channel index, the primary or alternate control structure must also be selected.

uDMAChannelControlSet(UDMA_CHANNEL_UART0RX | UDMA_PRI_SELECT, ...);

In order to help make it clear when one or the other form is to be used, the parameters are named differently in the API description. For functions that require just the channel number, the name of the parameter is ulChannelNum. For functions that require the channel index of the channel control structure, the name of the parameter is ulChannelStructIdx.

Selecting uDMA Channels

The uDMA controller has 32 channels, and therefore most of the API functions take a channel number with a value from 0-31 or a channel index with a value from 0-63 (the 32-63 is specified with the logical OR of the channel number with UDMA_ALT_SELECT). In order to avoid the need for hardcoded channel numbers in code, macros are provided that map channel names to channel numbers.

To use the default channel mapping, you may use one of the following choices whenever a channel number or index is needed. This list is all the possible channels that are defined by the API. However not all channels are available on all parts, depending on which peripherals are available on the part and which of those support uDMA. Please consult the data sheet for your specific part to see which uDMA channels are supported.

UDMA_CHANNEL_USBEP1RX for USB endpoint 1 receive
UDMA_CHANNEL_USBEP1TX for USB endpoint 1 transmit
UDMA_CHANNEL_USBEP2RX for USB endpoint 2 receive
UDMA_CHANNEL_USBEP2TX for USB endpoint 2 transmit
UDMA_CHANNEL_USBEP3RX for USB endpoint 3 receive
UDMA_CHANNEL_USBEP3TX for USB endpoint 3 transmit
UDMA_CHANNEL_ETH0RX for ethernet receive
UDMA_CHANNEL_ETH0TX for ethernet transmit
UDMA_CHANNEL_UART0RX for UART 0 receive channel
UDMA_CHANNEL_UART0TX for UART 0 transmit channel
UDMA_CHANNEL_UART1RX for UART 1 receive channel
UDMA_CHANNEL_UART1TX for UART 1 transmit channel
UDMA_CHANNEL_SSI0RX for SSI 0 receive channel
UDMA_CHANNEL_SSI0TX for SSI 0 transmit channel
UDMA_CHANNEL_SSI1RX for SSI 1 receive channel
UDMA_CHANNEL_SSI1TX for SSI 1 transmit channel
UDMA_CHANNEL_ADC0 for ADC0 sequencer 0
UDMA_CHANNEL_ADC1 for ADC0 sequencer 1
UDMA_CHANNEL_ADC2 for ADC0 sequencer 2
UDMA_CHANNEL_ADC3 for ADC0 sequencer 3
UDMA_CHANNEL_TMR0A for Timer 0A
UDMA_CHANNEL_TMR0B for Timer 0B
UDMA_CHANNEL_TMR1A for Timer 1A
UDMA_CHANNEL_TMR1B for Timer 1B
UDMA_CHANNEL_I2S0RX for I2S receive
UDMA_CHANNEL_I2S0TX for I2S transmit
UDMA_CHANNEL_SW for the software dedicated uDMA channel

Some MSP432E4 parts also provide a secondary channel mapping. For those parts, each channel has a secondary peripheral mapping, allowing more choices in channel mapping and to allow some additional peripherals to use uDMA that are not available in the default mapping.

In order to select the default or secondary channel mapping, use the functions uDMAChannelSelectDefault() or uDMAChannelSelectSecondary(). Each channel can be configured individually to use the default or secondary mapping.

For example, the default for channel 0 is USBEP1RX. However this channel also has a secondary mapping to UART2RX. If an application requires use of uDMA with UART2 and does not use USB, then this channel could be remapped to UART2RX with the following function call:

uDMAChannelSelectSecondary(UDMA_DEF_USBEP1RX_SEC_UART2RX);

For channels that have been configured to use the secondary mapping, there is a set of macros to use for specifying the channel. Here is the list of channels when secondary mapping is used. As before, this is the full list, the actual channels available depend on which specific MSP432E4 part is used.

UDMA_SEC_CHANNEL_UART2RX_0 for UART2 receive using uDMA channel 0
UDMA_SEC_CHANNEL_UART2TX_1 for UART2 transmit using uDMA channel 1
UDMA_SEC_CHANNEL_TMR3A for Timer 3A
UDMA_SEC_CHANNEL_TMR3B for Timer 3B
UDMA_SEC_CHANNEL_TMR2A_4 for Timer 2A using uDMA channel 4
UDMA_SEC_CHANNEL_TMR2B_5 for Timer 2B using uDMA channel 5
UDMA_SEC_CHANNEL_TMR2A_6 for Timer 2A using uDMA channel 6
UDMA_SEC_CHANNEL_TMR2B_7 for Timer 2B using uDMA channel 7
UDMA_SEC_CHANNEL_UART1RX for UART1 receive
UDMA_SEC_CHANNEL_UART1TX for UART1 transmit
UDMA_SEC_CHANNEL_SSI1RX for SSI1 receive
UDMA_SEC_CHANNEL_SSI1TX for SSI1 transmit
UDMA_SEC_CHANNEL_UART2RX_12 for UART2 receive using uDMA channel 12
UDMA_SEC_CHANNEL_UART2TX_13 for UART2 transmit using uDMA channel 13
UDMA_SEC_CHANNEL_TMR2A_14 for Timer 2A using uDMA channel 14
UDMA_SEC_CHANNEL_TMR2B_15 for Timer 2B using uDMA channel 15
UDMA_SEC_CHANNEL_TMR1A for Timer 1A
UDMA_SEC_CHANNEL_TMR1B for Timer 1B
UDMA_SEC_CHANNEL_EPI0RX for EPI read
UDMA_SEC_CHANNEL_EPI0TX for EPI write
UDMA_SEC_CHANNEL_ADC10 for ADC1 sequencer 0
UDMA_SEC_CHANNEL_ADC11 for ADC1 sequencer 1
UDMA_SEC_CHANNEL_ADC12 for ADC1 sequencer 2
UDMA_SEC_CHANNEL_ADC13 for ADC1 sequencer 3
UDMA_SEC_CHANNEL_SW for the software dedicated uDMA channel

Further, some MSP432E4 parts provide up to five possible channel assignments. For those parts, us the uDMAChannelAssign() function to configure the channel assignments.

Programming Example

The following example sets up the uDMA controller to perform a software initiated memory-to-memory transfer:

//
// The application must allocate the channel control table.  This one is a
// full table for all modes and channels.
// NOTE: This table must be 1024-byte aligned.
//
uint8_t pui8DMAControlTable[1024];
//
// Source and destination buffers used for the DMA transfer.
//
uint8_t pui8SourceBuffer[256];
uint8_t pui8DestBuffer[256];
//
// Enable the UDMA peripheral
//
SysCtlPeripheralEnable(SYSCTL_PERIPH_UDMA);
//
// Wait for the UDMA module to be ready.
//
while(!SysCtlPeripheralReady(SYSCTL_PERIPH_UDMA))
{
}
// // Enable the uDMA controller. //
uDMAEnable();
//
// Set the base for the channel control table.
//
uDMAControlBaseSet(&pui8DMAControlTable[0]);
//
// No attributes must be set for a software-based transfer.  The attributes
// are cleared by default, but are explicitly cleared here, in case they
// were set elsewhere.
//
uDMAChannelAttributeDisable(UDMA_CHANNEL_SW, UDMA_CONFIG_ALL);
//
// Now set up the characteristics of the transfer for 8-bit data size, with
// source and destination increments in bytes, and a byte-wise buffer copy.
//  A bus arbitration size of 8 is used.
//
uDMAChannelControlSet(UDMA_CHANNEL_SW | UDMA_PRI_SELECT,
                      UDMA_SIZE_8 | UDMA_SRC_INC_8 |
                      UDMA_DST_INC_8 | UDMA_ARB_8);
//
// The transfer buffers and transfer size are now configured.  The transfer
// uses AUTO mode, which means that the transfer automatically runs to
// completion after the first request.
//
uDMAChannelTransferSet(UDMA_CHANNEL_SW | UDMA_PRI_SELECT,
                       UDMA_MODE_AUTO, pui8SourceBuffer, pui8DestBuffer,
                       sizeof(pui8DestBuffer));
//
// Finally, the channel must be enabled.  Because this is a software-
// initiated transfer, a request must also be made.  The request starts the
// transfer.
//
uDMAChannelEnable(UDMA_CHANNEL_SW);
uDMAChannelRequest(UDMA_CHANNEL_SW);

Macro Definition Documentation

§ uDMATaskStructEntry

#define uDMATaskStructEntry	(	ui32TransferCount,
		ui32ItemSize,
		ui32SrcIncrement,
		pvSrcAddr,
		ui32DstIncrement,
		pvDstAddr,
		ui32ArbSize,
		ui32Mode
	)

Value:

{                                                                         \
        (((ui32SrcIncrement) == UDMA_SRC_INC_NONE) ? (void *)(pvSrcAddr) :    \
            ((void *)(&((uint8_t *)(pvSrcAddr))[((ui32TransferCount) <<       \
                                         ((ui32SrcIncrement) >> 26)) - 1]))), \
            (((ui32DstIncrement) == UDMA_DST_INC_NONE) ? (void *)(pvDstAddr) :\
            ((void *)(&((uint8_t *)(pvDstAddr))[((ui32TransferCount) <<       \
                                         ((ui32DstIncrement) >> 30)) - 1]))), \
        (ui32SrcIncrement) | (ui32DstIncrement) | (ui32ItemSize) |            \
            (ui32ArbSize) |                                                   \
        (((ui32TransferCount) - 1) << 4) |                                    \
        ((((ui32Mode) == UDMA_MODE_MEM_SCATTER_GATHER) ||                     \
          ((ui32Mode) == UDMA_MODE_PER_SCATTER_GATHER)) ?                     \
                (ui32Mode) | UDMA_MODE_ALT_SELECT : (ui32Mode)), 0            \
    }

A helper macro for building scatter-gather task table entries.

Parameters

ui32TransferCount	is the count of items to transfer for this task.
ui32ItemSize	is the bit size of the items to transfer for this task.
ui32SrcIncrement	is the bit size increment for source data.
pvSrcAddr	is the starting address of the data to transfer.
ui32DstIncrement	is the bit size increment for destination data.
pvDstAddr	is the starting address of the destination data.
ui32ArbSize	is the arbitration size to use for the transfer task.
ui32Mode	is the transfer mode for this task.

This macro is intended to be used to help populate a table of uDMA tasks for a scatter-gather transfer. This macro will calculate the values for the fields of a task structure entry based on the input parameters.

There are specific requirements for the values of each parameter. No checking is done so it is up to the caller to ensure that correct values are used for the parameters.

The ui32TransferCount parameter is the number of items that will be transferred by this task. It must be in the range 1-1024.

The ui32ItemSize parameter is the bit size of the transfer data. It must be one of UDMA_SIZE_8, UDMA_SIZE_16, or UDMA_SIZE_32.

The ui32SrcIncrement parameter is the increment size for the source data. It must be one of UDMA_SRC_INC_8, UDMA_SRC_INC_16, UDMA_SRC_INC_32, or UDMA_SRC_INC_NONE.

The pvSrcAddr parameter is a void pointer to the beginning of the source data.

The ui32DstIncrement parameter is the increment size for the destination data. It must be one of UDMA_DST_INC_8, UDMA_DST_INC_16, UDMA_DST_INC_32, or UDMA_DST_INC_NONE.

The pvDstAddr parameter is a void pointer to the beginning of the location where the data will be transferred.

The ui32ArbSize parameter is the arbitration size for the transfer, and must be one of UDMA_ARB_1, UDMA_ARB_2, UDMA_ARB_4, and so on up to UDMA_ARB_1024. This is used to select the arbitration size in powers of 2, from 1 to 1024.

The ui32Mode parameter is the mode to use for this transfer task. It must be one of UDMA_MODE_BASIC, UDMA_MODE_AUTO, UDMA_MODE_MEM_SCATTER_GATHER, or UDMA_MODE_PER_SCATTER_GATHER. Note that normally all tasks will be one of the scatter-gather modes while the last task is a task list will be AUTO or BASIC.

This macro is intended to be used to initialize individual entries of a structure of tDMAControlTable type, like this:

//!     tDMAControlTable MyTaskList[] =
//!     {
//!         uDMATaskStructEntry(Task1Count, UDMA_SIZE_8,
//!                             UDMA_SRC_INC_8, MySourceBuf,
//!                             UDMA_DST_INC_8, MyDestBuf,
//!                             UDMA_ARB_8, UDMA_MODE_MEM_SCATTER_GATHER),
//!         uDMATaskStructEntry(Task2Count, ...),
//!     }
//!

\return Nothing; this is not a function.

Function Documentation

§ uDMAInit()

void uDMAInit ( void )

Initializes the uDMA for use.

This function assigns a default peripheral mapping for uDMA channels 20-25. This function must be called in order to prevent multiple channels from being assigned to the same peripheral by moving these channels to an encoding where they are in reserved status.

Returns: None.

References UDMA_CH20_RESERVED7, UDMA_CH21_RESERVED7, UDMA_CH22_RESERVED7, UDMA_CH23_RESERVED7, UDMA_CH24_RESERVED7, UDMA_CH25_RESERVED7, and uDMAChannelAssign().

§ uDMAEnable()

void uDMAEnable ( void )

Enables the uDMA controller for use.

This function enables the uDMA controller. The uDMA controller must be enabled before it can be configured and used.

Returns: None.

References HWREG, UDMA_CFG, and UDMA_CFG_MASTEN.

§ uDMADisable()

void uDMADisable ( void )

Disables the uDMA controller for use.

This function disables the uDMA controller. Once disabled, the uDMA controller cannot operate until re-enabled with uDMAEnable().

Returns: None.

References HWREG, and UDMA_CFG.

§ uDMAErrorStatusGet()

uint32_t uDMAErrorStatusGet ( void )

Gets the uDMA error status.

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.

Returns: Returns non-zero if a uDMA error is pending.

References HWREG, and UDMA_ERRCLR.

§ uDMAErrorStatusClear()

void uDMAErrorStatusClear ( void )

Clears the uDMA error interrupt.

This function clears a pending uDMA error interrupt. This function should be called from within the uDMA error interrupt handler to clear the interrupt.

Returns: None.

References HWREG, and UDMA_ERRCLR.

§ uDMAChannelEnable()

void uDMAChannelEnable ( uint32_t ui32ChannelNum )

Enables a uDMA channel for operation.

Parameters

ui32ChannelNum is the channel number to enable.

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.

Returns: None.

References ASSERT, HWREG, and UDMA_ENASET.

§ uDMAChannelDisable()

void uDMAChannelDisable ( uint32_t ui32ChannelNum )

Disables a uDMA channel for operation.

Parameters

ui32ChannelNum is the channel number to disable.

This function disables a specific uDMA channel. Once disabled, a channel cannot respond to uDMA transfer requests until re-enabled via uDMAChannelEnable().

Returns: None.

References ASSERT, HWREG, and UDMA_ENACLR.

§ uDMAChannelIsEnabled()

bool uDMAChannelIsEnabled ( uint32_t ui32ChannelNum )

Checks if a uDMA channel is enabled for operation.

Parameters

ui32ChannelNum is the channel number to check.

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

Returns: Returns true if the channel is enabled, false if disabled.

References ASSERT, HWREG, and UDMA_ENASET.

§ uDMAControlBaseSet()

void uDMAControlBaseSet ( void * psControlTable )

Sets the base address for the channel control table.

Parameters

psControlTable is a pointer to the 1024-byte-aligned base address of the uDMA channel control table.

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 technical reference manual and the data sheet for more information about the channel control table.

Returns: None.

References ASSERT, HWREG, and UDMA_CTLBASE.

§ uDMAControlBaseGet()

void* uDMAControlBaseGet ( void )

Gets the base address for the channel control table.

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.

Returns: Returns a pointer to the base address of the channel control table.

References HWREG, and UDMA_CTLBASE.

§ uDMAControlAlternateBaseGet()

void* uDMAControlAlternateBaseGet ( void )

Gets the base address for the channel control table alternate structures.

This function gets the base address of the second half of the channel control table that holds the alternate control structures for each channel.

Returns: Returns a pointer to the base address of the second half of the channel control table.

References HWREG, and UDMA_ALTBASE.

§ uDMAChannelRequest()

void uDMAChannelRequest ( uint32_t ui32ChannelNum )

Requests a uDMA channel to start a transfer.

Parameters

ui32ChannelNum is the channel number on which to request a uDMA transfer.

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.

Note: 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.

Returns: None.

References ASSERT, HWREG, and UDMA_SWREQ.

§ uDMAChannelAttributeEnable()

void uDMAChannelAttributeEnable	(	uint32_t	ui32ChannelNum,
		uint32_t	ui32Attr
	)

Enables attributes of a uDMA channel.

Parameters

ui32ChannelNum	is the channel to configure.
ui32Attr	is a combination of attributes for the channel.

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

The ui32Attr parameter is the logical OR of any of the following:

UDMA_ATTR_USEBURST is used to restrict transfers to use only burst mode.
UDMA_ATTR_ALTSELECT is used to select the alternate control structure for this channel (it is very unlikely that this flag should be used).
UDMA_ATTR_HIGH_PRIORITY is used to set this channel to high priority.
UDMA_ATTR_REQMASK is used to mask the hardware request signal from the peripheral for this channel.

Returns: None.

References ASSERT, HWREG, UDMA_ALTSET, UDMA_ATTR_ALTSELECT, UDMA_ATTR_HIGH_PRIORITY, UDMA_ATTR_REQMASK, UDMA_ATTR_USEBURST, UDMA_PRIOSET, UDMA_REQMASKSET, and UDMA_USEBURSTSET.

§ uDMAChannelAttributeDisable()

void uDMAChannelAttributeDisable	(	uint32_t	ui32ChannelNum,
		uint32_t	ui32Attr
	)

Disables attributes of a uDMA channel.

Parameters

ui32ChannelNum	is the channel to configure.
ui32Attr	is a combination of attributes for the channel.

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

The ui32Attr parameter is the logical OR of any of the following:

UDMA_ATTR_USEBURST is used to restrict transfers to use only burst mode.
UDMA_ATTR_ALTSELECT is used to select the alternate control structure for this channel.
UDMA_ATTR_HIGH_PRIORITY is used to set this channel to high priority.
UDMA_ATTR_REQMASK is used to mask the hardware request signal from the peripheral for this channel.

Returns: None.

References ASSERT, HWREG, UDMA_ALTCLR, UDMA_ATTR_ALTSELECT, UDMA_ATTR_HIGH_PRIORITY, UDMA_ATTR_REQMASK, UDMA_ATTR_USEBURST, UDMA_PRIOCLR, UDMA_REQMASKCLR, and UDMA_USEBURSTCLR.

§ uDMAChannelAttributeGet()

uint32_t uDMAChannelAttributeGet ( uint32_t ui32ChannelNum )

Gets the enabled attributes of a uDMA channel.

Parameters

ui32ChannelNum is the channel to configure.

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

Returns

Returns the logical OR of the attributes of the uDMA channel, which can be any of the following:

UDMA_ATTR_USEBURST is used to restrict transfers to use only burst mode.
UDMA_ATTR_ALTSELECT is used to select the alternate control structure for this channel.
UDMA_ATTR_HIGH_PRIORITY is used to set this channel to high priority.
UDMA_ATTR_REQMASK is used to mask the hardware request signal from the peripheral for this channel.

References ASSERT, HWREG, UDMA_ALTSET, UDMA_ATTR_ALTSELECT, UDMA_ATTR_HIGH_PRIORITY, UDMA_ATTR_REQMASK, UDMA_ATTR_USEBURST, UDMA_PRIOSET, UDMA_REQMASKSET, and UDMA_USEBURSTSET.

§ uDMAChannelControlSet()

void uDMAChannelControlSet	(	uint32_t	ui32ChannelStructIndex,
		uint32_t	ui32Control
	)

Sets the control parameters for a uDMA channel control structure.

Parameters

ui32ChannelStructIndex	is the logical OR of the uDMA channel number with UDMA_PRI_SELECT or UDMA_ALT_SELECT.
ui32Control	is logical OR of several control values to set the control parameters for the channel.

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

The ui32ChannelStructIndex 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.

The ui32Control parameter is the logical OR of five values: the data size, the source address increment, the destination address increment, the arbitration size, and the use burst flag. The choices available for each of these values is described below.

Choose the data size from one of UDMA_SIZE_8, UDMA_SIZE_16, or UDMA_SIZE_32 to select a data size of 8, 16, or 32 bits.

Choose the source address increment from one of UDMA_SRC_INC_8, UDMA_SRC_INC_16, UDMA_SRC_INC_32, or UDMA_SRC_INC_NONE to select an address increment of 8-bit bytes, 16-bit half-words, 32-bit words, or to select non-incrementing.

Choose the destination address increment from one of UDMA_DST_INC_8, UDMA_DST_INC_16, UDMA_DST_INC_32, or UDMA_DST_INC_NONE to select an address increment of 8-bit bytes, 16-bit half-words, 32-bit words, or to select non-incrementing.

The arbitration size determines how many items are transferred before the uDMA controller re-arbitrates for the bus. Choose the arbitration size from one of UDMA_ARB_1, UDMA_ARB_2, UDMA_ARB_4, UDMA_ARB_8, through UDMA_ARB_1024 to select the arbitration size from 1 to 1024 items, in powers of 2.

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.

Note: The address increment cannot be smaller than the data size.

Returns: None.

References ASSERT, HWREG, UDMA_CHCTL_ARBSIZE_M, UDMA_CHCTL_DSTINC_M, UDMA_CHCTL_DSTSIZE_M, UDMA_CHCTL_NXTUSEBURST, UDMA_CHCTL_SRCINC_M, UDMA_CHCTL_SRCSIZE_M, UDMA_CTLBASE, and tDMAControlTable::ui32Control.

§ uDMAChannelTransferSet()

void uDMAChannelTransferSet	(	uint32_t	ui32ChannelStructIndex,
		uint32_t	ui32Mode,
		void *	pvSrcAddr,
		void *	pvDstAddr,
		uint32_t	ui32TransferSize
	)

Sets the transfer parameters for a uDMA channel control structure.

Parameters

ui32ChannelStructIndex	is the logical OR of the uDMA channel number with either UDMA_PRI_SELECT or UDMA_ALT_SELECT.
ui32Mode	is the type of uDMA transfer.
pvSrcAddr	is the source address for the transfer.
pvDstAddr	is the destination address for the transfer.
ui32TransferSize	is the number of data items to transfer.

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

The ui32ChannelStructIndex 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.

The ui32Mode parameter should be one of the following values:

UDMA_MODE_STOP stops the uDMA transfer. The controller sets the mode to this value at the end of a transfer.
UDMA_MODE_BASIC to perform a basic transfer based on request.
UDMA_MODE_AUTO to perform a transfer that always completes once started even if the request is removed.
UDMA_MODE_PINGPONG to 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 to set up a memory scatter-gather transfer.
UDMA_MODE_PER_SCATTER_GATHER to set up a peripheral scatter-gather transfer.

The pvSrcAddr and pvDstAddr parameters are pointers to the first location of the data to be transferred. These addresses should be aligned according to the item size. The compiler takes care of this alignment if the pointers are pointing to storage of the appropriate data type.

The ui32TransferSize parameter is the number of data items, not the number of bytes.

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 uDMAChannelEnable() 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 uDMAChannelEnable() must be called again after setting up the next transfer.

Note: 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 uDMAChannelModeGet() returns UDMA_MODE_STOP. 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 uDMAChannelModeGet() function returns UDMA_MODE_STOP when a channel control structure is inactive and safe to modify.

Returns: None.

References ASSERT, HWREG, tDMAControlTable::pvDstEndAddr, tDMAControlTable::pvSrcEndAddr, UDMA_ALT_SELECT, UDMA_CHCTL_DSTINC_M, UDMA_CHCTL_SRCINC_M, UDMA_CHCTL_XFERMODE_M, UDMA_CHCTL_XFERSIZE_M, UDMA_CTLBASE, UDMA_DST_INC_NONE, UDMA_MODE_ALT_SELECT, UDMA_MODE_MEM_SCATTER_GATHER, UDMA_MODE_PER_SCATTER_GATHER, UDMA_SRC_INC_NONE, and tDMAControlTable::ui32Control.

§ uDMAChannelScatterGatherSet()

void uDMAChannelScatterGatherSet	(	uint32_t	ui32ChannelNum,
		uint32_t	ui32TaskCount,
		void *	pvTaskList,
		uint32_t	ui32IsPeriphSG
	)

Configures a uDMA channel for scatter-gather mode.

Parameters

ui32ChannelNum	is the uDMA channel number.
ui32TaskCount	is the number of scatter-gather tasks to execute.
pvTaskList	is a pointer to the beginning of the scatter-gather task list.
ui32IsPeriphSG	is a flag to indicate it is a peripheral scatter-gather transfer (else it is memory scatter-gather transfer)

This function is used to configure a channel for scatter-gather mode. The caller must have already set up a task list and must pass a pointer to the start of the task list as the pvTaskList parameter. The ui32TaskCount parameter is the count of tasks in the task list, not the size of the task list. The flag bIsPeriphSG should be used to indicate if scatter-gather should be configured for peripheral or memory operation.

See also: uDMATaskStructEntry

Returns: None.

References ASSERT, HWREG, tDMAControlTable::pvDstEndAddr, tDMAControlTable::pvSrcEndAddr, UDMA_ALT_SELECT, UDMA_ALTCLR, UDMA_CHCTL_ARBSIZE_4, UDMA_CHCTL_DSTINC_32, UDMA_CHCTL_DSTSIZE_32, UDMA_CHCTL_SRCINC_32, UDMA_CHCTL_SRCSIZE_32, UDMA_CHCTL_XFERMODE_MEM_SG, UDMA_CHCTL_XFERMODE_PER_SG, UDMA_CHCTL_XFERSIZE_S, UDMA_CTLBASE, tDMAControlTable::ui32Control, and tDMAControlTable::ui32Spare.

§ uDMAChannelSizeGet()

uint32_t uDMAChannelSizeGet ( uint32_t ui32ChannelStructIndex )

Gets the current transfer size for a uDMA channel control structure.

Parameters

ui32ChannelStructIndex is the logical OR of the uDMA channel number with either UDMA_PRI_SELECT or UDMA_ALT_SELECT.

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. If a partial transfer has already occurred, then the number of remaining items is returned. If the transfer is complete, then 0 is returned.

Returns: Returns the number of items remaining to transfer.

References ASSERT, HWREG, UDMA_CHCTL_XFERMODE_M, UDMA_CHCTL_XFERSIZE_M, UDMA_CTLBASE, and tDMAControlTable::ui32Control.

§ uDMAChannelModeGet()

uint32_t uDMAChannelModeGet ( uint32_t ui32ChannelStructIndex )

Gets the transfer mode for a uDMA channel control structure.

Parameters

ui32ChannelStructIndex is the logical OR of the uDMA channel number with either UDMA_PRI_SELECT or UDMA_ALT_SELECT.

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.

Returns: Returns the transfer mode of the specified channel and control structure, which is one of the following values: UDMA_MODE_STOP, UDMA_MODE_BASIC, UDMA_MODE_AUTO, UDMA_MODE_PINGPONG, UDMA_MODE_MEM_SCATTER_GATHER, or UDMA_MODE_PER_SCATTER_GATHER.

References ASSERT, HWREG, UDMA_CHCTL_XFERMODE_M, UDMA_CTLBASE, UDMA_MODE_ALT_SELECT, UDMA_MODE_MEM_SCATTER_GATHER, UDMA_MODE_PER_SCATTER_GATHER, and tDMAControlTable::ui32Control.

§ uDMAIntRegister()

void uDMAIntRegister	(	uint32_t	ui32IntChannel,
		void(*)(void)	pfnHandler
	)

Registers an interrupt handler for the uDMA controller.

Parameters

ui32IntChannel	identifies which uDMA interrupt is to be registered.
pfnHandler	is a pointer to the function to be called when the interrupt is activated.

This function registers and enables the handler to be called when the uDMA controller generates an interrupt. The ui32IntChannel parameter should be one of the following:

INT_UDMA to register an interrupt handler to process interrupts from the uDMA software channel (UDMA_CHANNEL_SW)
INT_UDMAERR to register an interrupt handler to process uDMA error interrupts

See also: IntRegister() for important information about registering interrupt handlers.

Note: The interrupt handler for the uDMA is for transfer completion when the channel UDMA_CHANNEL_SW is used and for error interrupts. The interrupts for each peripheral channel are handled through the individual peripheral interrupt handlers.

Returns: None.

References ASSERT, IntEnable(), and IntRegister().

§ uDMAIntUnregister()

void uDMAIntUnregister ( uint32_t ui32IntChannel )

Unregisters an interrupt handler for the uDMA controller.

Parameters

ui32IntChannel identifies which uDMA interrupt to unregister.

This function disables and unregisters the handler to be called for the specified uDMA interrupt. The ui32IntChannel parameter should be one of INT_UDMA or INT_UDMAERR as documented for the function uDMAIntRegister().

See also: IntRegister() for important information about registering interrupt handlers.

Returns: None.

References IntDisable(), and IntUnregister().

§ uDMAChannelAssign()

void uDMAChannelAssign ( uint32_t ui32Mapping )

Assigns a peripheral mapping for a uDMA channel.

Parameters

ui32Mapping is a macro specifying the peripheral assignment for a channel.

This function assigns a peripheral mapping to a uDMA channel. It is used to select which peripheral is used for a uDMA channel. The parameter ui32Mapping should be one of the macros named UDMA_CHn_tttt from the header file udma.h. For example, to assign uDMA channel 0 to the UART2 RX channel, the parameter should be the macro UDMA_CH0_UART2RX.

Please consult the data sheet for a table showing all the possible peripheral assignments for the uDMA channels.

Returns: None.

References ASSERT, HWREG, and UDMA_CHMAP0.

Referenced by uDMAInit().

Data Structures

Macros

Functions

Detailed Description

Introduction

API Functions

Programming Example

Macro Definition Documentation

§ uDMATaskStructEntry

Function Documentation

§ uDMAInit()

§ uDMAEnable()

§ uDMADisable()

§ uDMAErrorStatusGet()

§ uDMAErrorStatusClear()

§ uDMAChannelEnable()

§ uDMAChannelDisable()

§ uDMAChannelIsEnabled()

§ uDMAControlBaseSet()

§ uDMAControlBaseGet()

§ uDMAControlAlternateBaseGet()

§ uDMAChannelRequest()

§ uDMAChannelAttributeEnable()

§ uDMAChannelAttributeDisable()

§ uDMAChannelAttributeGet()

§ uDMAChannelControlSet()

§ uDMAChannelTransferSet()

§ uDMAChannelScatterGatherSet()

§ uDMAChannelSizeGet()

§ uDMAChannelModeGet()

§ uDMAIntRegister()

§ uDMAIntUnregister()

§ uDMAChannelAssign()