Xmega Application Note


dma_driver.h File Reference

XMEGA DMA Controller driver header file. More...

#include "avr_compiler.h"

Include dependency graph for dma_driver.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Defines

#define DMA_Disable()   ( DMA.CTRL &= ~DMA_ENABLE_bm )
 This function disables the DMA module.
#define DMA_Enable()   ( DMA.CTRL |= DMA_ENABLE_bm )
 This function enable the DMA module.

Functions

uint8_t DMA_CH_IsOngoing (volatile DMA_CH_t *channel)
 This function checks if the channel has on-going transfers not finished yet.
uint8_t DMA_CH_IsPending (volatile DMA_CH_t *channel)
 This function check if the channel has transfers pending.
void DMA_ConfigDoubleBuffering (DMA_DBUFMODE_t dbufMode)
 This function configures the double buffering feature of the DMA.
void DMA_DisableChannel (volatile DMA_CH_t *channel)
 This function disables one DMA channel sub module.
void DMA_DisableSingleShot (volatile DMA_CH_t *channel)
 This function disables single-shot transfer mode for a channel.
void DMA_EnableChannel (volatile DMA_CH_t *channel)
 This function enables one DMA channel sub module.
void DMA_EnableSingleShot (volatile DMA_CH_t *channel)
 This function enables single-shot transfer mode for a channel.
uint8_t DMA_IsOngoing (void)
 This function checks if any channel have on-going transfers are not finished yet.
uint8_t DMA_IsPending (void)
 This function check if there are any transfers pending.
void DMA_Reset (void)
 This function forces a software reset of the DMA module.
void DMA_ResetChannel (volatile DMA_CH_t *channel)
 This function forces a software reset of the DMA channel sub module.
uint8_t DMA_ReturnStatus_blocking (volatile DMA_CH_t *channel)
 This function return the interrupt flag status of a channel.
uint8_t DMA_ReturnStatus_non_blocking (volatile DMA_CH_t *channel)
 This function return the interrupt flag status of a channel.
void DMA_SetIntLevel (volatile DMA_CH_t *channel, DMA_CH_TRNINTLVL_t transferInt, DMA_CH_ERRINTLVL_t errorInt)
 This function configures the interrupt levels for one DMA channel.
void DMA_SetPriority (DMA_PRIMODE_t priMode)
 This function selects what priority scheme to use for the DMA channels.
void DMA_SetTriggerSource (volatile DMA_CH_t *channel, uint8_t trigger)
 This function sets the transfer trigger source for a channel.
void DMA_SetupBlock (volatile DMA_CH_t *channel, const void *srcAddr, DMA_CH_SRCRELOAD_t srcReload, DMA_CH_SRCDIR_t srcDirection, void *destAddr, DMA_CH_DESTRELOAD_t destReload, DMA_CH_DESTDIR_t destDirection, uint16_t blockSize, DMA_CH_BURSTLEN_t burstMode, uint8_t repeatCount, bool useRepeat)
 This function configures the necessary registers for a block transfer.
void DMA_StartTransfer (volatile DMA_CH_t *channel)
 This function sends a manual transfer request to the channel.


Detailed Description

XMEGA DMA Controller driver header file.

This file contains the function prototypes and enumerator definitions for various configuration parameters for the XMEGA DMA driver.

The driver is not intended for size and/or speed critical code, since most functions are just a few lines of code, and the function call overhead would decrease code performance. The driver is intended for rapid prototyping and documentation purposes for getting started with the XMEGA DMA module.

For size and/or speed critical code, it is recommended to copy the function contents directly into your application instead of making a function call.

Application note:
AVR1304: Using the XMEGA DMA Controller
Documentation
For comprehensive code documentation, supported compilers, compiler settings and supported devices see readme.html
Author:
Atmel Corporation: http://www.atmel.com
Support email: avr@atmel.com
Revision
2593
Date
2009-07-17 15:22:29 +0200 (fr, 17 jul 2009)

Copyright (c) 2008, Atmel Corporation All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The name of ATMEL may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Definition in file dma_driver.h.


Define Documentation

 
#define DMA_Disable (  )     ( DMA.CTRL &= ~DMA_ENABLE_bm )

This function disables the DMA module.

Note:
On-going transfers will be aborted.

Definition at line 76 of file dma_driver.h.

 
#define DMA_Enable (  )     ( DMA.CTRL |= DMA_ENABLE_bm )

This function enable the DMA module.

Note:
Each individual DMA channel must be enabled separately using the DMA_EnableChannel() function.

Definition at line 70 of file dma_driver.h.

Referenced by main().


Function Documentation

uint8_t DMA_CH_IsOngoing ( volatile DMA_CH_t *  channel  ) 

This function checks if the channel has on-going transfers not finished yet.

Parameters:
channel Channel to check.
Returns:
Non-zero if the selected channel have on-going transfers, zero otherwise.

Definition at line 119 of file dma_driver.c.

00120 {
00121         uint8_t flagMask;
00122         flagMask = channel->CTRLB & DMA_CH_CHBUSY_bm;
00123         return flagMask;
00124 }

uint8_t DMA_CH_IsPending ( volatile DMA_CH_t *  channel  ) 

This function check if the channel has transfers pending.

This function checks if the channel selected have transfers that are pending, which means that a transfer has been requested by a trigger source or by a manual request, but the channel haven't yet started its transfer.

Parameters:
channel Channel to check.
Returns:
Non-zero if the selected channel have pending transfers, zero otherwise.

Definition at line 149 of file dma_driver.c.

00150 {
00151         uint8_t flagMask;
00152         flagMask = channel->CTRLB & DMA_CH_CHPEND_bm;
00153         return flagMask;
00154 }

void DMA_ConfigDoubleBuffering ( DMA_DBUFMODE_t  dbufMode  ) 

This function configures the double buffering feature of the DMA.

Channel pair 0/1 and/or channel pair 2/3 can be configured to operation in a chained mode. This means that once the first channel has completed its transfer, the second channel takes over automatically. It is important to setup the channel pair with equal block sizes, repeat modes etc.

Do not change these settings after a transfer has started.

Parameters:
dbufMode Double buffering mode.

Definition at line 88 of file dma_driver.c.

00089 {
00090         DMA.CTRL = ( DMA.CTRL & ~DMA_DBUFMODE_gm ) | dbufMode;
00091 }

void DMA_DisableChannel ( volatile DMA_CH_t *  channel  ) 

This function disables one DMA channel sub module.

Note:
On-going transfers will be aborted and the error flag be set if a channel is disabled in the middle of a transfer.
Parameters:
channel The channel to disable.

Definition at line 242 of file dma_driver.c.

00243 {
00244         channel->CTRLA &= ~DMA_CH_ENABLE_bm;
00245 }

void DMA_DisableSingleShot ( volatile DMA_CH_t *  channel  ) 

This function disables single-shot transfer mode for a channel.

In single-shot mode, one transfer trigger (manual or from a trigger source) only causes one single data transfer (1, 2, 4, or 8 byte). When not in single-shot mode, one transfer trigger causes one entire block transfer.

Do not change this setting after a transfer has started.

Parameters:
channel The channel to configure.

Definition at line 361 of file dma_driver.c.

00362 {
00363         channel->CTRLA &= ~DMA_CH_SINGLE_bm;
00364 }

void DMA_EnableChannel ( volatile DMA_CH_t *  channel  ) 

This function enables one DMA channel sub module.

Note:
A DMA channel will be automatically disabled when a transfer is finished.
Parameters:
channel The channel to enable.

Definition at line 229 of file dma_driver.c.

Referenced by BlockMemCopy(), and MultiBlockMemCopy().

00230 {
00231         channel->CTRLA |= DMA_CH_ENABLE_bm;
00232 }

void DMA_EnableSingleShot ( volatile DMA_CH_t *  channel  ) 

This function enables single-shot transfer mode for a channel.

In single-shot mode, one transfer trigger (manual or from a trigger source) only causes one single data transfer (1, 2, 4, or 8 byte). When not in single-shot mode, one transfer trigger causes one entire block transfer. Do not change this setting after a transfer has started.

Parameters:
channel The channel to configure.

Definition at line 345 of file dma_driver.c.

00346 {
00347         channel->CTRLA |= DMA_CH_SINGLE_bm;
00348 }

uint8_t DMA_IsOngoing ( void   ) 

This function checks if any channel have on-going transfers are not finished yet.

Returns:
Non-zero if any channel have on-going transfers, zero otherwise.

Definition at line 131 of file dma_driver.c.

00132 {
00133         uint8_t flagMask;
00134         flagMask = DMA.STATUS & 0xF0;
00135         return flagMask;
00136 }

uint8_t DMA_IsPending ( void   ) 

This function check if there are any transfers pending.

This function checks if any channel have transfers that are pending, which means that a transfer has been requested by a trigger source or by a manual request, but the channels haven't yet started its transfer.

Returns:
Non-zero if the selected channel have pending transfers, zero otherwise.

Definition at line 166 of file dma_driver.c.

00167 {
00168         uint8_t flagMask;
00169         flagMask = DMA.STATUS & 0x0F;
00170         return flagMask;
00171 }

void DMA_Reset ( void   ) 

This function forces a software reset of the DMA module.

Prototyping of functions.

All registers will be set to their default values. If the DMA module is enabled, it must and will be disabled before being reset. It will not be enabled afterwards.

Definition at line 68 of file dma_driver.c.

00069 {                                   
00070         DMA.CTRL &= ~DMA_ENABLE_bm;
00071         DMA.CTRL |= DMA_RESET_bm;   
00072         while (DMA.CTRL & DMA_RESET_bm);        // Wait until reset is completed
00073 }

void DMA_ResetChannel ( volatile DMA_CH_t *  channel  ) 

This function forces a software reset of the DMA channel sub module.

All registers will be set to their default values. If the channel is enabled, it must and will be disabled before being reset. It will not be enabled afterwards.

Parameters:
channel The channel to reset.

Definition at line 256 of file dma_driver.c.

00257 {
00258         channel->CTRLA &= ~DMA_CH_ENABLE_bm;
00259         channel->CTRLA |= DMA_CH_RESET_bm;
00260         channel->CTRLA &= ~DMA_CH_RESET_bm;
00261 }

uint8_t DMA_ReturnStatus_blocking ( volatile DMA_CH_t *  channel  ) 

This function return the interrupt flag status of a channel.

This function return the status of the channel selected either finishes an on-going transfer or encounters an error and aborts the transfer.

Note:
Flags covered by the channel will be cleared when this function exits. However, it will return the flag status. This is a BLOCKING function, and will go into a dead-lock if the flags never get set.
Parameters:
channel The channel to check.
Returns:
Relevant interrupt flags.

Definition at line 207 of file dma_driver.c.

00208 {
00209         uint8_t flagMask;
00210         uint8_t relevantFlags;
00211 
00212         flagMask = DMA_CH_ERRIF_bm | DMA_CH_TRNIF_bm;
00213 
00214         do {
00215                 relevantFlags = channel->CTRLB & flagMask;
00216         } while (relevantFlags == 0x00);
00217 
00218         channel->CTRLB = flagMask;
00219         return relevantFlags;
00220 }

uint8_t DMA_ReturnStatus_non_blocking ( volatile DMA_CH_t *  channel  ) 

This function return the interrupt flag status of a channel.

This function return the status the channels selected finishes an on-going transfer or encounters an error and aborts the transfer.

Note:
Flags covered by the channel will NOT be cleared when this function exits.
Parameters:
channel The channel to check.
Returns:
Relevant interrupt flags.

Definition at line 185 of file dma_driver.c.

Referenced by MultiBlockMemCopy().

00186 {
00187         uint8_t relevantFlags;
00188         relevantFlags = channel->CTRLB & (DMA_CH_ERRIF_bm | DMA_CH_TRNIF_bm);
00189         return relevantFlags;
00190 }

void DMA_SetIntLevel ( volatile DMA_CH_t *  channel,
DMA_CH_TRNINTLVL_t  transferInt,
DMA_CH_ERRINTLVL_t  errorInt 
)

This function configures the interrupt levels for one DMA channel.

Note:
The interrupt level parameter use the data type for channel 0, regardless of which channel is used. This is because we use the same function for all channel. This method relies upon channel bit fields to be located this way: CH3:CH2:CH1:CH0.
Parameters:
channel The channel to configure.
transferInt Transfer Complete Interrupt Level.
errorInt Transfer Error Interrupt Level.

Definition at line 275 of file dma_driver.c.

Referenced by main().

00278 {
00279         channel->CTRLB = (channel->CTRLB & ~(DMA_CH_ERRINTLVL_gm | DMA_CH_TRNINTLVL_gm)) |
00280                          transferInt | errorInt;
00281 }

void DMA_SetPriority ( DMA_PRIMODE_t  priMode  ) 

This function selects what priority scheme to use for the DMA channels.

It decides what channels to schedule in a round-robin manner, which means that they take turns in acquiring the data bus for individual data transfers. Channels not included in the round-robin scheme will have fixed priorities, with channel 0 having highest priority.

Note:
Do not change these settings after a transfer has started.
Parameters:
priMode An enum selection the priority scheme to use.

Definition at line 105 of file dma_driver.c.

00106 {
00107         DMA.CTRL = ( DMA.CTRL & ~DMA_PRIMODE_gm ) | priMode;
00108 }

void DMA_SetTriggerSource ( volatile DMA_CH_t *  channel,
uint8_t  trigger 
)

This function sets the transfer trigger source for a channel.

Note:
A manual transfer requests can be used even after setting a trigger source. Do not change this setting after a transfer has started.
Parameters:
channel The channel to configure.
trigger The trigger source ID.

Definition at line 375 of file dma_driver.c.

00376 {
00377         channel->TRIGSRC = trigger;
00378 }

void DMA_SetupBlock ( volatile DMA_CH_t *  channel,
const void *  srcAddr,
DMA_CH_SRCRELOAD_t  srcReload,
DMA_CH_SRCDIR_t  srcDirection,
void *  destAddr,
DMA_CH_DESTRELOAD_t  destReload,
DMA_CH_DESTDIR_t  destDirection,
uint16_t  blockSize,
DMA_CH_BURSTLEN_t  burstMode,
uint8_t  repeatCount,
bool  useRepeat 
)

This function configures the necessary registers for a block transfer.

Note:
The transfer must be manually triggered or a trigger source selected before the transfer starts. It is possible to reload the source and/or destination address after each data transfer, block transfer or only when the entire transfer is complete. Do not change these settings after a transfer has started.
Parameters:
channel The channel to configure.
srcAddr Source memory address.
srcReload Source address reload mode.
srcDirection Source address direction (fixed, increment, or decrement).
destAddr Destination memory address.
destReload Destination address reload mode.
destDirection Destination address direction (fixed, increment, or decrement).
blockSize Block size in number of bytes (0 = 64k).
burstMode Number of bytes per data transfer (1, 2, 4, or 8 bytes).
repeatCount Number of blocks, 0x00 if you want to repeat at infinitum.
useRepeat True if reapeat should be used, false if not.

Definition at line 304 of file dma_driver.c.

Referenced by BlockMemCopy(), and MultiBlockMemCopy().

00315 {
00316         channel->SRCADDR0 = (( (uint32_t) srcAddr) >> 0*8 ) & 0xFF;
00317         channel->SRCADDR1 = (( (uint32_t) srcAddr) >> 1*8 ) & 0xFF;
00318         channel->SRCADDR2 = (( (uint32_t) srcAddr) >> 2*8 ) & 0xFF;
00319 
00320         channel->DESTADDR0 = (( (uint32_t) destAddr) >> 0*8 ) & 0xFF;
00321         channel->DESTADDR1 = (( (uint32_t) destAddr) >> 1*8 ) & 0xFF;
00322         channel->DESTADDR2 = (( (uint32_t) destAddr) >> 2*8 ) & 0xFF;
00323 
00324         channel->ADDRCTRL = (uint8_t) srcReload | srcDirection |
00325                                       destReload | destDirection;
00326         channel->TRFCNT = blockSize;
00327         channel->CTRLA = ( channel->CTRLA & ~( DMA_CH_BURSTLEN_gm | DMA_CH_REPEAT_bm ) ) |
00328                           burstMode | ( useRepeat ? DMA_CH_REPEAT_bm : 0);
00329 
00330         if ( useRepeat ) {
00331                 channel->REPCNT = repeatCount;
00332         }
00333 }

void DMA_StartTransfer ( volatile DMA_CH_t *  channel  ) 

This function sends a manual transfer request to the channel.

The bit will automatically clear when transfer starts.

Parameters:
channel The channel to request a transfer for.

Definition at line 387 of file dma_driver.c.

Referenced by BlockMemCopy(), and MultiBlockMemCopy().

00388 {
00389         channel->CTRLA |= DMA_CH_TRFREQ_bm;
00390 }

@DOC_TITLE@
Generated on Fri Jul 17 17:12:43 2009 for AVR1304 Using the XMEGA DMA Controller by doxygen 1.5.9