| Kinetis SDK API Reference Manual 1.0.0-beta Freescale Semiconductor, Inc.

- Introduction
- Related Pages
- API Usage

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

The section describes the programming interface of the DMA Peripheral driver. More...

## Data Structures
struct | dma_channel_t
| Data structure for the DMA channel management. More...

## Typedefs
typedef void(* | dma_callback_t )(void *parameter, dma_channel_status_t status)
| A definition for the DMA channel callback function. More...

## Enumerations
enum | dma_channel_status_t { kDmaIdle, kDmaNormal, kDmaError }
| Channel status for DMA channel. More...
enum | dma_transfer_type_t { kDmaPeripheralToMemory, kDmaMemoryToPeripheral, kDmaMemoryToMemory, kDmaPeripheralToPeripheral }
| Type for DMA transfer. More...
enum | dma_channel_type_t { kDmaInvalidChannel = 0xFFU, kDmaAnyChannel = 0xFEU }
| Type for the DMA channel, which is used for the DMA channel allocation. More...

## DMA Driver
dma_status_t | dma_init (void)
| Initializes the DMA.
dma_status_t | dma_deinit (void)
| De-initializes the DMA.
dma_status_t | dma_register_callback (dma_channel_t *chn, dma_callback_t callback, void *para)
| Registers the callback function and a parameter. More...
uint32_t | dma_get_descriptor_status (dma_channel_t *chn)
| Gets the status of the EDMA channel descriptor chain. More...
uint32_t | dma_request_channel (uint32_t channel, dma_request_source_t source, dma_channel_t *chn)
| Requests a DMA channel. More...
dma_status_t | dma_free_channel (dma_channel_t *chn)
| Frees DMA channel hardware and software resource. More...
dma_status_t | dma_start_channel (dma_channel_t *chn)
| Starts a DMA channel. More...
dma_status_t | dma_stop_channel (dma_channel_t *chn)
| Stops a DMA channel. More...
dma_status_t | dma_config_transfer (dma_channel_t *chn, dma_transfer_type_t type, uint32_t size, uint32_t sourceAddr, uint32_t destAddr, uint32_t length)
| Configures a transfer for the DMA. More...
void | dma_IRQhandler (uint32_t channel)
| DMA IRQ handler for both an interrupt and an error. More...

### DMA PERIPHERAL Driver

# Overview

The DMA driver requests, configures, and uses the DMA hardware. It supports module initializations and DMA channel configurations.

# Initialization

To initialize the DMA module, call the dma_init() function. Configuration data structure does not need to be passed. This function enables the DMA module and clock automatically.

# Channel concept

DMA module consists of many channels. The DMA peripheral driver is designed based on the channel concept. All tasks should start by requesting a DMA channel and end by freeing a DMA channel. By getting a channel allocated, the user can configure and run operations on the DMA module. If a channel is not allocated, a system error may occur.

# DMA request concept

DMA request triggers a DMA transfer. The DMA request table is available in chip configuration chapters in a Reference Manual.

# Memory allocation

DMA peripheral driver does not allocate memory dynamically. The user must provide the allocated memory pointer for the driver and ensure that the memory is valid. Otherwise, a system error occurs. The user needs to provide the memory for the [dma_channel_t]. The driver must store the status data for every channel and the dma_channel_t is designed for this purpose.

# Call diagram

To use the DMA driver, follow these steps:

1. Initialize the DMA module: dma_init().
2. Request a DMA channel: dma_request_channel().
3. Configure the TCD: dma_config_transfer().
4. Register callback function: dma_register_callback().
5. Start the DMA channel: dma_start_channel().
6. [OPTION] Stop the DMA channel: dma_stop_channel().
7. Free the DMA channel: dma_free_channel().

This is an example code to initialize and configure a memory-to-memory transfer:
uint32_t j, temp;
dma_channel_t chan_handler;
uint8_t *srcAddr, *destAddr;
fsl_rtos_status syncStatus;
srcAddr = malloc(kDmaTestBufferSize);
destAddr = malloc(kDmaTestBufferSize);
if (((uint32_t)srcAddr == 0x0U) & ((uint32_t)destAddr == 0x0U))
{
printf("Fali to allocate memory for test! \r\n");
goto error;
}
/* Init the memory buffer. */
for (j = 0; j < kDmaTestBufferSize; j++)
{
srcAddr[j] = j;
destAddr[j] = 0;
}
temp = dma_request_channel(channel, kDmaRequestMux0AlwaysOn62, &chan_handler);
if (temp != channel)
{
printf("Failed to request channel %d !\r\n", channel);
goto error;
}
dma_config_transfer(&chan_handler, kDmaMemoryToMemory,
0x1U,
(uint32_t)srcAddr, (uint32_t)destAddr,
kDmaTestBufferSize);
dma_register_callback(&chan_handler, test_callback, &chan_handler);
dma_start_channel(&chan_handler);
//Wait until channel complete...
dma_stop_channel(&chan_handler);
dma_free_channel(&chan_handler);

## Data Structure Documentation

struct dma_channel_t

### Data Fields
uint8_t | channel
| Channel number.
uint8_t | dmamuxModule
| Dmamux module index.
uint8_t | dmamuxChannel
| Dmamux module channel.
dma_callback_t | callback
| Callback function for this channel.
void * | parameter
| Parameter for the callback function.
volatile dma_channel_status_t | status
| Channel status.

## Typedef Documentation

typedef void(* dma_callback_t)(void *parameter, dma_channel_status_t status)

A prototype for the callback function registered into the DMA driver.

## Enumeration Type Documentation

enum dma_channel_status_t

A structure describing the status of the DMA channel. The user can get the status from the channel callback function.

Enumerator
kDmaIdle | DMA channel is idle.
kDmaNormal | DMA channel is occupied.
kDmaError | Error occurs in the DMA channel.

enum dma_transfer_type_t

Enumerator
kDmaPeripheralToMemory | Transfer from the peripheral to memory.
kDmaMemoryToPeripheral | Transfer from the memory to peripheral.
kDmaMemoryToMemory | Transfer from the memory to memory.
kDmaPeripheralToPeripheral | Transfer from the peripheral to peripheral.

enum dma_channel_type_t

Enumerator
kDmaInvalidChannel | Macros indicating the failure of the channel request.
kDmaAnyChannel | Macros used when requesting a channel. kEdmaAnyChannel means a request of dynamic channel allocation.

## Function Documentation

dma_status_t dma_register_callback | ( | dma_channel_t * | chn,
|  | dma_callback_t | callback,
|  | void * | para
| ) |  |

The user registers the callback function and a parameter for a specified DMA channel. When the channel interrupt or a channel error happens, the callback and the parameter are called. The user parameter is also provided to give a channel status.

Parameters

  chn | A handler for the DMA channel
  callback | Callback function
  para | A parameter for callback functions

uint32_t dma_get_descriptor_status | ( | dma_channel_t * | chn | ) |

Gets the left bytes to be transferred.

Parameters

  chn | A handler for the DMA channel

uint32_t dma_request_channel | ( | uint32_t | channel,
|  | dma_request_source_t | source,
|  | dma_channel_t * | chn
| ) |  |

This function provides two ways to allocate a DMA channel. The first way is a static allocation. The second way is a dynamic allocation. To allocate a channel dynamically, the user needs to set the channel parameter with the value of kDmaAnyChannel. The driver searches into all available free channels and assigns the first channel to the user. To allocate the channel statically, the user needs to set the channel parameter with the value of a specified channel. If the channel is available, the driver assigns the channel to the user. Notes: The user must provide a handler memory for the DMA channel. The driver initializes the handler and configures the handler memory.

Parameters

  channel | A DMA channel number. If a channel is assigned with a valid channel number, the DMA driver tries to assign a specified channel to the user. If a channel is assigned with kDmaAnyChannel, the DMA driver searches all available channels and assigns the first channel to the user.
  source | A DMA hardware request.
  chan | Memory pointing to DMA channel. The user must ensure that the handler memory is valid and that it will not be released or changed by any other codes before the channel dma_free_channel() operation.

Returns
  If the channel allocation is successful, the return value indicates the requested channel. If not, the driver returns a kDmaInvalidChannel value to indicate that the request operation has failed.

dma_status_t dma_free_channel | ( | dma_channel_t * | chn | ) |

This function frees the relevant software and hardware resources. Both the request and the free operations need to be called in a pair.

Parameters

  chn | Memory pointing to DMA channel.

dma_status_t dma_start_channel | ( | dma_channel_t * | chn | ) |

Starts a DMA channel. The driver starts a DMA channel by enabling the DMA request. A software start bit is not used in the DMA Peripheral driver.

Parameters

  chn | Memory pointing to the DMA channel.

dma_status_t dma_stop_channel | ( | dma_channel_t * | chn | ) |

Parameters

  chn | Memory pointing to the DMA channel.

dma_status_t dma_config_transfer | ( | dma_channel_t * | chn,
|  | dma_transfer_type_t | type,
|  | uint32_t | size,
|  | uint32_t | sourceAddr,
|  | uint32_t | destAddr,
|  | uint32_t | length
| ) |  |

Configures a transfer for the DMA.

Parameters

  chn | Memory pointing to the DMA channel.
  type | Transfer type.
  size | Size to be transferred on each DMA write/read. Source/Dest share the same write/read size.
  sourceAddr | Source address.
  destAddr | Destination address.
  length | Bytes to be transferred.

void dma_IRQhandler | ( | uint32_t | channel | ) |

Parameters

  channel | DMA channel number.