SMART ARM-based Microcontrollers AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver APPLICATION NOTE Introduction ® ® This driver for Atmel | SMART ARM -based microcontrollers provides an interface for the configuration and management of the the Peripheral Direct Memory Access (DMA) Controller (PDC) module. The PDC transfers data between on-chip serial peripherals and the on and/or off-chip memories. The link between the PDC and a serial peripheral is operated by the AHB to ABP bridge. This module: • Performs transfers to/from APB communication serial peripherals • Supports half-duplex and full-duplex peripherals Devices from the following series can use this module: • Atmel | SMART SAM3A • Atmel | SMART SAM3N • Atmel | SMART SAM3S • Atmel | SMART SAM3U • Atmel | SMART SAM3X • Atmel | SMART SAM4E • Atmel | SMART SAM4N • Atmel | SMART SAM4S • Atmel | SMART SAM G The outline of this documentation is as follows: • Prerequisites • Module Overview • Special Considerations • Extra Information • Examples • API Overview Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 Table of Contents Introduction......................................................................................................................1 1. Software License....................................................................................................... 4 2. Prerequisites..............................................................................................................5 3. Module Overview....................................................................................................... 6 4. Special Considerations.............................................................................................. 7 5. Extra Information....................................................................................................... 8 6. Examples................................................................................................................... 9 7. API Overview........................................................................................................... 10 7.1. 7.2. 7.3. Variable and Type Definitions..................................................................................................... 10 7.1.1. Type pdc_packet_t.......................................................................................................10 Structure Definitions................................................................................................................... 10 7.2.1. Struct pdc_packet........................................................................................................ 10 Function Definitions....................................................................................................................10 7.3.1. Function pdc_disable_transfer().................................................................................. 10 7.3.2. Function pdc_enable_transfer()...................................................................................10 7.3.3. Function pdc_read_rx_counter().................................................................................. 11 7.3.4. Function pdc_read_rx_next_counter()......................................................................... 11 7.3.5. Function pdc_read_rx_next_ptr()................................................................................. 11 7.3.6. Function pdc_read_rx_ptr()......................................................................................... 12 7.3.7. Function pdc_read_status()......................................................................................... 12 7.3.8. Function pdc_read_tx_counter()..................................................................................12 7.3.9. Function pdc_read_tx_next_counter()......................................................................... 13 7.3.10. Function pdc_read_tx_next_ptr().................................................................................13 7.3.11. Function pdc_read_tx_ptr()..........................................................................................13 7.3.12. 7.3.13. 7.3.14. Function pdc_rx_clear_cnt()........................................................................................ 13 Function pdc_rx_init().................................................................................................. 14 Function pdc_tx_init().................................................................................................. 14 8. Extra Information for Peripheral DMA Controller..................................................... 15 8.1. 8.2. 8.3. 8.4. Acronyms....................................................................................................................................15 Dependencies.............................................................................................................................15 Errata..........................................................................................................................................15 Module History............................................................................................................................15 9. Examples for Peripheral DMA Controller.................................................................16 9.1. 9.2. Quick Start Guide for PDC - Basic............................................................................................. 16 Peripheral DMA Controller Example...........................................................................................17 9.2.1. Purpose....................................................................................................................... 17 9.2.2. Requirements.............................................................................................................. 17 Atmel AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver [APPLICATION NOTE] Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 2 9.2.3. Description...................................................................................................................17 9.2.4. Usage.......................................................................................................................... 17 10. Document Revision History..................................................................................... 18 Atmel AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver [APPLICATION NOTE] Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 3 1. Software License 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. 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 A PARTICULAR PURPOSE AND NON-INFRINGEMENT 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. Atmel AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver [APPLICATION NOTE] Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 4 2. Prerequisites There are no prerequisites for this module. Atmel AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver [APPLICATION NOTE] Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 5 3. Module Overview The user interface of each PDC channel is integrated into the user interface of the peripheral it serves. The user interface of unidirectional channels (receive only or transmit only), contains two 32-bit memory pointers and two 16-bit counters, one set (pointer, counter) for current transfer and one set (pointer, counter) for next transfer. The bidirectional channel user interface contains four 32-bit memory pointers and four 16-bit counters. Each set (pointer, counter) is used by current transmit, next transmit, current receive and next receive. Using the PDC removes processor overhead by reducing its intervention during the transfer. This significantly reduces the number of clock cycles required for a data transfer, which improves microcontroller performance. To launch a transfer, the peripheral triggers its associated PDC channels by using transmit and receive signals. When the programmed data is transferred, an end of transfer interrupt is generated by the peripheral itself. Atmel AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver [APPLICATION NOTE] Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 6 4. Special Considerations There are no special considerations for this module. Atmel AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver [APPLICATION NOTE] Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 7 5. Extra Information For extra information, see Extra Information for Peripheral DMA Controller. This includes: • Acronyms • Dependencies • Errata • Module History Atmel AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver [APPLICATION NOTE] Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 8 6. Examples For a list of examples related to this driver, see Examples for Peripheral DMA Controller. Atmel AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver [APPLICATION NOTE] Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 9 7. API Overview 7.1. Variable and Type Definitions 7.1.1. Type pdc_packet_t typedef struct pdc_packet pdc_packet_t 7.2. Structure Definitions 7.2.1. Struct pdc_packet Table 7-1 Members Type Name Description uint32_t ul_addr Start address of the transfer packet data. uint32_t ul_size Transfer packet size (in units of the peripheral data width). 7.3. Function Definitions 7.3.1. Function pdc_disable_transfer() Disable PDC transfers (TX and/or RX). void pdc_disable_transfer( Pdc * p_pdc, uint32_t ul_controls) Table 7-2 Parameters Data direction Parameter name Description 7.3.2. [out] p_pdc Device structure pointer [in] ul_controls Transfer directions (bit PERIPH_PTCR_TXTDIS, bit PERIPH_PTCR_TXTDIS) Function pdc_enable_transfer() Enable PDC transfers (TX and/or RX). void pdc_enable_transfer( Pdc * p_pdc, uint32_t ul_controls) Note: It is forbidden to set both TXTEN and RXTEN for a half duplex peripheral. Atmel AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver [APPLICATION NOTE] Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 10 Table 7-3 Parameters Data direction Parameter name Description 7.3.3. [out] p_pdc Device structure pointer [in] ul_controls Transfer directions (bit PERIPH_PTCR_RXTEN and bit PERIPH_PTCR_TXTEN) Function pdc_read_rx_counter() Return Receive Counter Register (RCR) value. uint32_t pdc_read_rx_counter( Pdc * p_pdc) Table 7-4 Parameters Data direction Parameter name Description [in] p_pdc Device structure pointer Returns Receive Counter Register value. 7.3.4. Function pdc_read_rx_next_counter() Return Receive Next Counter Register (RNCR) value. uint32_t pdc_read_rx_next_counter( Pdc * p_pdc) Table 7-5 Parameters Data direction Parameter name Description [in] p_pdc Device structure pointer Returns Receive Next Counter Register value. 7.3.5. Function pdc_read_rx_next_ptr() Return Receive Next Pointer Register (RNPR) value. uint32_t pdc_read_rx_next_ptr( Pdc * p_pdc) Table 7-6 Parameters Data direction Parameter name Description [in] p_pdc Device structure pointer Returns Receive Next Pointer Register value. Atmel AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver [APPLICATION NOTE] Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 11 7.3.6. Function pdc_read_rx_ptr() Return Receive Pointer Register (RPR) value. uint32_t pdc_read_rx_ptr( Pdc * p_pdc) Table 7-7 Parameters Data direction Parameter name Description [in] p_pdc Device structure pointer Returns Receive Pointer Register value. 7.3.7. Function pdc_read_status() Read PDC status. uint32_t pdc_read_status( Pdc * p_pdc) Table 7-8 Parameters Data direction Parameter name Description [in] p_pdc Device structure pointer Name Description Bit RXTEN Receiver Transfer Enabled 8 TXTEN Transmitter Transfer Enabled 1 Returns PDC status register bit map. 7.3.8. Function pdc_read_tx_counter() Return Transmit Counter Register (TCR) value. uint32_t pdc_read_tx_counter( Pdc * p_pdc) Table 7-9 Parameters Data direction Parameter name Description [in] p_pdc Device structure pointer Returns Transmit Counter Register value. Atmel AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver [APPLICATION NOTE] Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 12 7.3.9. Function pdc_read_tx_next_counter() Return Transmit Next Counter Register (TNCR) value. uint32_t pdc_read_tx_next_counter( Pdc * p_pdc) Table 7-10 Parameters Data direction Parameter name Description [in] p_pdc Device structure pointer Returns Transmit Next Counter Register value. 7.3.10. Function pdc_read_tx_next_ptr() Return Transmit Next Pointer Register (TNPR) value. uint32_t pdc_read_tx_next_ptr( Pdc * p_pdc) Table 7-11 Parameters Data direction Parameter name Description [in] p_pdc Device structure pointer Returns Transmit Next Pointer Register value. 7.3.11. Function pdc_read_tx_ptr() Return Transmit Pointer Register (TPR) value. uint32_t pdc_read_tx_ptr( Pdc * p_pdc) Table 7-12 Parameters Data direction Parameter name Description [in] p_pdc Device structure pointer Returns Transmit Pointer Register value. 7.3.12. Function pdc_rx_clear_cnt() Clear PDC buffer receive counter. void pdc_rx_clear_cnt( Pdc * p_pdc) Atmel AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver [APPLICATION NOTE] Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 13 Table 7-13 Parameters 7.3.13. Data direction Parameter name Description [out] p_pdc Device structure pointer Function pdc_rx_init() Configure PDC for data receive. void pdc_rx_init( Pdc * p_pdc, pdc_packet_t * p_packet, pdc_packet_t * p_next_packet) Table 7-14 Parameters Data direction Parameter name Description 7.3.14. [out] p_pdc Device structure pointer [in] p_packet Pointer to packet information for current buffer register set. Use NULL to leave unaltered. [in] p_next_packet Pointer to packet information for next buffer register set. Use NULL to leave unaltered. Function pdc_tx_init() Configure PDC for data transmit. void pdc_tx_init( Pdc * p_pdc, pdc_packet_t * p_packet, pdc_packet_t * p_next_packet) Table 7-15 Parameters Data direction Parameter name Description [out] p_pdc Device structure pointer [in] p_packet Pointer to packet information for current buffer register set. Use NULL to leave unaltered. [in] p_next_packet Pointer to packet information for next buffer register set. Use NULL to leave unaltered. Atmel AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver [APPLICATION NOTE] Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 14 8. Extra Information for Peripheral DMA Controller 8.1. Acronyms Below is a table listing the acronyms used in this module, along with their intended meanings. 8.2. Acronym Definition AHB Advanced High-performance Bus AMBA Advanced Microcontroller Bus Architecture QSG Quick Start Guide RCR Receive Counter Register RNCR Return Receive Next Counter Register RNPR Receive Next Pointer Register RPR Receive Pointer Register TCR Transmit Counter Register TNCR Transmit Next Counter Register TNPR Transmit Next Pointer Register TPR Transmit Pointer Register Dependencies This driver has the following dependencies: • 8.3. None Errata There are no errata related to this driver. 8.4. Module History An overview of the module history is presented in the table below, with details on the enhancements and fixes made to the module since its first release. The current version of this corresponds to the newest version in the table. Changelog Initial document release Atmel AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver [APPLICATION NOTE] Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 15 9. Examples for Peripheral DMA Controller This is a list of the available Quick Start guides (QSGs) and example applications for SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver. QSGs are simple examples with step-by-step instructions to configure and use this driver in a selection of use cases. Note that a QSG can be compiled as a standalone application or be added to the user application. • • 9.1. Quick Start Guide for PDC - Basic Peripheral DMA Controller Example Quick Start Guide for PDC - Basic This is the quickstart guide for SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver with step-by-step instructions on how to configure and use the driver. A handler is required for the interrupt, below is a simple example: void console_uart_irq_handler(void) { /* Get UART status and check if PDC receive buffer is full */ if ((uart_get_status(CONSOLE_UART) & UART_SR_RXBUFF) == UART_SR_RXBUFF) { /* Configure PDC for data transfer (RX and TX) */ pdc_rx_init(g_p_uart_pdc, &g_pdc_uart_packet, NULL); pdc_tx_init(g_p_uart_pdc, &g_pdc_uart_packet, NULL); } } First initialise the board: sysclk_init(); board_init(); Now setup the PDC registers: /* Get pointer to UART PDC register base */ g_p_uart_pdc = uart_get_pdc_base(CONSOLE_UART); /* Initialize PDC data packet for transfer */ g_pdc_uart_packet.ul_addr = (uint32_t) g_uc_pdc_buffer; g_pdc_uart_packet.ul_size = BUFFER_SIZE; /* Configure PDC for data receive */ pdc_rx_init(g_p_uart_pdc, &g_pdc_uart_packet, NULL); /* Enable PDC transfers */ pdc_enable_transfer(g_p_uart_pdc, PERIPH_PTCR_RXTEN | PERIPH_PTCR_TXTEN); Enable UART IRQ: uart_enable_interrupt(CONSOLE_UART, UART_IER_RXBUFF); Enable UART interrupt NVIC_EnableIRQ(CONSOLE_UART_IRQn); Atmel AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver [APPLICATION NOTE] Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 16 Once the required number of bytes have been transferred, an interrupt is triggered and the handler will run. The main program may execute other code or be busy-waiting: while (1) { } 9.2. Peripheral DMA Controller Example 9.2.1. Purpose The pdc_uart example demonstrates how to use PDC driver to receive/send data from/to the UART. 9.2.2. Requirements This example can be used on any SAM3/4 boards. 9.2.3. Description The SAM controller waits for BUFFER_SIZE data to receive from the UART. As soon as the expected amount of data is received, the whole buffer is sent back to the terminal. 9.2.4. Usage 1. 2. 3. Build the program and download it into the evaluation board. ® On the computer, open, and configure a terminal application (e.g., HyperTerminal on Microsoft ® Windows ) with these settings: • 115200 baud • 8 bits of data • No parity • 1 stop bit • No flow control In the terminal window, the following text should appear (values depend on the board and chip used): -- PDC Uart Example xxx --- xxxxxx-xx -- Compiled: xxx xx xxxx xx:xx:xx -- 4. The sent text should appear. Atmel AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver [APPLICATION NOTE] Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 17 10. Document Revision History Doc. Rev. Date Comments 42316B 07/2015 Updated title of application note and added list of supported devices 42316A 05/2014 Initial document release Atmel AT08642: SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver [APPLICATION NOTE] Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 18 Atmel Corporation © 1600 Technology Drive, San Jose, CA 95110 USA T: (+1)(408) 441.0311 F: (+1)(408) 436.4200 | www.atmel.com 2015 Atmel Corporation. / Rev.: Atmel-42316B-SAM3A-3N-3S-3U-3X-4E-4N-4S-G-Peripheral-DMA-Controller-PDC-Driver_AT08642_Application Note-07/2015 ® ® Atmel , Atmel logo and combinations thereof, Enabling Unlimited Possibilities , and others are registered trademarks or trademarks of Atmel Corporation in U.S. and ® ® ® other countries. ARM , ARM Connected , and others are registered trademarks of ARM Ltd. Windows is a registered trademark of Microsoft Corporation in U.S. and or other countries. Other terms and product names may be trademarks of 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 by this 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, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 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 OF INFORMATION) 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 no representations 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 at any 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 be used in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life. SAFETY-CRITICAL, MILITARY, AND AUTOMOTIVE APPLICATIONS DISCLAIMER: Atmel products are not designed for and will not be used in connection with any applications where the failure of such products would reasonably be expected to result in significant personal injury or death (“Safety-Critical Applications”) without an Atmel officer's specific written consent. Safety-Critical Applications include, without limitation, life support devices and systems, equipment or systems for the operation of nuclear facilities and weapons systems. Atmel products are not designed nor intended for use in military or aerospace applications or environments unless specifically designated by Atmel as military-grade. Atmel products are not designed nor intended for use in automotive applications unless specifically designated by Atmel as automotive-grade.