In many cases, the descriptor configuration only has to be done once if re-using the channel for the same type of DMA cycles later.

To activate the DMA cycle, use the respective DMA_Activate...() function.

For ping-pong DMA cycles, use DMA_RefreshPingPong() from the callback to prepare the completed descriptor for reuse. Notice that the refresh must be done prior to the other active descriptor completes, otherwise the ping-pong DMA cycle will halt.

Typedef Documentation

primary - Indicates if callback is invoked for completion of primary (true) or alternate (false) descriptor. Mainly useful for ping-pong DMA cycles, to know which descriptor to refresh.

user - User definable reference that may be used to pass information to be used by the callback handler. If used, referenced data must be valid at the point when the interrupt handler invokes callback. If callback changes any data in the provided user structure, remember that those changes are done in interrupt context and proper protection of data may be required.

Prior to activating the DMA cycle, the channel and descriptor to be used must have been properly configured.

Note

If using this function on a channel already activated and in use by the DMA controller, the behavior is undefined.

Parameters

[in]

channel

The DMA channel to activate the DMA cycle for.

[in]

primary

true - activate using the primary descriptor

false - activate using an alternate descriptor

[in]

useBurst

The burst feature is only used on peripherals supporting DMA bursts. Bursts must not be used if the total length (as given by nMinus1) is less than the arbitration rate configured for the descriptor. See the reference manual for more details on burst usage.

[in]

dst

An address to a start location to transfer data to. If NULL, leave setting in descriptor as is from a previous activation.

[in]

src

An address to a start location to transfer data from. If NULL, leave setting in descriptor as is from a previous activation.

[in]

nMinus1

A number of DMA transfer elements (minus 1) to transfer (<= 1023). The size of the DMA transfer element (1, 2 or 4 bytes) is configured with DMA_CfgDescr().

Prior to activating the DMA cycle, the channel and both descriptors must have been properly configured. The primary descriptor is always the first descriptor to be used by the DMA controller.

Note

If using this function on a channel already activated and in use by the DMA controller, the behavior is undefined.

Parameters

[in]

channel

The DMA channel to activate DMA cycle for.

[in]

useBurst

The burst feature is only used on peripherals supporting DMA bursts. Bursts must not be used if the total length (as given by nMinus1) is less than the arbitration rate configured for the descriptors. See the reference manual for more details on burst usage. Notice that this setting is used for both the primary and alternate descriptors.

[in]

primDst

An address to a start location to transfer data to, for the primary descriptor. If NULL, leave setting in descriptor as is from a previous activation.

[in]

primSrc

An address to a start location to transfer data from, for the primary descriptor. If NULL, leave setting in the descriptor as is from a previous activation.

[in]

primNMinus1

A number of DMA transfer elements (minus 1) to transfer (<= 1023), for primary descriptor. The size of the DMA transfer element (1, 2 or 4 bytes) is configured with DMA_CfgDescr().

[in]

altDst

An address to a start location to transfer data to, for an alternate descriptor. If NULL, leave setting in descriptor as is from a previous activation.

[in]

altSrc

An address to a start location to transfer data from, for an alternate descriptor. If NULL, leave setting in descriptor as is from a previous activation.

[in]

altNMinus1

A number of DMA transfer elements (minus 1) to transfer (<= 1023), for an alternate descriptor. The size of the DMA transfer element (1, 2 or 4 bytes) is configured with DMA_CfgDescr().

Activate the DMA scatter-gather cycle (used for either memory-peripheral or memory-memory transfers).

Prior to activating the DMA cycle, the array with alternate descriptors must have been properly configured. This function can be reused without reconfiguring the alternate descriptors, as long as count is the same.

Note

If using this function on a channel already activated and in use by the DMA controller, the behavior is undefined.

Parameters

[in]

channel

The DMA channel to activate DMA cycle for.

[in]

useBurst

The burst feature is only used on peripherals supporting DMA bursts (this parameter is ignored for memory scatter-gather cycles). This parameter determines if bursts should be enabled during DMA transfers using the alternate descriptors. Bursts must not be used if the total length (as given by nMinus1 for the alternate descriptor) is less than the arbitration rate configured for the descriptor. See the reference manual for more details on burst usage.

[in,out]

altDescr

A pointer to a start of an array with prepared alternate descriptors. The last descriptor will have its cycle control type reprogrammed to a basic type.

[in]

count

A number of alternate descriptors in altDescr array. The maximum number of alternate descriptors is 256.

Configure an alternate DMA descriptor for use with scatter-gather DMA cycles.

In scatter-gather mode, the alternate descriptors are located in one contiguous memory area. Each of the alternate descriptors must be fully configured prior to starting the scatter-gather DMA cycle.

The DMA cycle is not activated by this function. See DMA_ActivateScatterGather() to activate the DMA cycle. In some cases, the alternate configuration only has to be done once and all subsequent transfers may be activated with the activate function.

This function resets and prepares the DMA controller for use. Although it may be used several times, it is normally only used during system initialization. If reused during a normal operation, any ongoing DMA transfers will be aborted. When complete, the DMA controller is in an enabled state.

Note

Must be invoked before using the DMA controller.

Parameters

[in]

init

A pointer to a structure containing the DMA initialization information.

If using the default interrupt vector table setup provided, this function is automatically placed in the IRQ table due to weak linking. If taking control over the interrupt vector table in some other way, this interrupt handler must be installed to support callback actions.

For the user to implement a custom IRQ handler or run without a DMA IRQ handler, define EXCLUDE_DEFAULT_DMA_IRQ_HANDLER with a #define statement or with the compiler option -D.

During a ping-pong DMA cycle, the DMA controller automatically alternates between the primary and alternate descriptors, when completing use of a descriptor. While the other descriptor is in use by the DMA controller, the software should refresh the completed descriptor. This is typically done from the callback defined for the ping-pong cycle.

Parameters

[in]

channel

The DMA channel to refresh the ping-pong descriptor for.

[in]

primary

true - refresh the primary descriptor

false - refresh an alternate descriptor

[in]

useBurst

The burst feature is only used on peripherals supporting DMA bursts. Bursts must not be used if the total length (as given by nMinus1) is less than the arbitration rate configured for the descriptor. See the reference manual for more details on burst usage.

[in]

dst

An address to a start location to transfer data to. If NULL, leave setting in descriptor as is.

[in]

src

An address to a start location to transfer data from. If NULL, leave setting in descriptor as is.

[in]

nMinus1

A number of DMA transfer elements (minus 1) to transfer (<= 1023). The size of the DMA transfer element (1, 2 or 4 bytes) is configured with DMA_CfgDescr().

[in]

stop

Indicate that the DMA ping-pong cycle stops when done using this descriptor.