mbed official / mbed

The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.

Dependents:   hello SerialTestv11 SerialTestv12 Sierpinski ... more

mbed 2

This is the mbed 2 library. If you'd like to learn about Mbed OS please see the mbed-os docs.

TARGET_SAMR21G18A/TOOLCHAIN_ARM_STD/dma.h@171:3a7713b1edbc, 2018-11-08 (annotated)

Committer:
AnnaBridge
Date:
Thu Nov 08 11:45:42 2018 +0000
Revision:
171:3a7713b1edbc
Parent:
TARGET_SAMD21J18A/TARGET_Atmel/TARGET_SAM_CortexM0P/drivers/dma/dma.h@111:4336505e4b1c 
mbed library. Release version 164

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Kojto 111:4336505e4b1c 1 /**
Kojto 111:4336505e4b1c 2 * \file
Kojto 111:4336505e4b1c 3 *
Kojto 111:4336505e4b1c 4 * \brief SAM Direct Memory Access Controller Driver
Kojto 111:4336505e4b1c 5 *
Kojto 111:4336505e4b1c 6 * Copyright (C) 2014-2015 Atmel Corporation. All rights reserved.
Kojto 111:4336505e4b1c 7 *
Kojto 111:4336505e4b1c 8 * \asf_license_start
Kojto 111:4336505e4b1c 9 *
Kojto 111:4336505e4b1c 10 * \page License
Kojto 111:4336505e4b1c 11 *
Kojto 111:4336505e4b1c 12 * Redistribution and use in source and binary forms, with or without
Kojto 111:4336505e4b1c 13 * modification, are permitted provided that the following conditions are met:
Kojto 111:4336505e4b1c 14 *
Kojto 111:4336505e4b1c 15 * 1. Redistributions of source code must retain the above copyright notice,
Kojto 111:4336505e4b1c 16 * this list of conditions and the following disclaimer.
Kojto 111:4336505e4b1c 17 *
Kojto 111:4336505e4b1c 18 * 2. Redistributions in binary form must reproduce the above copyright notice,
Kojto 111:4336505e4b1c 19 * this list of conditions and the following disclaimer in the documentation
Kojto 111:4336505e4b1c 20 * and/or other materials provided with the distribution.
Kojto 111:4336505e4b1c 21 *
Kojto 111:4336505e4b1c 22 * 3. The name of Atmel may not be used to endorse or promote products derived
Kojto 111:4336505e4b1c 23 * from this software without specific prior written permission.
Kojto 111:4336505e4b1c 24 *
Kojto 111:4336505e4b1c 25 * 4. This software may only be redistributed and used in connection with an
Kojto 111:4336505e4b1c 26 * Atmel microcontroller product.
Kojto 111:4336505e4b1c 27 *
Kojto 111:4336505e4b1c 28 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
Kojto 111:4336505e4b1c 29 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
Kojto 111:4336505e4b1c 30 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
Kojto 111:4336505e4b1c 31 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
Kojto 111:4336505e4b1c 32 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
Kojto 111:4336505e4b1c 33 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
Kojto 111:4336505e4b1c 34 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
Kojto 111:4336505e4b1c 35 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
Kojto 111:4336505e4b1c 36 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
Kojto 111:4336505e4b1c 37 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
Kojto 111:4336505e4b1c 38 * POSSIBILITY OF SUCH DAMAGE.
Kojto 111:4336505e4b1c 39 *
Kojto 111:4336505e4b1c 40 * \asf_license_stop
Kojto 111:4336505e4b1c 41 *
Kojto 111:4336505e4b1c 42 */
Kojto 111:4336505e4b1c 43 /*
Kojto 111:4336505e4b1c 44 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
Kojto 111:4336505e4b1c 45 */
Kojto 111:4336505e4b1c 46 #ifndef DMA_H_INCLUDED
Kojto 111:4336505e4b1c 47 #define DMA_H_INCLUDED
Kojto 111:4336505e4b1c 48
Kojto 111:4336505e4b1c 49 #ifdef __cplusplus
Kojto 111:4336505e4b1c 50 extern "C" {
Kojto 111:4336505e4b1c 51 #endif
Kojto 111:4336505e4b1c 52
Kojto 111:4336505e4b1c 53 /**
Kojto 111:4336505e4b1c 54 * \defgroup asfdoc_sam0_dma_group SAM Direct Memory Access Controller Driver (DMAC)
Kojto 111:4336505e4b1c 55 *
Kojto 111:4336505e4b1c 56 * This driver for Atmel&reg; | SMART SAM devices provides an interface for the configuration
Kojto 111:4336505e4b1c 57 * and management of the Direct Memory Access Controller(DMAC) module within
Kojto 111:4336505e4b1c 58 * the device. The DMAC can transfer data between memories and peripherals, and
Kojto 111:4336505e4b1c 59 * thus off-load these tasks from the CPU. The module supports peripheral to
Kojto 111:4336505e4b1c 60 * peripheral, peripheral to memory, memory to peripheral, and memory to memory
Kojto 111:4336505e4b1c 61 * transfers.
Kojto 111:4336505e4b1c 62 *
Kojto 111:4336505e4b1c 63 * The following peripherals are used by the DMAC Driver:
Kojto 111:4336505e4b1c 64 * - DMAC (Direct Memory Access Controller)
Kojto 111:4336505e4b1c 65 *
Kojto 111:4336505e4b1c 66 * The following devices can use this module:
Kojto 111:4336505e4b1c 67 * - Atmel | SMART SAM D21
Kojto 111:4336505e4b1c 68 * - Atmel | SMART SAM R21
Kojto 111:4336505e4b1c 69 * - Atmel | SMART SAM D10/D11
Kojto 111:4336505e4b1c 70 * - Atmel | SMART SAM L21
Kojto 111:4336505e4b1c 71 * - Atmel | SMART SAM DAx
Kojto 111:4336505e4b1c 72 * - Atmel | SMART SAM C20/C21
Kojto 111:4336505e4b1c 73 *
Kojto 111:4336505e4b1c 74 * The outline of this documentation is as follows:
Kojto 111:4336505e4b1c 75 * - \ref asfdoc_sam0_dma_prerequisites
Kojto 111:4336505e4b1c 76 * - \ref asfdoc_sam0_dma_module_overview
Kojto 111:4336505e4b1c 77 * - \ref asfdoc_sam0_dma_special_considerations
Kojto 111:4336505e4b1c 78 * - \ref asfdoc_sam0_dma_extra_info
Kojto 111:4336505e4b1c 79 * - \ref asfdoc_sam0_dma_examples
Kojto 111:4336505e4b1c 80 * - \ref asfdoc_sam0_dma_api_overview
Kojto 111:4336505e4b1c 81 *
Kojto 111:4336505e4b1c 82 *
Kojto 111:4336505e4b1c 83 * \section asfdoc_sam0_dma_prerequisites Prerequisites
Kojto 111:4336505e4b1c 84 *
Kojto 111:4336505e4b1c 85 * There are no prerequisites for this module.
Kojto 111:4336505e4b1c 86 *
Kojto 111:4336505e4b1c 87 *
Kojto 111:4336505e4b1c 88 * \section asfdoc_sam0_dma_module_overview Module Overview
Kojto 111:4336505e4b1c 89 *
Kojto 111:4336505e4b1c 90 * SAM devices with DMAC enables high data transfer rates with minimum
Kojto 111:4336505e4b1c 91 * CPU intervention and frees up CPU time. With access to all peripherals,
Kojto 111:4336505e4b1c 92 * the DMAC can handle automatic transfer of data to/from modules.
Kojto 111:4336505e4b1c 93 * It supports static and incremental addressing for both source and
Kojto 111:4336505e4b1c 94 * destination.
Kojto 111:4336505e4b1c 95 *
Kojto 111:4336505e4b1c 96 * The DMAC when used with Event System or peripheral triggers, provides a
Kojto 111:4336505e4b1c 97 * considerable advantage by reducing the power consumption and performing
Kojto 111:4336505e4b1c 98 * data transfer in the background.
Kojto 111:4336505e4b1c 99 * For example if the ADC is configured to generate an event, it can trigger
Kojto 111:4336505e4b1c 100 * the DMAC to transfer the data into another peripheral or into SRAM.
Kojto 111:4336505e4b1c 101 * The CPU can remain in sleep during this time to reduce power consumption.
Kojto 111:4336505e4b1c 102 *
Kojto 111:4336505e4b1c 103 * <table>
Kojto 111:4336505e4b1c 104 * <tr>
Kojto 111:4336505e4b1c 105 * <th>Device</th>
Kojto 111:4336505e4b1c 106 * <th>Dma channel number</th>
Kojto 111:4336505e4b1c 107 * </tr>
Kojto 111:4336505e4b1c 108 * <tr>
Kojto 111:4336505e4b1c 109 * <td>SAMD21/R21/C20/C21</td>
Kojto 111:4336505e4b1c 110 * <td>12</td>
Kojto 111:4336505e4b1c 111 * </tr>
Kojto 111:4336505e4b1c 112 * <tr>
Kojto 111:4336505e4b1c 113 * <td>SAMD10/D11</td>
Kojto 111:4336505e4b1c 114 * <td>6</td>
Kojto 111:4336505e4b1c 115 * </tr>
Kojto 111:4336505e4b1c 116 * <tr>
Kojto 111:4336505e4b1c 117 * <td>SAML21</td>
Kojto 111:4336505e4b1c 118 * <td>16</td>
Kojto 111:4336505e4b1c 119 * </tr>
Kojto 111:4336505e4b1c 120 * </table>
Kojto 111:4336505e4b1c 121 * The DMA channel operation can be suspended at any time by software, by events
Kojto 111:4336505e4b1c 122 * from event system, or after selectable descriptor execution. The operation
Kojto 111:4336505e4b1c 123 * can be resumed by software or by events from event system.
Kojto 111:4336505e4b1c 124 * The DMAC driver for SAM supports four types of transfers such as
Kojto 111:4336505e4b1c 125 * peripheral to peripheral, peripheral to memory, memory to peripheral, and
Kojto 111:4336505e4b1c 126 * memory to memory.
Kojto 111:4336505e4b1c 127 *
Kojto 111:4336505e4b1c 128 * The basic transfer unit is a beat which is defined as a single bus access.
Kojto 111:4336505e4b1c 129 * There can be multiple beats in a single block transfer and multiple block
Kojto 111:4336505e4b1c 130 * transfers in a DMA transaction.
Kojto 111:4336505e4b1c 131 * DMA transfer is based on descriptors, which holds transfer properties
Kojto 111:4336505e4b1c 132 * such as the source and destination addresses, transfer counter, and other
Kojto 111:4336505e4b1c 133 * additional transfer control information.
Kojto 111:4336505e4b1c 134 * The descriptors can be static or linked. When static, a single block transfer
Kojto 111:4336505e4b1c 135 * is performed. When linked, a number of transfer descriptors can be used to
Kojto 111:4336505e4b1c 136 * enable multiple block transfers within a single DMA transaction.
Kojto 111:4336505e4b1c 137 *
Kojto 111:4336505e4b1c 138 * The implementation of the DMA driver is based on the idea that DMA channel
Kojto 111:4336505e4b1c 139 * is a finite resource of entities with the same abilities. A DMA channel resource
Kojto 111:4336505e4b1c 140 * is able to move a defined set of data from a source address to destination
Kojto 111:4336505e4b1c 141 * address triggered by a transfer trigger. On the SAM devices there are 12
Kojto 111:4336505e4b1c 142 * DMA resources available for allocation. Each of these DMA resources can trigger
Kojto 111:4336505e4b1c 143 * interrupt callback routines and peripheral events.
Kojto 111:4336505e4b1c 144 * The other main features are
Kojto 111:4336505e4b1c 145 *
Kojto 111:4336505e4b1c 146 * - Selectable transfer trigger source
Kojto 111:4336505e4b1c 147 * - Software
Kojto 111:4336505e4b1c 148 * - Event System
Kojto 111:4336505e4b1c 149 * - Peripheral
Kojto 111:4336505e4b1c 150 * - Event input and output is supported for the four lower channels
Kojto 111:4336505e4b1c 151 * - Four level channel priority
Kojto 111:4336505e4b1c 152 * - Optional interrupt generation on transfer complete, channel error or channel suspend
Kojto 111:4336505e4b1c 153 * - Supports multi-buffer or circular buffer mode by linking multiple descriptors
Kojto 111:4336505e4b1c 154 * - Beat size configurable as 8-bit, 16-bit, or 32-bit
Kojto 111:4336505e4b1c 155 *
Kojto 111:4336505e4b1c 156 * A simplified block diagram of the DMA Resource can be seen in
Kojto 111:4336505e4b1c 157 * \ref asfdoc_sam0_dma_module_block_diagram "the figure below".
Kojto 111:4336505e4b1c 158 *
Kojto 111:4336505e4b1c 159 * \anchor asfdoc_sam0_dma_module_block_diagram
Kojto 111:4336505e4b1c 160 * \dot
Kojto 111:4336505e4b1c 161 * digraph overview {
Kojto 111:4336505e4b1c 162 * splines = false;
Kojto 111:4336505e4b1c 163 * rankdir=LR;
Kojto 111:4336505e4b1c 164 *
Kojto 111:4336505e4b1c 165 * mux1 [label="Transfer Trigger", shape=box];
Kojto 111:4336505e4b1c 166 *
Kojto 111:4336505e4b1c 167 * dma [label="DMA Channel", shape=polygon, sides=6, orientation=60, style=filled, fillcolor=darkolivegreen1, height=1, width=1];
Kojto 111:4336505e4b1c 168 * descriptor [label="Transfer Descriptor", shape=box, style=filled, fillcolor=lightblue];
Kojto 111:4336505e4b1c 169 *
Kojto 111:4336505e4b1c 170 * mux1 -> dma;
Kojto 111:4336505e4b1c 171 * descriptor -> dma;
Kojto 111:4336505e4b1c 172 *
Kojto 111:4336505e4b1c 173 * interrupt [label="Interrupt", shape=box];
Kojto 111:4336505e4b1c 174 * events [label="Events", shape=box];
Kojto 111:4336505e4b1c 175 *
Kojto 111:4336505e4b1c 176 * dma:e -> interrupt:w;
Kojto 111:4336505e4b1c 177 * dma:e -> events:w;
Kojto 111:4336505e4b1c 178 *
Kojto 111:4336505e4b1c 179 * {rank=same; descriptor dma}
Kojto 111:4336505e4b1c 180 *
Kojto 111:4336505e4b1c 181 * }
Kojto 111:4336505e4b1c 182 * \enddot
Kojto 111:4336505e4b1c 183 *
Kojto 111:4336505e4b1c 184 * \subsection asfdoc_sam0_dma_features Driver Feature Macro Definition
Kojto 111:4336505e4b1c 185 * <table>
Kojto 111:4336505e4b1c 186 * <tr>
Kojto 111:4336505e4b1c 187 * <th>Driver Feature Macro</th>
Kojto 111:4336505e4b1c 188 * <th>Supported devices</th>
Kojto 111:4336505e4b1c 189 * </tr>
Kojto 111:4336505e4b1c 190 * <tr>
Kojto 111:4336505e4b1c 191 * <td>FEATURE_DMA_CHANNEL_STANDBY</td>
Kojto 111:4336505e4b1c 192 * <td>SAML21/C20/C21</td>
Kojto 111:4336505e4b1c 193 * </tr>
Kojto 111:4336505e4b1c 194 * </table>
Kojto 111:4336505e4b1c 195 * \note The specific features are only available in the driver when the
Kojto 111:4336505e4b1c 196 * selected device supports those features.
Kojto 111:4336505e4b1c 197 *
Kojto 111:4336505e4b1c 198 * \subsection asfdoc_sam0_dma_module_overview_dma_transf_term Terminology Used in DMAC Transfers
Kojto 111:4336505e4b1c 199 *
Kojto 111:4336505e4b1c 200 * <table border="0" cellborder="1" cellspacing="0" >
Kojto 111:4336505e4b1c 201 * <tr>
Kojto 111:4336505e4b1c 202 * <th> Name </th> <th> Description </th>
Kojto 111:4336505e4b1c 203 * </tr>
Kojto 111:4336505e4b1c 204 * <tr>
Kojto 111:4336505e4b1c 205 * <td > Beat </td>
Kojto 111:4336505e4b1c 206 * <td > It is a single bus access by the DMAC.
Kojto 111:4336505e4b1c 207 * Configurable as 8-bit, 16-bit, or 32-bit
Kojto 111:4336505e4b1c 208 * </td>
Kojto 111:4336505e4b1c 209 * </tr>
Kojto 111:4336505e4b1c 210 * <tr>
Kojto 111:4336505e4b1c 211 * <td > Burst </td>
Kojto 111:4336505e4b1c 212 * <td> It is a transfer of n-beats (n=1,4,8,16).
Kojto 111:4336505e4b1c 213 * For the DMAC module in SAM, the burst size is one beat.
Kojto 111:4336505e4b1c 214 * Arbitration takes place each time a burst transfer is completed
Kojto 111:4336505e4b1c 215 * </td>
Kojto 111:4336505e4b1c 216 * </tr>
Kojto 111:4336505e4b1c 217 * <tr>
Kojto 111:4336505e4b1c 218 * <td > Block transfer </td>
Kojto 111:4336505e4b1c 219 * <td> A single block transfer is a configurable number of (1 to 64k)
Kojto 111:4336505e4b1c 220 * beat transfers
Kojto 111:4336505e4b1c 221 * </td>
Kojto 111:4336505e4b1c 222 * </tr>
Kojto 111:4336505e4b1c 223 * </table>
Kojto 111:4336505e4b1c 224 *
Kojto 111:4336505e4b1c 225 * \subsection asfdoc_sam0_dma_module_overview_dma_channels DMA Channels
Kojto 111:4336505e4b1c 226 * The DMAC in each device consists of several DMA channels, which
Kojto 111:4336505e4b1c 227 * along with the transfer descriptors defines the data transfer properties.
Kojto 111:4336505e4b1c 228 * - The transfer control descriptor defines the source and destination
Kojto 111:4336505e4b1c 229 * addresses, source and destination address increment settings, the
Kojto 111:4336505e4b1c 230 * block transfer count and event output condition selection
Kojto 111:4336505e4b1c 231 * - Dedicated channel registers control the peripheral trigger source,
Kojto 111:4336505e4b1c 232 * trigger mode settings, event input actions, and channel priority level
Kojto 111:4336505e4b1c 233 * settings
Kojto 111:4336505e4b1c 234 *
Kojto 111:4336505e4b1c 235 * With a successful DMA resource allocation, a dedicated
Kojto 111:4336505e4b1c 236 * DMA channel will be assigned. The channel will be occupied until the
Kojto 111:4336505e4b1c 237 * DMA resource is freed. A DMA resource handle is used to identify the specific
Kojto 111:4336505e4b1c 238 * DMA resource.
Kojto 111:4336505e4b1c 239 * When there are multiple channels with active requests, the arbiter prioritizes
Kojto 111:4336505e4b1c 240 * the channels requesting access to the bus.
Kojto 111:4336505e4b1c 241 *
Kojto 111:4336505e4b1c 242 * \subsection asfdoc_sam0_dma_module_overview_dma_trigger DMA Triggers
Kojto 111:4336505e4b1c 243 * DMA transfer can be started only when a DMA transfer request is acknowledged/granted by the arbiter. A
Kojto 111:4336505e4b1c 244 * transfer request can be triggered from software, peripheral, or an event. There
Kojto 111:4336505e4b1c 245 * are dedicated source trigger selections for each DMA channel usage.
Kojto 111:4336505e4b1c 246
Kojto 111:4336505e4b1c 247 *
Kojto 111:4336505e4b1c 248 * \subsection asfdoc_sam0_dma_module_overview_dma_transfer_descriptor DMA Transfer Descriptor
Kojto 111:4336505e4b1c 249 * The transfer descriptor resides in the SRAM and
Kojto 111:4336505e4b1c 250 * defines these channel properties.
Kojto 111:4336505e4b1c 251 * <table border="0" cellborder="1" cellspacing="0" >
Kojto 111:4336505e4b1c 252 * <tr>
Kojto 111:4336505e4b1c 253 * <th> Field name </th> <th> Field width </th>
Kojto 111:4336505e4b1c 254 * </tr>
Kojto 111:4336505e4b1c 255 * <tr>
Kojto 111:4336505e4b1c 256 * <td > Descriptor Next Address </td> <td > 32 bits </td>
Kojto 111:4336505e4b1c 257 * </tr>
Kojto 111:4336505e4b1c 258 * <tr>
Kojto 111:4336505e4b1c 259 * <td > Destination Address </td> <td> 32 bits </td>
Kojto 111:4336505e4b1c 260 * </tr>
Kojto 111:4336505e4b1c 261 * <tr>
Kojto 111:4336505e4b1c 262 * <td > Source Address </td> <td> 32 bits </td>
Kojto 111:4336505e4b1c 263 * </tr>
Kojto 111:4336505e4b1c 264 * <tr>
Kojto 111:4336505e4b1c 265 * <td > Block Transfer Counter </td> <td> 16 bits </td>
Kojto 111:4336505e4b1c 266 * </tr>
Kojto 111:4336505e4b1c 267 * <tr>
Kojto 111:4336505e4b1c 268 * <td > Block Transfer Control </td> <td> 16 bits </td>
Kojto 111:4336505e4b1c 269 * </tr>
Kojto 111:4336505e4b1c 270 * </table>
Kojto 111:4336505e4b1c 271 *
Kojto 111:4336505e4b1c 272 * Before starting a transfer, at least one descriptor should be configured.
Kojto 111:4336505e4b1c 273 * After a successful allocation of a DMA channel, the transfer descriptor can
Kojto 111:4336505e4b1c 274 * be added with a call to \ref dma_add_descriptor(). If there is a transfer
Kojto 111:4336505e4b1c 275 * descriptor already allocated to the DMA resource, the descriptor will
Kojto 111:4336505e4b1c 276 * be linked to the next descriptor address.
Kojto 111:4336505e4b1c 277 *
Kojto 111:4336505e4b1c 278 * \subsection asfdoc_sam0_dma_module_overview_dma_output DMA Interrupts/Events
Kojto 111:4336505e4b1c 279 * Both an interrupt callback and an peripheral event can be triggered by the
Kojto 111:4336505e4b1c 280 * DMA transfer. Three types of callbacks are supported by the DMA driver:
Kojto 111:4336505e4b1c 281 * transfer complete, channel suspend, and transfer error. Each of these callback
Kojto 111:4336505e4b1c 282 * types can be registered and enabled for each channel independently through
Kojto 111:4336505e4b1c 283 * the DMA driver API.
Kojto 111:4336505e4b1c 284 *
Kojto 111:4336505e4b1c 285 * The DMAC module can also generate events on transfer complete. Event
Kojto 111:4336505e4b1c 286 * generation is enabled through the DMA channel, event channel configuration,
Kojto 111:4336505e4b1c 287 * and event user multiplexing is done through the events driver.
Kojto 111:4336505e4b1c 288 *
Kojto 111:4336505e4b1c 289 * The DMAC can generate events in the below cases:
Kojto 111:4336505e4b1c 290 *
Kojto 111:4336505e4b1c 291 * - When a block transfer is complete
Kojto 111:4336505e4b1c 292 *
Kojto 111:4336505e4b1c 293 * - When each beat transfer within a block transfer is complete
Kojto 111:4336505e4b1c 294 *
Kojto 111:4336505e4b1c 295 * \section asfdoc_sam0_dma_special_considerations Special Considerations
Kojto 111:4336505e4b1c 296 *
Kojto 111:4336505e4b1c 297 * There are no special considerations for this module.
Kojto 111:4336505e4b1c 298 *
Kojto 111:4336505e4b1c 299 *
Kojto 111:4336505e4b1c 300 * \section asfdoc_sam0_dma_extra_info Extra Information
Kojto 111:4336505e4b1c 301 *
Kojto 111:4336505e4b1c 302 * For extra information, see \ref asfdoc_sam0_dma_extra. This includes:
Kojto 111:4336505e4b1c 303 * - \ref asfdoc_sam0_dma_extra_acronyms
Kojto 111:4336505e4b1c 304 * - \ref asfdoc_sam0_dma_extra_dependencies
Kojto 111:4336505e4b1c 305 * - \ref asfdoc_sam0_dma_extra_errata
Kojto 111:4336505e4b1c 306 * - \ref asfdoc_sam0_dma_extra_history
Kojto 111:4336505e4b1c 307 *
Kojto 111:4336505e4b1c 308 *
Kojto 111:4336505e4b1c 309 * \section asfdoc_sam0_dma_examples Examples
Kojto 111:4336505e4b1c 310 *
Kojto 111:4336505e4b1c 311 * For a list of examples related to this driver, see
Kojto 111:4336505e4b1c 312 * \ref asfdoc_sam0_dma_exqsg.
Kojto 111:4336505e4b1c 313 *
Kojto 111:4336505e4b1c 314 *
Kojto 111:4336505e4b1c 315 * \section asfdoc_sam0_dma_api_overview API Overview
Kojto 111:4336505e4b1c 316 * @{
Kojto 111:4336505e4b1c 317 */
Kojto 111:4336505e4b1c 318
Kojto 111:4336505e4b1c 319 #include <compiler.h>
Kojto 111:4336505e4b1c 320 #include "conf_dma.h"
Kojto 111:4336505e4b1c 321
Kojto 111:4336505e4b1c 322 #if (SAML21) || (SAMC20) || (SAMC21) || defined(__DOXYGEN__)
Kojto 111:4336505e4b1c 323 #define FEATURE_DMA_CHANNEL_STANDBY
Kojto 111:4336505e4b1c 324 #endif
Kojto 111:4336505e4b1c 325
Kojto 111:4336505e4b1c 326 /** DMA invalid channel number. */
Kojto 111:4336505e4b1c 327 #define DMA_INVALID_CHANNEL 0xff
Kojto 111:4336505e4b1c 328
Kojto 111:4336505e4b1c 329 /** ExInitial description section. */
Kojto 111:4336505e4b1c 330 extern DmacDescriptor descriptor_section[CONF_MAX_USED_CHANNEL_NUM];
Kojto 111:4336505e4b1c 331
Kojto 111:4336505e4b1c 332 /* DMA channel interrup flag. */
Kojto 111:4336505e4b1c 333 extern uint8_t g_chan_interrupt_flag[CONF_MAX_USED_CHANNEL_NUM];
Kojto 111:4336505e4b1c 334
Kojto 111:4336505e4b1c 335 /** DMA priority level. */
Kojto 111:4336505e4b1c 336 enum dma_priority_level {
Kojto 111:4336505e4b1c 337 /** Priority level 0. */
Kojto 111:4336505e4b1c 338 DMA_PRIORITY_LEVEL_0,
Kojto 111:4336505e4b1c 339 /** Priority level 1. */
Kojto 111:4336505e4b1c 340 DMA_PRIORITY_LEVEL_1,
Kojto 111:4336505e4b1c 341 /** Priority level 2. */
Kojto 111:4336505e4b1c 342 DMA_PRIORITY_LEVEL_2,
Kojto 111:4336505e4b1c 343 /** Priority level 3. */
Kojto 111:4336505e4b1c 344 DMA_PRIORITY_LEVEL_3,
Kojto 111:4336505e4b1c 345 };
Kojto 111:4336505e4b1c 346
Kojto 111:4336505e4b1c 347 /** DMA input actions. */
Kojto 111:4336505e4b1c 348 enum dma_event_input_action {
Kojto 111:4336505e4b1c 349 /** No action. */
Kojto 111:4336505e4b1c 350 DMA_EVENT_INPUT_NOACT,
Kojto 111:4336505e4b1c 351 /** Normal transfer and periodic transfer trigger. */
Kojto 111:4336505e4b1c 352 DMA_EVENT_INPUT_TRIG,
Kojto 111:4336505e4b1c 353 /** Conditional transfer trigger. */
Kojto 111:4336505e4b1c 354 DMA_EVENT_INPUT_CTRIG,
Kojto 111:4336505e4b1c 355 /** Conditional block transfer. */
Kojto 111:4336505e4b1c 356 DMA_EVENT_INPUT_CBLOCK,
Kojto 111:4336505e4b1c 357 /** Channel suspend operation. */
Kojto 111:4336505e4b1c 358 DMA_EVENT_INPUT_SUSPEND,
Kojto 111:4336505e4b1c 359 /** Channel resume operation. */
Kojto 111:4336505e4b1c 360 DMA_EVENT_INPUT_RESUME,
Kojto 111:4336505e4b1c 361 /** Skip next block suspend action. */
Kojto 111:4336505e4b1c 362 DMA_EVENT_INPUT_SSKIP,
Kojto 111:4336505e4b1c 363 };
Kojto 111:4336505e4b1c 364
Kojto 111:4336505e4b1c 365 /**
Kojto 111:4336505e4b1c 366 * Address increment step size. These bits select the address increment step
Kojto 111:4336505e4b1c 367 * size. The setting apply to source or destination address, depending on
Kojto 111:4336505e4b1c 368 * STEPSEL setting.
Kojto 111:4336505e4b1c 369 */
Kojto 111:4336505e4b1c 370 enum dma_address_increment_stepsize {
Kojto 111:4336505e4b1c 371 /** The address is incremented by (beat size * 1). */
Kojto 111:4336505e4b1c 372 DMA_ADDRESS_INCREMENT_STEP_SIZE_1 = 0,
Kojto 111:4336505e4b1c 373 /** The address is incremented by (beat size * 2). */
Kojto 111:4336505e4b1c 374 DMA_ADDRESS_INCREMENT_STEP_SIZE_2,
Kojto 111:4336505e4b1c 375 /** The address is incremented by (beat size * 4). */
Kojto 111:4336505e4b1c 376 DMA_ADDRESS_INCREMENT_STEP_SIZE_4,
Kojto 111:4336505e4b1c 377 /** The address is incremented by (beat size * 8). */
Kojto 111:4336505e4b1c 378 DMA_ADDRESS_INCREMENT_STEP_SIZE_8,
Kojto 111:4336505e4b1c 379 /** The address is incremented by (beat size * 16). */
Kojto 111:4336505e4b1c 380 DMA_ADDRESS_INCREMENT_STEP_SIZE_16,
Kojto 111:4336505e4b1c 381 /** The address is incremented by (beat size * 32). */
Kojto 111:4336505e4b1c 382 DMA_ADDRESS_INCREMENT_STEP_SIZE_32,
Kojto 111:4336505e4b1c 383 /** The address is incremented by (beat size * 64). */
Kojto 111:4336505e4b1c 384 DMA_ADDRESS_INCREMENT_STEP_SIZE_64,
Kojto 111:4336505e4b1c 385 /** The address is incremented by (beat size * 128). */
Kojto 111:4336505e4b1c 386 DMA_ADDRESS_INCREMENT_STEP_SIZE_128,
Kojto 111:4336505e4b1c 387 };
Kojto 111:4336505e4b1c 388
Kojto 111:4336505e4b1c 389 /**
Kojto 111:4336505e4b1c 390 * DMA step selection. This bit determines whether the step size setting
Kojto 111:4336505e4b1c 391 * is applied to source or destination address.
Kojto 111:4336505e4b1c 392 */
Kojto 111:4336505e4b1c 393 enum dma_step_selection {
Kojto 111:4336505e4b1c 394 /** Step size settings apply to the destination address. */
Kojto 111:4336505e4b1c 395 DMA_STEPSEL_DST = 0,
Kojto 111:4336505e4b1c 396 /** Step size settings apply to the source address. */
Kojto 111:4336505e4b1c 397 DMA_STEPSEL_SRC,
Kojto 111:4336505e4b1c 398 };
Kojto 111:4336505e4b1c 399
Kojto 111:4336505e4b1c 400 /** The basic transfer unit in DMAC is a beat, which is defined as a
Kojto 111:4336505e4b1c 401 * single bus access. Its size is configurable and applies to both read
Kojto 111:4336505e4b1c 402 * and write. */
Kojto 111:4336505e4b1c 403 enum dma_beat_size {
Kojto 111:4336505e4b1c 404 /** 8-bit access. */
Kojto 111:4336505e4b1c 405 DMA_BEAT_SIZE_BYTE = 0,
Kojto 111:4336505e4b1c 406 /** 16-bit access. */
Kojto 111:4336505e4b1c 407 DMA_BEAT_SIZE_HWORD,
Kojto 111:4336505e4b1c 408 /** 32-bit access. */
Kojto 111:4336505e4b1c 409 DMA_BEAT_SIZE_WORD,
Kojto 111:4336505e4b1c 410 };
Kojto 111:4336505e4b1c 411
Kojto 111:4336505e4b1c 412 /**
Kojto 111:4336505e4b1c 413 * Block action definitions.
Kojto 111:4336505e4b1c 414 */
Kojto 111:4336505e4b1c 415 enum dma_block_action {
Kojto 111:4336505e4b1c 416 /** No action. */
Kojto 111:4336505e4b1c 417 DMA_BLOCK_ACTION_NOACT = 0,
Kojto 111:4336505e4b1c 418 /** Channel in normal operation and sets transfer complete interrupt flag
Kojto 111:4336505e4b1c 419 * after block transfer. */
Kojto 111:4336505e4b1c 420 DMA_BLOCK_ACTION_INT,
Kojto 111:4336505e4b1c 421 /** Trigger channel suspend after block transfer and sets channel
Kojto 111:4336505e4b1c 422 * suspend interrupt flag once the channel is suspended. */
Kojto 111:4336505e4b1c 423 DMA_BLOCK_ACTION_SUSPEND,
Kojto 111:4336505e4b1c 424 /** Sets transfer complete interrupt flag after a block transfer and
Kojto 111:4336505e4b1c 425 * trigger channel suspend. The channel suspend interrupt flag will be set
Kojto 111:4336505e4b1c 426 * once the channel is suspended. */
Kojto 111:4336505e4b1c 427 DMA_BLOCK_ACTION_BOTH,
Kojto 111:4336505e4b1c 428 };
Kojto 111:4336505e4b1c 429
Kojto 111:4336505e4b1c 430 /** Event output selection. */
Kojto 111:4336505e4b1c 431 enum dma_event_output_selection {
Kojto 111:4336505e4b1c 432 /** Event generation disable. */
Kojto 111:4336505e4b1c 433 DMA_EVENT_OUTPUT_DISABLE = 0,
Kojto 111:4336505e4b1c 434 /** Event strobe when block transfer complete. */
Kojto 111:4336505e4b1c 435 DMA_EVENT_OUTPUT_BLOCK,
Kojto 111:4336505e4b1c 436 /** Event output reserved. */
Kojto 111:4336505e4b1c 437 DMA_EVENT_OUTPUT_RESERVED,
Kojto 111:4336505e4b1c 438 /** Event strobe when beat transfer complete. */
Kojto 111:4336505e4b1c 439 DMA_EVENT_OUTPUT_BEAT,
Kojto 111:4336505e4b1c 440 };
Kojto 111:4336505e4b1c 441
Kojto 111:4336505e4b1c 442 /** DMA trigger action type. */
Kojto 111:4336505e4b1c 443 enum dma_transfer_trigger_action {
Kojto 111:4336505e4b1c 444 /** Perform a block transfer when triggered. */
Kojto 111:4336505e4b1c 445 DMA_TRIGGER_ACTON_BLOCK = DMAC_CHCTRLB_TRIGACT_BLOCK_Val,
Kojto 111:4336505e4b1c 446 /** Perform a beat transfer when triggered. */
Kojto 111:4336505e4b1c 447 DMA_TRIGGER_ACTON_BEAT = DMAC_CHCTRLB_TRIGACT_BEAT_Val,
Kojto 111:4336505e4b1c 448 /** Perform a transaction when triggered. */
Kojto 111:4336505e4b1c 449 DMA_TRIGGER_ACTON_TRANSACTION = DMAC_CHCTRLB_TRIGACT_TRANSACTION_Val,
Kojto 111:4336505e4b1c 450 };
Kojto 111:4336505e4b1c 451
Kojto 111:4336505e4b1c 452 /**
Kojto 111:4336505e4b1c 453 * Callback types for DMA callback driver.
Kojto 111:4336505e4b1c 454 */
Kojto 111:4336505e4b1c 455 enum dma_callback_type {
Kojto 111:4336505e4b1c 456 /** Callback for any of transfer errors. A transfer error is flagged
Kojto 111:4336505e4b1c 457 * if a bus error is detected during an AHB access or when the DMAC
Kojto 111:4336505e4b1c 458 * fetches an invalid descriptor. */
Kojto 111:4336505e4b1c 459 DMA_CALLBACK_TRANSFER_ERROR,
Kojto 111:4336505e4b1c 460 /** Callback for transfer complete. */
Kojto 111:4336505e4b1c 461 DMA_CALLBACK_TRANSFER_DONE,
Kojto 111:4336505e4b1c 462 /** Callback for channel suspend. */
Kojto 111:4336505e4b1c 463 DMA_CALLBACK_CHANNEL_SUSPEND,
Kojto 111:4336505e4b1c 464 /** Number of available callbacks. */
Kojto 111:4336505e4b1c 465 DMA_CALLBACK_N,
Kojto 111:4336505e4b1c 466 };
Kojto 111:4336505e4b1c 467
Kojto 111:4336505e4b1c 468 /**
Kojto 111:4336505e4b1c 469 * DMA transfer descriptor configuration. When the source or destination address
Kojto 111:4336505e4b1c 470 * increment is enabled, the addresses stored into the configuration structure
Kojto 111:4336505e4b1c 471 * must correspond to the end of the transfer.
Kojto 111:4336505e4b1c 472 *
Kojto 111:4336505e4b1c 473 */
Kojto 111:4336505e4b1c 474 struct dma_descriptor_config {
Kojto 111:4336505e4b1c 475 /** Descriptor valid flag used to identify whether a descriptor is
Kojto 111:4336505e4b1c 476 valid or not. */
Kojto 111:4336505e4b1c 477 bool descriptor_valid;
Kojto 111:4336505e4b1c 478 /** This is used to generate an event on specific transfer action in
Kojto 111:4336505e4b1c 479 a channel. Supported only in four lower channels. */
Kojto 111:4336505e4b1c 480 enum dma_event_output_selection event_output_selection;
Kojto 111:4336505e4b1c 481 /** Action taken when a block transfer is completed. */
Kojto 111:4336505e4b1c 482 enum dma_block_action block_action;
Kojto 111:4336505e4b1c 483 /** Beat size is configurable as 8-bit, 16-bit, or 32-bit. */
Kojto 111:4336505e4b1c 484 enum dma_beat_size beat_size;
Kojto 111:4336505e4b1c 485 /** Used for enabling the source address increment. */
Kojto 111:4336505e4b1c 486 bool src_increment_enable;
Kojto 111:4336505e4b1c 487 /** Used for enabling the destination address increment. */
Kojto 111:4336505e4b1c 488 bool dst_increment_enable;
Kojto 111:4336505e4b1c 489 /** This bit selects whether the source or destination address is
Kojto 111:4336505e4b1c 490 using the step size settings. */
Kojto 111:4336505e4b1c 491 enum dma_step_selection step_selection;
Kojto 111:4336505e4b1c 492 /** The step size for source/destination address increment.
Kojto 111:4336505e4b1c 493 The next address is calculated
Kojto 111:4336505e4b1c 494 as next_addr = addr + (2^step_size * beat size). */
Kojto 111:4336505e4b1c 495 enum dma_address_increment_stepsize step_size;
Kojto 111:4336505e4b1c 496 /** It is the number of beats in a block. This count value is
Kojto 111:4336505e4b1c 497 * decremented by one after each beat data transfer. */
Kojto 111:4336505e4b1c 498 uint16_t block_transfer_count;
Kojto 111:4336505e4b1c 499 /** Transfer source address. */
Kojto 111:4336505e4b1c 500 uint32_t source_address;
Kojto 111:4336505e4b1c 501 /** Transfer destination address. */
Kojto 111:4336505e4b1c 502 uint32_t destination_address;
Kojto 111:4336505e4b1c 503 /** Set to zero for static descriptors. This must have a valid memory
Kojto 111:4336505e4b1c 504 address for linked descriptors. */
Kojto 111:4336505e4b1c 505 uint32_t next_descriptor_address;
Kojto 111:4336505e4b1c 506 };
Kojto 111:4336505e4b1c 507
Kojto 111:4336505e4b1c 508 /** Configurations for DMA events. */
Kojto 111:4336505e4b1c 509 struct dma_events_config {
Kojto 111:4336505e4b1c 510 /** Event input actions. */
Kojto 111:4336505e4b1c 511 enum dma_event_input_action input_action;
Kojto 111:4336505e4b1c 512 /** Enable DMA event output. */
Kojto 111:4336505e4b1c 513 bool event_output_enable;
Kojto 111:4336505e4b1c 514 };
Kojto 111:4336505e4b1c 515
Kojto 111:4336505e4b1c 516 /** DMA configurations for transfer. */
Kojto 111:4336505e4b1c 517 struct dma_resource_config {
Kojto 111:4336505e4b1c 518 /** DMA transfer priority. */
Kojto 111:4336505e4b1c 519 enum dma_priority_level priority;
Kojto 111:4336505e4b1c 520 /**DMA peripheral trigger index. */
Kojto 111:4336505e4b1c 521 uint8_t peripheral_trigger;
Kojto 111:4336505e4b1c 522 /** DMA trigger action. */
Kojto 111:4336505e4b1c 523 enum dma_transfer_trigger_action trigger_action;
Kojto 111:4336505e4b1c 524 #ifdef FEATURE_DMA_CHANNEL_STANDBY
Kojto 111:4336505e4b1c 525 /** Keep DMA channel enabled in standby sleep mode if true. */
Kojto 111:4336505e4b1c 526 bool run_in_standby;
Kojto 111:4336505e4b1c 527 #endif
Kojto 111:4336505e4b1c 528 /** DMA events configurations. */
Kojto 111:4336505e4b1c 529 struct dma_events_config event_config;
Kojto 111:4336505e4b1c 530 };
Kojto 111:4336505e4b1c 531
Kojto 111:4336505e4b1c 532 /** Forward definition of the DMA resource. */
Kojto 111:4336505e4b1c 533 struct dma_resource;
Kojto 111:4336505e4b1c 534 /** Type definition for a DMA resource callback function. */
Kojto 111:4336505e4b1c 535 typedef void (*dma_callback_t)(struct dma_resource *const resource);
Kojto 111:4336505e4b1c 536
Kojto 111:4336505e4b1c 537 /** Structure for DMA transfer resource. */
Kojto 111:4336505e4b1c 538 struct dma_resource {
Kojto 111:4336505e4b1c 539 /** Allocated DMA channel ID. */
Kojto 111:4336505e4b1c 540 uint8_t channel_id;
Kojto 111:4336505e4b1c 541 /** Array of callback functions for DMA transfer job. */
Kojto 111:4336505e4b1c 542 dma_callback_t callback[DMA_CALLBACK_N];
Kojto 111:4336505e4b1c 543 /** Bit mask for enabled callbacks. */
Kojto 111:4336505e4b1c 544 uint8_t callback_enable;
Kojto 111:4336505e4b1c 545 /** Status of the last job. */
Kojto 111:4336505e4b1c 546 volatile enum status_code job_status;
Kojto 111:4336505e4b1c 547 /** Transferred data size. */
Kojto 111:4336505e4b1c 548 uint32_t transfered_size;
Kojto 111:4336505e4b1c 549 /** DMA transfer descriptor. */
Kojto 111:4336505e4b1c 550 DmacDescriptor* descriptor;
Kojto 111:4336505e4b1c 551 };
Kojto 111:4336505e4b1c 552
Kojto 111:4336505e4b1c 553 /**
Kojto 111:4336505e4b1c 554 * \brief Get DMA resource status.
Kojto 111:4336505e4b1c 555 *
Kojto 111:4336505e4b1c 556 * \param[in] resource Pointer to the DMA resource
Kojto 111:4336505e4b1c 557 *
Kojto 111:4336505e4b1c 558 * \return Status of the DMA resource.
Kojto 111:4336505e4b1c 559 */
Kojto 111:4336505e4b1c 560 static inline enum status_code dma_get_job_status(struct dma_resource *resource)
Kojto 111:4336505e4b1c 561 {
Kojto 111:4336505e4b1c 562 Assert(resource);
Kojto 111:4336505e4b1c 563
Kojto 111:4336505e4b1c 564 return resource->job_status;
Kojto 111:4336505e4b1c 565 }
Kojto 111:4336505e4b1c 566
Kojto 111:4336505e4b1c 567 /**
Kojto 111:4336505e4b1c 568 * \brief Check if the given DMA resource is busy.
Kojto 111:4336505e4b1c 569 *
Kojto 111:4336505e4b1c 570 * \param[in] resource Pointer to the DMA resource
Kojto 111:4336505e4b1c 571 *
Kojto 111:4336505e4b1c 572 * \return Status which indicates whether the DMA resource is busy.
Kojto 111:4336505e4b1c 573 *
Kojto 111:4336505e4b1c 574 * \retval true The DMA resource has an on-going transfer
Kojto 111:4336505e4b1c 575 * \retval false The DMA resource is not busy
Kojto 111:4336505e4b1c 576 */
Kojto 111:4336505e4b1c 577 static inline bool dma_is_busy(struct dma_resource *resource)
Kojto 111:4336505e4b1c 578 {
Kojto 111:4336505e4b1c 579 Assert(resource);
Kojto 111:4336505e4b1c 580
Kojto 111:4336505e4b1c 581 return (resource->job_status == STATUS_BUSY);
Kojto 111:4336505e4b1c 582 }
Kojto 111:4336505e4b1c 583
Kojto 111:4336505e4b1c 584 /**
Kojto 111:4336505e4b1c 585 * \brief Enable a callback function for a dedicated DMA resource.
Kojto 111:4336505e4b1c 586 *
Kojto 111:4336505e4b1c 587 * \param[in] resource Pointer to the DMA resource
Kojto 111:4336505e4b1c 588 * \param[in] type Callback function type
Kojto 111:4336505e4b1c 589 *
Kojto 111:4336505e4b1c 590 */
Kojto 111:4336505e4b1c 591 static inline void dma_enable_callback(struct dma_resource *resource,
Kojto 111:4336505e4b1c 592 enum dma_callback_type type)
Kojto 111:4336505e4b1c 593 {
Kojto 111:4336505e4b1c 594 Assert(resource);
Kojto 111:4336505e4b1c 595
Kojto 111:4336505e4b1c 596 resource->callback_enable |= 1 << type;
Kojto 111:4336505e4b1c 597 g_chan_interrupt_flag[resource->channel_id] |= (1UL << type);
Kojto 111:4336505e4b1c 598 }
Kojto 111:4336505e4b1c 599
Kojto 111:4336505e4b1c 600 /**
Kojto 111:4336505e4b1c 601 * \brief Disable a callback function for a dedicated DMA resource.
Kojto 111:4336505e4b1c 602 *
Kojto 111:4336505e4b1c 603 * \param[in] resource Pointer to the DMA resource
Kojto 111:4336505e4b1c 604 * \param[in] type Callback function type
Kojto 111:4336505e4b1c 605 *
Kojto 111:4336505e4b1c 606 */
Kojto 111:4336505e4b1c 607 static inline void dma_disable_callback(struct dma_resource *resource,
Kojto 111:4336505e4b1c 608 enum dma_callback_type type)
Kojto 111:4336505e4b1c 609 {
Kojto 111:4336505e4b1c 610 Assert(resource);
Kojto 111:4336505e4b1c 611
Kojto 111:4336505e4b1c 612 resource->callback_enable &= ~(1 << type);
Kojto 111:4336505e4b1c 613 g_chan_interrupt_flag[resource->channel_id] &= (~(1UL << type) & DMAC_CHINTENSET_MASK);
Kojto 111:4336505e4b1c 614 DMAC->CHINTENCLR.reg = (1UL << type);
Kojto 111:4336505e4b1c 615 }
Kojto 111:4336505e4b1c 616
Kojto 111:4336505e4b1c 617 /**
Kojto 111:4336505e4b1c 618 * \brief Register a callback function for a dedicated DMA resource.
Kojto 111:4336505e4b1c 619 *
Kojto 111:4336505e4b1c 620 * There are three types of callback functions, which can be registered:
Kojto 111:4336505e4b1c 621 * - Callback for transfer complete
Kojto 111:4336505e4b1c 622 * - Callback for transfer error
Kojto 111:4336505e4b1c 623 * - Callback for channel suspend
Kojto 111:4336505e4b1c 624 *
Kojto 111:4336505e4b1c 625 * \param[in] resource Pointer to the DMA resource
Kojto 111:4336505e4b1c 626 * \param[in] callback Pointer to the callback function
Kojto 111:4336505e4b1c 627 * \param[in] type Callback function type
Kojto 111:4336505e4b1c 628 *
Kojto 111:4336505e4b1c 629 */
Kojto 111:4336505e4b1c 630 static inline void dma_register_callback(struct dma_resource *resource,
Kojto 111:4336505e4b1c 631 dma_callback_t callback, enum dma_callback_type type)
Kojto 111:4336505e4b1c 632 {
Kojto 111:4336505e4b1c 633 Assert(resource);
Kojto 111:4336505e4b1c 634
Kojto 111:4336505e4b1c 635 resource->callback[type] = callback;
Kojto 111:4336505e4b1c 636 }
Kojto 111:4336505e4b1c 637
Kojto 111:4336505e4b1c 638 /**
Kojto 111:4336505e4b1c 639 * \brief Unregister a callback function for a dedicated DMA resource.
Kojto 111:4336505e4b1c 640 *
Kojto 111:4336505e4b1c 641 * There are three types of callback functions:
Kojto 111:4336505e4b1c 642 * - Callback for transfer complete
Kojto 111:4336505e4b1c 643 * - Callback for transfer error
Kojto 111:4336505e4b1c 644 * - Callback for channel suspend
Kojto 111:4336505e4b1c 645 *
Kojto 111:4336505e4b1c 646 * The application can unregister any of the callback functions which
Kojto 111:4336505e4b1c 647 * are already registered and are no longer needed.
Kojto 111:4336505e4b1c 648 *
Kojto 111:4336505e4b1c 649 * \param[in] resource Pointer to the DMA resource
Kojto 111:4336505e4b1c 650 * \param[in] type Callback function type
Kojto 111:4336505e4b1c 651 *
Kojto 111:4336505e4b1c 652 */
Kojto 111:4336505e4b1c 653 static inline void dma_unregister_callback(struct dma_resource *resource,
Kojto 111:4336505e4b1c 654 enum dma_callback_type type)
Kojto 111:4336505e4b1c 655 {
Kojto 111:4336505e4b1c 656 Assert(resource);
Kojto 111:4336505e4b1c 657
Kojto 111:4336505e4b1c 658 resource->callback[type] = NULL;
Kojto 111:4336505e4b1c 659 }
Kojto 111:4336505e4b1c 660
Kojto 111:4336505e4b1c 661 /**
Kojto 111:4336505e4b1c 662 * \brief Will set a software trigger for resource.
Kojto 111:4336505e4b1c 663 *
Kojto 111:4336505e4b1c 664 * This function is used to set a software trigger on the DMA channel
Kojto 111:4336505e4b1c 665 * associated with resource. If a trigger is already pending no new trigger
Kojto 111:4336505e4b1c 666 * will be generated for the channel.
Kojto 111:4336505e4b1c 667 *
Kojto 111:4336505e4b1c 668 * \param[in] resource Pointer to the DMA resource
Kojto 111:4336505e4b1c 669 */
Kojto 111:4336505e4b1c 670 static inline void dma_trigger_transfer(struct dma_resource *resource)
Kojto 111:4336505e4b1c 671 {
Kojto 111:4336505e4b1c 672 Assert(resource);
Kojto 111:4336505e4b1c 673
Kojto 111:4336505e4b1c 674 DMAC->SWTRIGCTRL.reg |= (1 << resource->channel_id);
Kojto 111:4336505e4b1c 675 }
Kojto 111:4336505e4b1c 676
Kojto 111:4336505e4b1c 677 /**
Kojto 111:4336505e4b1c 678 * \brief Initializes DMA transfer configuration with predefined default values.
Kojto 111:4336505e4b1c 679 *
Kojto 111:4336505e4b1c 680 * This function will initialize a given DMA descriptor configuration structure to
Kojto 111:4336505e4b1c 681 * a set of known default values. This function should be called on
Kojto 111:4336505e4b1c 682 * any new instance of the configuration structure before being
Kojto 111:4336505e4b1c 683 * modified by the user application.
Kojto 111:4336505e4b1c 684 *
Kojto 111:4336505e4b1c 685 * The default configuration is as follows:
Kojto 111:4336505e4b1c 686 * \li Set the descriptor as valid
Kojto 111:4336505e4b1c 687 * \li Disable event output
Kojto 111:4336505e4b1c 688 * \li No block action
Kojto 111:4336505e4b1c 689 * \li Set beat size as byte
Kojto 111:4336505e4b1c 690 * \li Enable source increment
Kojto 111:4336505e4b1c 691 * \li Enable destination increment
Kojto 111:4336505e4b1c 692 * \li Step size is applied to the destination address
Kojto 111:4336505e4b1c 693 * \li Address increment is beat size multiplied by 1
Kojto 111:4336505e4b1c 694 * \li Default transfer size is set to 0
Kojto 111:4336505e4b1c 695 * \li Default source address is set to NULL
Kojto 111:4336505e4b1c 696 * \li Default destination address is set to NULL
Kojto 111:4336505e4b1c 697 * \li Default next descriptor not available
Kojto 111:4336505e4b1c 698 * \param[out] config Pointer to the configuration
Kojto 111:4336505e4b1c 699 *
Kojto 111:4336505e4b1c 700 */
Kojto 111:4336505e4b1c 701 static inline void dma_descriptor_get_config_defaults(struct dma_descriptor_config *config)
Kojto 111:4336505e4b1c 702 {
Kojto 111:4336505e4b1c 703 Assert(config);
Kojto 111:4336505e4b1c 704
Kojto 111:4336505e4b1c 705 /* Set descriptor as valid */
Kojto 111:4336505e4b1c 706 config->descriptor_valid = true;
Kojto 111:4336505e4b1c 707 /* Disable event output */
Kojto 111:4336505e4b1c 708 config->event_output_selection = DMA_EVENT_OUTPUT_DISABLE;
Kojto 111:4336505e4b1c 709 /* No block action */
Kojto 111:4336505e4b1c 710 config->block_action = DMA_BLOCK_ACTION_NOACT;
Kojto 111:4336505e4b1c 711 /* Set beat size to one byte */
Kojto 111:4336505e4b1c 712 config->beat_size = DMA_BEAT_SIZE_BYTE;
Kojto 111:4336505e4b1c 713 /* Enable source increment */
Kojto 111:4336505e4b1c 714 config->src_increment_enable = true;
Kojto 111:4336505e4b1c 715 /* Enable destination increment */
Kojto 111:4336505e4b1c 716 config->dst_increment_enable = true;
Kojto 111:4336505e4b1c 717 /* Step size is applied to the destination address */
Kojto 111:4336505e4b1c 718 config->step_selection = DMA_STEPSEL_DST;
Kojto 111:4336505e4b1c 719 /* Address increment is beat size multiplied by 1*/
Kojto 111:4336505e4b1c 720 config->step_size = DMA_ADDRESS_INCREMENT_STEP_SIZE_1;
Kojto 111:4336505e4b1c 721 /* Default transfer size is set to 0 */
Kojto 111:4336505e4b1c 722 config->block_transfer_count = 0;
Kojto 111:4336505e4b1c 723 /* Default source address is set to NULL */
Kojto 111:4336505e4b1c 724 config->source_address = (uint32_t)NULL;
Kojto 111:4336505e4b1c 725 /* Default destination address is set to NULL */
Kojto 111:4336505e4b1c 726 config->destination_address = (uint32_t)NULL;
Kojto 111:4336505e4b1c 727 /** Next descriptor address set to 0 */
Kojto 111:4336505e4b1c 728 config->next_descriptor_address = 0;
Kojto 111:4336505e4b1c 729 }
Kojto 111:4336505e4b1c 730
Kojto 111:4336505e4b1c 731 /**
Kojto 111:4336505e4b1c 732 * \brief Update DMA descriptor.
Kojto 111:4336505e4b1c 733 *
Kojto 111:4336505e4b1c 734 * This function can update the descriptor of an allocated DMA resource.
Kojto 111:4336505e4b1c 735 *
Kojto 111:4336505e4b1c 736 */
Kojto 111:4336505e4b1c 737 static inline void dma_update_descriptor(struct dma_resource *resource,
Kojto 111:4336505e4b1c 738 DmacDescriptor* descriptor)
Kojto 111:4336505e4b1c 739 {
Kojto 111:4336505e4b1c 740 Assert(resource);
Kojto 111:4336505e4b1c 741
Kojto 111:4336505e4b1c 742 resource->descriptor = descriptor;
Kojto 111:4336505e4b1c 743 }
Kojto 111:4336505e4b1c 744
Kojto 111:4336505e4b1c 745 /**
Kojto 111:4336505e4b1c 746 * \brief Reset DMA descriptor.
Kojto 111:4336505e4b1c 747 *
Kojto 111:4336505e4b1c 748 * This function will clear the DESCADDR register of an allocated DMA resource.
Kojto 111:4336505e4b1c 749 *
Kojto 111:4336505e4b1c 750 */
Kojto 111:4336505e4b1c 751 static inline void dma_reset_descriptor(struct dma_resource *resource)
Kojto 111:4336505e4b1c 752 {
Kojto 111:4336505e4b1c 753 Assert(resource);
Kojto 111:4336505e4b1c 754
Kojto 111:4336505e4b1c 755 resource->descriptor = NULL;
Kojto 111:4336505e4b1c 756 }
Kojto 111:4336505e4b1c 757
Kojto 111:4336505e4b1c 758 void dma_get_config_defaults(struct dma_resource_config *config);
Kojto 111:4336505e4b1c 759 enum status_code dma_allocate(struct dma_resource *resource,
Kojto 111:4336505e4b1c 760 struct dma_resource_config *config);
Kojto 111:4336505e4b1c 761 enum status_code dma_free(struct dma_resource *resource);
Kojto 111:4336505e4b1c 762 enum status_code dma_start_transfer_job(struct dma_resource *resource);
Kojto 111:4336505e4b1c 763 void dma_abort_job(struct dma_resource *resource);
Kojto 111:4336505e4b1c 764 void dma_suspend_job(struct dma_resource *resource);
Kojto 111:4336505e4b1c 765 void dma_resume_job(struct dma_resource *resource);
Kojto 111:4336505e4b1c 766 void dma_descriptor_create(DmacDescriptor* descriptor,
Kojto 111:4336505e4b1c 767 struct dma_descriptor_config *config);
Kojto 111:4336505e4b1c 768 enum status_code dma_add_descriptor(struct dma_resource *resource,
Kojto 111:4336505e4b1c 769 DmacDescriptor* descriptor);
Kojto 111:4336505e4b1c 770
Kojto 111:4336505e4b1c 771 /** @} */
Kojto 111:4336505e4b1c 772
Kojto 111:4336505e4b1c 773 /**
Kojto 111:4336505e4b1c 774 * \page asfdoc_sam0_dma_extra Extra Information for DMAC Driver
Kojto 111:4336505e4b1c 775 *
Kojto 111:4336505e4b1c 776 * \section asfdoc_sam0_dma_extra_acronyms Acronyms
Kojto 111:4336505e4b1c 777 * Below is a table listing the acronyms used in this module, along with their
Kojto 111:4336505e4b1c 778 * intended meanings.
Kojto 111:4336505e4b1c 779 *
Kojto 111:4336505e4b1c 780 * <table>
Kojto 111:4336505e4b1c 781 * <tr>
Kojto 111:4336505e4b1c 782 * <th>Acronym</th>
Kojto 111:4336505e4b1c 783 * <th>Description</th>
Kojto 111:4336505e4b1c 784 * </tr>
Kojto 111:4336505e4b1c 785 * <tr>
Kojto 111:4336505e4b1c 786 * <td>DMA</td>
Kojto 111:4336505e4b1c 787 * <td>Direct Memory Access</td>
Kojto 111:4336505e4b1c 788 * </tr>
Kojto 111:4336505e4b1c 789 * <tr>
Kojto 111:4336505e4b1c 790 * <td>DMAC</td>
Kojto 111:4336505e4b1c 791 * <td>Direct Memory Access Controller </td>
Kojto 111:4336505e4b1c 792 * </tr>
Kojto 111:4336505e4b1c 793 * <tr>
Kojto 111:4336505e4b1c 794 * <td>CPU</td>
Kojto 111:4336505e4b1c 795 * <td>Central Processing Unit</td>
Kojto 111:4336505e4b1c 796 * </tr>
Kojto 111:4336505e4b1c 797 * </table>
Kojto 111:4336505e4b1c 798 *
Kojto 111:4336505e4b1c 799 *
Kojto 111:4336505e4b1c 800 * \section asfdoc_sam0_dma_extra_dependencies Dependencies
Kojto 111:4336505e4b1c 801 * This driver has the following dependencies:
Kojto 111:4336505e4b1c 802 *
Kojto 111:4336505e4b1c 803 * - \ref asfdoc_sam0_system_clock_group "System Clock Driver"
Kojto 111:4336505e4b1c 804 *
Kojto 111:4336505e4b1c 805 *
Kojto 111:4336505e4b1c 806 * \section asfdoc_sam0_dma_extra_errata Errata
Kojto 111:4336505e4b1c 807 * There are no errata related to this driver.
Kojto 111:4336505e4b1c 808 *
Kojto 111:4336505e4b1c 809 *
Kojto 111:4336505e4b1c 810 * \section asfdoc_sam0_dma_extra_history Module History
Kojto 111:4336505e4b1c 811 * An overview of the module history is presented in the table below, with
Kojto 111:4336505e4b1c 812 * details on the enhancements and fixes made to the module since its first
Kojto 111:4336505e4b1c 813 * release. The current version of this corresponds to the newest version in
Kojto 111:4336505e4b1c 814 * the table.
Kojto 111:4336505e4b1c 815 *
Kojto 111:4336505e4b1c 816 * <table>
Kojto 111:4336505e4b1c 817 * <tr>
Kojto 111:4336505e4b1c 818 * <th>Changelog</th>
Kojto 111:4336505e4b1c 819 * </tr>
Kojto 111:4336505e4b1c 820 * <tr>
Kojto 111:4336505e4b1c 821 * <td>Add SAM C21 support</td>
Kojto 111:4336505e4b1c 822 * </tr>
Kojto 111:4336505e4b1c 823 * <tr>
Kojto 111:4336505e4b1c 824 * <td>Add SAM L21 support</td>
Kojto 111:4336505e4b1c 825 * </tr>
Kojto 111:4336505e4b1c 826 * <tr>
Kojto 111:4336505e4b1c 827 * <td>Initial Release</td>
Kojto 111:4336505e4b1c 828 * </tr>
Kojto 111:4336505e4b1c 829 * </table>
Kojto 111:4336505e4b1c 830 */
Kojto 111:4336505e4b1c 831
Kojto 111:4336505e4b1c 832 /**
Kojto 111:4336505e4b1c 833 * \page asfdoc_sam0_dma_exqsg Examples for DMAC Driver
Kojto 111:4336505e4b1c 834 *
Kojto 111:4336505e4b1c 835 * This is a list of the available Quick Start Guides (QSGs) and example
Kojto 111:4336505e4b1c 836 * applications for \ref asfdoc_sam0_dma_group. QSGs are simple examples with
Kojto 111:4336505e4b1c 837 * step-by-step instructions to configure and use this driver in a selection of
Kojto 111:4336505e4b1c 838 * use cases. Note that QSGs can be compiled as a standalone application or be
Kojto 111:4336505e4b1c 839 * added to the user application.
Kojto 111:4336505e4b1c 840 *
Kojto 111:4336505e4b1c 841 * - \subpage asfdoc_sam0_dma_basic_use_case
Kojto 111:4336505e4b1c 842 *
Kojto 111:4336505e4b1c 843 * \note More DMA usage examples are available in peripheral QSGs.
Kojto 111:4336505e4b1c 844 * A quick start guide for TC/TCC
Kojto 111:4336505e4b1c 845 * shows the usage of DMA event trigger; SERCOM SPI/USART/I<SUP>2</SUP>C has example for
Kojto 111:4336505e4b1c 846 * DMA transfer from peripheral to memory or from memory to peripheral;
Kojto 111:4336505e4b1c 847 * ADC/DAC shows peripheral to peripheral transfer.
Kojto 111:4336505e4b1c 848 *
Kojto 111:4336505e4b1c 849 * \page asfdoc_sam0_dma_document_revision_history Document Revision History
Kojto 111:4336505e4b1c 850 *
Kojto 111:4336505e4b1c 851 * <table>
Kojto 111:4336505e4b1c 852 * <tr>
Kojto 111:4336505e4b1c 853 * <th>Doc. Rev.</td>
Kojto 111:4336505e4b1c 854 * <th>Date</td>
Kojto 111:4336505e4b1c 855 * <th>Comments</td>
Kojto 111:4336505e4b1c 856 * </tr>
Kojto 111:4336505e4b1c 857 * <tr>
Kojto 111:4336505e4b1c 858 * <td>C</td>
Kojto 111:4336505e4b1c 859 * <td>06/2015</td>
Kojto 111:4336505e4b1c 860 * <td>Added SAML21, SAMC21, and SAMDAx support</td>
Kojto 111:4336505e4b1c 861 * </tr>
Kojto 111:4336505e4b1c 862 * <tr>
Kojto 111:4336505e4b1c 863 * <td>B</td>
Kojto 111:4336505e4b1c 864 * <td>12/2014</td>
Kojto 111:4336505e4b1c 865 * <td>Added SAMR21 and SAMD10/D11 support</td>
Kojto 111:4336505e4b1c 866 * </tr>
Kojto 111:4336505e4b1c 867 * <tr>
Kojto 111:4336505e4b1c 868 * <td>A</td>
Kojto 111:4336505e4b1c 869 * <td>02/2014</td>
Kojto 111:4336505e4b1c 870 * <td>Initial release</td>
Kojto 111:4336505e4b1c 871 * </tr>
Kojto 111:4336505e4b1c 872 * </table>
Kojto 111:4336505e4b1c 873 */
Kojto 111:4336505e4b1c 874
Kojto 111:4336505e4b1c 875 #ifdef __cplusplus
Kojto 111:4336505e4b1c 876 }
Kojto 111:4336505e4b1c 877 #endif
Kojto 111:4336505e4b1c 878
Kojto 111:4336505e4b1c 879 #endif /* DMA_H_INCLUDED */