/**
 * \file
 *
 * \brief SAM Peripheral DMA Controller (PDC) driver.
 *
 * Copyright (c) 2011-2018 Microchip Technology Inc. and its subsidiaries.
 *
 * \asf_license_start
 *
 * \page License
 *
 * Subject to your compliance with these terms, you may use Microchip
 * software and any derivatives exclusively with Microchip products.
 * It is your responsibility to comply with third party license terms applicable
 * to your use of third party software (including open source software) that
 * may accompany Microchip software.
 *
 * THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES,
 * WHETHER EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE,
 * INCLUDING ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY,
 * AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL MICROCHIP BE
 * LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE, INCIDENTAL OR CONSEQUENTIAL
 * LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND WHATSOEVER RELATED TO THE
 * SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS BEEN ADVISED OF THE
 * POSSIBILITY OR THE DAMAGES ARE FORESEEABLE.  TO THE FULLEST EXTENT
 * ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN ANY WAY
 * RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY,
 * THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE.
 *
 * \asf_license_stop
 *
 */
/*
 * Support and FAQ: visit <a href="https://www.microchip.com/support/">Microchip 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 */