Diff: mbed-dev/targets/TARGET_Atmel/TARGET_SAM_CortexM4/drivers/pdc/pdc.h

Revision:

18:6a4db94011d3

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mbed-dev/targets/TARGET_Atmel/TARGET_SAM_CortexM4/drivers/pdc/pdc.h	Sun May 14 23:18:57 2017 +0000
@@ -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&reg; | SMART ARM&reg;-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 */