circuitpython/atmel-samd/asf/sam0/drivers/dma/dma_sam_b.h

/**
 * \file
 *
 * \brief Direct Memory Access Controller Driver for SAMB
 *
 * Copyright (C) 2015-2016 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 DMA_H_INCLUDED
#define DMA_H_INCLUDED

#ifdef __cplusplus
extern "C" {
#endif

/**
 * \defgroup asfdoc_samb_dma_group SAM Direct Memory Access Controller Driver (DMAC)
 *
 * This driver for Atmel&reg; | SMART SAM devices provides an interface for the configuration
 * and management of the Direct Memory Access Controller(DMAC) module within
 * the device. The DMAC can transfer data between memories and peripherals, and
 * thus off-load these tasks from the CPU. The module supports peripheral to
 * peripheral, peripheral to memory, memory to peripheral, and memory to memory
 * transfers.
 *
 * The following peripherals are used by the DMAC Driver:
 * - DMAC (Direct Memory Access Controller)
 *
 * The following devices can use this module:
 *  - Atmel | SMART SAM B11
 *
 * The outline of this documentation is as follows:
 * - \ref asfdoc_samb_dma_prerequisites
 * - \ref asfdoc_samb_dma_module_overview
 * - \ref asfdoc_samb_dma_special_considerations
 * - \ref asfdoc_samb_dma_extra_info
 * - \ref asfdoc_samb_dma_examples
 * - \ref asfdoc_samb_dma_api_overview
 *
 *
 * \section asfdoc_samb_dma_prerequisites Prerequisites
 *
 * There are no prerequisites for this module.
 *
 *
 * \section asfdoc_samb_dma_module_overview Module Overview
 *
 * SAM devices with DMAC enables high data transfer rates with minimum
 * CPU intervention and frees up CPU time. With access to all peripherals,
 * the DMAC can handle automatic transfer of data to/from modules.
 * It supports static and incremental addressing for both source and
 * destination.
 *
 * The DMAC when used with peripheral triggers, provides a
 * considerable advantage by reducing the power consumption and performing
 * data transfer in the background.
 * The CPU can remain in sleep during this time to reduce power consumption.
 *
 * <table>
 *    <tr>
 *      <th>Device</th>
 *      <th>Dma channel number</th>
 *    </tr>
 *    <tr>
 *      <td>SAMB11</td>
 *      <td>4</td>
 *    </tr>
 * </table>
 * The DMA channel operation can be suspended at any time by software, 
 * or after selectable descriptor execution. The DMAC driver for SAM 
 * supports four types of transfers such as peripheral to peripheral,
 * peripheral to memory, memory to peripheral, and memory to memory.
 *
 * The basic transfer unit is a beat which is defined as a single bus access.
 * There can be multiple beats in a single block transfer and multiple block
 * transfers in a DMA transaction.
 * DMA transfer is based on descriptors, which holds transfer properties
 * such as the source and destination addresses, transfer counter, and other
 * additional transfer control information.
 * The descriptors can be static or linked. When static, a single block transfer
 * is performed. When linked, a number of transfer descriptors can be used to
 * enable multiple block transfers within a single DMA transaction.
 *
 * The implementation of the DMA driver is based on the idea that DMA channel
 * is a finite resource of entities with the same abilities. A DMA channel resource
 * is able to move a defined set of data from a source address to destination
 * address triggered by a transfer trigger. On the SAM devices there are 12
 * DMA resources available for allocation. Each of these DMA resources can trigger
 * interrupt callback routines.
 * The other main features are:
 *
 * - Selectable transfer trigger source
 *  - Software
 *  - Peripheral
 * - Tree level channel priority
 *  - Normal level
 *  - High level
 *  - Top level
 * - Optional interrupt generation on transfer complete, channel error
 * - Supports multi-buffer or circular buffer mode by linking multiple descriptors
 * - Beat size configurable as 8-bit, 16-bit, or 32-bit
 *
 * A simplified block diagram of the DMA Resource can be seen in
 * \ref asfdoc_samb_dma_module_block_diagram "the figure below".
 *
 * \anchor asfdoc_samb_dma_module_block_diagram
 * \dot
 * digraph overview {
 * splines = false;
 * rankdir=LR;
 *
 * mux1 [label="Transfer Trigger", shape=box];
 *
 * dma [label="DMA Channel", shape=polygon, sides=6, orientation=60, style=filled, fillcolor=darkolivegreen1, height=1, width=1];
 * descriptor [label="Transfer Descriptor", shape=box, style=filled, fillcolor=lightblue];
 *
 * mux1 -> dma;
 * descriptor -> dma;
 *
 * interrupt [label="Interrupt", shape=box];
 * events [label="Events", shape=box];
 *
 * dma:e -> interrupt:w;
 * dma:e -> events:w;
 *
 * {rank=same; descriptor dma}
 *
 * }
 * \enddot
 *
 * \subsection asfdoc_samb_dma_module_overview_dma_channels DMA Channels
 * The DMAC in each device consists of several DMA channels, which
 * along with the transfer descriptors defines the data transfer properties.
 * - The transfer control descriptor defines the source and destination
 * addresses, source and destination address increment settings, the
 * block transfer count
 * - Dedicated channel registers control the peripheral trigger source,
 * trigger mode settings, and channel priority level settings
 *
 * With a successful DMA resource allocation, a dedicated
 * DMA channel will be assigned. The channel will be occupied until the
 * DMA resource is freed. A DMA resource handle is used to identify the specific
 * DMA resource.
 * When there are multiple channels with active requests, the arbiter prioritizes
 * the channels requesting access to the bus.
 *
 * \subsection asfdoc_samb_dma_module_overview_dma_trigger DMA Triggers
 * DMA transfer can be started only when a DMA transfer request is acknowledged/granted by the arbiter. A
 * transfer request can be triggered from software, peripheral. There
 * are dedicated source trigger selections for each DMA channel usage.
 *
 * \subsection asfdoc_samb_dma_module_overview_dma_transfer_descriptor DMA Transfer Descriptor
 * The transfer descriptor resides in the SRAM and
 * defines these channel properties.
 *
 * <table>
 *   <tr>
 *     <th>Field name</th>
 *     <th>Field width</th>
 *   </tr>
 *   <tr>
 *     <td>Source Address</td>
 *     <td>32 bits</td>
 *   </tr>
 *   <tr>
 *     <td>Destination Address</td>
 *     <td>32 bits</td>
 *   </tr>
 *   <tr>
 *     <td>Block Transfer Counter</td>
 *     <td>32 bits</td>
 *   </tr>
 *   <tr>
 *     <td>Descriptor Next Address</td>
 *     <td>30 bits</td>
 *   </tr>
 *   <tr>
 *     <td>Block Transfer Interrupt</td>
 *     <td>1 bit</td>
 *   </tr>
 *   <tr>
 *     <td>Block Transfer Stop Control</td>
 *     <td>1 bit</td>
 *   </tr>
 * </table>
 *
 * Before starting a transfer, at least one descriptor should be configured.
 * After a successful allocation of a DMA channel, the transfer descriptor can
 * be added with a call to \ref dma_add_descriptor(). If there is a transfer
 * descriptor already allocated to the DMA resource, the descriptor will
 * be linked to the next descriptor address.
 *
 * \subsection asfdoc_samb_dma_module_overview_dma_output DMA Interrupts
 * Both an interrupt callback and an peripheral can be triggered by the
 * DMA transfer. Three types of callbacks are supported by the DMA driver:
 * transfer complete, channel suspend, and transfer error. Each of these callback
 * types can be registered and enabled for each channel independently through
 * the DMA driver API.
 *
 *
 * \section asfdoc_samb_dma_special_considerations Special Considerations
 *
 * There are no special considerations for this module.
 *
 *
 * \section asfdoc_samb_dma_extra_info Extra Information
 *
 * For extra information, see \ref asfdoc_samb_dma_extra. This includes:
 * - \ref asfdoc_samb_dma_extra_acronyms
 * - \ref asfdoc_samb_dma_extra_dependencies
 * - \ref asfdoc_samb_dma_extra_errata
 * - \ref asfdoc_samb_dma_extra_history
 *
 *
 * \section asfdoc_samb_dma_examples Examples
 *
 * For a list of examples related to this driver, see
 * \ref asfdoc_samb_dma_exqsg.
 *
 *
 * \section asfdoc_samb_dma_api_overview API Overview
 * @{
 */

#include <compiler.h>
#include <system_sam_b.h>
#include "conf_dma.h"

/** DMA IRQn number. */
#define PROV_DMA_CTRL0_IRQn		15

/** DMA invalid channel number. */
#define DMA_INVALID_CHANNEL        0xff

/** DMA peripheral index */
enum dma_peripheral_index {
	MEMORY_DMA_PERIPHERAL = 0,
	UART0RX_DMA_PERIPHERAL,
	UART0TX_DMA_PERIPHERAL,
	UART1RX_DMA_PERIPHERAL,
	UART1TX_DMA_PERIPHERAL,
	SPI0RX_DMA_PERIPHERAL,
	SPI0TX_DMA_PERIPHERAL,
	SPI1RX_DMA_PERIPHERAL,
	SPI1TX_DMA_PERIPHERAL,
	I2C0RX_DMA_PERIPHERAL,
	I2C0TX_DMA_PERIPHERAL,
	I2C1RX_DMA_PERIPHERAL,
	I2C1TX_DMA_PERIPHERAL,
	DUALTIMER0_DMA_PERIPHERAL = 15,
	TIMER0_DMA_PERIPHERAL,
};

/** DMA channel index */
enum dma_ch_index {
	/** DMA channel 0 */
	DMA_CHANNEL_0 = 0,
	/** DMA channel 1 */
	DMA_CHANNEL_1,
	/** DMA channel 2 */
	DMA_CHANNEL_2,
	/** DMA channel 3 */
	DMA_CHANNEL_3,
};

enum dma_endian_swap {
	/** DMA endian no swap */
	DMA_ENDIAN_NO_SWAP,
	/** DMA endian 16-bit */
	DMA_ENDIAN_SIZE_16,
	/** DMA endian 32-bit */
	DMA_ENDIAN_SIZE_32,
	/** DMA endian 64-bit */
	DMA_ENDIAN_SIZE_64,
};

/**
 * Callback types for DMA callback driver.
 */
enum dma_callback_type {
	/** Callback for transfer complete */
	DMA_CALLBACK_TRANSFER_DONE,
	/** AHB read slave error */
	DMA_CALLBACK_READ_ERR,
	/**  AHB write slave error */
	DMA_CALLBACK_WRITE_ERR,
	/** FIFO has been overflown */
	DMA_CALLBACK_FIFO_OVERFLOW,
	/** FIFO has been underflows */
	DMA_CALLBACK_FIFO_UNDERFLOW,
	/** Read timeout on AHB bus (timeout value fixed at 1024 cycles) */
	DMA_CALLBACK_READ_TIMEOUT,
	/** Write timeout on AHB bus (timeout value fixed at 1024 cycles) */
	DMA_CALLBACK_WRITE_TIMEOUT,
	/** Channel active but did not start a burst for 2048 cycles */
	DMA_CALLBACK_WDT_TRIGGER,
	/** Number of available callbacks */
	DMA_CALLBACK_N,
};

/**
 * DMA transfer descriptor configuration. When the source or destination address
 * increment is enabled, the addresses stored into the configuration structure
 * must correspond to the end of the transfer.
 */
struct dma_descriptor {
	/** Start address of read buffer */
	uint32_t read_start_addr;
	/** Start address of write buffer */
	uint32_t write_start_addr;
	/** Size (in bytes) of buffer to transfer */
	uint32_t buffer_size;
	union {
		struct {
			/** Active high interrupt enable once buffer has been transferred */
			uint32_t set_interrupt:1;
			/** If set, channel stops when buffer done, otherwise load from cmd_next_addr */
			uint32_t last:1;
			/** Address of next command if cmd_last is not set */
			uint32_t next_addr:30;
		} cmd;
		uint32_t next;
	};
};
/** Structure for DMA source/description */
struct dma_config {
	/** Maximum number of bytes of an AHB read/write burst */
	uint8_t max_burst;
	/** Number of AHB read/write commands to issue before channel is released */
	uint8_t tokens;
	/** If true, the controller will increment the next burst address */
	bool enable_inc_addr;
	/** Index of peripheral to read/write from (0 if memory or no peripheral flow control) */
	enum dma_peripheral_index periph;
	/** 
	 * Number of cycles to wait for read/write request signal to update 
	 * after issuing the read/write clear signal
	 */
	uint8_t periph_delay;
	/** Top priority enable */
	bool enable_proi_top;
	/** Top priority channel index */
	uint8_t proi_top_index;
	/** High priority enable */
	bool enable_proi_high;
	/** High priority channel index */
	uint8_t proi_high_index;
};

/** Structure for DMA transfer resource */
struct dma_resource_config {
	struct dma_config src;
	struct dma_config des;
	/** If true, channel will work in joint mode */
	bool enable_joint_mode;
	/** Endian Byte Swapping */
	enum dma_endian_swap swap;
};

/** Forward definition of the DMA resource */
struct dma_resource;
/** Type definition for a DMA resource callback function */
typedef void (*dma_callback_t)(struct dma_resource *const resource);

/** Structure for DMA transfer resource */
struct dma_resource {
	/** Allocated DMA channel ID */
	uint8_t channel_id;
	/** Array of callback functions for DMA transfer job */
	dma_callback_t callback[DMA_CALLBACK_N];
	/** Bit mask for enabled callbacks */
	uint8_t callback_enable;
	/** Status of the last job */
	volatile enum status_code job_status;
	/** Transferred data size */
	uint32_t transfered_size;
	/** DMA transfer descriptor */
	struct dma_descriptor* descriptor;
};

/**
 * \brief Get DMA resource status.
 *
 * \param[in] resource Pointer to the DMA resource
 *
 * \return Status of the DMA resource.
 */
static inline enum status_code dma_get_job_status(struct dma_resource *resource)
{
	return resource->job_status;
}

/**
 * \brief Enable a callback function for a dedicated DMA resource.
 *
 * \param[in] resource Pointer to the DMA resource
 * \param[in] type Callback function type
 *
 */
static inline void dma_enable_callback(struct dma_resource *resource,
		enum dma_callback_type type)
{
	resource->callback_enable |= 1 << type;
}

/**
 * \brief Disable a callback function for a dedicated DMA resource.
 *
 * \param[in] resource Pointer to the DMA resource
 * \param[in] type Callback function type
 *
 */
static inline void dma_disable_callback(struct dma_resource *resource,
		enum dma_callback_type type)
{
	resource->callback_enable &= ~(1 << type);
}

/**
 * \brief Register a callback function for a dedicated DMA resource.
 *
 * There are three types of callback functions, which can be registered:
 * - Callback for transfer complete
 * - Callback for transfer error
 * - Callback for channel suspend
 *
 * \param[in] resource Pointer to the DMA resource
 * \param[in] callback Pointer to the callback function
 * \param[in] type Callback function type
 *
 */
static inline void dma_register_callback(struct dma_resource *resource,
		dma_callback_t callback, enum dma_callback_type type)
{
	resource->callback[type] = callback;
}

/**
 * \brief Unregister a callback function for a dedicated DMA resource.
 *
 * There are three types of callback functions:
 * - Callback for transfer complete
 * - Callback for transfer error
 * - Callback for channel suspend
 *
 * The application can unregister any of the callback functions which
 * are already registered and are no longer needed.
 *
 * \param[in] resource Pointer to the DMA resource
 * \param[in] type Callback function type
 *
 */
static inline void dma_unregister_callback(struct dma_resource *resource,
		enum dma_callback_type type)
{
	resource->callback[type] = NULL;
}

/**
 * \brief Initializes DMA transfer configuration with predefined default values.
 *
 * This function will initialize a given DMA descriptor configuration structure to
 * a set of known default values. This function should be called on
 * any new instance of the configuration structure before being
 * modified by the user application.
 *
 * The default configuration is as follows:
 *  \li Set the read start address as 0
 *  \li Set the write start address as 0
 *  \li Set buffer size as 1
 *  \li Set beat size as byte
 *  \li Enable the interrupt
 *  \li Enable the channel stops when buffer done
 *  \li Set next command address to 0
 * \param[out] config Pointer to the configuration
 *
 */
static inline void dma_descriptor_get_config_defaults(struct dma_descriptor *config)
{
	/* Default read buffer size is set to 0 */
	config->read_start_addr = 0;
	/* Default write buffer size is set to 0 */
	config->write_start_addr = 0;
	/* Set beat size to one byte */
	config->buffer_size = 1;
	/* Enable transferred interrupt */
	config->cmd.set_interrupt = 1;
	/* Channel stops when buffer done */
	config->cmd.last = 1;
	/* Set next command to 0 */
	config->cmd.next_addr = 0;
}

/**
 * \brief Update DMA descriptor.
 *
 * This function can update the descriptor of an allocated DMA resource.
 *
 */
static inline void dma_update_descriptor(struct dma_resource *resource,
		struct dma_descriptor* descriptor)
{
	resource->descriptor = descriptor;
}

/**
 * \brief Reset DMA descriptor.
 *
 * This function will clear the DESCADDR register of an allocated DMA resource.
 *
 */
static inline void dma_reset_descriptor(struct dma_resource *resource)
{
	resource->descriptor = NULL;
}

void dma_get_config_defaults(struct dma_resource_config *config);
enum status_code dma_allocate(struct dma_resource *resource,
		struct dma_resource_config *config);
enum status_code dma_add_descriptor(struct dma_resource *resource,
		struct dma_descriptor* descriptor);
enum status_code dma_start_transfer_job(struct dma_resource *resource);
enum status_code dma_free(struct dma_resource *resource);
uint8_t dma_get_status(uint8_t channel);
uint8_t dma_get_interrupt_status(uint8_t channel);
void dma_clear_interrupt_status(uint8_t channel, uint8_t flag);
/** @} */

/**
 * \page asfdoc_samb_dma_extra Extra Information for DMAC Driver
 *
 * \section asfdoc_samb_dma_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>Description</th>
 *   </tr>
 *   <tr>
 *     <td>DMA</td>
 *     <td>Direct Memory Access</td>
 *   </tr>
 *   <tr>
 *     <td>DMAC</td>
 *     <td>Direct Memory Access Controller </td>
 *   </tr>
 *   <tr>
 *     <td>CPU</td>
 *     <td>Central Processing Unit</td>
 *   </tr>
 * </table>
 *
 *
 * \section asfdoc_samb_dma_extra_dependencies Dependencies
 * There are no dependencies related to this driver.
 *
 *
 * \section asfdoc_samb_dma_extra_errata Errata
 * There are no errata related to this driver.
 *
 *
 * \section asfdoc_samb_dma_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 Release</td>
 *   </tr>
 * </table>
 */

 /**
 * \page asfdoc_samb_dma_exqsg Examples for DMAC Driver
 *
 * This is a list of the available Quick Start Guides (QSGs) and example
 * applications for \ref asfdoc_samb_dma_group. QSGs are simple examples with
 * step-by-step instructions to configure and use this driver in a selection of
 * use cases. Note that QSGs can be compiled as a standalone application or be
 * added to the user application.
 *
 * - \subpage asfdoc_samb_dma_basic_use_case
 *
 * \note More DMA usage examples are available in peripheral QSGs.
 *
 * \page asfdoc_samb_dma_document_revision_history Document Revision History
 *
 * <table>
 *    <tr>
 *        <th>Doc. Rev.</td>
 *        <th>Date</td>
 *        <th>Comments</td>
 *    </tr>
 *    <tr>
 *        <td>A</td>
 *        <td>09/2015</td>
 *        <td>Initial release</td>
 *    </tr>
 * </table>
 */

#ifdef __cplusplus
}
#endif

#endif /* DMA_H_INCLUDED */