EFM32 Gecko Software Documentation
efm32g-doc-5.1.2
|
DMADRV Direct Memory Access Driver.
The DMADRV driver makes it possible to write code using DMA which will work regardless of the type of DMA controller on the underlying microcontroller. It will also make it possible to use DMA in several modules, without the modules knowing of each others existence. The driver does not preclude use of the native emlib API of the underlying DMA controller, on the contrary, this will often result in more efficient code and is a necessity when doing complex DMA operations. The housekeeping functions of this driver will be valuable even in this use-case.
The source files for the DMA driver library resides in the emdrv/dmadrv folder, and are named dmadrv.c and dmadrv.h.
Some properties of the DMADRV driver are compile-time configurable. These properties are stored in a file named dmadrv_config.h. A template for this file, containing default values, resides in the emdrv/config folder. Currently the configuration options are:
Both configuration options will help reduce the drivers ram memory footprint.
To configure DMADRV, provide your own configuration file. Here is a sample dmadrv_config.h file:
#ifndef __SILICON_LABS_DMADRV_CONFIG_H__ #define __SILICON_LABS_DMADRV_CONFIG_H__ // DMADRV DMA interrupt priority configuration option. // Set DMA interrupt priority. Range is 0..7, 0 is highest priority. #define EMDRV_DMADRV_DMA_IRQ_PRIORITY 4 // DMADRV channel count configuration option. // Number of DMA channels to support. A lower DMA channel count will reduce // ram memory footprint. #define EMDRV_DMADRV_DMA_CH_COUNT 4 // DMADRV native API configuration option. // Use the native emlib api of the DMA controller, but still use DMADRV // housekeeping functions as AllocateChannel/FreeChannel etc. #define EMDRV_DMADRV_USE_NATIVE_API #endif
This section contain brief descriptions of the functions in the API. You will find detailed information on input and output parameters and return values by clicking on the hyperlinked function names. Most functions return an error code, ECODE_EMDRV_DMADRV_OK is returned on success, see ecode.h and dmadrv.h for other error codes.
Your application code must include one header file: dmadrv.h.
DMADRV_Init(), DMADRV_DeInit()
These functions initializes or deinitializes the DMADRV driver. Typically DMADRV_Init() is called once in your startup code.
DMADRV_AllocateChannel(), DMADRV_FreeChannel()
DMA channel reserve and release functions. It is recommended that application code check that DMADRV_AllocateChannel() returns ECODE_EMDRV_DMADRV_OK before starting a DMA transfer.
DMADRV_MemoryPeripheral()
Start a DMA transfer from memory to a peripheral.
DMADRV_PeripheralMemory()
Start a DMA transfer from a peripheral to memory.
DMADRV_MemoryPeripheralPingPong()
Start a DMA ping-pong transfer from memory to a peripheral.
DMADRV_PeripheralMemoryPingPong()
Start a DMA ping-pong transfer from a peripheral to memory.
DMADRV_LdmaStartTransfer()
Start a DMA transfer on a LDMA controller. This function can only be used when configuration option EMDRV_DMADRV_USE_NATIVE_API is defined. It is a wrapper around similar emlib ldma function, but adds support for completion callback and user defined callback function parameter.
DMADRV_StopTransfer()
Stop an ongoing DMA transfer.
DMADRV_TransferActive()
Check if a transfer is ongoing.
DMADRV_TransferCompletePending()
Check if a transfer completion is pending.
DMADRV_TransferDone()
Check if a transfer has completed.
DMADRV_TransferRemainingCount()
Get number of items remaining in a transfer.
Transfer a text string to USART1.
#include "dmadrv.h" char str[] = "Hello DMA !"; unsigned int channel; int main( void ) { // Initialize DMA. DMADRV_Init(); // Request a DMA channel. DMADRV_AllocateChannel( &channel, NULL ); // Start the DMA transfer. DMADRV_MemoryPeripheral( channel, dmadrvPeripheralSignal_USART1_TXBL, (void*)&(USART1->TXDATA), str, true, sizeof( str ), dmadrvDataSize1, NULL, NULL ); return 0; }
Macros | |
#define | DMADRV_MAX_XFER_COUNT ((int)((_DMA_CTRL_N_MINUS_1_MASK >> _DMA_CTRL_N_MINUS_1_SHIFT) + 1)) |
Maximum length of one DMA transfer. | |
#define | ECODE_EMDRV_DMADRV_ALREADY_FREED ( ECODE_EMDRV_DMADRV_BASE | 0x00000006 ) |
DMA channel was free. | |
#define | ECODE_EMDRV_DMADRV_ALREADY_INITIALIZED ( ECODE_EMDRV_DMADRV_BASE | 0x00000003 ) |
DMA has already been initialized. | |
#define | ECODE_EMDRV_DMADRV_CH_NOT_ALLOCATED ( ECODE_EMDRV_DMADRV_BASE | 0x00000007 ) |
The channel is not reserved. | |
#define | ECODE_EMDRV_DMADRV_CHANNELS_EXHAUSTED ( ECODE_EMDRV_DMADRV_BASE | 0x00000004 ) |
No DMA channels available. | |
#define | ECODE_EMDRV_DMADRV_IN_USE ( ECODE_EMDRV_DMADRV_BASE | 0x00000005 ) |
DMA is in use. | |
#define | ECODE_EMDRV_DMADRV_NOT_INITIALIZED ( ECODE_EMDRV_DMADRV_BASE | 0x00000002 ) |
DMA is not initialized. | |
#define | ECODE_EMDRV_DMADRV_OK ( ECODE_OK ) |
Success return value. | |
#define | ECODE_EMDRV_DMADRV_PARAM_ERROR ( ECODE_EMDRV_DMADRV_BASE | 0x00000001 ) |
Illegal input parameter. | |
Typedefs | |
typedef bool(* | DMADRV_Callback_t) (unsigned int channel, unsigned int sequenceNo, void *userParam) |
DMADRV transfer completion callback function. More... | |
Functions | |
Ecode_t | DMADRV_AllocateChannel (unsigned int *channelId, void *capabilities) |
Allocate (reserve) a DMA channel. More... | |
Ecode_t | DMADRV_DeInit (void) |
Deinitialize DMADRV. More... | |
Ecode_t | DMADRV_FreeChannel (unsigned int channelId) |
Free an allocate (reserved) DMA channel. More... | |
Ecode_t | DMADRV_Init (void) |
Initialize DMADRV. More... | |
Ecode_t | DMADRV_MemoryPeripheral (unsigned int channelId, DMADRV_PeripheralSignal_t peripheralSignal, void *dst, void *src, bool srcInc, int len, DMADRV_DataSize_t size, DMADRV_Callback_t callback, void *cbUserParam) |
Start a memory to peripheral DMA transfer. More... | |
Ecode_t | DMADRV_MemoryPeripheralPingPong (unsigned int channelId, DMADRV_PeripheralSignal_t peripheralSignal, void *dst, void *src0, void *src1, bool srcInc, int len, DMADRV_DataSize_t size, DMADRV_Callback_t callback, void *cbUserParam) |
Start a memory to peripheral ping-pong DMA transfer. More... | |
Ecode_t | DMADRV_PauseTransfer (unsigned int channelId) |
Pause an ongoing DMA transfer. More... | |
Ecode_t | DMADRV_PeripheralMemory (unsigned int channelId, DMADRV_PeripheralSignal_t peripheralSignal, void *dst, void *src, bool dstInc, int len, DMADRV_DataSize_t size, DMADRV_Callback_t callback, void *cbUserParam) |
Start a peripheral to memory DMA transfer. More... | |
Ecode_t | DMADRV_PeripheralMemoryPingPong (unsigned int channelId, DMADRV_PeripheralSignal_t peripheralSignal, void *dst0, void *dst1, void *src, bool dstInc, int len, DMADRV_DataSize_t size, DMADRV_Callback_t callback, void *cbUserParam) |
Start a peripheral to memory ping-pong DMA transfer. More... | |
Ecode_t | DMADRV_ResumeTransfer (unsigned int channelId) |
Resume an ongoing DMA transfer. More... | |
Ecode_t | DMADRV_StopTransfer (unsigned int channelId) |
Stop an ongoing DMA transfer. More... | |
Ecode_t | DMADRV_TransferActive (unsigned int channelId, bool *active) |
Check if a transfer is running. More... | |
Ecode_t | DMADRV_TransferCompletePending (unsigned int channelId, bool *pending) |
Check if a transfer complete is pending. More... | |
Ecode_t | DMADRV_TransferDone (unsigned int channelId, bool *done) |
Check if a transfer has completed. More... | |
Ecode_t | DMADRV_TransferRemainingCount (unsigned int channelId, int *remaining) |
Get number of items remaining in a transfer. More... | |
typedef bool(* DMADRV_Callback_t) (unsigned int channel, unsigned int sequenceNo, void *userParam) |
DMADRV transfer completion callback function.
The callback function is called when a transfer has completed.
[in] | channel | The DMA channel number. |
[in] | sequenceNo | The number of times the callback had been called. Useful on long chains of linked transfers or on endless ping-pong type transfers. |
[in] | userParam | Optional user parameter supplied on DMA invocation. |
enum DMADRV_Datasize_t |
Peripherals that can trigger UDMA transfers.
Ecode_t DMADRV_AllocateChannel | ( | unsigned int * | channelId, |
void * | capabilities | ||
) |
Allocate (reserve) a DMA channel.
[out] | channelId | The channel Id assigned by DMADRV. |
[in] | capabilities | Not used. |
Definition at line 131 of file dmadrv.c.
References CORE_DECLARE_IRQ_STATE, CORE_ENTER_ATOMIC, CORE_EXIT_ATOMIC, ECODE_EMDRV_DMADRV_CHANNELS_EXHAUSTED, ECODE_EMDRV_DMADRV_NOT_INITIALIZED, ECODE_EMDRV_DMADRV_OK, ECODE_EMDRV_DMADRV_PARAM_ERROR, and initialized.
Referenced by MIC_init(), and SPIDRV_Init().
Ecode_t DMADRV_DeInit | ( | void | ) |
Deinitialize DMADRV.
If no DMA channels are currently allocated, it will disable DMA hardware and mask associated interrupts.
Definition at line 177 of file dmadrv.c.
References _DMA_CONFIG_RESETVALUE, _DMA_IEN_RESETVALUE, CMU_ClockEnable(), cmuClock_DMA, CORE_DECLARE_IRQ_STATE, CORE_ENTER_ATOMIC, CORE_EXIT_ATOMIC, DMA, DMA_IRQn, ECODE_EMDRV_DMADRV_IN_USE, ECODE_EMDRV_DMADRV_OK, and initialized.
Referenced by SPIDRV_DeInit(), and UARTDRV_DeInit().
Ecode_t DMADRV_FreeChannel | ( | unsigned int | channelId | ) |
Free an allocate (reserved) DMA channel.
[in] | channelId | The channel Id to free. |
Definition at line 225 of file dmadrv.c.
References CORE_DECLARE_IRQ_STATE, CORE_ENTER_ATOMIC, CORE_EXIT_ATOMIC, ECODE_EMDRV_DMADRV_ALREADY_FREED, ECODE_EMDRV_DMADRV_NOT_INITIALIZED, ECODE_EMDRV_DMADRV_OK, ECODE_EMDRV_DMADRV_PARAM_ERROR, and initialized.
Referenced by MIC_deInit(), SPIDRV_DeInit(), and UARTDRV_DeInit().
Ecode_t DMADRV_Init | ( | void | ) |
Initialize DMADRV.
The DMA hw is initialized.
Definition at line 262 of file dmadrv.c.
References CORE_DECLARE_IRQ_STATE, CORE_ENTER_ATOMIC, CORE_EXIT_ATOMIC, DMA_Init(), DMA_IRQn, ECODE_EMDRV_DMADRV_ALREADY_INITIALIZED, ECODE_EMDRV_DMADRV_OK, ECODE_EMDRV_DMADRV_PARAM_ERROR, and initialized.
Referenced by MIC_init(), SPIDRV_Init(), UARTDRV_InitLeuart(), and UARTDRV_InitUart().
Ecode_t DMADRV_MemoryPeripheral | ( | unsigned int | channelId, |
DMADRV_PeripheralSignal_t | peripheralSignal, | ||
void * | dst, | ||
void * | src, | ||
bool | srcInc, | ||
int | len, | ||
DMADRV_DataSize_t | size, | ||
DMADRV_Callback_t | callback, | ||
void * | cbUserParam | ||
) |
Start a memory to peripheral DMA transfer.
[in] | channelId | Not used |
[in] | peripheralSignal | Selects which peripheral/peripheralsignal to use. |
[in] | dst | Destination (peripheral register) memory address. |
[in] | src | Source memory address. |
[in] | srcInc | Set to true to enable source address increment (increment is according to size parameter). |
[in] | len | Number if items (of size size) to transfer. |
[in] | size | Item size, byte, halfword or word. |
[in] | callback | Function to call on dma completion, use NULL if not needed. |
[in] | cbUserParam | Optional user parameter to feed to the callback function. Use NULL if not needed. |
Ecode_t DMADRV_MemoryPeripheralPingPong | ( | unsigned int | channelId, |
DMADRV_PeripheralSignal_t | peripheralSignal, | ||
void * | dst, | ||
void * | src0, | ||
void * | src1, | ||
bool | srcInc, | ||
int | len, | ||
DMADRV_DataSize_t | size, | ||
DMADRV_Callback_t | callback, | ||
void * | cbUserParam | ||
) |
Start a memory to peripheral ping-pong DMA transfer.
[in] | channelId | Not used |
[in] | peripheralSignal | Selects which peripheral/peripheralsignal to use. |
[in] | dst | Destination (peripheral register) memory address. |
[in] | src0 | Source memory address of first (ping) buffer. |
[in] | src1 | Source memory address of second (pong) buffer. |
[in] | srcInc | Set to true to enable source address increment (increment is according to size parameter). |
[in] | len | Number if items (of size size) to transfer. |
[in] | size | Item size, byte, halfword or word. |
[in] | callback | Function to call on dma completion, use NULL if not needed. |
[in] | cbUserParam | Optional user parameter to feed to the callback function. Use NULL if not needed. |
Ecode_t DMADRV_PauseTransfer | ( | unsigned int | channelId | ) |
Pause an ongoing DMA transfer.
[in] | channelId | The channel Id of the transfer to pause. |
Definition at line 645 of file dmadrv.c.
References DMA_ChannelRequestEnable(), ECODE_EMDRV_DMADRV_CH_NOT_ALLOCATED, ECODE_EMDRV_DMADRV_NOT_INITIALIZED, ECODE_EMDRV_DMADRV_OK, ECODE_EMDRV_DMADRV_PARAM_ERROR, and initialized.
Referenced by UARTDRV_PauseTransmit().
Ecode_t DMADRV_PeripheralMemory | ( | unsigned int | channelId, |
DMADRV_PeripheralSignal_t | peripheralSignal, | ||
void * | dst, | ||
void * | src, | ||
bool | dstInc, | ||
int | len, | ||
DMADRV_DataSize_t | size, | ||
DMADRV_Callback_t | callback, | ||
void * | cbUserParam | ||
) |
Start a peripheral to memory DMA transfer.
[in] | channelId | Not used |
[in] | peripheralSignal | Selects which peripheral/peripheralsignal to use. |
[in] | dst | Destination memory address. |
[in] | src | Source memory (peripheral register) address. |
[in] | dstInc | Set to true to enable destination address increment (increment is according to size parameter). |
[in] | len | Number if items (of size size) to transfer. |
[in] | size | Item size, byte, halfword or word. |
[in] | callback | Function to call on dma completion, use NULL if not needed. |
[in] | cbUserParam | Optional user parameter to feed to the callback function. Use NULL if not needed. |
Definition at line 539 of file dmadrv.c.
Referenced by MIC_start().
Ecode_t DMADRV_PeripheralMemoryPingPong | ( | unsigned int | channelId, |
DMADRV_PeripheralSignal_t | peripheralSignal, | ||
void * | dst0, | ||
void * | dst1, | ||
void * | src, | ||
bool | dstInc, | ||
int | len, | ||
DMADRV_DataSize_t | size, | ||
DMADRV_Callback_t | callback, | ||
void * | cbUserParam | ||
) |
Start a peripheral to memory ping-pong DMA transfer.
[in] | channelId | Not used |
[in] | peripheralSignal | Selects which peripheral/peripheralsignal to use. |
[in] | dst0 | Destination memory address of first (ping) buffer. |
[in] | dst1 | Destination memory address of second (pong) buffer. |
[in] | src | Source memory (peripheral register) address. |
[in] | dstInc | Set to true to enable destination address increment (increment is according to size parameter). |
[in] | len | Number if items (of size size) to transfer. |
[in] | size | Item size, byte, halfword or word. |
[in] | callback | Function to call on dma completion, use NULL if not needed. |
[in] | cbUserParam | Optional user parameter to feed to the callback function. Use NULL if not needed. |
Ecode_t DMADRV_ResumeTransfer | ( | unsigned int | channelId | ) |
Resume an ongoing DMA transfer.
[in] | channelId | The channel Id of the transfer to resume. |
Definition at line 682 of file dmadrv.c.
References DMA_ChannelRequestEnable(), ECODE_EMDRV_DMADRV_CH_NOT_ALLOCATED, ECODE_EMDRV_DMADRV_NOT_INITIALIZED, ECODE_EMDRV_DMADRV_OK, ECODE_EMDRV_DMADRV_PARAM_ERROR, and initialized.
Referenced by UARTDRV_ResumeTransmit().
Ecode_t DMADRV_StopTransfer | ( | unsigned int | channelId | ) |
Stop an ongoing DMA transfer.
[in] | channelId | The channel Id of the transfer to stop. |
Definition at line 719 of file dmadrv.c.
References DMA_ChannelEnable(), ECODE_EMDRV_DMADRV_CH_NOT_ALLOCATED, ECODE_EMDRV_DMADRV_NOT_INITIALIZED, ECODE_EMDRV_DMADRV_OK, ECODE_EMDRV_DMADRV_PARAM_ERROR, and initialized.
Referenced by SPIDRV_AbortTransfer(), SPIDRV_DeInit(), and UARTDRV_Abort().
Ecode_t DMADRV_TransferActive | ( | unsigned int | channelId, |
bool * | active | ||
) |
Check if a transfer is running.
[in] | channelId | The channel Id of the transfer to check. |
[out] | active | True if transfer is running, false otherwise. |
Definition at line 759 of file dmadrv.c.
References DMA_ChannelEnabled(), ECODE_EMDRV_DMADRV_CH_NOT_ALLOCATED, ECODE_EMDRV_DMADRV_NOT_INITIALIZED, ECODE_EMDRV_DMADRV_OK, ECODE_EMDRV_DMADRV_PARAM_ERROR, and initialized.
Referenced by UARTDRV_PauseTransmit(), and UARTDRV_ResumeTransmit().
Ecode_t DMADRV_TransferCompletePending | ( | unsigned int | channelId, |
bool * | pending | ||
) |
Check if a transfer complete is pending.
Will check channel interrupt flag. This assumes that the DMA is configured to giva a completion interrupt.
[in] | channelId | The channel Id of the transfer to check. |
[out] | pending | True if a transfer complete is pending, false otherwise. |
Definition at line 811 of file dmadrv.c.
References DMA, ECODE_EMDRV_DMADRV_CH_NOT_ALLOCATED, ECODE_EMDRV_DMADRV_NOT_INITIALIZED, ECODE_EMDRV_DMADRV_OK, ECODE_EMDRV_DMADRV_PARAM_ERROR, and initialized.
Ecode_t DMADRV_TransferDone | ( | unsigned int | channelId, |
bool * | done | ||
) |
Check if a transfer has completed.
[in] | channelId | The channel Id of the transfer to check. |
[out] | done | True if a transfer has completed, false otherwise. |
Definition at line 864 of file dmadrv.c.
References _DMA_CTRL_N_MINUS_1_MASK, _DMA_CTRL_N_MINUS_1_SHIFT, CORE_ATOMIC_SECTION, DMA, ECODE_EMDRV_DMADRV_CH_NOT_ALLOCATED, ECODE_EMDRV_DMADRV_NOT_INITIALIZED, ECODE_EMDRV_DMADRV_OK, ECODE_EMDRV_DMADRV_PARAM_ERROR, and initialized.
Ecode_t DMADRV_TransferRemainingCount | ( | unsigned int | channelId, |
int * | remaining | ||
) |
Get number of items remaining in a transfer.
[in] | channelId | The channel Id of the transfer to check. |
[out] | remaining | Number of items remaining in the transfer. |
Definition at line 930 of file dmadrv.c.
References _DMA_CTRL_N_MINUS_1_MASK, _DMA_CTRL_N_MINUS_1_SHIFT, CORE_ATOMIC_SECTION, DMA, ECODE_EMDRV_DMADRV_CH_NOT_ALLOCATED, ECODE_EMDRV_DMADRV_NOT_INITIALIZED, ECODE_EMDRV_DMADRV_OK, ECODE_EMDRV_DMADRV_PARAM_ERROR, and initialized.
Referenced by SPIDRV_AbortTransfer(), UARTDRV_Abort(), UARTDRV_GetReceiveStatus(), and UARTDRV_GetTransmitStatus().