1 /**
2 * @file xmc_dma.h
3 * @date 2018-09-18
4 *
5 * @cond
6 *********************************************************************************************************************
7 * XMClib v2.1.24 - XMC Peripheral Driver Library
8 *
9 * Copyright (c) 2015-2019, Infineon Technologies AG
10 * All rights reserved.
11 *
12 * Redistribution and use in source and binary forms, with or without modification,are permitted provided that the
13 * following conditions are met:
14 *
15 * Redistributions of source code must retain the above copyright notice, this list of conditions and the following
16 * disclaimer.
17 *
18 * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
19 * disclaimer in the documentation and/or other materials provided with the distribution.
20 *
21 * Neither the name of the copyright holders nor the names of its contributors may be used to endorse or promote
22 * products derived from this software without specific prior written permission.
23 *
24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
25 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
26 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
27 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
28 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
29 * WHETHER IN CONTRACT, STRICT LIABILITY,OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 *
32 * To improve the quality of the software, users are encouraged to share modifications, enhancements or bug fixes with
33 * Infineon Technologies AG dave@infineon.com).
34 *********************************************************************************************************************
35 *
36 * Change History
37 * --------------
38 *
39 * 2015-02-20:
40 * - Initial <br>
41 *
42 * 2015-06-20:
43 * - Add the declarations for the following APIs: <br>
44 * XMC_DMA_DisableRequestLine, XMC_DMA_ClearRequestLine, <br>
45 * XMC_DMA_CH_ClearSourcePeripheralRequest, <br>
46 * XMC_DMA_CH_ClearDestinationPeripheralRequest <br>
47 * - Documentation updates <br>
48 * - Removed version macros and declaration of GetDriverVersion API <br>
49 *
50 * 2016-10-28:
51 * - Fix documentation on maximum block size
52 *
53 * 2017-09-28:
54 * - Improved documentation and added XMC_DMA_CH_EnableFifo() and XMC_DMA_CH_DisableFifo()
55 *
56 * 2018-09-18:
57 * - Added XMC_DMA_CH_GetTransferredData()
58 *
59 * @endcond
60 */
61
62 #ifndef XMC_DMA_H
63 #define XMC_DMA_H
64
65 /*******************************************************************************
66 * HEADER FILES
67 *******************************************************************************/
68
69 #include "xmc_common.h"
70
71 #if defined (GPDMA0)
72
73 #include "xmc_dma_map.h"
74
75 /**
76 * @addtogroup XMClib XMC Peripheral Library
77 * @{
78 */
79
80 /**
81 * @addtogroup DMA
82 * @brief General purpose DMA (GPDMA) driver for the XMC4000 microcontroller family
83 *
84 * The GPDMA is a highly configurable DMA controller that allows high-speed data transfers
85 * between peripherals and memories. Complex data transfers can be done with minimal
86 * intervention of the processor, making CPU available for other operations.
87 *
88 * GPDMA provides extensive support for XMC microcontroller peripherals like A/D, D/A
89 * converters and timers. Data transfers through communication interfaces (USIC) using the
90 * GPDMA increase efficiency and parallelism for real-time applications.
91 *
92 * The DMA low level driver provides functions to configure and initialize the GPDMA
93 * hardware peripheral.
94 * @{
95 */
96
97 /*******************************************************************************
98 * MACROS
99 *******************************************************************************/
100
101 #if defined (GPDMA0)
102 #define XMC_DMA0 ((XMC_DMA_t *)GPDMA0_CH0_BASE) /**< DMA module 0 */
103 #define XMC_DMA0_NUM_CHANNELS 8
104 #endif
105
106 #if defined (GPDMA1)
107 #define XMC_DMA1 ((XMC_DMA_t *)GPDMA1_CH0_BASE) /**< DMA module 1, only available in XMC45xx series */
108 #define XMC_DMA1_NUM_CHANNELS 4
109 #endif
110
111 /*******************************************************************************
112 * ENUMS
113 *******************************************************************************/
114
115 /**
116 * DMA transfer types
117 */
118 typedef enum XMC_DMA_CH_TRANSFER_TYPE
119 {
120 XMC_DMA_CH_TRANSFER_TYPE_SINGLE_BLOCK, /**< Single block */
121 XMC_DMA_CH_TRANSFER_TYPE_MULTI_BLOCK_SRCADR_CONTIGUOUS_DSTADR_RELOAD, /**< Multi-block: src address contiguous, dst address reload */
122 XMC_DMA_CH_TRANSFER_TYPE_MULTI_BLOCK_SRCADR_RELOAD_DSTADR_CONTIGUOUS, /**< Multi-block: src address reload, dst address contiguous */
123 XMC_DMA_CH_TRANSFER_TYPE_MULTI_BLOCK_SRCADR_RELOAD_DSTADR_RELOAD, /**< Multi-block: src address reload, dst address reload */
124 XMC_DMA_CH_TRANSFER_TYPE_MULTI_BLOCK_SRCADR_CONTIGUOUS_DSTADR_LINKED, /**< Multi-block: src address contiguous, dst address linked */
125 XMC_DMA_CH_TRANSFER_TYPE_MULTI_BLOCK_SRCADR_RELOAD_DSTADR_LINKED, /**< Multi-block: src address reload, dst address linked */
126 XMC_DMA_CH_TRANSFER_TYPE_MULTI_BLOCK_SRCADR_LINKED_DSTADR_CONTIGUOUS, /**< Multi-block: src address linked, dst address contiguous */
127 XMC_DMA_CH_TRANSFER_TYPE_MULTI_BLOCK_SRCADR_LINKED_DSTADR_RELOAD, /**< Multi-block: src address linked, dst address reload */
128 XMC_DMA_CH_TRANSFER_TYPE_MULTI_BLOCK_SRCADR_LINKED_DSTADR_LINKED /**< Multi-block: src address linked, dst address linked */
129 } XMC_DMA_CH_TRANSFER_TYPE_t;
130
131 /**
132 * DMA transfer flow modes
133 */
134 typedef enum XMC_DMA_CH_TRANSFER_FLOW
135 {
136 XMC_DMA_CH_TRANSFER_FLOW_M2M_DMA = 0x0UL, /**< Memory to memory (DMA flow controller) */
137 XMC_DMA_CH_TRANSFER_FLOW_M2P_DMA = 0x1UL, /**< Memory to peripheral (DMA flow controller) */
138 XMC_DMA_CH_TRANSFER_FLOW_P2M_DMA = 0x2UL, /**< Peripheral to memory (DMA flow controller) */
139 XMC_DMA_CH_TRANSFER_FLOW_P2P_DMA = 0x3UL, /**< Peripheral to peripheral (DMA flow controller) */
140 XMC_DMA_CH_TRANSFER_FLOW_P2M_PER = 0x4UL, /**< Peripheral to memory (Peripheral flow controller) */
141 XMC_DMA_CH_TRANSFER_FLOW_P2P_SRCPER = 0x5UL, /**< Peripheral to peripheral (Source peripheral flow controller) */
142 XMC_DMA_CH_TRANSFER_FLOW_M2P_PER = 0x6UL, /**< Memory to peripheral (Peripheral flow controller) */
143 XMC_DMA_CH_TRANSFER_FLOW_P2P_DSTPER = 0x7UL /**< Peripheral to peripheral (Destination peripheral flow controller) */
144 } XMC_DMA_CH_TRANSFER_FLOW_t;
145
146 /**
147 * Valid burst length values
148 */
149 typedef enum XMC_DMA_CH_BURST_LENGTH
150 {
151 XMC_DMA_CH_BURST_LENGTH_1 = 0x0UL, /**< Burst length: 1 word */
152 XMC_DMA_CH_BURST_LENGTH_4 = 0x1UL, /**< Burst length: 4 words */
153 XMC_DMA_CH_BURST_LENGTH_8 = 0x2UL /**< Burst length: 8 words */
154 } XMC_DMA_CH_BURST_LENGTH_t;
155
156 /**
157 * Valid transfer width values
158 */
159 typedef enum XMC_DMA_CH_TRANSFER_WIDTH
160 {
161 XMC_DMA_CH_TRANSFER_WIDTH_8 = 0x0UL, /**< 8-bit transfer width */
162 XMC_DMA_CH_TRANSFER_WIDTH_16 = 0x1UL, /**< 16-bit transfer width */
163 XMC_DMA_CH_TRANSFER_WIDTH_32 = 0x2UL /**< 32-bit transfer width */
164 } XMC_DMA_CH_TRANSFER_WIDTH_t;
165
166 /**
167 * DMA address count mode
168 */
169 typedef enum XMC_DMA_CH_ADDRESS_COUNT_MODE
170 {
171 XMC_DMA_CH_ADDRESS_COUNT_MODE_INCREMENT = 0x0UL, /**< Address count mode: increment */
172 XMC_DMA_CH_ADDRESS_COUNT_MODE_DECREMENT = 0x1UL, /**< Address count mode: decrement */
173 XMC_DMA_CH_ADDRESS_COUNT_MODE_NO_CHANGE = 0x2UL /**< Address count mode: no change */
174 } XMC_DMA_CH_ADDRESS_COUNT_MODE_t;
175
176 /**
177 * DMA channel priorities
178 */
179 typedef enum XMC_DMA_CH_PRIORITY
180 {
181 XMC_DMA_CH_PRIORITY_0 = 0x0UL << GPDMA0_CH_CFGL_CH_PRIOR_Pos, /**< DMA channel priority 0 (low) */
182 XMC_DMA_CH_PRIORITY_1 = 0x1UL << GPDMA0_CH_CFGL_CH_PRIOR_Pos, /**< DMA channel priority 1 */
183 XMC_DMA_CH_PRIORITY_2 = 0x2UL << GPDMA0_CH_CFGL_CH_PRIOR_Pos, /**< DMA channel priority 2 */
184 XMC_DMA_CH_PRIORITY_3 = 0x3UL << GPDMA0_CH_CFGL_CH_PRIOR_Pos, /**< DMA channel priority 3 */
185 XMC_DMA_CH_PRIORITY_4 = 0x4UL << GPDMA0_CH_CFGL_CH_PRIOR_Pos, /**< DMA channel priority 4 */
186 XMC_DMA_CH_PRIORITY_5 = 0x5UL << GPDMA0_CH_CFGL_CH_PRIOR_Pos, /**< DMA channel priority 5 */
187 XMC_DMA_CH_PRIORITY_6 = 0x6UL << GPDMA0_CH_CFGL_CH_PRIOR_Pos, /**< DMA channel priority 6 */
188 XMC_DMA_CH_PRIORITY_7 = 0x7UL << GPDMA0_CH_CFGL_CH_PRIOR_Pos /**< DMA channel priority 7 (high) */
189 } XMC_DMA_CH_PRIORITY_t;
190
191 /**
192 * Source handshake interface
193 */
194 typedef enum XMC_DMA_CH_SRC_HANDSHAKING
195 {
196 XMC_DMA_CH_SRC_HANDSHAKING_HARDWARE = 0x0UL << GPDMA0_CH_CFGL_HS_SEL_SRC_Pos, /**< Source: hardware handshake */
197 XMC_DMA_CH_SRC_HANDSHAKING_SOFTWARE = 0x1UL << GPDMA0_CH_CFGL_HS_SEL_SRC_Pos /**< Source: software handshake */
198 } XMC_DMA_CH_SRC_HANDSHAKING_t;
199
200 /**
201 * Destination handshake interface
202 */
203 typedef enum XMC_DMA_CH_DST_HANDSHAKING
204 {
205 XMC_DMA_CH_DST_HANDSHAKING_HARDWARE = 0x0UL << GPDMA0_CH_CFGL_HS_SEL_DST_Pos, /**< Destination: hardware handshake */
206 XMC_DMA_CH_DST_HANDSHAKING_SOFTWARE = 0x1UL << GPDMA0_CH_CFGL_HS_SEL_DST_Pos /**< Destination: software handshake */
207 } XMC_DMA_CH_DST_HANDSHAKING_t;
208
209 /**
210 * DMA hardware handshaking interface
211 * Hardware handshaking available only if DMA is flow controller
212 */
213 typedef enum XMC_DMA_CH_HARDWARE_HANDSHAKING_IF
214 {
215 XMC_DMA_CH_HARDWARE_HANDSHAKING_IF_0 = 0x0UL, /**< Hardware handshaking interface 0 */
216 XMC_DMA_CH_HARDWARE_HANDSHAKING_IF_1 = 0x1UL, /**< Hardware handshaking interface 1 */
217 XMC_DMA_CH_HARDWARE_HANDSHAKING_IF_2 = 0x2UL, /**< Hardware handshaking interface 2 */
218 XMC_DMA_CH_HARDWARE_HANDSHAKING_IF_3 = 0x3UL, /**< Hardware handshaking interface 3 */
219 XMC_DMA_CH_HARDWARE_HANDSHAKING_IF_4 = 0x4UL, /**< Hardware handshaking interface 4 */
220 XMC_DMA_CH_HARDWARE_HANDSHAKING_IF_5 = 0x5UL, /**< Hardware handshaking interface 5 */
221 XMC_DMA_CH_HARDWARE_HANDSHAKING_IF_6 = 0x6UL, /**< Hardware handshaking interface 6 */
222 XMC_DMA_CH_HARDWARE_HANDSHAKING_IF_7 = 0x7UL /**< Hardware handshaking interface 7 */
223 } XMC_DMA_CH_HARDWARE_HANDSHAKING_IF_t;
224
225 /**
226 * DMA events
227 */
228 typedef enum XMC_DMA_CH_EVENT
229 {
230 XMC_DMA_CH_EVENT_TRANSFER_COMPLETE = 0x1UL, /**< Transfer complete event */
231 XMC_DMA_CH_EVENT_BLOCK_TRANSFER_COMPLETE = 0x2UL, /**< Block transfer complete event */
232 XMC_DMA_CH_EVENT_SRC_TRANSACTION_COMPLETE = 0x4UL, /**< Source transaction complete event */
233 XMC_DMA_CH_EVENT_DST_TRANSACTION_COMPLETE = 0x8UL, /**< Destination transaction complete event */
234 XMC_DMA_CH_EVENT_ERROR = 0x10UL /**< DMA error event */
235 } XMC_DMA_CH_EVENT_t;
236
237 /**
238 * Transaction types
239 */
240 typedef enum XMC_DMA_CH_TRANSACTION_TYPE
241 {
242 XMC_DMA_CH_TRANSACTION_TYPE_SINGLE, /**< Single DMA transaction */
243 XMC_DMA_CH_TRANSACTION_TYPE_BURST /**< Burst transaction */
244 } XMC_DMA_CH_TRANSACTION_TYPE_t;
245
246 /**
247 * DMA channel status values
248 */
249 typedef enum XMC_DMA_CH_STATUS
250 {
251 XMC_DMA_CH_STATUS_OK, /**< DMA status OK */
252 XMC_DMA_CH_STATUS_ERROR, /**< DMA status error */
253 XMC_DMA_CH_STATUS_BUSY /**< DMA is busy */
254 } XMC_DMA_CH_STATUS_t;
255
256 /*******************************************************************************
257 * DATA STRUCTURES
258 *******************************************************************************/
259
260 /**
261 * DMA channel configuration structure <br>
262 *
263 * The structure represents a collection of all hardware registers used
264 * to configure the DMA channel. It is contained within the ::XMC_DMA_t
265 * structure. It's registers can be used to configure DMA transfer details
266 * like source address, destination address, block size, incrementation
267 * modes and the like.
268 */
269
270 typedef struct {
271 __IO uint32_t SAR;
272 __I uint32_t RESERVED0;
273 __IO uint32_t DAR;
274 __I uint32_t RESERVED1;
275 __IO uint32_t LLP;
276 __I uint32_t RESERVED2;
277 __IO uint32_t CTLL;
278 __IO uint32_t CTLH;
279 __IO uint32_t SSTAT;
280 __I uint32_t RESERVED3;
281 __IO uint32_t DSTAT;
282 __I uint32_t RESERVED4;
283 __IO uint32_t SSTATAR;
284 __I uint32_t RESERVED5;
285 __IO uint32_t DSTATAR;
286 __I uint32_t RESERVED6;
287 __IO uint32_t CFGL;
288 __IO uint32_t CFGH;
289 __IO uint32_t SGR;
290 __I uint32_t RESERVED7;
291 __IO uint32_t DSR;
292 __I uint32_t RESERVED8;
293 } GPDMA_CH_t;
294
295 /**
296 * DMA device structure <br>
297 *
298 * The structure represents a collection of all hardware registers used
299 * to configure the GPDMA peripheral on the XMC4000 series of microcontrollers.
300 * The registers can be accessed with ::XMC_DMA0 and ::XMC_DMA1.
301 */
302 typedef struct {
303 GPDMA_CH_t CH[8];
304
305 __IO uint32_t RAWCHEV[10];
306 __I uint32_t STATUSCHEV[10];
307 __IO uint32_t MASKCHEV[10];
308 __O uint32_t CLEARCHEV[10];
309 __I uint32_t STATUSGLEV;
310 __I uint32_t RESERVED20;
311 __IO uint32_t REQSRCREG;
312 __I uint32_t RESERVED21;
313 __IO uint32_t REQDSTREG;
314 __I uint32_t RESERVED22;
315 __IO uint32_t SGLREQSRCREG;
316 __I uint32_t RESERVED23;
317 __IO uint32_t SGLREQDSTREG;
318 __I uint32_t RESERVED24;
319 __IO uint32_t LSTSRCREG;
320 __I uint32_t RESERVED25;
321 __IO uint32_t LSTDSTREG;
322 __I uint32_t RESERVED26;
323 __IO uint32_t DMACFGREG;
324 __I uint32_t RESERVED27;
325 __IO uint32_t CHENREG;
326 __I uint32_t RESERVED28;
327 __I uint32_t ID;
328 __I uint32_t RESERVED29[19];
329 __I uint32_t TYPE;
330 __I uint32_t VERSION;
331 } XMC_DMA_t;
332
333 /* Anonymous structure/union guard start */
334 #if defined (__CC_ARM)
335 #pragma push
336 #pragma anon_unions
337 #elif defined (__TASKING__)
338 #pragma warning 586
339 #endif
340
341 /**
342 * DMA channel linked list item.
343 * Note: Needs to be word aligned
344 */
345 typedef struct XMC_DMA_LLI
346 {
347 uint32_t src_addr; /**< Source address */
348 uint32_t dst_addr; /**< Destination address */
349 struct XMC_DMA_LLI *llp; /**< Linked list pointer of type XMC_DMA_LLI_t */
350 union
351 {
352 struct
353 {
354 uint32_t enable_interrupt: 1; /**< Enable interrupts? */
355 uint32_t dst_transfer_width: 3; /**< Destination transfer width (:: XMC_DMA_CH_TRANSFER_WIDTH_t) */
356 uint32_t src_transfer_width: 3; /**< Source transfer width (:: XMC_DMA_CH_TRANSFER_WIDTH_t) */
357 uint32_t dst_address_count_mode: 2; /**< Destination address count mode (:: XMC_DMA_CH_ADDRESS_COUNT_MODE_t) */
358 uint32_t src_address_count_mode: 2; /**< Source address count mode (:: XMC_DMA_CH_ADDRESS_COUNT_MODE_t) */
359 uint32_t dst_burst_length: 3; /**< Destination burst length (:: XMC_DMA_CH_BURST_LENGTH_t) */
360 uint32_t src_burst_length: 3; /**< Source burst length (:: XMC_DMA_CH_BURST_LENGTH_t) */
361 uint32_t enable_src_gather: 1; /**< Enable source gather? */
362 uint32_t enable_dst_scatter: 1; /**< Enable destination scatter? */
363 uint32_t : 1; /**< Reserved bits */
364 uint32_t transfer_flow: 3; /**< DMA transfer flow (:: XMC_DMA_CH_TRANSFER_FLOW_t) */
365 uint32_t : 4; /**< Reserved bits */
366 uint32_t enable_dst_linked_list: 1; /**< Enable destination linked list? */
367 uint32_t enable_src_linked_list: 1; /**< Enable source linked list? */
368 uint32_t : 3; /**< Reserved bits */
369 };
370 uint32_t control;
371 };
372 uint32_t block_size; /**< Transfer block size */
373 uint32_t src_status; /**< Source status */
374 uint32_t dst_status; /**< Destination status */
375 } XMC_DMA_LLI_t;
376
377 typedef XMC_DMA_LLI_t **XMC_DMA_LIST_t; /**< Type definition for a linked list pointer */
378
379 /**
380 * DMA channel configuration structure
381 */
382 typedef struct XMC_DMA_CH_CONFIG
383 {
384 union
385 {
386 uint32_t control;
387 struct
388 {
389 uint32_t enable_interrupt: 1; /**< Enable interrupts? */
390 uint32_t dst_transfer_width: 3; /**< Destination transfer width (:: XMC_DMA_CH_TRANSFER_WIDTH_t) */
391 uint32_t src_transfer_width: 3; /**< Source transfer width (:: XMC_DMA_CH_TRANSFER_WIDTH_t) */
392 uint32_t dst_address_count_mode: 2; /**< Destination address count mode (:: XMC_DMA_CH_ADDRESS_COUNT_MODE_t) */
393 uint32_t src_address_count_mode: 2; /**< Source address count mode (:: XMC_DMA_CH_ADDRESS_COUNT_MODE_t) */
394 uint32_t dst_burst_length: 3; /**< Destination burst length (:: XMC_DMA_CH_BURST_LENGTH_t) */
395 uint32_t src_burst_length: 3; /**< Source burst length (:: XMC_DMA_CH_BURST_LENGTH_t) */
396 uint32_t enable_src_gather: 1; /**< Enable source gather? */
397 uint32_t enable_dst_scatter: 1; /**< Enable destination scatter? */
398 uint32_t : 1;
399 uint32_t transfer_flow: 3; /**< DMA transfer flow (:: XMC_DMA_CH_TRANSFER_FLOW_t) */
400 uint32_t : 9;
401 };
402 };
403
404 uint32_t src_addr; /**< Source address */
405 uint32_t dst_addr; /**< Destination address */
406 XMC_DMA_LLI_t *linked_list_pointer; /**< Linked list pointer */
407
408 union
409 {
410 uint32_t src_gather_control;
411 struct
412 {
413 uint32_t src_gather_interval: 20; /**< Source gather interval */
414 uint32_t src_gather_count: 12; /**< Source gather count */
415 };
416 };
417
418 union
419 {
420 uint32_t dst_scatter_control;
421 struct
422 {
423 uint32_t dst_scatter_interval: 20; /**< Destination scatter interval */
424 uint32_t dst_scatter_count: 12; /**< Destination scatter count */
425 };
426 };
427
428 uint16_t block_size; /**< Block size for DMA controlled transfers [max. 4095] */
429 XMC_DMA_CH_TRANSFER_TYPE_t transfer_type; /**< DMA transfer type (:: XMC_DMA_CH_TRANSFER_TYPE_t) */
430 XMC_DMA_CH_PRIORITY_t priority; /**< DMA channel priority (::XMC_DMA_CH_PRIORITY_t) */
431 XMC_DMA_CH_SRC_HANDSHAKING_t src_handshaking; /**< DMA source handshaking interface (:: XMC_DMA_CH_SRC_HANDSHAKING_t) */
432 uint8_t src_peripheral_request; /**< Source peripheral request. See xmc_dma_map.h */
433 XMC_DMA_CH_DST_HANDSHAKING_t dst_handshaking; /**< DMA destination handshaking interface (:: XMC_DMA_CH_DST_HANDSHAKING_t) */
434 uint8_t dst_peripheral_request; /**< Destination peripheral request. See xmc_dma_map.h */
435 } XMC_DMA_CH_CONFIG_t;
436
437 /* Anonymous structure/union guard end */
438 #if defined (__CC_ARM)
439 #pragma pop
440 #elif defined (__TASKING__)
441 #pragma warning restore
442 #endif
443
444 /**
445 * DMA channel event handler
446 */
447 typedef void (*XMC_DMA_CH_EVENT_HANDLER_t)(XMC_DMA_CH_EVENT_t event);
448
449 /*******************************************************************************
450 * API PROTOTYPES
451 *******************************************************************************/
452
453 #ifdef __cplusplus
454 extern "C" {
455 #endif
456
457 /**
458 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
459 * @return None
460 *
461 * \par<b>Description: </b><br>
462 * Initialize the GPDMA peripheral <br>
463 *
464 * \par
465 * The function initializes a prioritized list of DMA channels and enables the GPDMA
466 * peripheral.
467 */
468 void XMC_DMA_Init(XMC_DMA_t *const dma);
469
470 /**
471 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
472 * @return None
473 *
474 * \par<b>Description: </b><br>
475 * Enable the GPDMA peripheral <br>
476 *
477 * \par
478 * The function de-asserts the GPDMA peripheral reset. In addition, it un-gates the
479 * GPDMA0 peripheral clock for all XMC4000 series of microcontrollers with an exception
480 * of the XMC4500 microcontroller. The XMC4500 doesn't support gating.
481 */
482 void XMC_DMA_Enable(XMC_DMA_t *const dma);
483
484 /**
485 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
486 * @return None
487 *
488 * \par<b>Description: </b><br>
489 * Disable the GPDMA peripheral <br>
490 *
491 * \par
492 * The function asserts the GPDMA peripheral reset. In addition, it gates the GPDMA0
493 * peripheral clock for all XMC4000 series of microcontrollers with an exception of
494 * the XMC4500 microcontroller. The XMC4500 doesn't support gating.
495 */
496 void XMC_DMA_Disable(XMC_DMA_t *const dma);
497
498 /**
499 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
500 * @return bool
501 *
502 * \par<b>Description: </b><br>
503 * Check if the GPDMA peripheral is enabled <br>
504 *
505 * \par
506 * For the XMC4500 microcontroller, the function checks if the GPDMA module is asserted
507 * and returns "false" if it is. In addition, it also checks if the clock is gated
508 * for the other XMC4000 series of microcontrollers. It returns "true" if the peripheral
509 * is enabled.
510 */
511 bool XMC_DMA_IsEnabled(const XMC_DMA_t *const dma);
512
513 /**
514 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
515 * @return uint32_t DMA event status
516 *
517 * \par<b>Description: </b><br>
518 * Get DMA event status <br>
519 *
520 * \par
521 * The function returns the collective (global) status of GPDMA events. The following
522 * lists the various DMA events and their corresponding enumeration. The return value
523 * of this function may then be masked with any one of the following enumerations to
524 * obtain the status of individual DMA events. <br>
525 *
526 * \par
527 * Transfer complete -> ::XMC_DMA_CH_EVENT_TRANSFER_COMPLETE <br>
528 * Block transfer complete -> ::XMC_DMA_CH_EVENT_BLOCK_TRANSFER_COMPLETE <br>
529 * Source transaction complete -> ::XMC_DMA_CH_EVENT_SRC_TRANSACTION_COMPLETE <br>
530 * Destination transaction complete -> ::XMC_DMA_CH_EVENT_DST_TRANSACTION_COMPLETE <br>
531 * DMA error event -> ::XMC_DMA_CH_EVENT_ERROR <br>
532 */
XMC_DMA_GetEventStatus(XMC_DMA_t * const dma)533 __STATIC_INLINE uint32_t XMC_DMA_GetEventStatus(XMC_DMA_t *const dma)
534 {
535 return (dma->STATUSGLEV);
536 }
537
538 /**
539 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
540 * @return uint32_t DMA transfer complete status
541 *
542 * \par<b>Description: </b><br>
543 * Get transfer complete status <br>
544 *
545 * \par
546 * The function returns GPDMA transfer complete interrupt status. <br>
547 */
XMC_DMA_GetChannelsTransferCompleteStatus(XMC_DMA_t * const dma)548 __STATIC_INLINE uint32_t XMC_DMA_GetChannelsTransferCompleteStatus(XMC_DMA_t *const dma)
549 {
550 return (dma->STATUSCHEV[0]);
551 }
552
553 /**
554 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
555 * @return uint32_t DMA block complete status
556 *
557 * \par<b>Description: </b><br>
558 * Get block transfer complete status <br>
559 *
560 * \par
561 * The function returns GPDMA block transfer complete interrupt status. <br>
562 */
XMC_DMA_GetChannelsBlockCompleteStatus(XMC_DMA_t * const dma)563 __STATIC_INLINE uint32_t XMC_DMA_GetChannelsBlockCompleteStatus(XMC_DMA_t *const dma)
564 {
565 return (dma->STATUSCHEV[2]);
566 }
567
568 /**
569 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
570 * @return uint32_t DMA event status
571 *
572 * \par<b>Description: </b><br>
573 * Get source transaction complete status <br>
574 *
575 * \par
576 * The function returns the source transaction complete interrupt status. <br>
577 *
578 * \par<b>Note: </b><br>
579 * If the source peripheral is memory, the source transaction complete interrupt is
580 * ignored.
581 */
XMC_DMA_GetChannelsSourceTransactionCompleteStatus(XMC_DMA_t * const dma)582 __STATIC_INLINE uint32_t XMC_DMA_GetChannelsSourceTransactionCompleteStatus(XMC_DMA_t *const dma)
583 {
584 return (dma->STATUSCHEV[4]);
585 }
586
587 /**
588 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
589 * @return uint32_t DMA event status
590 *
591 * \par<b>Description: </b><br>
592 * Get destination transaction complete status <br>
593 *
594 * \par
595 * The function returns the destination transaction complete interrupt status <br>
596 *
597 * \par<b>Note: </b><br>
598 * If the destination peripheral is memory, the destination transaction complete
599 * interrupt is ignored.
600 */
XMC_DMA_GetChannelsDestinationTransactionCompleteStatus(XMC_DMA_t * const dma)601 __STATIC_INLINE uint32_t XMC_DMA_GetChannelsDestinationTransactionCompleteStatus(XMC_DMA_t *const dma)
602 {
603 return (dma->STATUSCHEV[6]);
604 }
605
606 /**
607 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
608 * @return uint32_t DMA error event status
609 *
610 * \par<b>Description: </b><br>
611 * Get DMA error event status <br>
612 *
613 * \par
614 * The function returns error interrupt status. <br>
615 */
XMC_DMA_GetChannelsErrorStatus(XMC_DMA_t * const dma)616 __STATIC_INLINE uint32_t XMC_DMA_GetChannelsErrorStatus(XMC_DMA_t *const dma)
617 {
618 return (dma->STATUSCHEV[8]);
619 }
620
621 /**
622 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
623 * @param line Which DLR (DMA line router) line should the function use?
624 * @param peripheral Which hardware peripheral is the GPDMA communicating with?
625 * @return None
626 *
627 * \par<b>Description: </b><br>
628 * Enable request line <br>
629 *
630 * \par
631 * The function enables a DLR (DMA line router) line and selects a service request
632 * source, resulting in the trigger of a DMA transfer. <br>
633 *
634 * \par<b>Note: </b><br>
635 * The DLR is used for a DMA transfer typically involving a peripheral; For example,
636 * the ADC peripheral may use the DLR in hardware handshaking mode to transfer
637 * ADC conversion values to a destination memory block.
638 */
639 void XMC_DMA_EnableRequestLine(XMC_DMA_t *const dma, uint8_t line, uint8_t peripheral);
640
641 /**
642 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
643 * @param line Which DLR (DMA line router) line should the function use?
644 * @return None
645 *
646 * \par<b>Description: </b><br>
647 * Disable request line <br>
648 *
649 * \par
650 * The function disables a DLR (DMA line router) line by clearing appropriate bits
651 * in the LNEN register. <br>
652 */
653 void XMC_DMA_DisableRequestLine(XMC_DMA_t *const dma, uint8_t line);
654
655 /**
656 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
657 * @param line Which DLR (DMA line router) line should the function use?
658 * @return None
659 *
660 * \par<b>Description: </b><br>
661 * Clear request line <br>
662 *
663 * \par
664 * The function clears a DLR (DMA line router) request line. <br>
665 */
666 void XMC_DMA_ClearRequestLine(XMC_DMA_t *const dma, uint8_t line);
667
668 /**
669 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
670 * @param line The line for which the overrun status is requested
671 * @return bool "true" if overrun occured, "false" otherwise
672 *
673 * \par<b>Description: </b><br>
674 * Get overrun status of a DLR line <br>
675 *
676 * \par
677 * The DLR module's OVERSTAT register keeps track of DMA service request overruns.
678 * Should an overrun occur, the bit corresponding to the used DLR line is set. The
679 * function simply reads this status and returns "true" if an overrun is detected
680 * It returns "false" if an overrun isn't registered.
681 */
682 bool XMC_DMA_GetOverrunStatus(XMC_DMA_t *const dma, const uint8_t line);
683
684 /**
685 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
686 * @param line The line for which the overrun status must be cleared
687 * @return None
688 *
689 * \par<b>Description: </b><br>
690 * Clear overrun status of a DLR line <br>
691 *
692 * \par
693 * The function clears the overrun status of a line by setting the corresponding
694 * line bit in the DLR's OVERCLR register.
695 */
696 void XMC_DMA_ClearOverrunStatus(XMC_DMA_t *const dma, const uint8_t line);
697
698 /**
699 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
700 * @param channel The GPDMA channel (number) which needs to be initialized
701 * @param config A constant pointer to ::XMC_DMA_CH_CONFIG_t, pointing to a const
702 * channel configuration
703 * @return XMC_DMA_CH_STATUS_t Initialization status
704 *
705 * \par<b>Description: </b><br>
706 * Initialize a GPDMA channel with provided channel configuration <br>
707 *
708 * \par
709 * The function sets up the following channel configuration parameters for a GPDMA
710 * channel (specified by the parameter channel): <br>
711 * 1) Source and destination addresses (and linked list address if requested) <br>
712 * 2) Source and destination handshaking interface (hardware or software?) <br>
713 * 3) Scatter/gather configuration <br>
714 * 4) Source and destination peripheral request (DMA is the flow controller) <br>
715 * 5) Transfer flow and type <br>
716 *
717 * \par
718 * The function returns one of the following values: <br>
719 * 1) In case the DMA channel is not enabled: ::XMC_DMA_CH_STATUS_BUSY <br>
720 * 2) If the GPDMA module itself is not enabled: ::XMC_DMA_CH_STATUS_ERROR <br>
721 * 3) If the configuration was successful: ::XMC_DMA_CH_STATUS_OK <br>
722 *
723 * \par
724 * Once the initialization is successful, calling ::XMC_DMA_CH_Enable() will trigger
725 * a GPDMA transfer.
726 */
727 XMC_DMA_CH_STATUS_t XMC_DMA_CH_Init(XMC_DMA_t *const dma, const uint8_t channel, const XMC_DMA_CH_CONFIG_t *const config);
728
729 /**
730 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
731 * @param channel Which DMA channel should be enabled?
732 * @return None
733 *
734 * \par<b>Description: </b><br>
735 * Enable a GPDMA channel <br>
736 *
737 * \par
738 * The function sets the GPDMA's CHENREG register to enable a DMA channel. Please
739 * ensure that the GPDMA module itself is enabled before calling this function.
740 * See ::XMC_DMA_Enable() for details.
741 */
XMC_DMA_CH_Enable(XMC_DMA_t * const dma,const uint8_t channel)742 __STATIC_INLINE void XMC_DMA_CH_Enable(XMC_DMA_t *const dma, const uint8_t channel)
743 {
744 dma->CHENREG = (uint32_t)(0x101UL << channel);
745 }
746
747 /**
748 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
749 * @param channel Which DMA channel should be disabled?
750 * @return None
751 *
752 * \par<b>Description: </b><br>
753 * Disable a GPDMA channel <br>
754 *
755 * \par
756 * The function resets the GPDMA's CHENREG register to disable a DMA channel.
757 */
758 void XMC_DMA_CH_Disable(XMC_DMA_t *const dma, const uint8_t channel);
759
760 /**
761 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
762 * @param channel Which DMA channel should be disabled?
763 * @return bool
764 *
765 * \par<b>Description: </b><br>
766 * Check if a GPDMA channel is enabled <br>
767 *
768 * \par
769 * The function reads the GPDMA's CHENREG register to check if a DMA channel is
770 * enabled or not. The function returns "true" is the requested channel is enabled,
771 * "false" otherwise.
772 */
773 bool XMC_DMA_CH_IsEnabled(XMC_DMA_t *const dma, const uint8_t channel);
774
775 /**
776 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
777 * @param channel Which DMA channel should suspend transfer?
778 * @return None
779 *
780 * \par<b>Description: </b><br>
781 * Suspend a GPDMA channel transfer <br>
782 *
783 * \par
784 * The function sets the CH_SUSP bit of the GPDMA's GFGL register to initiate a
785 * DMA transfer suspend. The function may be called after enabling the DMA channel.
786 * Please see ::XMC_DMA_CH_Enable() for more information.
787 *
788 * \par<b>Related API: </b><br>
789 * ::XMC_DMA_CH_Resume() <br>
790 */
791 void XMC_DMA_CH_Suspend(XMC_DMA_t *const dma, const uint8_t channel);
792
793 /**
794 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
795 * @param channel Which DMA channel should resume transfer?
796 * @return None
797 *
798 * \par<b>Description: </b><br>
799 * Resume a GPDMA channel <br>
800 *
801 * \par
802 * The function clears the CH_SUSP bit of the GPDMA's GFGL register to resume a
803 * DMA transfer. The function may be called after enabling the DMA channel. Please
804 * see ::XMC_DMA_CH_Enable() for more information.
805 *
806 * \par<b>Related API: </b><br>
807 * ::XMC_DMA_CH_Suspend() <br>
808 */
809 void XMC_DMA_CH_Resume(XMC_DMA_t *const dma, const uint8_t channel);
810
811 /**
812 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
813 * @param channel A DMA channel
814 * @param addr source address
815 * @return None
816 *
817 * \par<b>Description: </b><br>
818 * This function sets the source address of the specified channel <br>
819 *
820 * \par
821 * The function may be called after enabling the DMA channel. Please
822 * see ::XMC_DMA_CH_Enable() for more information.
823 *
824 * \par<b>Related API: </b><br>
825 * ::XMC_DMA_CH_SetDestinationAddress() <br>
826 */
XMC_DMA_CH_SetSourceAddress(XMC_DMA_t * const dma,const uint8_t channel,uint32_t addr)827 __STATIC_INLINE void XMC_DMA_CH_SetSourceAddress(XMC_DMA_t *const dma, const uint8_t channel, uint32_t addr)
828 {
829 dma->CH[channel].SAR = addr;
830 }
831
832 /**
833 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
834 * @param channel A DMA channel
835 * @param addr destination address
836 * @return None
837 *
838 * \par<b>Description: </b><br>
839 * This function sets the destination address of the specified channel <br>
840 *
841 * \par
842 * The function may be called after enabling the DMA channel. Please
843 * see ::XMC_DMA_CH_Enable() for more information.
844 *
845 * \par<b>Related API: </b><br>
846 * ::XMC_DMA_CH_SetSourceAddress() <br>
847 */
XMC_DMA_CH_SetDestinationAddress(XMC_DMA_t * const dma,const uint8_t channel,uint32_t addr)848 __STATIC_INLINE void XMC_DMA_CH_SetDestinationAddress(XMC_DMA_t *const dma, const uint8_t channel, uint32_t addr)
849 {
850 dma->CH[channel].DAR = addr;
851 }
852
853 /**
854 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
855 * @param channel A DMA channel
856 * @param block_size Transfer size [1-2048]
857 * @return None
858 *
859 * \par<b>Description: </b><br>
860 * This function sets the block size of a transfer<br>
861 *
862 * \par
863 * The function may be called after enabling the DMA channel. Please
864 * see ::XMC_DMA_CH_Enable() for more information.
865 *
866 */
XMC_DMA_CH_SetBlockSize(XMC_DMA_t * const dma,const uint8_t channel,uint32_t block_size)867 __STATIC_INLINE void XMC_DMA_CH_SetBlockSize(XMC_DMA_t *const dma, const uint8_t channel, uint32_t block_size)
868 {
869 dma->CH[channel].CTLH = block_size;
870 }
871
872 /**
873 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
874 * @param channel A DMA channel
875 * @param ll_ptr linked list pointer
876 * @return None
877 *
878 * \par<b>Description: </b><br>
879 * This function sets the linked list pointer<br>
880 *
881 * \par
882 * The function may be called after enabling the DMA channel. Please
883 * see ::XMC_DMA_CH_Enable() for more information.
884 *
885 */
XMC_DMA_CH_SetLinkedListPointer(XMC_DMA_t * const dma,const uint8_t channel,XMC_DMA_LLI_t * ll_ptr)886 __STATIC_INLINE void XMC_DMA_CH_SetLinkedListPointer(XMC_DMA_t *const dma, const uint8_t channel, XMC_DMA_LLI_t *ll_ptr)
887 {
888 dma->CH[channel].LLP = (uint32_t)ll_ptr;
889 }
890
891 /**
892 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
893 * @param channel Which DMA channel should be checked for a suspended transfer?
894 * @return bool
895 *
896 * \par<b>Description: </b><br>
897 * Check if a GPDMA <br>
898 *
899 * \par
900 * The function reads the CH_SUSP bit of the GPDMA's GFGL register to check if a
901 * DMA transfer for the requested channel has been suspended. The function returns
902 * "true" if it detects a transfer suspension or "false" if it doesn't.
903 *
904 * \par<b>Related API: </b><br>
905 * ::XMC_DMA_CH_Suspend(), ::XMC_DMA_CH_Resume() <br>
906 */
907 bool XMC_DMA_CH_IsSuspended(XMC_DMA_t *const dma, const uint8_t channel);
908
909 /**
910 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
911 * @param channel The channel for which the event(s) need(s) to be enabled
912 * @param event A valid GPDMA event (::XMC_DMA_CH_EVENT_t) or a valid combination
913 * of logically OR'd GPDMA events
914 * @return None
915 *
916 * \par<b>Description: </b><br>
917 * Enable GPDMA event(s) <br>
918 *
919 * \par
920 * The following events are supported by the GPDMA peripheral: <br>
921 * 1) Transfer complete event <br>
922 * 2) Block transfer complete event <br>
923 * 3) Source transaction complete event <br>
924 * 4) Destination transaction complete event <br>
925 * 5) DMA error event <br>
926 *
927 * \par
928 * The function can be used to enable one (or more) of the aforementioned events.
929 * Once the events have been enabled, ::XMC_DMA_CH_SetEventHandler() API can be
930 * used to set a callback function.
931 */
932 void XMC_DMA_CH_EnableEvent(XMC_DMA_t *const dma, const uint8_t channel, const uint32_t event);
933
934 /**
935 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
936 * @param channel The channel for which the event(s) need(s) to be disabled
937 * @param event A valid GPDMA event (::XMC_DMA_CH_EVENT_t) or a valid combination
938 * of logically OR'd GPDMA events
939 * @return None
940 *
941 * \par<b>Description: </b><br>
942 * Disable GPDMA event(s) <br>
943 *
944 * \par
945 * The following events are supported by the GPDMA peripheral: <br>
946 * 1) Transfer complete event <br>
947 * 2) Block transfer complete event <br>
948 * 3) Source transaction complete event <br>
949 * 4) Destination transaction complete event <br>
950 * 5) DMA error event <br>
951 *
952 * \par
953 * The function can be used to disable one (or more) of the aforementioned events.
954 */
955 void XMC_DMA_CH_DisableEvent(XMC_DMA_t *const dma, const uint8_t channel, const uint32_t event);
956
957 /**
958 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
959 * @param channel The channel for which the event(s) need(s) to be disabled
960 * @param event A valid GPDMA event (::XMC_DMA_CH_EVENT_t) or a valid combination
961 * of logically OR'd GPDMA events
962 * @return None
963 *
964 * \par<b>Description: </b><br>
965 * Clear GPDMA event status <br>
966 *
967 * \par
968 * The following events are supported by the GPDMA peripheral: <br>
969 * 1) Transfer complete event <br>
970 * 2) Block transfer complete event <br>
971 * 3) Source transaction complete event <br>
972 * 4) Destination transaction complete event <br>
973 * 5) DMA error event <br>
974 *
975 * \par
976 * The function is used to clear the status of one (or more) of the aforementioned
977 * events. Typically, its use is in the GPDMA interrupt handler function. Once an
978 * event is detected, an appropriate callback function must run and the event status
979 * should be cleared.
980 */
981 void XMC_DMA_CH_ClearEventStatus(XMC_DMA_t *const dma, const uint8_t channel, const uint32_t event);
982
983 /**
984 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
985 * @param channel The channel for which the event(s) status must be obtained
986 * @return Event status
987 *
988 * \par<b>Description: </b><br>
989 * Get GPDMA channel event status <br>
990 *
991 * \par
992 * The function is used obtain the status of one (or more) of the aforementioned
993 * events. The return value may then be masked with any one of the following
994 * enumerations to obtain the status of individual DMA events. <br>
995 *
996 * \par
997 * Transfer complete -> ::XMC_DMA_CH_EVENT_TRANSFER_COMPLETE <br>
998 * Block transfer complete -> ::XMC_DMA_CH_EVENT_BLOCK_TRANSFER_COMPLETE <br>
999 * Source transaction complete -> ::XMC_DMA_CH_EVENT_SRC_TRANSACTION_COMPLETE <br>
1000 * Destination transaction complete -> ::XMC_DMA_CH_EVENT_DST_TRANSACTION_COMPLETE <br>
1001 * DMA error event -> ::XMC_DMA_CH_EVENT_ERROR <br>
1002 *
1003 * \par
1004 * Typically, its use is in the GPDMA interrupt handler function. Once an event is
1005 * detected, an appropriate callback function must run and the event status should
1006 * be cleared.
1007 */
1008 uint32_t XMC_DMA_CH_GetEventStatus(XMC_DMA_t *const dma, const uint8_t channel);
1009
1010 /**
1011 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1012 * @param channel Which DMA channel is used for source gather?
1013 * @param interval Gather interval
1014 * @param count Gather count
1015 * @return None
1016 *
1017 * \par<b>Description: </b><br>
1018 * Enable source gather <br>
1019 *
1020 * \par
1021 * The function is used to enable the source gather feature in the GPDMA peripheral.
1022 * The user must also specify the gather count and interval. Once the configuration
1023 * is successful, calling ::XMC_DMA_CH_EnableEvent() will initiate source gather.
1024 * This function is normally used in conjunction with destination scatter. Please
1025 * see ::XMC_DMA_CH_EnableDestinationScatter() for additional information.
1026 */
1027 void XMC_DMA_CH_EnableSourceGather(XMC_DMA_t *const dma, const uint8_t channel, uint32_t interval, uint16_t count);
1028
1029 /**
1030 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1031 * @param channel The source gather for which DMA channel is to be disabled?
1032 * @return None
1033 *
1034 * \par<b>Description: </b><br>
1035 * Disable source gather <br>
1036 *
1037 * \par
1038 * The function is used to disable the source gather feature in the GPDMA peripheral.
1039 */
1040 void XMC_DMA_CH_DisableSourceGather(XMC_DMA_t *const dma, const uint8_t channel);
1041
1042 /**
1043 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1044 * @param channel Which DMA channel is used for destination scatter?
1045 * @param interval Scatter interval
1046 * @param count Scatter count
1047 * @return None
1048 *
1049 * \par<b>Description: </b><br>
1050 * Enable destination scatter <br>
1051 *
1052 * \par
1053 * The function is used to enable the destination scatter feature in the GPDMA
1054 * peripheral. The user must also specify the scatter count and interval. Once
1055 * the configuration is successful, calling ::XMC_DMA_CH_EnableEvent() will
1056 * initiate destination gather. This function is normally used in conjunction
1057 * with source gather. Please see ::XMC_DMA_CH_EnableSourceGather() for
1058 * additional information.
1059 */
1060 void XMC_DMA_CH_EnableDestinationScatter(XMC_DMA_t *const dma, const uint8_t channel, uint32_t interval, uint16_t count);
1061
1062 /**
1063 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1064 * @param channel The source gather for which DMA channel is to be disabled?
1065 * @return None
1066 *
1067 * \par<b>Description: </b><br>
1068 * Disable source gather <br>
1069 *
1070 * \par
1071 * The function is used to disable the destination scatter feature in the GPDMA
1072 * peripheral.
1073 */
1074 void XMC_DMA_CH_DisableDestinationScatter(XMC_DMA_t *const dma, const uint8_t channel);
1075
1076 /**
1077 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1078 * @param channel Which DMA channel is being used?
1079 * @param type Transaction type: Single/burst mode
1080 * @param last Specify "true" if it is the last source request trigger, "false"
1081 * otherwise
1082 * @return None
1083 *
1084 * \par<b>Description: </b><br>
1085 * Trigger source request <br>
1086 *
1087 * \par
1088 * The function can be used for GPDMA transfers involving a peripheral in software
1089 * handshaking mode viz. Memory -> peripheral and peripheral -> peripheral.
1090 *
1091 * \par
1092 * One would typically use this function in a (destination) peripheral's event
1093 * callback function to trigger the source request.
1094 */
1095 void XMC_DMA_CH_TriggerSourceRequest(XMC_DMA_t *const dma, const uint8_t channel, const XMC_DMA_CH_TRANSACTION_TYPE_t type, bool last);
1096
1097 /**
1098 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1099 * @param channel Which DMA channel is being used?
1100 * @param type Transaction type: Single/burst mode
1101 * @param last Specify "true" if it is the last destination request trigger, "false"
1102 * otherwise
1103 * @return None
1104 *
1105 * \par<b>Description: </b><br>
1106 * Trigger destination request <br>
1107 *
1108 * \par
1109 * The function can be used for GPDMA transfers involving a peripheral in software
1110 * handshaking mode viz. Peripheral -> memory and peripheral -> peripheral.
1111 *
1112 * \par
1113 * One would typically use this function in a (source) peripheral's event
1114 * callback function to trigger the destination request.
1115 */
1116 void XMC_DMA_CH_TriggerDestinationRequest(XMC_DMA_t *const dma, const uint8_t channel, const XMC_DMA_CH_TRANSACTION_TYPE_t type, bool last);
1117
1118 /**
1119 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1120 * @param channel The channel for which the source address must be reloaded
1121 * @return None
1122 *
1123 * \par<b>Description: </b><br>
1124 * Enable source address reload <br>
1125 *
1126 * \par
1127 * The function is used to automatically reload the source DMA address (from its
1128 * initial value) at the end of every block in a multi-block transfer. The auto-
1129 * reload will begin soon after the DMA channel initialization (configured for a
1130 * multi-block transaction).
1131 */
1132 void XMC_DMA_CH_EnableSourceAddressReload(XMC_DMA_t *const dma, const uint8_t channel);
1133
1134 /**
1135 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1136 * @param channel The channel for which the source address reload must be disabled
1137 * @return None
1138 *
1139 * \par<b>Description: </b><br>
1140 * Disable source address reload <br>
1141 *
1142 * \par
1143 * The source DMA address can be automatically reloaded from its initial value at
1144 * the end of every block in a multi-block transfer. To disable this feature, use
1145 * this function.
1146 */
1147 void XMC_DMA_CH_DisableSourceAddressReload(XMC_DMA_t *const dma, const uint8_t channel);
1148
1149 /**
1150 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1151 * @param channel The channel for which the destination address must be reloaded
1152 * @return None
1153 *
1154 * \par<b>Description: </b><br>
1155 * Enable source address reload <br>
1156 *
1157 * \par
1158 * The function is used to automatically reload the destination DMA address (from
1159 * its initial value) at the end of every block in a multi-block transfer. The auto-
1160 * reload will begin soon after the DMA channel initialization (configured for a
1161 * multi-block transaction).
1162 */
1163 void XMC_DMA_CH_EnableDestinationAddressReload(XMC_DMA_t *const dma, const uint8_t channel);
1164
1165 /**
1166 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1167 * @param channel The channel for which the destination address reload must be
1168 * disabled
1169 * @return None
1170 *
1171 * \par<b>Description: </b><br>
1172 * Disable destination address reload <br>
1173 *
1174 * \par
1175 * The destination DMA address can be automatically reloaded from its initial value
1176 * at the end of every block in a multi-block transfer. To disable this feature,
1177 * use this function.
1178 */
1179 void XMC_DMA_CH_DisableDestinationAddressReload(XMC_DMA_t *const dma, const uint8_t channel);
1180
1181 /**
1182 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1183 * @param channel Which DMA channel is participating in a multi-block transfer?
1184 * @return None
1185 *
1186 * \par<b>Description: </b><br>
1187 * Trigger the end of a multi-block transfer <br>
1188 *
1189 * \par
1190 * The function is used signal the end of multi-block DMA transfer. It clears the
1191 * RELOAD_SRC and RELOAD_DST bits of the CFGL register to keep the source and
1192 * destination addresses from getting updated. The function is typically used in
1193 * an event handler to signal that the next block getting transferred is the last
1194 * block in the transfer sequence.
1195 */
1196 void XMC_DMA_CH_RequestLastMultiblockTransfer(XMC_DMA_t *const dma, const uint8_t channel);
1197
1198 /**
1199 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1200 * @param channel The channel for which the event handler is being registered
1201 * @param event_handler The event handler which will be invoked when the DMA event
1202 * occurs
1203 * @return None
1204 *
1205 * \par<b>Description: </b><br>
1206 * Set a GPDMA event handler to service GPDMA events <br>
1207 *
1208 * \par
1209 * The function is used to register user callback functions for servicing DMA events.
1210 * Call this function after enabling the GPDMA events (See ::XMC_DMA_CH_EnableEvent())
1211 */
1212 void XMC_DMA_CH_SetEventHandler(XMC_DMA_t *const dma, const uint8_t channel, XMC_DMA_CH_EVENT_HANDLER_t event_handler);
1213
1214 /**
1215 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1216 * @param channel The source peripheral request for which DMA channel is to be cleared?
1217 * @return None
1218 *
1219 * \par<b>Description: </b><br>
1220 * Clear source peripheral request <br>
1221 *
1222 * \par
1223 * The function is used to clear the source peripheral request for a given DMA
1224 * channel.
1225 */
1226 void XMC_DMA_CH_ClearSourcePeripheralRequest(XMC_DMA_t *const dma, uint8_t channel);
1227
1228 /**
1229 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1230 * @param channel The destination peripheral request for which DMA channel is to be cleared?
1231 * @return None
1232 *
1233 * \par<b>Description: </b><br>
1234 * Clear destination peripheral request <br>
1235 *
1236 * \par
1237 * The function is used to clear the destination peripheral request for a given DMA
1238 * channel.
1239 */
1240 void XMC_DMA_CH_ClearDestinationPeripheralRequest(XMC_DMA_t *const dma, uint8_t channel);
1241
1242 /**
1243 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1244 * @param channel The destination peripheral request for which DMA channel is to be cleared?
1245 * @return None
1246 *
1247 * \par<b>Description: </b><br>
1248 * Enable FIFO mode <br>
1249 *
1250 * \par
1251 * Special mode to improve bandwidth. When enabled, the channel waits until the FIFO <br>
1252 * is less than half full to fetch the data from the source peripheral, and waits until the FIFO is greater <br>
1253 * than or equal to half full in order to send data to the destination peripheral. Because of this, the <br>
1254 * channel can transfer the data using bursts, which eliminates the need to arbitrate for the AHB master <br>
1255 * interface in each single AHB transfer.
1256 *
1257 * \par<b>Related APIs:</b><br>
1258 * XMC_DMA_CH_DisableFifoMode()\n\n
1259 */
XMC_DMA_CH_EnableFifoMode(XMC_DMA_t * const dma,uint8_t channel)1260 __STATIC_INLINE void XMC_DMA_CH_EnableFifoMode(XMC_DMA_t *const dma, uint8_t channel)
1261 {
1262 dma->CH[channel].CFGH |= GPDMA0_CH_CFGH_FIFO_MODE_Msk;
1263 }
1264
1265 /**
1266 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1267 * @param channel The destination peripheral request for which DMA channel is to be cleared?
1268 * @return None
1269 *
1270 * \par<b>Description: </b><br>
1271 * Disable FIFO mode <br>
1272 *
1273 * \par
1274 * When the FIFO mode is not enabled, the channel waits only until <br>
1275 * the FIFO can transmit or accept a single AHB transfer before it requests the master bus interface. <br>
1276 *
1277 * \par<b>Related APIs:</b><br>
1278 * XMC_DMA_CH_EnableFifoMode()\n\n
1279 */
XMC_DMA_CH_DisableFifoMode(XMC_DMA_t * const dma,uint8_t channel)1280 __STATIC_INLINE void XMC_DMA_CH_DisableFifoMode(XMC_DMA_t *const dma, uint8_t channel)
1281 {
1282 dma->CH[channel].CFGH &= ~GPDMA0_CH_CFGH_FIFO_MODE_Msk;
1283 }
1284
1285 /**
1286 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1287 * @param channel The destination peripheral request for which DMA channel is to be cleared?
1288 * @return Total number of data items already read from the source peripheral
1289 *
1290 * \par<b>Description: </b><br>
1291 * Obtain the total number of data items already read from the source peripheral <br>
1292 *
1293 * \par<b>Note: </b><br>
1294 * The width of the single transaction is determined by src_transfer_width.
1295 *
1296 */
XMC_DMA_CH_GetTransferredData(XMC_DMA_t * const dma,const uint8_t channel)1297 __STATIC_INLINE uint32_t XMC_DMA_CH_GetTransferredData(XMC_DMA_t *const dma, const uint8_t channel)
1298 {
1299 return (dma->CH[channel].CTLH & GPDMA0_CH_CTLH_BLOCK_TS_Msk);
1300
1301 }
1302
1303 /**
1304 * @param dma A constant pointer to XMC_DMA_t, pointing to the GPDMA base address
1305 * @return None
1306 *
1307 * \par<b>Description: </b><br>
1308 * Default GPDMA IRQ handler <br>
1309 *
1310 * \par
1311 * The function implements a default GPDMA IRQ handler. It can be used within the
1312 * following (device specific) routines: <br>
1313 * 1) GPDMA0_0_IRQHandler <br>
1314 * 2) GPDMA1_0_IRQHandler <br>
1315 *
1316 * The function handles the enabled GPDMA events and runs the user callback function
1317 * registered by the user to service the event. To register a callback function,
1318 * see ::XMC_DMA_CH_SetEventHandler()
1319 */
1320 void XMC_DMA_IRQHandler(XMC_DMA_t *const dma);
1321
1322 #ifdef __cplusplus
1323 }
1324 #endif
1325
1326 /**
1327 * @} (end addtogroup DMA)
1328 */
1329
1330 /**
1331 * @} (end addtogroup XMClib)
1332 */
1333
1334 #endif /* defined (GPDMA0) */
1335 #endif /* XMC_DMA_H */
1336
