Kinetis SDK v.2.0 API Reference Manual  Rev. 0
Freescale Semiconductor, Inc.
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
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,
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_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

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.

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

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.

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.

Enumerator
kDMA_MemoryToMemory 

Memory to Memory transfer.

kDMA_PeripheralToMemory 

Peripheral to Memory transfer.

kDMA_MemoryToPeripheral 

Memory to Peripheral transfer.

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
baseDMA peripheral base address.
void DMA_Deinit ( DMA_Type *  base)

This function gates the DMA clock.

Parameters
baseDMA 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
baseDMA peripheral base address.
channelDMA 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.transferSize = sizeof(uint32_t) * BUFF_LENGTH;
DMA_SetTransferConfig(DMA0, 0, &transferConfig);
Parameters
baseDMA peripheral base address.
channelDMA channel number.
configPointer 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
baseDMA peripheral base address.
channelDMA channel number.
configPointer to the channel link configuration structure.
static void DMA_SetSourceAddress ( DMA_Type *  base,
uint32_t  channel,
uint32_t  srcAddr 
)
inlinestatic
Parameters
baseDMA peripheral base address.
channelDMA channel number.
srcAddrDMA source address.
static void DMA_SetDestinationAddress ( DMA_Type *  base,
uint32_t  channel,
uint32_t  destAddr 
)
inlinestatic
Parameters
baseDMA peripheral base address.
channelDMA channel number.
destAddrDMA destination address.
static void DMA_SetTransferSize ( DMA_Type *  base,
uint32_t  channel,
uint32_t  size 
)
inlinestatic
Parameters
baseDMA peripheral base address.
channelDMA channel number.
sizeThe 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
baseDMA peripheral base address.
channelDMA channel number.
srcModulosource address modulo.
destModulodestination address modulo.
static void DMA_EnableCycleSteal ( DMA_Type *  base,
uint32_t  channel,
bool  enable 
)
inlinestatic

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
baseDMA peripheral base address.
channelDMA channel number.
enableThe command for enable (true) or disable (false).
static void DMA_EnableAutoAlign ( DMA_Type *  base,
uint32_t  channel,
bool  enable 
)
inlinestatic

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

Parameters
baseDMA peripheral base address.
channelDMA channel number.
enableThe command for enable (true) or disable (false).
static void DMA_EnableAsyncRequest ( DMA_Type *  base,
uint32_t  channel,
bool  enable 
)
inlinestatic

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

Parameters
baseDMA peripheral base address.
channelDMA channel number.
enableThe command for enable (true) or disable (false).
static void DMA_EnableInterrupts ( DMA_Type *  base,
uint32_t  channel 
)
inlinestatic
Parameters
baseDMA peripheral base address.
channelDMA channel number.
static void DMA_DisableInterrupts ( DMA_Type *  base,
uint32_t  channel 
)
inlinestatic
Parameters
baseDMA peripheral base address.
channelDMA channel number.
static void DMA_EnableChannelRequest ( DMA_Type *  base,
uint32_t  channel 
)
inlinestatic
Parameters
baseDMA peripheral base address.
channelThe DMA channel number.
static void DMA_DisableChannelRequest ( DMA_Type *  base,
uint32_t  channel 
)
inlinestatic
Parameters
baseDMA peripheral base address.
channelDMA channel number.
static void DMA_TriggerChannelStart ( DMA_Type *  base,
uint32_t  channel 
)
inlinestatic

This function starts only one read/write iteration.

Parameters
baseDMA peripheral base address.
channelThe DMA channel number.
static uint32_t DMA_GetRemainingBytes ( DMA_Type *  base,
uint32_t  channel 
)
inlinestatic
Parameters
baseDMA peripheral base address.
channelDMA channel number.
Returns
The number of bytes which have not been transferred yet.
static uint32_t DMA_GetChannelStatusFlags ( DMA_Type *  base,
uint32_t  channel 
)
inlinestatic
Parameters
baseDMA peripheral base address.
channelDMA 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 
)
inlinestatic
Parameters
baseDMA peripheral base address.
channelDMA channel number.
maskThe 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
handleDMA handle pointer. The DMA handle stores callback function and parameters.
baseDMA peripheral base address.
channelDMA 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
handleDMA handle pointer.
callbackDMA callback function pointer.
userDataParameter 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
configPointer to the user configuration structure of type dma_transfer_config_t.
srcAddrDMA transfer source address.
srcWidthDMA transfer source address width (byte).
destAddrDMA transfer destination address.
destWidthDMA transfer destination address width (byte).
transferBytesDMA transfer bytes to be transferred.
typeDMA 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
handleDMA handle pointer.
configPointer to DMA transfer configuration structure.
optionsAdditional configurations for transfer. Use the defined dma_transfer_options_t type.
Return values
kStatus_DMA_SuccessIt indicates that the DMA submit transfer request succeeded.
kStatus_DMA_BusyIt 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)
inlinestatic

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

Parameters
handleDMA handle pointer.
Return values
kStatus_DMA_SuccessIt indicates that the DMA start transfer succeed.
kStatus_DMA_BusyIt indicates that the DMA has started a transfer.
static void DMA_StopTransfer ( dma_handle_t handle)
inlinestatic

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

Parameters
handleDMA 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
handleDMA 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
handleDMA handle pointer.