DMADRV - DMA Driver#

Direct Memory Access Driver.

Introduction#

The DMADRV driver supports writing code using DMA which will work regardless of the type of the DMA controller on the underlying microcontroller. Additionally, DMA can be used in several modules that are completely unaware of each other. The driver does not preclude use of the native emlib or peripheral API of the underlying DMA controller. On the contrary, it will often result in more efficient code and is necessary for complex DMA operations. The housekeeping functions of this driver are valuable even in this use-case.

The dmadrv.c and dmadrv.h source files are in the emdrv/dmadrv folder.

Note

DMA transfer completion callback functions are called from within the DMA interrupt handler. On versions of the DMA controller with one interrupt per channel, the callback function is called from its respective channel interrupt handler.

Configuration Options#

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, is in the emdrv/config folder. IC specific versions of dmadrv_config.h files are available in config/sx_xch directories. Currently the configuration options are as follows:

The interrupt priority of the DMA peripheral.
A number of DMA channels to support.
Use the native emlib/peripheral API belonging to the underlying DMA hardware in combination with the DMADRV API.

Both configuration options will help reduce the driver's RAM footprint.

To configure DMADRV, provide a custom configuration file. This is an example 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 the highest priority.
#define EMDRV_DMADRV_DMA_IRQ_PRIORITY 4

  // DMADRV channel count configuration option.
  // A number of DMA channels to support. A lower DMA channel count will reduce
  // RAM footprint.
#define EMDRV_DMADRV_DMA_CH_COUNT 4

#endif

The API#

This section contains brief descriptions of the API functions. For more information about input and output parameters and return values, click on the hyperlinked function names. Most functions return an error code, ECODE_EMDRV_DMADRV_OK is returned on success, see ECODE - Error Codes and Error Codes for other error codes.

The application code must include dmadrv.h header file.

DMADRV_Init(), DMADRV_DeInit()
These functions initialize or deinitialize the DMADRV driver. Typically, DMADRV_Init() is called once in the 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 an LDMA controller.

DMADRV_PauseTransfer()
Pause an ongoing DMA transfer.

DMADRV_ResumeTransfer()
Resume paused DMA transfer.

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.

Example#

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;
  }

Modules#

Error Codes

Typedefs#

typedef bool(*

DMADRV_Callback_t)(unsigned int channel, unsigned int sequenceNo, void *userParam)

DMADRV transfer completion callback function.

[in]	channel	The DMA channel number.
[in]	sequenceNo	The number of times the callback was called. Useful on long chains of linked transfers or on endless ping-pong type transfers.
[in]	userParam	Optional user parameter supplied on DMA invocation.

[out]	channelId	The channel ID assigned by DMADRV.
[in]	capabilities	Not used.

[in]	channelId	The channel ID to use for the transfer.
[in]	peripheralSignal	Selects which peripheral/peripheralsignal to use.
[in]	dst	A destination (peripheral register) memory address.
[in]	src	A source memory address.
[in]	srcInc	Set to true to enable source address increment (increments according to size parameter).
[in]	len	A number of items (of size size) to transfer.
[in]	size	An item size, byte, halfword or word.
[in]	callback	A function to call on DMA completion, use NULL if not needed.
[in]	cbUserParam	An optional user parameter to feed to the callback function. Use NULL if not needed.

[in]	channelId	The channel ID to use.
[in]	transfer	A DMA transfer configuration data structure.
[in]	descriptor	A DMA transfer descriptor, can be an array of descriptors linked together.
[in]	callback	An optional callback function for signalling completion. May be NULL if not needed.
[in]	cbUserParam	An optional user parameter to feed to the callback function. May be NULL if not needed.

[in]	channelId	The channel ID of the transfer to check.
[out]	active	True if transfer is running, false otherwise.

DMADRV - DMA Driver#

Introduction#

Configuration Options#

The API#

Example#

Modules#

Typedefs#

Functions#

Typedef Documentation#

DMADRV_Callback_t#

Function Documentation#

DMADRV_AllocateChannel#

DMADRV_DeInit#

DMADRV_FreeChannel#

DMADRV_Init#

DMADRV_MemoryPeripheral#

DMADRV_PeripheralMemory#

DMADRV_MemoryPeripheralPingPong#

DMADRV_PeripheralMemoryPingPong#

DMADRV_LdmaStartTransfer#

DMADRV_PauseTransfer#

DMADRV_ResumeTransfer#

DMADRV_StopTransfer#

DMADRV_TransferActive#

DMADRV_TransferCompletePending#

DMADRV_TransferDone#

DMADRV_TransferRemainingCount#