CC3200 Peripheral Driver Library User's Guide: UDMA_Micro_Direct_Memory_Access_api

CC3200 Peripheral Driver

CC3200 Peripheral Driver Library User's Guide  1.2.0
UDMA_Micro_Direct_Memory_Access_api

Data Structures

struct  tDMAControlTable
 

Functions

void uDMAEnable (void)
 
void uDMADisable (void)
 
unsigned long uDMAErrorStatusGet (void)
 
void uDMAErrorStatusClear (void)
 
void uDMAChannelEnable (unsigned long ulChannelNum)
 
void uDMAChannelDisable (unsigned long ulChannelNum)
 
tBoolean uDMAChannelIsEnabled (unsigned long ulChannelNum)
 
void uDMAControlBaseSet (void *pControlTable)
 
void * uDMAControlBaseGet (void)
 
void * uDMAControlAlternateBaseGet (void)
 
void uDMAChannelRequest (unsigned long ulChannelNum)
 
void uDMAChannelAttributeEnable (unsigned long ulChannelNum, unsigned long ulAttr)
 
void uDMAChannelAttributeDisable (unsigned long ulChannelNum, unsigned long ulAttr)
 
unsigned long uDMAChannelAttributeGet (unsigned long ulChannelNum)
 
void uDMAChannelControlSet (unsigned long ulChannelStructIndex, unsigned long ulControl)
 
void uDMAChannelTransferSet (unsigned long ulChannelStructIndex, unsigned long ulMode, void *pvSrcAddr, void *pvDstAddr, unsigned long ulTransferSize)
 
void uDMAChannelScatterGatherSet (unsigned long ulChannelNum, unsigned ulTaskCount, void *pvTaskList, unsigned long ulIsPeriphSG)
 
unsigned long uDMAChannelSizeGet (unsigned long ulChannelStructIndex)
 
unsigned long uDMAChannelModeGet (unsigned long ulChannelStructIndex)
 
void uDMAIntRegister (unsigned long ulIntChannel, void(*pfnHandler)(void))
 
void uDMAIntUnregister (unsigned long ulIntChannel)
 
unsigned long uDMAIntStatus (void)
 
void uDMAIntClear (unsigned long ulChanMask)
 
void uDMAChannelAssign (unsigned long ulMapping)
 

Detailed Description

Function Documentation

void uDMAChannelAssign ( unsigned long  ulMapping)

Assigns a peripheral mapping for a uDMA channel.

Parameters
ulMappingis 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 ulMapping 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 for a particular device.

Note
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.
Returns
None.
void uDMAChannelAttributeDisable ( unsigned long  ulChannelNum,
unsigned long  ulAttr 
)

Disables attributes of a uDMA channel.

Parameters
ulChannelNumis the channel to configure.
ulAttris a combination of attributes for the channel.

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

The ulAttr 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.
void uDMAChannelAttributeEnable ( unsigned long  ulChannelNum,
unsigned long  ulAttr 
)

Enables attributes of a uDMA channel.

Parameters
ulChannelNumis the channel to configure.
ulAttris a combination of attributes for the channel.

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

The ulAttr 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.
unsigned long uDMAChannelAttributeGet ( unsigned long  ulChannelNum)

Gets the enabled attributes of a uDMA channel.

Parameters
ulChannelNumis 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.
void uDMAChannelControlSet ( unsigned long  ulChannelStructIndex,
unsigned long  ulControl 
)

Sets the control parameters for a uDMA channel control structure.

Parameters
ulChannelStructIndexis the logical OR of the uDMA channel number with UDMA_PRI_SELECT or UDMA_ALT_SELECT.
ulControlis 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 ulChannelStructIndex 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 ulControl 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 halfwords, 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 halfwords, 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.
void uDMAChannelDisable ( unsigned long  ulChannelNum)

Disables a uDMA channel for operation.

Parameters
ulChannelNumis 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.
void uDMAChannelEnable ( unsigned long  ulChannelNum)

Enables a uDMA channel for operation.

Parameters
ulChannelNumis 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.
tBoolean uDMAChannelIsEnabled ( unsigned long  ulChannelNum)

Checks if a uDMA channel is enabled for operation.

Parameters
ulChannelNumis 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.
unsigned long uDMAChannelModeGet ( unsigned long  ulChannelStructIndex)

Gets the transfer mode for a uDMA channel control structure.

Parameters
ulChannelStructIndexis 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.
void uDMAChannelRequest ( unsigned long  ulChannelNum)

Requests a uDMA channel to start a transfer.

Parameters
ulChannelNumis 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.
void uDMAChannelScatterGatherSet ( unsigned long  ulChannelNum,
unsigned  ulTaskCount,
void *  pvTaskList,
unsigned long  ulIsPeriphSG 
)

Configures a uDMA channel for scatter-gather mode.

Parameters
ulChannelNumis the uDMA channel number.
ulTaskCountis the number of scatter-gather tasks to execute.
pvTaskListis a pointer to the beginning of the scatter-gather task list.
ulIsPeriphSGis 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 ulTaskCount 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.
unsigned long uDMAChannelSizeGet ( unsigned long  ulChannelStructIndex)

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

Parameters
ulChannelStructIndexis 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.
void uDMAChannelTransferSet ( unsigned long  ulChannelStructIndex,
unsigned long  ulMode,
void *  pvSrcAddr,
void *  pvDstAddr,
unsigned long  ulTransferSize 
)

Sets the transfer parameters for a uDMA channel control structure.

Parameters
ulChannelStructIndexis the logical OR of the uDMA channel number with either UDMA_PRI_SELECT or UDMA_ALT_SELECT.
ulModeis the type of uDMA transfer.
pvSrcAddris the source address for the transfer.
pvDstAddris the destination address for the transfer.
ulTransferSizeis the number of data items to transfer.

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

The ulChannelStructIndex 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 ulMode 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 ulTransferSize parameter is the number of data items, not the number of bytes. The value of this parameter should not exceed 1024.

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.
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.
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.
void uDMAControlBaseSet ( void *  pControlTable)

Sets the base address for the channel control table.

Parameters
pControlTableis 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 introductory text and the microcontroller datasheet for more information about the channel control table.

Returns
None.
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.
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.
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.
unsigned long 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.
void uDMAIntClear ( unsigned long  ulChanMask)

Clears uDMA interrupt status.

Parameters
ulChanMaskis a 32-bit mask with one bit for each uDMA channel.

This function clears bits in the uDMA interrupt status register according to which bits are set in ulChanMask. There is one bit for each channel. If a a bit is set in ulChanMask, then that corresponding channel's interrupt status is cleared (if it was set).

Note
This function is only available on devices that have the DMA Channel Interrupt Status Register (DMACHIS). Please consult the data sheet for your part.
Returns
None.
void uDMAIntRegister ( unsigned long  ulIntChannel,
void(*)(void)  pfnHandler 
)

Registers an interrupt handler for the uDMA controller.

Parameters
ulIntChannelidentifies which uDMA interrupt is to be registered.
pfnHandleris 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 ulIntChannel parameter should be one of the following:

  • UDMA_INT_SW to register an interrupt handler to process interrupts from the uDMA software channel (UDMA_CHANNEL_SW)
  • UDMA_INT_ERR 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.
unsigned long uDMAIntStatus ( void  )

Gets the uDMA controller channel interrupt status.

This function is used to get the interrupt status of the uDMA controller. The returned value is a 32-bit bit mask that indicates which channels are requesting an interrupt. This function can be used from within an interrupt handler to determine or confirm which uDMA channel has requested an interrupt.

Note
This function is only available on devices that have the DMA Channel Interrupt Status Register (DMACHIS). Please consult the data sheet for your part.
Returns
Returns a 32-bit mask which indicates requesting uDMA channels. There is a bit for each channel and a 1 indicates that the channel is requesting an interrupt. Multiple bits can be set.
void uDMAIntUnregister ( unsigned long  ulIntChannel)

Unregisters an interrupt handler for the uDMA controller.

Parameters
ulIntChannelidentifies which uDMA interrupt to unregister.

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

See also
IntRegister() for important information about registering interrupt handlers.
Returns
None.
Generated on Thu Feb 18 2016 13:22:02 for CC3200 Peripheral Driver Library User's Guide by   doxygen 1.8.11