| Kinetis SDK v.2.0 API Reference Manual Rev. 0 Freescale Semiconductor, Inc.

- Main Page
- Related Pages
- API Reference

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Files | Data Structures | Typedefs | Enumerations
DMA: Direct Memory Access Controller Driver

## Overview

The KSDK provides a peripheral driver for the Direct Memory Access (DMA) of Kinetis devices.

# Typical use case

## DMA Operation

dma_transfer_config_t transferConfig;
uint32_t transferDone = false;
DMA_Init(DMA0);
DMA_CreateHandle(&g_DMA_Handle, DMA0, channel);
DMA_InstallCallback(&g_DMA_Handle, DMA_Callback, &transferDone);
DMA_PrepareTransfer(&transferConfig, srcAddr, srcWidth, destAddr, destWidth, transferBytes,
kDMA_MemoryToMemory);
DMA_SubmitTransfer(&g_DMA_Handle, &transferConfig, true);
DMA_StartTransfer(&g_DMA_Handle);
/* Wait for DMA transfer finish
while (transferDone != true);

## Files
file | fsl_dma.h

## Data Structures
struct | dma_transfer_config_t
| DMA transfer configuration structure. More...
struct | dma_channel_link_config_t
| DMA transfer configuration structure. More...
struct | dma_handle_t
| DMA DMA handle structure. More...

## Typedefs
typedef void(* | dma_callback )(struct _dma_handle *handle, void *userData)
| Callback function prototype for the DMA driver. More...

## Enumerations
enum | _dma_channel_status_flags { kDMA_TransactionsBCRFlag = DMA_DSR_BCR_BCR_MASK, kDMA_TransactionsDoneFlag = DMA_DSR_BCR_DONE_MASK, kDMA_TransactionsBusyFlag = DMA_DSR_BCR_BSY_MASK, kDMA_TransactionsRequestFlag = DMA_DSR_BCR_REQ_MASK, kDMA_BusErrorOnDestinationFlag = DMA_DSR_BCR_BED_MASK, kDMA_BusErrorOnSourceFlag = DMA_DSR_BCR_BES_MASK, kDMA_ConfigurationErrorFlag = DMA_DSR_BCR_CE_MASK }
| status flag for the DMA driver. More...
enum | dma_transfer_size_t { kDMA_Transfersize32bits = 0x0U, kDMA_Transfersize8bits, kDMA_Transfersize16bits }
| DMA transfer size type. More...
enum | dma_modulo_t { kDMA_ModuloDisable = 0x0U, kDMA_Modulo16Bytes, kDMA_Modulo32Bytes, kDMA_Modulo64Bytes, kDMA_Modulo128Bytes, kDMA_Modulo256Bytes, kDMA_Modulo512Bytes, kDMA_Modulo1KBytes, kDMA_Modulo2KBytes, kDMA_Modulo4KBytes, kDMA_Modulo8KBytes, kDMA_Modulo16KBytes, kDMA_Modulo32KBytes, kDMA_Modulo64KBytes, kDMA_Modulo128KBytes, kDMA_Modulo256KBytes }
| Configuration type for the DMA modulo. More...
enum | dma_channel_link_type_t { kDMA_ChannelLinkDisable = 0x0U, kDMA_ChannelLinkChannel1AndChannel2, kDMA_ChannelLinkChannel1, kDMA_ChannelLinkChannel1AfterBCR0 }
| DMA channel link type. More...
enum | dma_transfer_type_t { kDMA_MemoryToMemory = 0x0U, kDMA_PeripheralToMemory, kDMA_MemoryToPeripheral }
| DMA transfer type. More...
enum | dma_transfer_options_t { kDMA_NoOptions = 0x0U, kDMA_EnableInterrupt }
| DMA transfer options. More...
enum | _dma_transfer_status
| DMA transfer status.

## Driver version
#define | FSL_DMA_DRIVER_VERSION (MAKE_VERSION(2, 0, 0))
| DMA driver version 2.0.0. More...

## DMA Initialization and De-initialization
void | DMA_Init (DMA_Type *base)
| Initializes the DMA peripheral. More...
void | DMA_Deinit (DMA_Type *base)
| Deinitializes the DMA peripheral. More...

## DMA Channel Operation
void | DMA_ResetChannel (DMA_Type *base, uint32_t channel)
| Resets the DMA channel. More...
void | DMA_SetTransferConfig (DMA_Type *base, uint32_t channel, const dma_transfer_config_t *config)
| Configures the DMA transfer attribute. More...
void | DMA_SetChannelLinkConfig (DMA_Type *base, uint32_t channel, const dma_channel_link_config_t *config)
| Configures the DMA channel link feature. More...
static void | DMA_SetSourceAddress (DMA_Type *base, uint32_t channel, uint32_t srcAddr)
| Sets the DMA source address for the DMA transfer. More...
static void | DMA_SetDestinationAddress (DMA_Type *base, uint32_t channel, uint32_t destAddr)
| Sets the DMA destination address for the DMA transfer. More...
static void | DMA_SetTransferSize (DMA_Type *base, uint32_t channel, uint32_t size)
| Sets the DMA transfer size for the DMA transfer. More...
void | DMA_SetModulo (DMA_Type *base, uint32_t channel, dma_modulo_t srcModulo, dma_modulo_t destModulo)
| Sets the DMA modulo for the DMA transfer. More...
static void | DMA_EnableCycleSteal (DMA_Type *base, uint32_t channel, bool enable)
| Enables the DMA cycle steal for the DMA transfer. More...
static void | DMA_EnableAutoAlign (DMA_Type *base, uint32_t channel, bool enable)
| Enables the DMA auto align for the DMA transfer. More...
static void | DMA_EnableAsyncRequest (DMA_Type *base, uint32_t channel, bool enable)
| Enables the DMA async request for the DMA transfer. More...
static void | DMA_EnableInterrupts (DMA_Type *base, uint32_t channel)
| Enables an interrupt for the DMA transfer. More...
static void | DMA_DisableInterrupts (DMA_Type *base, uint32_t channel)
| Disables an interrupt for the DMA transfer. More...

## DMA Channel Transfer Operation
static void | DMA_EnableChannelRequest (DMA_Type *base, uint32_t channel)
| Enables the DMA hardware channel request. More...
static void | DMA_DisableChannelRequest (DMA_Type *base, uint32_t channel)
| Disables the DMA hardware channel request. More...
static void | DMA_TriggerChannelStart (DMA_Type *base, uint32_t channel)
| Starts the DMA transfer with a software trigger. More...

## DMA Channel Status Operation
static uint32_t | DMA_GetRemainingBytes (DMA_Type *base, uint32_t channel)
| Gets the remaining bytes of the current DMA transfer. More...
static uint32_t | DMA_GetChannelStatusFlags (DMA_Type *base, uint32_t channel)
| Gets the DMA channel status flags. More...
static void | DMA_ClearChannelStatusFlags (DMA_Type *base, uint32_t channel, uint32_t mask)
| Clears the DMA channel status flags. More...

## DMA Channel Transactional Operation
void | DMA_CreateHandle (dma_handle_t *handle, DMA_Type *base, uint32_t channel)
| Creates the DMA handle. More...
void | DMA_SetCallback (dma_handle_t *handle, dma_callback callback, void *userData)
| Sets the DMA callback function. More...
void | DMA_PrepareTransfer (dma_transfer_config_t *config, void *srcAddr, uint32_t srcWidth, void *destAddr, uint32_t destWidth, uint32_t transferBytes, dma_transfer_type_t type)
| Prepares the DMA transfer configuration structure. More...
status_t | DMA_SubmitTransfer (dma_handle_t *handle, const dma_transfer_config_t *config, uint32_t options)
| Submits the DMA transfer request. More...
static void | DMA_StartTransfer (dma_handle_t *handle)
| DMA starts a transfer. More...
static void | DMA_StopTransfer (dma_handle_t *handle)
| DMA stops a transfer. More...
void | DMA_AbortTransfer (dma_handle_t *handle)
| DMA aborts a transfer. More...
void | DMA_HandleIRQ (dma_handle_t *handle)
| DMA IRQ handler for current transfer complete. More...

## Data Structure Documentation

struct dma_transfer_config_t

### Data Fields
uint32_t | srcAddr
| DMA transfer source address. More...
uint32_t | destAddr
| DMA destination address. More...
bool | enableSrcIncrement
| Source address increase after each transfer. More...
dma_transfer_size_t | srcSize
| Source transfer size unit. More...
bool | enableDestIncrement
| Destination address increase after each transfer. More...
dma_transfer_size_t | destSize
| Destination transfer unit. More...
uint32_t | transferSize
| The number of bytes to be transferred. More...

#### Field Documentation

uint32_t dma_transfer_config_t::srcAddr

uint32_t dma_transfer_config_t::destAddr

bool dma_transfer_config_t::enableSrcIncrement

dma_transfer_size_t dma_transfer_config_t::srcSize

bool dma_transfer_config_t::enableDestIncrement

dma_transfer_size_t dma_transfer_config_t::destSize

uint32_t dma_transfer_config_t::transferSize

struct dma_channel_link_config_t

### Data Fields
dma_channel_link_type_t | linkType
| Channel link type. More...
uint32_t | channel1
| The index of channel 1. More...
uint32_t | channel2
| The index of channel 2. More...

#### Field Documentation

dma_channel_link_type_t dma_channel_link_config_t::linkType

uint32_t dma_channel_link_config_t::channel1

uint32_t dma_channel_link_config_t::channel2

struct dma_handle_t

### Data Fields
DMA_Type * | base
| DMA peripheral address. More...
uint8_t | channel
| DMA channel used. More...
dma_callback | callback
| DMA callback function. More...
void * | userData
| Callback parameter. More...

#### Field Documentation

DMA_Type* dma_handle_t::base

uint8_t dma_handle_t::channel

dma_callback dma_handle_t::callback

void* dma_handle_t::userData

## Macro Definition Documentation

#define FSL_DMA_DRIVER_VERSION (MAKE_VERSION(2, 0, 0))

## Typedef Documentation

typedef void(* dma_callback)(struct _dma_handle *handle, void *userData)

## Enumeration Type Documentation

enum _dma_channel_status_flags

Enumerator
kDMA_TransactionsBCRFlag | Contains the number of bytes yet to be transferred for a given block.
kDMA_TransactionsDoneFlag | Transactions Done.
kDMA_TransactionsBusyFlag | Transactions Busy.
kDMA_TransactionsRequestFlag | Transactions Request.
kDMA_BusErrorOnDestinationFlag | Bus Error on Destination.
kDMA_BusErrorOnSourceFlag | Bus Error on Source.
kDMA_ConfigurationErrorFlag | Configuration Error.

enum dma_transfer_size_t

Enumerator
kDMA_Transfersize32bits | 32 bits are transferred for every read/write
kDMA_Transfersize8bits | 8 bits are transferred for every read/write
kDMA_Transfersize16bits | 16b its are transferred for every read/write

enum dma_modulo_t

Enumerator
kDMA_ModuloDisable | Buffer disabled.
kDMA_Modulo16Bytes | Circular buffer size is 16 bytes.
kDMA_Modulo32Bytes | Circular buffer size is 32 bytes.
kDMA_Modulo64Bytes | Circular buffer size is 64 bytes.
kDMA_Modulo128Bytes | Circular buffer size is 128 bytes.
kDMA_Modulo256Bytes | Circular buffer size is 256 bytes.
kDMA_Modulo512Bytes | Circular buffer size is 512 bytes.
kDMA_Modulo1KBytes | Circular buffer size is 1 KB.
kDMA_Modulo2KBytes | Circular buffer size is 2 KB.
kDMA_Modulo4KBytes | Circular buffer size is 4 KB.
kDMA_Modulo8KBytes | Circular buffer size is 8 KB.
kDMA_Modulo16KBytes | Circular buffer size is 16 KB.
kDMA_Modulo32KBytes | Circular buffer size is 32 KB.
kDMA_Modulo64KBytes | Circular buffer size is 64 KB.
kDMA_Modulo128KBytes | Circular buffer size is 128 KB.
kDMA_Modulo256KBytes | Circular buffer size is 256 KB.

enum dma_channel_link_type_t

Enumerator
kDMA_ChannelLinkDisable | No channel link.
kDMA_ChannelLinkChannel1AndChannel2 | Perform a link to channel LCH1 after each cycle-steal transfer. followed by a link to LCH2 after the BCR decrements to 0.
kDMA_ChannelLinkChannel1 | Perform a link to LCH1 after each cycle-steal transfer.
kDMA_ChannelLinkChannel1AfterBCR0 | Perform a link to LCH1 after the BCR decrements.

enum dma_transfer_type_t

Enumerator
kDMA_MemoryToMemory | Memory to Memory transfer.
kDMA_PeripheralToMemory | Peripheral to Memory transfer.
kDMA_MemoryToPeripheral | Memory to Peripheral transfer.

enum dma_transfer_options_t

Enumerator
kDMA_NoOptions | Transfer without options.
kDMA_EnableInterrupt | Enable interrupt while transfer complete.

## Function Documentation

void DMA_Init | ( | DMA_Type * | base | ) |

This function ungates the DMA clock.

Parameters

  base | DMA peripheral base address.

void DMA_Deinit | ( | DMA_Type * | base | ) |

This function gates the DMA clock.

Parameters

  base | DMA peripheral base address.

void DMA_ResetChannel | ( | DMA_Type * | base,
|  | uint32_t | channel
| ) |  |

Sets all register values to reset values and enables the cycle steal and auto stop channel request features.

Parameters

  base | DMA peripheral base address.
  channel | DMA channel number.

void DMA_SetTransferConfig | ( | DMA_Type * | base,
|  | uint32_t | channel,
|  | const dma_transfer_config_t * | config
| ) |  |

This function configures the transfer attribute including the source address, destination address, transfer size, and so on. This example shows how to set up the the dma_transfer_config_t parameters and how to call the DMA_ConfigBasicTransfer function.

dma_transfer_config_t transferConfig;
memset(&transferConfig, 0, sizeof(transferConfig));
transferConfig.srcAddr = (uint32_t)srcAddr;
transferConfig.destAddr = (uint32_t)destAddr;
transferConfig.enbaleSrcIncrement = true;
transferConfig.enableDestIncrement = true;
transferConfig.srcSize = kDMA_Transfersize32bits;
transferConfig.destSize = kDMA_Transfersize32bits;
transferConfig.transferSize = sizeof(uint32_t) * BUFF_LENGTH;
DMA_SetTransferConfig(DMA0, 0, &transferConfig);

Parameters

  base | DMA peripheral base address.
  channel | DMA channel number.
  config | Pointer to the DMA transfer configuration structure.

void DMA_SetChannelLinkConfig | ( | DMA_Type * | base,
|  | uint32_t | channel,
|  | const dma_channel_link_config_t * | config
| ) |  |

This function allows DMA channels to have their transfers linked. The current DMA channel triggers a DMA request to the linked channels (LCH1 or LCH2) depending on the channel link type. Perform a link to channel LCH1 after each cycle-steal transfer followed by a link to LCH2 after the BCR decrements to 0 if the type is kDMA_ChannelLinkChannel1AndChannel2. Perform a link to LCH1 after each cycle-steal transfer if the type is kDMA_ChannelLinkChannel1. Perform a link to LCH1 after the BCR decrements to 0 if the type is kDMA_ChannelLinkChannel1AfterBCR0.

Parameters

  base | DMA peripheral base address.
  channel | DMA channel number.
  config | Pointer to the channel link configuration structure.

static void DMA_SetSourceAddress | ( | DMA_Type * | base,
|  | uint32_t | channel,
|  | uint32_t | srcAddr
| ) |  |
| inline static

Parameters

  base | DMA peripheral base address.
  channel | DMA channel number.
  srcAddr | DMA source address.

static void DMA_SetDestinationAddress | ( | DMA_Type * | base,
|  | uint32_t | channel,
|  | uint32_t | destAddr
| ) |  |
| inline static

Parameters

  base | DMA peripheral base address.
  channel | DMA channel number.
  destAddr | DMA destination address.

static void DMA_SetTransferSize | ( | DMA_Type * | base,
|  | uint32_t | channel,
|  | uint32_t | size
| ) |  |
| inline static

Parameters

  base | DMA peripheral base address.
  channel | DMA channel number.
  size | The number of bytes to be transferred.

void DMA_SetModulo | ( | DMA_Type * | base,
|  | uint32_t | channel,
|  | dma_modulo_t | srcModulo,
|  | dma_modulo_t | destModulo
| ) |  |

This function defines a specific address range specified to be the value after (SAR + SSIZE)/(DAR + DSIZE) calculation is performed or the original register value. It provides the ability to implement a circular data queue easily.

Parameters

  base | DMA peripheral base address.
  channel | DMA channel number.
  srcModulo | source address modulo.
  destModulo | destination address modulo.

static void DMA_EnableCycleSteal | ( | DMA_Type * | base,
|  | uint32_t | channel,
|  | bool | enable
| ) |  |
| inline static

If the cycle steal feature is enabled (true), the DMA controller forces a single read/write transfer per request, or it continuously makes read/write transfers until the BCR decrements to 0.

Parameters

  base | DMA peripheral base address.
  channel | DMA channel number.
  enable | The command for enable (true) or disable (false).

static void DMA_EnableAutoAlign | ( | DMA_Type * | base,
|  | uint32_t | channel,
|  | bool | enable
| ) |  |
| inline static

If the auto align feature is enabled (true), the appropriate address register increments, regardless of DINC or SINC.

Parameters

  base | DMA peripheral base address.
  channel | DMA channel number.
  enable | The command for enable (true) or disable (false).

static void DMA_EnableAsyncRequest | ( | DMA_Type * | base,
|  | uint32_t | channel,
|  | bool | enable
| ) |  |
| inline static

If the async request feature is enabled (true), the DMA supports asynchronous DREQs while the MCU is in stop mode.

Parameters

  base | DMA peripheral base address.
  channel | DMA channel number.
  enable | The command for enable (true) or disable (false).

static void DMA_EnableInterrupts | ( | DMA_Type * | base,
|  | uint32_t | channel
| ) |  |
| inline static

Parameters

  base | DMA peripheral base address.
  channel | DMA channel number.

static void DMA_DisableInterrupts | ( | DMA_Type * | base,
|  | uint32_t | channel
| ) |  |
| inline static

Parameters

  base | DMA peripheral base address.
  channel | DMA channel number.

static void DMA_EnableChannelRequest | ( | DMA_Type * | base,
|  | uint32_t | channel
| ) |  |
| inline static

Parameters

  base | DMA peripheral base address.
  channel | The DMA channel number.

static void DMA_DisableChannelRequest | ( | DMA_Type * | base,
|  | uint32_t | channel
| ) |  |
| inline static

Parameters

  base | DMA peripheral base address.
  channel | DMA channel number.

static void DMA_TriggerChannelStart | ( | DMA_Type * | base,
|  | uint32_t | channel
| ) |  |
| inline static

This function starts only one read/write iteration.

Parameters

  base | DMA peripheral base address.
  channel | The DMA channel number.

static uint32_t DMA_GetRemainingBytes | ( | DMA_Type * | base,
|  | uint32_t | channel
| ) |  |
| inline static

Parameters

  base | DMA peripheral base address.
  channel | DMA channel number.

Returns
  The number of bytes which have not been transferred yet.

static uint32_t DMA_GetChannelStatusFlags | ( | DMA_Type * | base,
|  | uint32_t | channel
| ) |  |
| inline static

Parameters

  base | DMA peripheral base address.
  channel | DMA channel number.

Returns
  The mask of the channel status. Use the _dma_channel_status_flags type to decode the return 32 bit variables.

static void DMA_ClearChannelStatusFlags | ( | DMA_Type * | base,
|  | uint32_t | channel,
|  | uint32_t | mask
| ) |  |
| inline static

Parameters

  base | DMA peripheral base address.
  channel | DMA channel number.
  mask | The mask of the channel status to be cleared. Use the defined _dma_channel_status_flags type.

void DMA_CreateHandle | ( | dma_handle_t * | handle,
|  | DMA_Type * | base,
|  | uint32_t | channel
| ) |  |

This function is called first if using the transactional API for the DMA. This function initializes the internal state of the DMA handle.

Parameters

  handle | DMA handle pointer. The DMA handle stores callback function and parameters.
  base | DMA peripheral base address.
  channel | DMA channel number.

void DMA_SetCallback | ( | dma_handle_t * | handle,
|  | dma_callback | callback,
|  | void * | userData
| ) |  |

This callback is called in the DMA IRQ handler. Use the callback to do something after the current transfer complete.

Parameters

  handle | DMA handle pointer.
  callback | DMA callback function pointer.
  userData | Parameter for callback function. If it is not needed, just set to NULL.

void DMA_PrepareTransfer | ( | dma_transfer_config_t * | config,
|  | void * | srcAddr,
|  | uint32_t | srcWidth,
|  | void * | destAddr,
|  | uint32_t | destWidth,
|  | uint32_t | transferBytes,
|  | dma_transfer_type_t | type
| ) |  |

This function prepares the transfer configuration structure according to the user input.

Parameters

  config | Pointer to the user configuration structure of type dma_transfer_config_t.
  srcAddr | DMA transfer source address.
  srcWidth | DMA transfer source address width (byte).
  destAddr | DMA transfer destination address.
  destWidth | DMA transfer destination address width (byte).
  transferBytes | DMA transfer bytes to be transferred.
  type | DMA transfer type.

status_t DMA_SubmitTransfer | ( | dma_handle_t * | handle,
|  | const dma_transfer_config_t * | config,
|  | uint32_t | options
| ) |  |

This function submits the DMA transfer request according to the transfer configuration structure.

Parameters

  handle | DMA handle pointer.
  config | Pointer to DMA transfer configuration structure.
  options | Additional configurations for transfer. Use the defined dma_transfer_options_t type.

Return values

  kStatus_DMA_Success | It indicates that the DMA submit transfer request succeeded.
  kStatus_DMA_Busy | It indicates that the DMA is busy. Submit transfer request is not allowed.

Note
  This function can't process multi transfer request.

static void DMA_StartTransfer | ( | dma_handle_t * | handle | ) |
| inline static

This function enables the channel request. Call this function after submitting a transfer request.

Parameters

  handle | DMA handle pointer.

Return values

  kStatus_DMA_Success | It indicates that the DMA start transfer succeed.
  kStatus_DMA_Busy | It indicates that the DMA has started a transfer.

static void DMA_StopTransfer | ( | dma_handle_t * | handle | ) |
| inline static

This function disables the channel request to stop a DMA transfer. The transfer can be resumed by calling the DMA_StartTransfer.

Parameters

  handle | DMA handle pointer.

void DMA_AbortTransfer | ( | dma_handle_t * | handle | ) |

This function disables the channel request and clears all status bits. Submit another transfer after calling this API.

Parameters

  handle | DMA handle pointer.

void DMA_HandleIRQ | ( | dma_handle_t * | handle | ) |

This function clears the channel interrupt flag and calls the callback function if it is not NULL.

Parameters

  handle | DMA handle pointer.