t
Fork of mbed-dev by
Diff: targets/TARGET_Atmel/TARGET_SAM_CortexM4/drivers/pdc/pdc.h
- Revision:
- 149:156823d33999
- Parent:
- 107:414e9c822e99
diff -r 21d94c44109e -r 156823d33999 targets/TARGET_Atmel/TARGET_SAM_CortexM4/drivers/pdc/pdc.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/targets/TARGET_Atmel/TARGET_SAM_CortexM4/drivers/pdc/pdc.h Fri Oct 28 11:17:30 2016 +0100 @@ -0,0 +1,323 @@ +/** + * \file + * + * \brief SAM Peripheral DMA Controller (PDC) driver. + * + * Copyright (c) 2011-2015 Atmel Corporation. All rights reserved. + * + * \asf_license_start + * + * \page 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. + * + * \asf_license_stop + * + */ +/* + * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a> + */ + +#ifndef PDC_H_INCLUDED +#define PDC_H_INCLUDED + +/** + * \defgroup asfdoc_sam_drivers_pdc_group SAM3A/3N/3S/3U/3X/4E/4N/4S/G Peripheral DMA Controller (PDC) Driver + * 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: + * - \ref asfdoc_sam_drivers_pdc_prerequisites + * - \ref asfdoc_sam_drivers_pdc_module_overview + * - \ref asfdoc_sam_drivers_pdc_special_considerations + * - \ref asfdoc_sam_drivers_pdc_extra_info + * - \ref asfdoc_sam_drivers_pdc_examples + * - \ref asfdoc_sam_drivers_pdc_api_overview + * + * + * \section asfdoc_sam_drivers_pdc_prerequisites Prerequisites + * + * There are no prerequisites for this module. + * + * + * \section asfdoc_sam_drivers_pdc_module_overview 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. + * + * \section asfdoc_sam_drivers_pdc_special_considerations Special Considerations + * There are no special considerations for this module. + * + * + * \section asfdoc_sam_drivers_pdc_extra_info Extra Information + + * For extra information, see \ref asfdoc_sam_drivers_pdc_extra. This includes: + * - \ref asfdoc_sam_drivers_pdc_extra_acronyms + * - \ref asfdoc_sam_drivers_pdc_extra_dependencies + * - \ref asfdoc_sam_drivers_pdc_extra_errata + * - \ref asfdoc_sam_drivers_pdc_extra_history + * + * \section asfdoc_sam_drivers_pdc_examples Examples + * + * For a list of examples related to this driver, see + * \ref asfdoc_sam_drivers_pdc_exqsg. + * + * + * \section asfdoc_sam_drivers_pdc_api_overview API Overview + * @{ + */ + +#include <compiler.h> + +/// @cond +/**INDENT-OFF**/ +#ifdef __cplusplus +extern "C" { +#endif +/**INDENT-ON**/ +/// @endcond + + /** + * \brief PDC data packet for transfer. + */ + typedef struct pdc_packet { + /** Start address of the transfer packet data. */ + uint32_t ul_addr; + /** Transfer packet size (in units of the peripheral data width). */ + uint32_t ul_size; + } pdc_packet_t; + + void pdc_tx_init(Pdc *p_pdc, pdc_packet_t *p_packet, + pdc_packet_t *p_next_packet); + void pdc_rx_init(Pdc *p_pdc, pdc_packet_t *p_packet, + pdc_packet_t *p_next_packet); + void pdc_rx_clear_cnt(Pdc *p_pdc); + void pdc_enable_transfer(Pdc *p_pdc, uint32_t ul_controls); + void pdc_disable_transfer(Pdc *p_pdc, uint32_t ul_controls); + uint32_t pdc_read_status(Pdc *p_pdc); + uint32_t pdc_read_rx_ptr(Pdc *p_pdc); + uint32_t pdc_read_rx_counter(Pdc *p_pdc); + uint32_t pdc_read_tx_ptr(Pdc *p_pdc); + uint32_t pdc_read_tx_counter(Pdc *p_pdc); + uint32_t pdc_read_rx_next_ptr(Pdc *p_pdc); + uint32_t pdc_read_rx_next_counter(Pdc *p_pdc); + uint32_t pdc_read_tx_next_ptr(Pdc *p_pdc); + uint32_t pdc_read_tx_next_counter(Pdc *p_pdc); + +/// @cond +/**INDENT-OFF**/ +#ifdef __cplusplus +} +#endif +/**INDENT-ON**/ +/// @endcond + +/** @} */ + +/** + * \page asfdoc_sam_drivers_pdc_extra Extra Information for Peripheral DMA Controller + * + * \section asfdoc_sam_drivers_pdc_extra_acronyms Acronyms + * Below is a table listing the acronyms used in this module, along with their + * intended meanings. + * + * <table> + * <tr> + * <th>Acronym</th> + * <th>Definition</th> + * </tr> + * </tr> + * <tr> + * <td>AHB</td> + * <td>Advanced High-performance Bus</td> + * </tr> + * <tr> + * <td>AMBA</td> + * <td> Advanced Microcontroller Bus Architecture</td> + * </tr> + * <tr> + * <td>QSG</td> + * <td>Quick Start Guide</td> + * + * </tr> + * <tr> + * <td>RCR</td> + * <td>Receive Counter Register</td> + * </tr> + * <tr> + * <td>RNCR</td> + * <td>Return Receive Next Counter Register</td> + * </tr> + * <tr> + * <td>RNPR</td> + * <td>Receive Next Pointer Register</td> + * </tr> + * <tr> + * <td>RPR</td> + * <td>Receive Pointer Register</td> + * </tr> + * <tr> + * <td>TCR</td> + * <td>Transmit Counter Register</td> + * </tr> + * <tr> + * <td>TNCR</td> + * <td>Transmit Next Counter Register</td> + * </tr> + * <tr> + * <td>TNPR</td> + * <td>Transmit Next Pointer Register</td> + * </tr> + * <tr> + * <td>TPR</td> + * <td>Transmit Pointer Register</td> + * </tr> + * </table> + * + * + * \section asfdoc_sam_drivers_pdc_extra_dependencies Dependencies + * This driver has the following dependencies: + * + * - None + * + * + * \section asfdoc_sam_drivers_pdc_extra_errata Errata + * There are no errata related to this driver. + * + * + * \section asfdoc_sam_drivers_pdc_extra_history 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. + * + * <table> + * <tr> + * <th>Changelog</th> + * </tr> + * <tr> + * <td>Initial document release</td> + * </tr> + * </table> + * + * + * + * \page asfdoc_sam_pdc_quickstart_basic Quick Start Guide for PDC - Basic + * This is the quickstart guide for \ref asfdoc_sam_drivers_pdc_group + * 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: + * \snippet pdc_uart_example.c int_handler + * + * First initialise the board: + * + * \snippet pdc_uart_example.c board_setup + * + * Now setup the PDC registers: + * \snippet pdc_uart_example.c pdc_config + * + * Enable UART IRQ: + * \snippet pdc_uart_example.c uart_irq + * + * Enable UART interrupt + * \snippet pdc_uart_example.c uart_nvic_irq + * + * 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: + * + * \snippet pdc_uart_example.c busy_waiting + * + * \page asfdoc_sam_drivers_pdc_exqsg Examples for Peripheral DMA Controller + * + * This is a list of the available Quick Start guides (QSGs) and example + * applications for \ref asfdoc_sam_drivers_pdc_group. 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. + * + * - \subpage asfdoc_sam_pdc_quickstart_basic + * - \subpage asfdoc_sam_drivers_pdc_example + * + * + * \page asfdoc_sam_drivers_pdc_document_revision_history Document Revision History + * + * <table> + * <tr> + * <th>Doc. Rev.</td> + * <th>Date</td> + * <th>Comments</td> + * </tr> + * <tr> + * <td>42316B</td> + * <td>07/2015</td> + * <td>Updated title of application note and added list of supported devices</td> + * </tr> + * <tr> + * <td>42316A</td> + * <td>05/2014</td> + * <td>Initial document release</td> + * </tr> + * </table> + * + */ + +#endif /* PDC_H_INCLUDED */