at07893: sam4l peripheral dma controller (pdca) asf...

42313A-MCU-05/2014

APPLICATION NOTE

AT07893: SAM4L Peripheral DMA Controller (PDCA)

ASF PROGRAMMERS MANUAL

SAM4L Peripheral DMA Controller (PDCA)

The Peripheral DMA Controller (PDCA) transfers data between on-chip peripheralmodules such as USART, SPI, and memories (those memories may be on or offchip). Using the PDCA avoids CPU intervention for data transfers, improving theperformance of the microcontroller. The PDCA can transfer data from memory to aperipheral or from a peripheral to memory.The outline of this documentation is as follows:

● Prerequisites

● Module Overview

● Special Considerations

● Extra Information

● Examples

● API Overview

AT07893: SAM4L Peripheral DMA Controller (PDCA) [APPLICATION NOTE]42313A-MCU-05/2014

2

Table of Contents

SAM4L Peripheral DMA Controller (PDCA) ....................................... 1

Software License ................................................................................ 4

1. Prerequisites ................................................................................. 5

2. Module Overview .......................................................................... 6

3. Special Considerations ................................................................. 7

4. Extra Information .......................................................................... 8

5. Examples ...................................................................................... 9

6. API Overview .............................................................................. 106.1. Variable and Type Definitions ...................................................... 10

6.1.1. Type pdca_callback_t ................................................... 106.1.2. Type pdca_channel_interrupt_mask_t .............................. 106.1.3. Type pdca_channel_num_t ............................................ 10

6.2. Structure Definitions ................................................................... 106.2.1. Struct pdca_channel_config_t .......................................... 10

6.3. Function Definitions ................................................................... 106.3.1. Function pdca_channel_clear_error() ............................... 106.3.2. Function pdca_channel_disable() .................................... 116.3.3. Function pdca_channel_disable_interrupt() ........................ 116.3.4. Function pdca_channel_enable() ..................................... 116.3.5. Function pdca_channel_enable_interrupt() ........................ 116.3.6. Function pdca_channel_get_handler() .............................. 126.3.7. Function pdca_channel_get_interrupt_mask() .................... 126.3.8. Function pdca_channel_is_enabled() ............................... 126.3.9. Function pdca_channel_read_load_size() .......................... 136.3.10. Function pdca_channel_read_reload_size() ....................... 136.3.11. Function pdca_channel_set_callback() ............................. 136.3.12. Function pdca_channel_set_config() ................................ 146.3.13. Function pdca_channel_write_load() ................................ 146.3.14. Function pdca_channel_write_reload() ............................. 146.3.15. Function pdca_disable() ................................................ 156.3.16. Function pdca_enable() ................................................. 156.3.17. Function pdca_get_channel_status() ................................ 15

6.4. Enumeration Definitions .............................................................. 166.4.1. Enum pdca_channel_status ........................................... 16

7. Extra Information for Peripheral DMA Controller Driver ............. 177.1. Acronyms ................................................................................ 177.2. Dependencies ........................................................................... 177.3. Errata ...................................................................................... 177.4. Module History ......................................................................... 17

8. Examples for Peripheral DMA Controller ................................... 188.1. Peripheral DMA Controller Example .............................................. 18

8.1.1. Purpose ...................................................................... 188.1.2. Requirements ............................................................... 188.1.3. Description ................................................................... 188.1.4. Usage ......................................................................... 18

9. Quickstart guide for SAM PDCA driver ...................................... 199.1. Basic use case ......................................................................... 19

9.1.1. Prerequisites ................................................................ 19


3

9.2. Setup steps .............................................................................. 199.2.1. Example code .............................................................. 199.2.2. Workflow ..................................................................... 19

Index ................................................................................................. 21

Document Revision History .............................................................. 22


4

Software LicenseRedistribution and use in source and binary forms, with or without modification, are permitted provided that thefollowing conditions are met:1. Redistributions of source code must retain the above copyright notice, this list of conditions and the followingdisclaimer.2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the followingdisclaimer 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 specificprior written permission.4. This software may only be redistributed and used in connection with an Atmel microcontroller product.THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR APARTICULAR PURPOSE AND NON-INFRINGEMENT ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. INNO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTEGOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVERCAUSED 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.


5

1. PrerequisitesThere are no prerequisites for this module.


6

2. Module OverviewThe Peripheral DMA Controller (PDCA) transfers data between on-chip peripheral modules such as USART,SPI, and memories (those memories may be on and off chip). Using the PDCA avoids CPU intervention fordata transfers, improving the performance of the microcontroller. The PDCA can transfer data from memory to aperipheral or from a peripheral to memory. The PDCA consists of multiple DMA channels. Each channel has:

● A Peripheral Select Register

● A 32-bit memory pointer

● A 16-bit transfer counter

● A 32-bit memory pointer reload value

● A 16-bit transfer counter reload value

The PDCA communicates with the peripheral modules over a set of handshake interfaces. The peripheral signalsthe PDCA when it is ready to receive or transmit data. The PDCA acknowledges the request when the transmissionhas started. When a transmit buffer is empty or a receive buffer is full, an optional interrupt request can begenerated.


7

3. Special ConsiderationsNone.


8

4. Extra InformationFor extra information, see Extra Information for Peripheral DMA Controller Driver. This includes:

● Acronyms

● Dependencies

● Errata

● Module History


9

5. ExamplesFor a list of examples related to this driver, see Examples for Peripheral DMA Controller.


10

6. API Overview

6.1 Variable and Type Definitions

6.1.1 Type pdca_callback_t

typedef void(* pdca_callback_t )(enum pdca_channel_status status)

PDCA callback type.

6.1.2 Type pdca_channel_interrupt_mask_t

typedef uint32_t pdca_channel_interrupt_mask_t

PDCA channel interrupt mask type.

6.1.3 Type pdca_channel_num_t

typedef uint8_t pdca_channel_num_t

PDCA channel number type.

6.2 Structure Definitions

6.2.1 Struct pdca_channel_config_t

PDCA channel configuration structure.

Table 6-1. Members

Type Name Descriptionvoid * addr Memory address.

bool etrig Enable/disable the transfer uponevent trigger.

uint32_t pid Select peripheral ID.

void * r_addr Next memory address.

uint32_t r_size Next transfer counter.

bool ring Ring buffer function.

uint32_t size Transfer counter.

uint32_t transfer_size Select the size of the transfer (inbytes, half-words or words).

6.3 Function Definitions

6.3.1 Function pdca_channel_clear_error()


11

Clear transfer error for the given channel.

void pdca_channel_clear_error( pdca_channel_num_t pdca_ch_number)

Table 6-2. Parameters

Data direction Parameter name Description[in] pdca_ch_number PDCA channel

6.3.2 Function pdca_channel_disable()

Disable the PDCA for the given channel.

void pdca_channel_disable( pdca_channel_num_t pdca_ch_number)



6.3.3 Function pdca_channel_disable_interrupt()

Disable PDCA interrupt.

void pdca_channel_disable_interrupt( pdca_channel_num_t pdca_ch_number, const pdca_channel_interrupt_mask_t pdca_channel_interrupt_mask)



[in] pdca_channel_interrupt_mask Interrupts to be disabled

6.3.4 Function pdca_channel_enable()

Enable the PDCA for the given channel.

void pdca_channel_enable( pdca_channel_num_t pdca_ch_number)



6.3.5 Function pdca_channel_enable_interrupt()


12

Enable PDCA transfer error interrupt.

void pdca_channel_enable_interrupt( pdca_channel_num_t pdca_ch_number, const pdca_channel_interrupt_mask_t pdca_channel_interrupt_mask)



[in] pdca_channel_interrupt_mask Interrupts to be enabled

6.3.6 Function pdca_channel_get_handler()

Get the base address of the specified PDCA channel configuration registers.

PdcaChannel * pdca_channel_get_handler( pdca_channel_num_t pdca_ch_number)


Data direction Parameter name Description[in] pdca_ch_number PDCA channel (range 0 15)

Returns The channel configuration registers base address.

6.3.7 Function pdca_channel_get_interrupt_mask()

Get PDCA interrupt mask.

pdca_channel_interrupt_mask_t pdca_channel_get_interrupt_mask( pdca_channel_num_t pdca_ch_number)



6.3.8 Function pdca_channel_is_enabled()

Check if PDCA channel is enabled.

bool pdca_channel_is_enabled( pdca_channel_num_t pdca_ch_number)


Data direction Parameter name Description[in] pdca_ch_number PDCA channel number to query


13

Table 6-10. Return Values

Return value Descriptiontrue PDCA channel is enabled

false PDCA channel is disabled

6.3.9 Function pdca_channel_read_load_size()

Read PDCA channel load values from hardware.

uint32_t pdca_channel_read_load_size( pdca_channel_num_t pdca_ch_number)

Each channel has a 16-bit Transfer Counter Register (TCR). This register must be written with the numberof transfers to be performed. The TCR register should contain the number of data items to be transferredindependently of the transfer size. The TCR can be read at any time during transfer to see the number of remainingtransfers.



Returns Size of the data block to load.

Note The size of a data item is held in the channel config structure. See pdca_channel_set_config andBasic use case for more deatils.

6.3.10 Function pdca_channel_read_reload_size()

Read PDCA channel reload values from hardware.

uint32_t pdca_channel_read_reload_size( pdca_channel_num_t pdca_ch_number)



Returns Size of the data block to reload.

6.3.11 Function pdca_channel_set_callback()

Set a callback for the specified PDCA channel.

void pdca_channel_set_callback(


14

pdca_channel_num_t pdca_ch_number, pdca_callback_t callback, uint8_t irq_line, uint8_t irq_level, const pdca_channel_interrupt_mask_t pdca_channel_interrupt_mask)


Data direction Parameter name Description[in] pdca_ch_number PDCA channel number (range 0

15)

[in] callback callback function pointer

[in] irq_line interrupt line

[in] irq_level interrupt level

[in] pdca_channel_interrupt_mask Interrupts to be enabled

6.3.12 Function pdca_channel_set_config()

Configure the specified PDCA channel.

void pdca_channel_set_config( pdca_channel_num_t pdca_ch_number, const pdca_channel_config_t * cfg)



[in] cfg Pointer to a PDCA channelconfiguration structure

6.3.13 Function pdca_channel_write_load()

Write PDCA channel load values to hardware.

void pdca_channel_write_load( pdca_channel_num_t pdca_ch_number, volatile void * addr, uint32_t size)



[in] addr Address where data to load isstored

[in] size Size of the data block to load

6.3.14 Function pdca_channel_write_reload()


15

Write PDCA channel reload values to hardware.

void pdca_channel_write_reload( pdca_channel_num_t pdca_ch_number, volatile void * addr, uint32_t size)



[in] addr Address where data to load isstoredr

[in] size Size of the data block to load

6.3.15 Function pdca_disable()

Disable the PDCA module.

void pdca_disable( Pdca * pdca)


Data direction Parameter name Description[in] pdca Base address of the PDCA module

6.3.16 Function pdca_enable()

Disable the PDCA module.

void pdca_enable( Pdca * pdca)


Data direction Parameter name Description[in] pdca Base address of the PDCA module

6.3.17 Function pdca_get_channel_status()

Get the PDCA channel transfer enable status.

enum pdca_channel_status pdca_get_channel_status( pdca_channel_num_t pdca_ch_number)




16

Returns 1 if channel transfer is enabled.0 if channel transfer is disabled.

6.4 Enumeration Definitions

6.4.1 Enum pdca_channel_status

PDCA channel status.

Table 6-20. Members

Enum value DescriptionPDCA_CH_FREE PDCA channel disabled.

PDCA_CH_BUSY PDCA channel enabled but transfer is on-going.

PDCA_CH_COUNTER_RELOAD_IS_ZERO PDCA channel counter reload is zero.

PDCA_CH_TRANSFER_COMPLETED PDCA channel has completed a block transfer.

PDCA_CH_TRANSFER_ERROR PDCA channel failed to complete a blocktransfer.


17

7. Extra Information for Peripheral DMA Controller Driver

7.1 AcronymsBelow is a table listing the acronyms used in this module, along with their intended meanings.

Acronym DefinitionDMA Direct Memory Access

QSG Quick Start Guide

7.2 DependenciesThis driver has the following dependencies:

● System Clock Management (Sysclock)

● Sleep Manager (Sleepmgr)

7.3 ErrataThere are no errata related to this driver.

7.4 Module HistoryAn overview of the module history is presented in the table below, with details on the enhancements and fixesmade to the module since its first release. The current version of this corresponds to the newest version in thetable.

ChangelogInitial document release


18

8. Examples for Peripheral DMA ControllerThis is a list of the available Quick Start Guides (QSGs) and example applications for SAM4L Peripheral DMAController (PDCA). QSGs are simple examples with step-by-step instructions to configure and use this driver ina selection of use cases. Note that QSGs can be compiled as a standalone application or be added to the userapplication.

● Peripheral DMA Controller Example

8.1 Peripheral DMA Controller Example

8.1.1 PurposeThe ASF example in pdca/pdca_usart_example demonstrates how to use PDCA driver to send data to the USART.

8.1.2 RequirementsThis example can be used on SAM4L series.

8.1.3 DescriptionThe SAM4L controller sends data in ascii_anim1.h and ascii_anim2.h from USART to the terminal.

8.1.4 Usage

1. Build the program and download it into the evaluation board.

2. On the computer, open, and configure a terminal application (e.g., HyperTerminal on Microsoft® Windows®)with these settings:

● 115200 bauds

● 8 bits of data

● No parity

● 1 stop bit

● No flow control

3. In the terminal window, the following text should appear (values depend on the board and chip used):

-- PDCA_USART Example xxx -- -- xxxxxx-xx -- Compiled: xxx xx xxxx xx:xx:xx --

4. The sent text should appear.


19

9. Quickstart guide for SAM PDCA driverThis is the quickstart guide for the SAM PDCA driver, with step-by-step instructions on how to configure and usethe driver in a selection of use cases.The use cases contain several code fragments. The code fragments in the steps for setup can be copied into acustom initialization function, while the steps for usage can be copied into, e.g., the main application function.

9.1 Basic use caseIn this basic use case, the PDCA module and channel are configured for:

● Select USART2 as peripheral

● Interrupt-based handling

9.1.1 Prerequisites

● System Clock Management (Sysclock)

9.2 Setup steps

9.2.1 Example codeAdd to application C-file:

void pdca_callback(void){ //Get PDCA RX channel status and check if PDCA transfer complete if (status == PDCA_CH_TRANSFER_COMPLETED) { pdca_channel_write_load(PDCA_RX_CHANNEL, g_uc_pdc_buffer, BUFFER_SIZE); pdca_channel_write_load(PDCA_TX_CHANNEL, g_uc_pdc_buffer, BUFFER_SIZE); }}void pdca_setup(void){ pdca_enable(PDCA);

pdca_channel_write_config(PDCA_RX_CHANNEL, &PDCA_RX_CONFIGS); pdca_channel_write_config(PDCA_TX_CHANNEL, &PDCA_TX_CONFIGS);

pdca_channel_set_callback(PDCA_RX_CHANNEL, pdca_tranfer_done, PDCA_0_IRQn, 1, PDCA_IER_TRC);

pdca_channel_enable(PDCA_RX_CHANNEL); pdca_channel_enable(PDCA_TX_CHANNEL);}

9.2.2 Workflow

1. Define the interrupt callback function in the application:

void pdca_callback(void){ //Get PDCA RX channel status and check if PDCA transfer complete if (status == PDCA_CH_TRANSFER_COMPLETED) { pdca_channel_write_load(PDCA_RX_CHANNEL, g_uc_pdc_buffer, BUFFER_SIZE); pdca_channel_write_load(PDCA_TX_CHANNEL, g_uc_pdc_buffer, BUFFER_SIZE); }}


20

2. Enable PDCA module:

pdca_enable(PDCA);

Note Includes enabling the module clock and clock sleep mode.

3. Configure PDCA channel with specified mode:

pdca_channel_write_config(PDCA_RX_CHANNEL, &PDCA_RX_CONFIGS); pdca_channel_write_config(PDCA_TX_CHANNEL, &PDCA_TX_CONFIGS);

4. Set the PDCA callback function and enable PDCA interrupt.

pdca_channel_set_callback(PDCA_RX_CHANNEL, pdca_tranfer_done, PDCA_0_IRQn, 1, PDCA_IER_TRC);

5. Enable PDCA channel:

pdca_channel_enable(PDCA_RX_CHANNEL); pdca_channel_enable(PDCA_TX_CHANNEL);


21

Index

EEnumeration Definitions

pdca_channel_status, 16

FFunction Definitions

pdca_channel_clear_error, 10pdca_channel_disable, 11pdca_channel_disable_interrupt, 11pdca_channel_enable, 11pdca_channel_enable_interrupt, 11pdca_channel_get_handler, 12pdca_channel_get_interrupt_mask, 12pdca_channel_is_enabled, 12pdca_channel_read_load_size, 13pdca_channel_read_reload_size, 13pdca_channel_set_callback, 13pdca_channel_set_config, 14pdca_channel_write_load, 14pdca_channel_write_reload, 14pdca_disable, 15pdca_enable, 15pdca_get_channel_status, 15

SStructure Definitions

pdca_channel_config_t, 10

TType Definitions

pdca_callback_t, 10pdca_channel_interrupt_mask_t, 10pdca_channel_num_t, 10


22

Document Revision History

Doc. Rev. Date Comments42313A 05/2014 Initial document release

Atmel Corporation 1600 Technology Drive, San Jose, CA 95110 USA T: (+1)(408) 441.0311 F: (+1)(408) 436.4200 | www.atmel.com

© 2014 Atmel Corporation. All rights reserved. / Rev.: 42313A-MCU-05/2014

Atmel®, Atmel logo and combinations thereof, Enabling Unlimited Possibilities®, and others are registered trademarks or trademarks of Atmel Corporation or itssubsidiaries. Windows® is a registered trademark of Microsoft Corporation in U.S. and or other countries. Other terms and product names may be trademarksof others.

Disclaimer: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted bythis document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMELASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THEIMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OFINFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes norepresentations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and products descriptions atany time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not beused in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life.

www.atmel.com

at07893: sam4l peripheral dma controller (pdca) asf...

Documents