1 /*
2 * edma3_drv.h
3 *
4 * This file contains Application Interface for the EDMA3 Driver. EDMA3 Driver
5 * uses the EDMA3 Resource Manager internally for resource allocation, interrupt
6 * handling and EDMA3 registers programming.
7 *
8 * Copyright (C) 2009-2012 Texas Instruments Incorporated - http://www.ti.com/
9 *
10 *
11 * Redistribution and use in source and binary forms, with or without
12 * modification, are permitted provided that the following conditions
13 * are met:
14 *
15 * Redistributions of source code must retain the above copyright
16 * notice, this list of conditions and the following disclaimer.
17 *
18 * Redistributions in binary form must reproduce the above copyright
19 * notice, this list of conditions and the following disclaimer in the
20 * documentation and/or other materials provided with the
21 * distribution.
22 *
23 * Neither the name of Texas Instruments Incorporated nor the names of
24 * its contributors may be used to endorse or promote products derived
25 * from this software without specific prior written permission.
26 *
27 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
28 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
29 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
30 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
31 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
32 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
33 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
34 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
35 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
36 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
37 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38 *
39 */
41 /** @defgroup EDMA3_LLD_DRV_API EDMA3 Driver
42 *
43 * @section Introduction
44 *
45 * @subsection xxx Overview
46 * EDMA3 Driver is a functional library providing APIs for programming,
47 * scheduling and synchronizing with EDMA transfers and many more.
48 */
50 #ifndef _EDMA3_DRV_H_
51 #define _EDMA3_DRV_H_
53 #include <stdint.h>
55 /* Include the Resource Manager header file */
56 #include <ti/sdo/edma3/rm/edma3_rm.h>
58 #ifdef __cplusplus
59 extern "C" {
60 #endif
62 /**
63 @defgroup EDMA3_LLD_DRV_SYMBOL EDMA3 Driver Symbols
64 @ingroup EDMA3_LLD_DRV_API
65 */
66 /**
67 @defgroup EDMA3_LLD_DRV_DATASTRUCT EDMA3 Driver Data Structures
68 @ingroup EDMA3_LLD_DRV_API
69 */
70 /**
71 @defgroup EDMA3_LLD_DRV_FUNCTION EDMA3 Driver APIs
72 @ingroup EDMA3_LLD_DRV_API
73 */
75 /**
76 @defgroup EDMA3_LLD_DRV_SYMBOL_DEFINE EDMA3 Driver Defines
77 @ingroup EDMA3_LLD_DRV_SYMBOL
78 */
79 /**
80 @defgroup EDMA3_LLD_DRV_SYMBOL_ENUM EDMA3 Driver Enums
81 @ingroup EDMA3_LLD_DRV_SYMBOL
82 */
84 /**
85 @defgroup EDMA3_LLD_DRV_FUNCTION_INIT EDMA3 Driver Initialization APIs
86 @ingroup EDMA3_LLD_DRV_FUNCTION
87 */
88 /**
89 @defgroup EDMA3_LLD_DRV_FUNCTION_BASIC EDMA3 Driver Basic APIs
90 @ingroup EDMA3_LLD_DRV_FUNCTION
91 */
92 /**
93 @defgroup EDMA3_LLD_DRV_FUNCTION_ADVANCED EDMA3 Driver Advanced APIs
94 @ingroup EDMA3_LLD_DRV_FUNCTION
95 */
97 /** @addtogroup EDMA3_LLD_DRV_SYMBOL_DEFINE
98 @{ */
100 /**
101 * @brief This is the EDMA3 LLD Version. Versions numbers are encoded in the following
102 * format:
103 * 0xAABBCCDD -> Arch (AA); API Changes (BB); Major (CC); Minor (DD)
104 */
105 #define EDMA3_LLD_DRV_VERSION_ID (0x020B0502)
107 /**
108 * @brief This is the version string which describes the EDMA3 LLD along with the
109 * date and build information.
110 */
111 #define EDMA3_LLD_DRV_VERSION_STR "EDMA3 LLD Revision: 02.11.05.02"
114 /** @brief EDMA3 Driver Error Codes Base define */
115 #define EDMA3_DRV_E_BASE (-128)
117 /**
118 * EDMA3 Driver Object Not Deleted yet.
119 * So it cannot be created.
120 */
121 #define EDMA3_DRV_E_OBJ_NOT_DELETED (EDMA3_DRV_E_BASE)
123 /**
124 * EDMA3 Driver Object Not Closed yet.
125 * So it cannot be deleted.
126 */
127 #define EDMA3_DRV_E_OBJ_NOT_CLOSED (EDMA3_DRV_E_BASE-1)
129 /**
130 * EDMA3 Driver Object Not Opened yet
131 * So it cannot be closed.
132 */
133 #define EDMA3_DRV_E_OBJ_NOT_OPENED (EDMA3_DRV_E_BASE-2)
135 /**
136 * While closing EDMA3 Driver, Resource Manager
137 * Close Failed.
138 */
139 #define EDMA3_DRV_E_RM_CLOSE_FAIL (EDMA3_DRV_E_BASE-3)
141 /** The requested DMA Channel not available */
142 #define EDMA3_DRV_E_DMA_CHANNEL_UNAVAIL (EDMA3_DRV_E_BASE-4)
144 /** The requested QDMA Channel not available */
145 #define EDMA3_DRV_E_QDMA_CHANNEL_UNAVAIL (EDMA3_DRV_E_BASE-5)
147 /** The requested PaRAM Set not available */
148 #define EDMA3_DRV_E_PARAM_SET_UNAVAIL (EDMA3_DRV_E_BASE-6)
150 /** The requested TCC not available */
151 #define EDMA3_DRV_E_TCC_UNAVAIL (EDMA3_DRV_E_BASE-7)
153 /** The registration of TCC failed */
154 #define EDMA3_DRV_E_TCC_REGISTER_FAIL (EDMA3_DRV_E_BASE-8)
156 /** The binding of Channel and PaRAM Set failed */
157 #define EDMA3_DRV_E_CH_PARAM_BIND_FAIL (EDMA3_DRV_E_BASE-9)
159 /**
160 * The address of the memory location passed as argument
161 * is not properly aligned. It should be 32 bytes aligned.
162 */
163 #define EDMA3_DRV_E_ADDRESS_NOT_ALIGNED (EDMA3_DRV_E_BASE-10)
165 /** Invalid Parameter passed to API */
166 #define EDMA3_DRV_E_INVALID_PARAM (EDMA3_DRV_E_BASE-11)
168 /** Invalid State of EDMA3 HW Obj */
169 #define EDMA3_DRV_E_INVALID_STATE (EDMA3_DRV_E_BASE-12)
171 /** EDMA3 Driver instance already exists for the specified region */
172 #define EDMA3_DRV_E_INST_ALREADY_EXISTS (EDMA3_DRV_E_BASE-13)
174 /** FIFO width not supported by the requested TC */
175 #define EDMA3_DRV_E_FIFO_WIDTH_NOT_SUPPORTED (EDMA3_DRV_E_BASE-14)
177 /** Semaphore related error */
178 #define EDMA3_DRV_E_SEMAPHORE (EDMA3_DRV_E_BASE-15)
180 /** EDMA3 Driver Instance does not exist, it is not opened yet */
181 #define EDMA3_DRV_E_INST_NOT_OPENED (EDMA3_DRV_E_BASE-16)
183 /**
184 * This define is used to specify that a DMA channel is NOT tied to any PaRAM
185 * Set and hence any available PaRAM Set could be used for that DMA channel.
186 * It could be used in dmaChannelPaRAMMap [EDMA3_MAX_DMA_CH], in global
187 * configuration structure EDMA3_RM_GblConfigParams.
188 *
189 * This value should mandatorily be used to mark DMA channels with no initial
190 * mapping to specific PaRAM Sets.
191 */
192 #define EDMA3_DRV_CH_NO_PARAM_MAP EDMA3_RM_CH_NO_PARAM_MAP
194 /**
195 * This define is used to specify that the DMA/QDMA channel is not tied to any
196 * TCC and hence any available TCC could be used for that DMA/QDMA channel.
197 * It could be used in dmaChannelTccMap [EDMA3_MAX_DMA_CH], in global
198 * configuration structure EDMA3_RM_GblConfigParams.
199 *
200 * This value should mandatorily be used to mark DMA channels with no initial
201 * mapping to specific TCCs.
202 */
203 #define EDMA3_DRV_CH_NO_TCC_MAP EDMA3_RM_CH_NO_TCC_MAP
205 /**
206 @}
207 */
209 /** @addtogroup EDMA3_LLD_DRV_DATASTRUCT
210 @{ */
212 /**\struct EDMA3_DRV_GblConfigParams
213 * \brief Init-time Configuration structure for EDMA3
214 * controller, to provide Global SoC specific Information.
215 *
216 * This configuration structure is used to specify the EDMA3 Driver
217 * global settings, specific to the SoC. For e.g. number of DMA/QDMA channels,
218 * number of PaRAM sets, TCCs, event queues, transfer controllers, base
219 * addresses of CC global registers and TC registers, interrupt number for
220 * EDMA3 transfer completion, CC error, event queues' priority, watermark
221 * threshold level etc.
222 * This configuration information is SoC specific and could be provided by the
223 * user at run-time while creating the EDMA3 Driver Object, using API
224 * EDMA3_DRV_create. In case user doesn't provide it, this information could be
225 * taken from the SoC specific configuration file edma3_<SOC_NAME>_cfg.c, in
226 * case it is available.
227 */
228 typedef struct {
229 /** Number of DMA Channels supported by the underlying EDMA3 Controller. */
230 uint32_t numDmaChannels;
232 /** Number of QDMA Channels supported by the underlying EDMA3 Controller */
233 uint32_t numQdmaChannels;
235 /**
236 * Number of Interrupt Channels supported by the underlying EDMA3
237 * Controller
238 */
239 uint32_t numTccs;
241 /** Number of PaRAM Sets supported by the underlying EDMA3 Controller */
242 uint32_t numPaRAMSets;
244 /** Number of Event Queues in the underlying EDMA3 Controller */
245 uint32_t numEvtQueue;
247 /**
248 * Number of Transfer Controllers (TCs) in the underlying EDMA3 Controller
249 */
250 uint32_t numTcs;
252 /** Number of Regions in the underlying EDMA3 Controller */
253 uint32_t numRegions;
255 /**
256 * \brief Channel mapping existence
257 *
258 * A value of 0 (No channel mapping) implies that there is fixed
259 * association between a DMA channel and a PaRAM Set or, in other words,
260 * DMA channel n can ONLY use PaRAM Set n (No availability of DCHMAP
261 * registers) for transfers to happen.
262 *
263 * A value of 1 implies the presence of DCHMAP registers for the DMA
264 * channels and hence the flexibility of associating any DMA channel to
265 * any PaRAM Set. In other words, ANY PaRAM Set can be used for ANY DMA
266 * channel (like QDMA Channels).
267 */
268 uint32_t dmaChPaRAMMapExists;
270 /** Existence of memory protection feature */
271 uint32_t memProtectionExists;
273 /** Base address of EDMA3 CC memory mapped registers. */
274 void *globalRegs;
276 /** Base address of EDMA3 TCs memory mapped registers. */
277 void *tcRegs[EDMA3_MAX_TC];
279 /**
280 * EDMA3 transfer completion interrupt line (could be different for ARM
281 * and DSP)
282 */
283 uint32_t xferCompleteInt;
285 /** EDMA3 CC error interrupt line (could be different for ARM and DSP) */
286 uint32_t ccError;
288 /** EDMA3 TCs error interrupt line (could be different for ARM and DSP) */
289 uint32_t tcError[EDMA3_MAX_TC];
291 /**
292 * \brief EDMA3 TC priority setting
293 *
294 * User can program the priority of the Event Queues
295 * at a system-wide level. This means that the user can set the
296 * priority of an IO initiated by either of the TCs (Transfer Controllers)
297 * relative to IO initiated by the other bus masters on the
298 * device (ARM, DSP, USB, etc)
299 */
300 uint32_t evtQPri [EDMA3_MAX_EVT_QUE];
302 /**
303 * \brief Event Queues Watermark Levels
305 * To Configure the Threshold level of number of events
306 * that can be queued up in the Event queues. EDMA3CC error register
307 * (CCERR) will indicate whether or not at any instant of time the
308 * number of events queued up in any of the event queues exceeds
309 * or equals the threshold/watermark value that is set
310 * in the queue watermark threshold register (QWMTHRA).
311 */
312 uint32_t evtQueueWaterMarkLvl [EDMA3_MAX_EVT_QUE];
314 /**
315 * \brief Default Burst Size (DBS) of TCs.
317 * An optimally-sized command is defined by the transfer controller
318 * default burst size (DBS). Different TCs can have different
319 * DBS values. It is defined in Bytes.
320 */
321 uint32_t tcDefaultBurstSize[EDMA3_MAX_TC];
323 /**
324 * \brief Mapping from DMA channels to PaRAM Sets
326 * If channel mapping exists (DCHMAP registers are present), this array
327 * stores the respective PaRAM Set for each DMA channel. User can
328 * initialize each array member with a specific PaRAM Set or with
329 * EDMA3_DRV_CH_NO_PARAM_MAP.
330 * If channel mapping doesn't exist, it is of no use as the EDMA3 RM
331 * automatically uses the right PaRAM Set for that DMA channel.
332 * Useful only if mapping exists, otherwise of no use.
333 */
334 uint32_t dmaChannelPaRAMMap [EDMA3_MAX_DMA_CH];
336 /**
337 * \brief Mapping from DMA channels to TCCs
338 *
339 * This array stores the respective TCC (interrupt channel) for each
340 * DMA channel. User can initialize each array member with a specific TCC
341 * or with EDMA3_DRV_CH_NO_TCC_MAP. This specific
342 * TCC code will be returned when the transfer is completed
343 * on the mapped DMA channel.
344 */
345 uint32_t dmaChannelTccMap [EDMA3_MAX_DMA_CH];
347 /**
348 * \brief Mapping from DMA channels to Hardware Events
349 *
350 * Each bit in this array corresponds to one DMA channel and tells whether
351 * this DMA channel is tied to any peripheral. That is whether any
352 * peripheral can send the synch event on this DMA channel or not.
353 * 1 means the channel is tied to some peripheral; 0 means it is not.
354 * DMA channels which are tied to some peripheral are RESERVED for that
355 * peripheral only. They are not allocated when user asks for 'ANY' DMA
356 * channel.
357 * All channels need not be mapped, some can be free also.
358 */
359 uint32_t dmaChannelHwEvtMap [EDMA3_MAX_DMA_CHAN_DWRDS];
360 } EDMA3_DRV_GblConfigParams;
362 /**\struct EDMA3_DRV_InstanceInitConfig
363 * \brief Init-time Region Specific Configuration structure for
364 * EDMA3 Driver, to provide region specific Information.
365 *
366 * This configuration structure is used to specify which EDMA3 resources are
367 * owned and reserved by the EDMA3 Driver instance. This configuration
368 * structure is shadow region specific and will be provided by the user at
369 * run-time while calling EDMA3_DRV_open ().
370 *
371 * Owned resources:
372 * ****************
373 *
374 * EDMA3 Driver Instances are tied to different shadow regions and hence different
375 * masters. Regions could be:
376 *
377 * a) ARM,
378 * b) DSP,
379 * c) IMCOP (Imaging Co-processor) etc.
380 *
381 * User can assign each EDMA3 resource to a shadow region using this structure.
382 * In this way, user specifies which resources are owned by the specific EDMA3
383 * DRV Instance.
384 * This assignment should also ensure that the same resource is not assigned
385 * to more than one shadow regions (unless desired in that way). Any assignment
386 * not following the above mentioned approach may have catastrophic
387 * consequences.
388 *
389 *
390 * Reserved resources:
391 * *******************
392 *
393 * During EDMA3 DRV initialization, user can reserve some of the EDMA3 resources
394 * for future use, by specifying which resources to reserve in the configuration
395 * data structure. These (critical) resources are reserved in advance so that
396 * they should not be allocated to someone else and thus could be used in
397 * future for some specific purpose.
398 *
399 * User can request different EDMA3 resources using two methods:
400 * a) By passing the resource type and the actual resource id,
401 * b) By passing the resource type and ANY as resource id
402 *
403 * For e.g. to request DMA channel 31, user will pass 31 as the resource id.
404 * But to request ANY available DMA channel (mainly used for memory-to-memory
405 * data transfer operations), user will pass EDMA3_DRV_DMA_CHANNEL_ANY as the
406 * resource id.
407 *
408 * During initialization, user may have reserved some of the DMA channels for
409 * some specific purpose (mainly for peripherals using EDMA). These reserved
410 * DMA channels then will not be returned when user requests ANY as the
411 * resource id.
412 *
413 * Same logic applies for QDMA channels and TCCs.
414 *
415 * For PaRAM Set, there is one difference. If the DMA channels are one-to-one
416 * tied to their respective PaRAM Sets (i.e. user cannot 'choose' the PaRAM Set
417 * for a particular DMA channel), EDMA3 Driver automatically reserves all those
418 * PaRAM Sets which are tied to the DMA channels. Then those PaRAM Sets would
419 * not be returned when user requests for ANY PaRAM Set (specifically for
420 * linking purpose). This is done in order to avoid allocating the PaRAM Set,
421 * tied to a particular DMA channel, for linking purpose. If this constraint is
422 * not there, that DMA channel thus could not be used at all, because of the
423 * unavailability of the desired PaRAM Set.
424 */
425 typedef struct
426 {
427 /** PaRAM Sets owned by the EDMA3 Driver Instance. */
428 uint32_t ownPaRAMSets[EDMA3_MAX_PARAM_DWRDS];
430 /** DMA Channels owned by the EDMA3 Driver Instance. */
431 uint32_t ownDmaChannels[EDMA3_MAX_DMA_CHAN_DWRDS];
433 /** QDMA Channels owned by the EDMA3 Driver Instance. */
434 uint32_t ownQdmaChannels[EDMA3_MAX_QDMA_CHAN_DWRDS];
436 /** TCCs owned by the EDMA3 Driver Instance. */
437 uint32_t ownTccs[EDMA3_MAX_TCC_DWRDS];
439 /**
440 * \brief Reserved PaRAM Sets
441 *
442 * PaRAM Sets reserved during initialization for future use. These will not
443 * be given when user requests for ANY available PaRAM Set for linking
444 * using 'EDMA3_DRV_LINK_CHANNEL' as channel id.
445 */
446 uint32_t resvdPaRAMSets[EDMA3_MAX_PARAM_DWRDS];
448 /**
449 * \brief Reserved DMA channels
450 *
451 * DMA channels reserved during initialization for future use. These will
452 * not be given when user requests for ANY available DMA channel using
453 * 'EDMA3_DRV_DMA_CHANNEL_ANY' as channel id.
454 */
455 uint32_t resvdDmaChannels[EDMA3_MAX_DMA_CHAN_DWRDS];
457 /**
458 * \brief Reserved QDMA channels
459 *
460 * QDMA channels reserved during initialization for future use. These will
461 * not be given when user requests for ANY available QDMA channel using
462 * 'EDMA3_DRV_QDMA_CHANNEL_ANY' as channel id.
463 */
464 uint32_t resvdQdmaChannels[EDMA3_MAX_QDMA_CHAN_DWRDS];
466 /**
467 * \brief Reserved TCCs
468 *
469 * TCCs reserved during initialization for future use. These will not
470 * be given when user requests for ANY available TCC using
471 * 'EDMA3_DRV_TCC_ANY' as resource id.
472 */
473 uint32_t resvdTccs[EDMA3_MAX_TCC_DWRDS];
474 }EDMA3_DRV_InstanceInitConfig;
476 /**\struct EDMA3_DRV_InitConfig
477 * \brief Used to Initialize the EDMA3 Driver Instance
478 *
479 * This configuration structure is used to initialize the EDMA3 DRV Instance.
480 * This configuration information is passed while opening the DRV instance.
481 */
482 typedef struct
483 {
484 /** Region Identification */
485 EDMA3_RM_RegionId regionId;
487 /**
488 * It tells whether the EDMA3 DRV instance is Master or not. Only the shadow
489 * region associated with this master instance will receive the EDMA3
490 * interrupts (if enabled).
491 */
492 uint32_t isMaster;
494 /**
495 * EDMA3 resources related shadow region specific information. Which all
496 * EDMA3 resources are owned and reserved by this particular instance are
497 * told in this configuration structure.
498 * User can also pass this structure as NULL. In that case, default static
499 * configuration would be taken from the platform specific configuration
500 * files (part of the Resource Manager), if available.
501 */
502 EDMA3_DRV_InstanceInitConfig *drvInstInitConfig;
504 /**
505 * EDMA3 Driver Instance specific semaphore handle.
506 * Used to share resources (DMA/QDMA channels, PaRAM Sets, TCCs etc)
507 * among different users.
508 */
509 void *drvSemHandle;
511 /**
512 * Instance wide global callback function to catch non-channel
513 * specific errors from the Channel controller. for eg, TCC
514 * error, queue threshold exceed error etc.
515 */
516 EDMA3_RM_GblErrCallback gblerrCb;
518 /**
519 * Application data to be passed back to the global error callback
520 * function
521 */
522 void *gblerrData;
523 } EDMA3_DRV_InitConfig;
525 /**\struct EDMA3_DRV_MiscParam
526 * \brief Used to specify the miscellaneous options during EDMA3 Driver
527 * Initialization.
528 *
529 * This configuration structure is used to specify some misc options
530 * while creating the Driver object. New options may also be added into this
531 * structure in future.
532 */
533 typedef struct {
534 /**
535 * In a multi-master system (for e.g. ARM + DSP), this option is used to
536 * distinguish between Master and Slave. Only the Master is allowed to
537 * program the global EDMA3 registers (like Queue priority, Queue water-
538 * mark level, error registers etc).
539 */
540 uint16_t isSlave;
542 /** For future use **/
543 uint16_t param;
544 }EDMA3_DRV_MiscParam;
546 /**
547 @}
548 */
550 /** @addtogroup EDMA3_LLD_DRV_FUNCTION_INIT
551 @{ */
553 /**
554 * \brief Create EDMA3 Driver Object
555 *
556 * This API is used to create the EDMA3 Driver Object. It should be
557 * called only ONCE for each EDMA3 hardware instance.
558 *
559 * Init-time Configuration structure for EDMA3 hardware is provided to pass the
560 * SoC specific information. This configuration information could be provided
561 * by the user at init-time. In case user doesn't provide it, this information
562 * could be taken from the SoC specific configuration file
563 * edma3_<SOC_NAME>_cfg.c, in case it is available.
564 *
565 * This API clears the error specific registers (EMCR/EMCRh, QEMCR, CCERRCLR)
566 * and sets the TCs priorities and Event Queues' watermark levels, if the 'miscParam'
567 * argument is NULL. User can avoid these registers' programming (in some specific
568 * use cases) by SETTING the 'isSlave' field of 'EDMA3_RM_MiscParam' configuration
569 * structure and passing this structure as the third argument (miscParam).
570 *
571 * After successful completion of this API, Driver Object's state
572 * changes to EDMA3_DRV_CREATED from EDMA3_DRV_DELETED.
573 *
574 * \param phyCtrllerInstId [IN] EDMA3 Controller Instance Id
575 * (Hardware instance id, starting from 0).
576 * \param gblCfgParams [IN] SoC specific configuration structure for the
577 * EDMA3 Hardware.
578 * \param miscParam [IN] Misc configuration options provided in the
579 * structure 'EDMA3_DRV_MiscParam'.
580 * For default options, user can pass NULL
581 * in this argument.
582 *
583 * \return EDMA3_DRV_SOK or EDMA3_DRV Error code
584 */
585 EDMA3_DRV_Result EDMA3_DRV_create (uint32_t phyCtrllerInstId,
586 const EDMA3_DRV_GblConfigParams *gblCfgParams,
587 const void *miscParam);
588 /**
589 * \brief Delete EDMA3 Driver Object
590 *
591 * Use this API to delete the EDMA3 Driver Object. It should be called only
592 * ONCE for each EDMA3 hardware instance. It should be called ONLY after
593 * closing all the EDMA3 Driver Instances.
594 *
595 * This API is used to delete the EDMA3 Driver Object. It should be called
596 * once for each EDMA3 hardware instance, ONLY after closing all the
597 * previously opened EDMA3 Driver Instances.
598 *
599 * After successful completion of this API, Driver Object's state
600 * changes to EDMA3_DRV_DELETED.
601 *
602 * \param phyCtrllerInstId [IN] EDMA3 Phy Controller Instance Id (Hardware
603 * instance id, starting from 0).
604 * \param param [IN] For possible future use.
605 *
606 * \return EDMA3_DRV_SOK or EDMA3_DRV Error code
607 */
608 EDMA3_DRV_Result EDMA3_DRV_delete (uint32_t phyCtrllerInstId,
609 const void *param);
611 /**
612 * \brief Open EDMA3 Driver Instance
613 *
614 * This API is used to open an EDMA3 Driver Instance. It could be
615 * called multiple times, for each possible EDMA3 shadow region. Maximum
616 * EDMA3_MAX_REGIONS instances are allowed for each EDMA3 hardware
617 * instance. Multiple instances on the same shadow region are NOT allowed.
618 *
619 * Also, only ONE Master Driver Instance is permitted. This master
620 * instance (and hence the region to which it belongs) will only receive the
621 * EDMA3 interrupts, if enabled.
622 *
623 * User could pass the instance specific configuration structure
624 * (initCfg.drvInstInitConfig) as a part of the 'initCfg' structure,
625 * during init-time. In case user doesn't provide it, this information could
626 * be taken from the SoC specific configuration file edma3_<SOC_NAME>_cfg.c,
627 * in case it is available.
628 *
629 * By default, this EDMA3 Driver instance will clear the PaRAM Sets while
630 * allocating them. To change the default behavior, user should use the IOCTL
631 * interface appropriately.
632 *
633 * \param phyCtrllerInstId [IN] EDMA3 Controller Instance Id (Hardware
634 * instance id, starting from 0).
635 * \param initCfg [IN] Used to Initialize the EDMA3 Driver
636 * Instance (Master or Slave).
637 * \param errorCode [OUT] Error code while opening DRV instance.
638 *
639 * \return EDMA3_DRV_Handle : If successfully opened, the API will return the
640 * associated driver's instance handle.
641 *
642 * \note This function disables the global interrupts (by calling API
643 * edma3OsProtectEntry with protection level
644 * EDMA3_OS_PROTECT_INTERRUPT) while modifying the global data
645 * structures, to make it re-entrant.
646 */
647 EDMA3_DRV_Handle EDMA3_DRV_open (uint32_t phyCtrllerInstId,
648 const EDMA3_DRV_InitConfig *initCfg,
649 EDMA3_DRV_Result *errorCode);
651 /**
652 * \brief Close the EDMA3 Driver Instance.
653 *
654 * This API is used to close a previously opened EDMA3 Driver Instance.
655 *
656 * \param hEdma [IN] Handle to the previously opened EDMA3
657 * Driver Instance.
658 * \param param [IN] For possible future use
659 *
660 * \return EDMA3_DRV_SOK or EDMA3_DRV Error code
661 *
662 * \note This function disables the global interrupts (by calling API
663 * edma3OsProtectEntry with protection level
664 * EDMA3_OS_PROTECT_INTERRUPT) while modifying the global data
665 * structures, to make it re-entrant.
666 */
667 EDMA3_DRV_Result EDMA3_DRV_close (EDMA3_DRV_Handle hEdma,
668 const void *param);
670 /**
671 @}
672 */
674 /** @addtogroup EDMA3_LLD_DRV_SYMBOL_DEFINE
675 @{ */
677 /* Defines for Logical Channel Values */
678 /*---------------------------------------------------------------------------*/
679 /**
680 * Used to specify any available DMA Channel while requesting
681 * one. Used in the API EDMA3_DRV_requestChannel().
682 * DMA channel from the pool of (owned && non_reserved && available_right_now)
683 * DMA channels will be chosen and returned.
684 */
685 #define EDMA3_DRV_DMA_CHANNEL_ANY 1002u
687 /**
688 * Used to specify any available QDMA Channel while requesting
689 * one. Used in the API EDMA3_DRV_requestChannel().
690 * QDMA channel from the pool of (owned && non_reserved && available_right_now)
691 * QDMA channels will be chosen and returned.
692 */
693 #define EDMA3_DRV_QDMA_CHANNEL_ANY 1003u
695 /**
696 * Used to specify any available TCC while requesting
697 * one. Used in the API EDMA3_DRV_requestChannel(), for
698 * both DMA and QDMA channels.
699 * TCC from the pool of (owned && non_reserved && available_right_now)
700 * TCCs will be chosen and returned.
701 */
702 #define EDMA3_DRV_TCC_ANY 1004u
704 /**
705 * Used to specify any available PaRAM Set while requesting
706 * one. Used in the API EDMA3_DRV_requestChannel(), for Link channels.
707 * PaRAM Set from the pool of (owned && non_reserved && available_right_now)
708 * PaRAM Sets will be chosen and returned.
709 */
710 #define EDMA3_DRV_LINK_CHANNEL 1005u
712 /**
713 * Used to specify any available PaRAM Set while requesting one. Used in the
714 * API EDMA3_DRV_requestChannel(), for Link channels.
715 * TCC code should also be specified and it will be used to populate the LINK
716 * field of the PaRAM Set. Without TCC code, the call will fail.
717 * PaRAM Set from the pool of (owned && non_reserved && available_right_now)
718 * PaRAM Sets will be chosen and returned.
719 */
720 #define EDMA3_DRV_LINK_CHANNEL_WITH_TCC 1006u
722 /**
723 @}
724 */
726 /** @addtogroup EDMA3_LLD_DRV_SYMBOL_ENUM
727 @{ */
729 /**
730 * \brief DMA Channels assigned to different Hardware Events.
731 *
732 * They should be used while requesting a specific DMA channel.
733 * One possible usage is to maintain a SoC specific file, which will
734 * contain the mapping of these hardware events to the respective
735 * peripherals for better understanding and lesser probability of
736 * errors. Also, if any event associated with a particular peripheral
737 * gets changed, only that SoC specific file needs to be changed.
738 * for eg, the sample SoC specific file "soc.h" can have these defines:
739 *
740 * #define EDMA3_DRV_HW_CHANNEL_MCBSP_TX EDMA3_DRV_HW_CHANNEL_EVENT_2
741 * #define EDMA3_DRV_HW_CHANNEL_MCBSP_RX EDMA3_DRV_HW_CHANNEL_EVENT_3
742 *
743 * These defines will be used by the MCBSP driver. The same event
744 * EDMA3_DRV_HW_CHANNEL_EVENT_2/3 could be mapped to some other
745 * peripheral also.
746 */
747 typedef enum
748 {
749 /** Channel assigned to EDMA3 Event 0 */
750 EDMA3_DRV_HW_CHANNEL_EVENT_0 = 0,
751 /** Channel assigned to EDMA3 Event 1 */
752 EDMA3_DRV_HW_CHANNEL_EVENT_1,
753 /** Channel assigned to EDMA3 Event 2 */
754 EDMA3_DRV_HW_CHANNEL_EVENT_2,
755 /** Channel assigned to EDMA3 Event 3 */
756 EDMA3_DRV_HW_CHANNEL_EVENT_3,
757 /** Channel assigned to EDMA3 Event 4 */
758 EDMA3_DRV_HW_CHANNEL_EVENT_4,
759 /** Channel assigned to EDMA3 Event 5 */
760 EDMA3_DRV_HW_CHANNEL_EVENT_5,
761 /** Channel assigned to EDMA3 Event 6 */
762 EDMA3_DRV_HW_CHANNEL_EVENT_6,
763 /** Channel assigned to EDMA3 Event 7 */
764 EDMA3_DRV_HW_CHANNEL_EVENT_7,
765 /** Channel assigned to EDMA3 Event 8 */
766 EDMA3_DRV_HW_CHANNEL_EVENT_8,
767 /** Channel assigned to EDMA3 Event 9 */
768 EDMA3_DRV_HW_CHANNEL_EVENT_9,
769 /** Channel assigned to EDMA3 Event 10 */
770 EDMA3_DRV_HW_CHANNEL_EVENT_10,
771 /** Channel assigned to EDMA3 Event 11 */
772 EDMA3_DRV_HW_CHANNEL_EVENT_11,
773 /** Channel assigned to EDMA3 Event 12 */
774 EDMA3_DRV_HW_CHANNEL_EVENT_12,
775 /** Channel assigned to EDMA3 Event 13 */
776 EDMA3_DRV_HW_CHANNEL_EVENT_13,
777 /** Channel assigned to EDMA3 Event 14 */
778 EDMA3_DRV_HW_CHANNEL_EVENT_14,
779 /** Channel assigned to EDMA3 Event 15 */
780 EDMA3_DRV_HW_CHANNEL_EVENT_15,
781 /** Channel assigned to EDMA3 Event 16 */
782 EDMA3_DRV_HW_CHANNEL_EVENT_16,
783 /** Channel assigned to EDMA3 Event 17 */
784 EDMA3_DRV_HW_CHANNEL_EVENT_17,
785 /** Channel assigned to EDMA3 Event 18 */
786 EDMA3_DRV_HW_CHANNEL_EVENT_18,
787 /** Channel assigned to EDMA3 Event 19 */
788 EDMA3_DRV_HW_CHANNEL_EVENT_19,
789 /** Channel assigned to EDMA3 Event 20 */
790 EDMA3_DRV_HW_CHANNEL_EVENT_20,
791 /** Channel assigned to EDMA3 Event 21 */
792 EDMA3_DRV_HW_CHANNEL_EVENT_21,
793 /** Channel assigned to EDMA3 Event 22 */
794 EDMA3_DRV_HW_CHANNEL_EVENT_22,
795 /** Channel assigned to EDMA3 Event 23 */
796 EDMA3_DRV_HW_CHANNEL_EVENT_23,
797 /** Channel assigned to EDMA3 Event 24 */
798 EDMA3_DRV_HW_CHANNEL_EVENT_24,
799 /** Channel assigned to EDMA3 Event 25 */
800 EDMA3_DRV_HW_CHANNEL_EVENT_25,
801 /** Channel assigned to EDMA3 Event 26 */
802 EDMA3_DRV_HW_CHANNEL_EVENT_26,
803 /** Channel assigned to EDMA3 Event 27 */
804 EDMA3_DRV_HW_CHANNEL_EVENT_27,
805 /** Channel assigned to EDMA3 Event 28 */
806 EDMA3_DRV_HW_CHANNEL_EVENT_28,
807 /** Channel assigned to EDMA3 Event 29 */
808 EDMA3_DRV_HW_CHANNEL_EVENT_29,
809 /** Channel assigned to EDMA3 Event 30 */
810 EDMA3_DRV_HW_CHANNEL_EVENT_30,
811 /** Channel assigned to EDMA3 Event 31 */
812 EDMA3_DRV_HW_CHANNEL_EVENT_31,
813 /** Channel assigned to EDMA3 Event 32 */
814 EDMA3_DRV_HW_CHANNEL_EVENT_32,
815 /** Channel assigned to EDMA3 Event 33 */
816 EDMA3_DRV_HW_CHANNEL_EVENT_33,
817 /** Channel assigned to EDMA3 Event 34 */
818 EDMA3_DRV_HW_CHANNEL_EVENT_34,
819 /** Channel assigned to EDMA3 Event 35 */
820 EDMA3_DRV_HW_CHANNEL_EVENT_35,
821 /** Channel assigned to EDMA3 Event 36 */
822 EDMA3_DRV_HW_CHANNEL_EVENT_36,
823 /** Channel assigned to EDMA3 Event 37 */
824 EDMA3_DRV_HW_CHANNEL_EVENT_37,
825 /** Channel assigned to EDMA3 Event 38 */
826 EDMA3_DRV_HW_CHANNEL_EVENT_38,
827 /** Channel assigned to EDMA3 Event 39 */
828 EDMA3_DRV_HW_CHANNEL_EVENT_39,
829 /** Channel assigned to EDMA3 Event 40 */
830 EDMA3_DRV_HW_CHANNEL_EVENT_40,
831 /** Channel assigned to EDMA3 Event 41 */
832 EDMA3_DRV_HW_CHANNEL_EVENT_41,
833 /** Channel assigned to EDMA3 Event 42 */
834 EDMA3_DRV_HW_CHANNEL_EVENT_42,
835 /** Channel assigned to EDMA3 Event 43 */
836 EDMA3_DRV_HW_CHANNEL_EVENT_43,
837 /** Channel assigned to EDMA3 Event 44 */
838 EDMA3_DRV_HW_CHANNEL_EVENT_44,
839 /** Channel assigned to EDMA3 Event 45 */
840 EDMA3_DRV_HW_CHANNEL_EVENT_45,
841 /** Channel assigned to EDMA3 Event 46 */
842 EDMA3_DRV_HW_CHANNEL_EVENT_46,
843 /** Channel assigned to EDMA3 Event 47 */
844 EDMA3_DRV_HW_CHANNEL_EVENT_47,
845 /** Channel assigned to EDMA3 Event 48 */
846 EDMA3_DRV_HW_CHANNEL_EVENT_48,
847 /** Channel assigned to EDMA3 Event 49 */
848 EDMA3_DRV_HW_CHANNEL_EVENT_49,
849 /** Channel assigned to EDMA3 Event 50 */
850 EDMA3_DRV_HW_CHANNEL_EVENT_50,
851 /** Channel assigned to EDMA3 Event 51 */
852 EDMA3_DRV_HW_CHANNEL_EVENT_51,
853 /** Channel assigned to EDMA3 Event 52 */
854 EDMA3_DRV_HW_CHANNEL_EVENT_52,
855 /** Channel assigned to EDMA3 Event 53 */
856 EDMA3_DRV_HW_CHANNEL_EVENT_53,
857 /** Channel assigned to EDMA3 Event 54 */
858 EDMA3_DRV_HW_CHANNEL_EVENT_54,
859 /** Channel assigned to EDMA3 Event 55 */
860 EDMA3_DRV_HW_CHANNEL_EVENT_55,
861 /** Channel assigned to EDMA3 Event 56 */
862 EDMA3_DRV_HW_CHANNEL_EVENT_56,
863 /** Channel assigned to EDMA3 Event 57 */
864 EDMA3_DRV_HW_CHANNEL_EVENT_57,
865 /** Channel assigned to EDMA3 Event 58 */
866 EDMA3_DRV_HW_CHANNEL_EVENT_58,
867 /** Channel assigned to EDMA3 Event 59 */
868 EDMA3_DRV_HW_CHANNEL_EVENT_59,
869 /** Channel assigned to EDMA3 Event 60 */
870 EDMA3_DRV_HW_CHANNEL_EVENT_60,
871 /** Channel assigned to EDMA3 Event 61 */
872 EDMA3_DRV_HW_CHANNEL_EVENT_61,
873 /** Channel assigned to EDMA3 Event 62 */
874 EDMA3_DRV_HW_CHANNEL_EVENT_62,
875 /** Channel assigned to EDMA3 Event 63 */
876 EDMA3_DRV_HW_CHANNEL_EVENT_63
877 } EDMA3_DRV_HW_CHANNEL_EVENT;
879 /**
880 @}
881 */
883 /** @addtogroup EDMA3_LLD_DRV_SYMBOL_DEFINE
884 @{ */
886 /**
887 * \brief QDMA Channel defines
888 *
889 * They should be used while requesting a specific QDMA channel in API
890 * EDMA3_DRV_requestChannel() as the argument (*pLch). Please note that
891 * these defines should ONLY be used in the API EDMA3_DRV_requestChannel() and
892 * not in any other API to perform further operations. They are only provided
893 * to allow user allocate specific QDMA channels.
894 */
895 /** QDMA Channel 0 */
896 #define EDMA3_DRV_QDMA_CHANNEL_0 (EDMA3_MAX_DMA_CH + EDMA3_MAX_PARAM_SETS)
897 /** QDMA Channel 1 */
898 #define EDMA3_DRV_QDMA_CHANNEL_1 (EDMA3_DRV_QDMA_CHANNEL_0+1u)
899 /** QDMA Channel 2 */
900 #define EDMA3_DRV_QDMA_CHANNEL_2 (EDMA3_DRV_QDMA_CHANNEL_0+2u)
901 /** QDMA Channel 3 */
902 #define EDMA3_DRV_QDMA_CHANNEL_3 (EDMA3_DRV_QDMA_CHANNEL_0+3u)
903 /** QDMA Channel 4 */
904 #define EDMA3_DRV_QDMA_CHANNEL_4 (EDMA3_DRV_QDMA_CHANNEL_0+4u)
905 /** QDMA Channel 5 */
906 #define EDMA3_DRV_QDMA_CHANNEL_5 (EDMA3_DRV_QDMA_CHANNEL_0+5u)
907 /** QDMA Channel 6 */
908 #define EDMA3_DRV_QDMA_CHANNEL_6 (EDMA3_DRV_QDMA_CHANNEL_0+6u)
909 /** QDMA Channel 7 */
910 #define EDMA3_DRV_QDMA_CHANNEL_7 (EDMA3_DRV_QDMA_CHANNEL_0+7u)
912 /**
913 @}
914 */
916 /** @addtogroup EDMA3_LLD_DRV_FUNCTION_BASIC
917 @{ */
919 /**
920 * \brief Request a DMA/QDMA/Link channel.
921 *
922 * Each channel (DMA/QDMA/Link) must be requested before initiating a DMA
923 * transfer on that channel.
924 *
925 * This API is used to allocate a logical channel (DMA/QDMA/Link) along with
926 * the associated resources. For DMA and QDMA channels, TCC and PaRAM Set are
927 * also allocated along with the requested channel. User can also specify a
928 * specific TCC which needs to be allocated with the DMA/QDMA channel or else
929 * can request any available TCC.
930 *
931 * For Link channels, ONLY a PaRAM Set is allocated and the allocated PaRAM Set
932 * number is returned as the logical channel no. A TCC code can also be
933 * specified while making the request. This TCC code will be copied to the
934 * LINK field of the allocated PaRAM Set and will be associated with the Link
935 * channel.
936 *
937 * User can request a specific logical channel - DMA, QDMA and Link, by passing
938 * the channel id in 'pLCh'. Note that the channel id is the same as the actual
939 * resource id in case of DMA channels and Link channels. For DMA channels,
940 * channel id lies between 0 and (max dma channels - 1). For Link channels,
941 * channel id lies between (max dma channels) and (max param sets - 1). To
942 * allocate specific QDMA channels, user SHOULD use the defines
943 * EDMA3_DRV_QDMA_CHANNEL_X mentioned above.
944 *
945 * User can also request ANY available logical channel by specifying the
946 * below mentioned values in '*pLCh':
947 * a) EDMA3_DRV_DMA_CHANNEL_ANY: For DMA channels
948 * b) EDMA3_DRV_QDMA_CHANNEL_ANY: For QDMA channels, and
949 * c) EDMA3_DRV_LINK_CHANNEL: For Link channels. Normally user should use this
950 * value to request link channels (PaRAM Sets used for linking purpose
951 * only), unless he wants to use some specific link channels (PaRAM Sets)
952 * which is also allowed.
953 * d) EDMA3_DRV_LINK_CHANNEL_WITH_TCC: For Link channels. User should
954 * use this value to request link channels with TCC code.
955 *
956 * This API internally uses EDMA3_RM_allocResource () to allocate the desired
957 * resources (DMA/QDMA channel, PaRAM Set and TCC).
958 *
959 * This API also registers a specific callback function, in case the same is
960 * provided, against the allocated TCC. To do this, this API calls
961 * EDMA3_RM_registerTccCb(), which is a part of the Resource Manager. Please
962 * note that the interrupts are enabled for the specific TCC only if callback
963 * function is provided. In the absence of this, the API assumes that the
964 * requested logical channel is going to be used in Poll mode environment.
965 *
966 * For DMA/QDMA channels, after allocating all the EDMA3 resources, this API
967 * sets the TCC field of the OPT PaRAM Word with the allocated TCC. It also sets
968 * the event queue for the channel allocated. The event queue needs to be
969 * specified by the user.
970 *
971 * For DMA channel, it also sets the DCHMAP register, if required.
972 *
973 * For QDMA channel, it sets the QCHMAP register and CCNT as trigger word and
974 * enables the QDMA channel by writing to the QEESR register.
975 *
976 * \param hEdma [IN] Handle to the previously opened Driver
977 * Instance.
978 * \param pLCh [IN/OUT] Requested logical channel id.
979 * Examples:
980 * - EDMA3_DRV_HW_CHANNEL_EVENT_0
981 * - To request a DMA Master Channel
982 * mapped to EDMA Event 0.
983 *
984 * - EDMA3_DRV_DMA_CHANNEL_ANY
985 * - For requesting any DMA Master channel
986 * with no event mapping.
987 *
988 * - EDMA3_DRV_QDMA_CHANNEL_ANY
989 * - For requesting any QDMA Master channel
990 *
991 * - EDMA3_DRV_QDMA_CHANNEL_0
992 * - For requesting the QDMA Channel 0.
993 *
994 * - EDMA3_DRV_LINK_CHANNEL
995 * - For requesting a DMA Slave Channel,
996 * - to be linked to some other Master
997 * - channel.
998 *
999 * - EDMA3_DRV_LINK_CHANNEL_WITH_TCC
1000 * - For requesting a DMA Slave Channel,
1001 * - to be linked to some other Master
1002 * - channel, with a TCC associated with it.
1003 *
1004 * In case user passes a specific channel
1005 * Id, pLCh value is left unchanged. In
1006 * case user requests ANY available
1007 * resource, the allocated channel id is
1008 * returned in pLCh.
1009 *
1010 * \note To request a PaRAM Set for the purpose of
1011 * linking to another channel, call the function with
1012 *
1013 * *pLCh = EDMA3_DRV_LINK_CHANNEL or EDMA3_DRV_LINK_CHANNEL_WITH_TCC
1014 *
1015 * This function will update *pLCh with the allocated Link channel
1016 * handle.
1017 *
1018 * \param pTcc [IN/OUT] The channel number on which the
1019 * completion/error interrupt is generated.
1020 * Not used if user requested for a Link
1021 * channel.
1022 * Examples:
1023 * - EDMA3_DRV_HW_CHANNEL_EVENT_0
1024 * - To request TCC associated with
1025 * - DMA Master Channel mapped to EDMA
1026 * - event 0.
1027 *
1028 * - EDMA3_DRV_TCC_ANY
1029 * - For requesting any TCC with no
1030 * - channel mapping.
1031 * In case user passes a specific TCC
1032 * value, pTcc value is left unchanged.
1033 * In case user requests ANY available TCC,
1034 * the allocated one is returned in pTcc
1035 *
1036 * \param evtQueue [IN] Event Queue Number to which the channel
1037 * will be mapped (valid only for the
1038 * Master Channel (DMA/QDMA) request)
1039 *
1040 * \param tccCb [IN] TCC callback - caters to channel-
1041 * specific events like "Event Miss Error"
1042 * or "Transfer Complete"
1043 *
1044 * \param cbData [IN] Data which will be passed directly to
1045 * the tccCb callback function
1046 *
1047 * \return EDMA3_DRV_SOK or EDMA3_DRV Error code
1048 *
1049 * \note This function internally uses EDMA3 Resource Manager, which
1050 * acquires a RM Instance specific semaphore
1051 * to prevent simultaneous access to the global pool of resources.
1052 * It also disables the global interrupts while modifying
1053 * the global CC registers.
1054 * It is re-entrant, but SHOULD NOT be called from the user callback
1055 * function (ISR context).
1056 */
1057 EDMA3_DRV_Result EDMA3_DRV_requestChannel (EDMA3_DRV_Handle hEdma,
1058 uint32_t *pLCh,
1059 uint32_t *pTcc,
1060 EDMA3_RM_EventQueue evtQueue,
1061 EDMA3_RM_TccCallback tccCb,
1062 void *cbData);
1064 /**
1065 * \brief Free the specified channel (DMA/QDMA/Link) and its associated
1066 * resources (PaRAM Set, TCC etc) and removes various mappings.
1067 *
1068 * This API internally uses EDMA3_RM_freeResource () to free the desired
1069 * resources.
1070 *
1071 * For Link channels, this API only frees the associated PaRAM Set.
1072 *
1073 * For DMA/QDMA channels, it does the following operations:
1074 * a) Disable any ongoing transfer on the channel,
1075 * b) Unregister the TCC Callback function and disable the interrupts,
1076 * c) Remove the channel to Event Queue mapping,
1077 * d) For DMA channels, clear the DCHMAP register, if available
1078 * e) For QDMA channels, clear the QCHMAP register,
1079 * f) Frees the DMA/QDMA channel in the end.
1080 *
1081 * \param hEdma [IN] Handle to the EDMA Driver Instance.
1082 * \param channelId [IN] Logical Channel number to be freed.
1083 *
1084 * \return EDMA3_DRV_SOK or EDMA3_DRV Error code
1085 *
1086 * \note This function disables the global interrupts while modifying
1087 * the global CC registers and while modifying global data structures,
1088 * to prevent simultaneous access to the global pool of resources.
1089 * It internally calls EDMA3_RM_freeResource () for resource
1090 * de-allocation. It is re-entrant.
1091 */
1092 EDMA3_DRV_Result EDMA3_DRV_freeChannel (EDMA3_DRV_Handle hEdma,
1093 uint32_t channelId);
1095 /**
1096 * \brief Disables the DMA Channel by clearing the Event Enable Register and
1097 * clears Error Register & Secondary Event Register for a specific DMA channel.
1098 *
1099 * This API clears the Event Enable register, Event Miss register and Secondary
1100 * Event register for a specific DMA channel. It also clears the CC Error
1101 * register.
1102 *
1103 * \param hEdma [IN] Handle to the EDMA Driver Instance.
1104 * \param channelId [IN] DMA Channel needs to be cleaned.
1105 *
1106 * \return EDMA3_DRV_SOK or EDMA3_DRV Error code
1107 *
1108 * \note This function is re-entrant for unique channelId values. It is non-
1109 * re-entrant for same channelId value.
1110 */
1111 EDMA3_DRV_Result EDMA3_DRV_clearErrorBits (EDMA3_DRV_Handle hEdma,
1112 uint32_t channelId);
1114 /**
1115 @}
1116 */
1118 /** @addtogroup EDMA3_LLD_DRV_FUNCTION_ADVANCED
1119 @{ */
1121 /**
1122 * \brief Link two logical channels.
1123 *
1124 * This API is used to link two previously allocated logical (DMA/QDMA/Link)
1125 * channels.
1126 *
1127 * It sets the Link field of the PaRAM set associated with first logical
1128 * channel (lCh1) to point it to the PaRAM set associated with second logical
1129 * channel (lCh2).
1130 *
1131 * It also sets the TCC field of PaRAM set of second logical channel to the
1132 * same as that of the first logical channel, only if the TCC field doesnot
1133 * contain a valid TCC code. In case the second logical channel has its own TCC,
1134 * the TCC field remains unchanged.
1135 *
1136 * \param hEdma [IN] Handle to the EDMA Driver Instance.
1137 * \param lCh1 [IN] Logical Channel to which particular channel
1138 * will be linked.
1139 * \param lCh2 [IN] Logical Channel which needs to be linked to
1140 * the first channel.
1141 * After the transfer based on the PaRAM set
1142 * of lCh1 is over, the PaRAM set of lCh2 will
1143 * be copied to the PaRAM set of lCh1 and
1144 * transfer will resume.
1145 * For DMA channels, another sync event is
1146 * required to initiate the transfer on the
1147 * Link channel.
1148 *
1149 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
1150 *
1151 * \note This function is re-entrant for unique lCh1 & lCh2 values. It is
1152 * non-re-entrant for same lCh1 & lCh2 values.
1153 */
1154 EDMA3_DRV_Result EDMA3_DRV_linkChannel ( EDMA3_DRV_Handle hEdma,
1155 uint32_t lCh1,
1156 uint32_t lCh2);
1158 /**
1159 * \brief Unlink the channel from the earlier linked logical channel.
1160 *
1161 * This function breaks the link between the specified
1162 * channel and the earlier linked logical channel
1163 * by clearing the Link Address field.
1164 *
1165 * \param hEdma [IN] Handle to the EDMA Driver Instance.
1166 * \param lCh [IN] Channel for which linking has to be removed
1167 *
1168 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
1169 *
1170 * \note This function is re-entrant for unique lCh values. It is non-
1171 * re-entrant for same lCh value.
1172 */
1173 EDMA3_DRV_Result EDMA3_DRV_unlinkChannel (EDMA3_DRV_Handle hEdma,
1174 uint32_t lCh);
1176 /**
1177 @}
1178 */
1180 /** @addtogroup EDMA3_LLD_DRV_SYMBOL_ENUM
1181 @{ */
1183 /**
1184 * \brief OPT Field Offset.
1185 *
1186 * Use this enum to set or get any of the
1187 * Fields within an OPT of a Parameter RAM set.
1188 */
1189 typedef enum
1190 {
1191 /**
1192 * Source addressing mode (INCR / FIFO)
1193 * (Bit 0)
1194 */
1195 EDMA3_DRV_OPT_FIELD_SAM = 0,
1197 /**
1198 * Destination addressing mode (INCR / FIFO)
1199 * (Bit 1)
1200 */
1201 EDMA3_DRV_OPT_FIELD_DAM = 1,
1203 /**
1204 * Transfer synchronization dimension (A-synchronized / AB-synchronized)
1205 * (Bit 2)
1206 */
1207 EDMA3_DRV_OPT_FIELD_SYNCDIM = 2,
1209 /**
1210 * The STATIC field
1211 * PaRAM set is static/non-static?
1212 * (Bit 3)
1213 */
1214 EDMA3_DRV_OPT_FIELD_STATIC = 3,
1216 /**
1217 * FIFO Width. Applies if either SAM or DAM is set to FIFO mode.
1218 * (Bitfield 8-10)
1219 */
1220 EDMA3_DRV_OPT_FIELD_FWID = 4,
1222 /**
1223 * Transfer complete code mode. Indicates the point at which a
1224 * transfer is considered completed for chaining and interrupt
1225 * generation.
1226 * (Bit 11)
1227 */
1228 EDMA3_DRV_OPT_FIELD_TCCMODE = 5,
1230 /**
1231 * Transfer Complete Code (TCC).
1232 * This 6-bit code is used to set the relevant bit in chaining enable
1233 * register (CER[TCC]/CERH[TCC]) for chaining or in interrupt pending
1234 * register (IPR[TCC]/IPRH[TCC]) for interrupts.
1235 * (Bitfield 12-17)
1236 */
1237 EDMA3_DRV_OPT_FIELD_TCC = 6,
1239 /**
1240 * Transfer complete interrupt enable/disable.
1241 * (Bit 20)
1242 */
1243 EDMA3_DRV_OPT_FIELD_TCINTEN = 7,
1245 /**
1246 * Intermediate transfer complete interrupt enable/disable.
1247 * (Bit 21)
1248 */
1249 EDMA3_DRV_OPT_FIELD_ITCINTEN = 8,
1251 /**
1252 * Transfer complete chaining enable/disable
1253 * (Bit 22)
1254 */
1255 EDMA3_DRV_OPT_FIELD_TCCHEN = 9,
1257 /**
1258 * Intermediate transfer completion chaining enable/disable
1259 * (Bit 23)
1260 */
1261 EDMA3_DRV_OPT_FIELD_ITCCHEN = 10
1263 } EDMA3_DRV_OptField;
1265 /**
1266 * \brief EDMA Addressing modes
1267 *
1268 * The EDMA3 TC supports two addressing modes
1269 * -# Increment transfer
1270 * -# FIFO transfer
1271 *
1272 * The SAM (Source Addressing Mode) and the DAM (Destination Addressing Mode)
1273 * can be independently set to either of the two via the OPT register.
1274 *
1275 */
1276 typedef enum
1277 {
1278 /**
1279 * Increment (INCR) mode. Source addressing within an array increments.
1280 * Source is not a FIFO.
1281 */
1282 EDMA3_DRV_ADDR_MODE_INCR = 0,
1284 /**
1285 * FIFO mode. Source addressing within an array wraps around upon
1286 * reaching FIFO width.
1287 */
1288 EDMA3_DRV_ADDR_MODE_FIFO = 1
1290 } EDMA3_DRV_AddrMode;
1292 /**
1293 * \brief EDMA Transfer Synchronization type.
1294 *
1295 * Two types of Synchronization of transfers are possible
1296 * -# A Synchronized
1297 * -# AB Syncronized
1298 * - A Sync
1299 * -# Each Array is submitted as one TR
1300 * -# (BCNT*CCNT) number of sync events are needed to completely service
1301 * a PaRAM set. (Where BCNT = Num of Arrays in a Frame;
1302 * CCNT = Num of Frames in a Block)
1303 * -# (S/D)CIDX = (Addr of First array in next frame)
1304 * minus (Addr of Last array in present frame)
1305 * (Where CIDX is the Inter-Frame index)
1306 *
1307 * - AB Sync
1308 * -# Each Frame is submitted as one TR
1309 * -# Only CCNT number of sync events are needed to completely service
1310 * a PaRAM set
1311 * -# (S/D)CIDX = (Addr of First array in next frame)
1312 * minus (Addr of First array of present frame)
1313 *
1314 * \note ABC sync transfers can be achieved logically by chaining multiple
1315 * AB sync transfers
1316 *
1317 */
1318 typedef enum
1319 {
1320 /**
1321 * A-synchronized.
1322 * Each event triggers the transfer of a single array of ACNT bytes
1323 */
1324 EDMA3_DRV_SYNC_A = 0 ,
1326 /**
1327 * AB-synchronized.
1328 * Each event triggers the transfer of BCNT arrays of ACNT bytes
1329 */
1330 EDMA3_DRV_SYNC_AB = 1
1332 } EDMA3_DRV_SyncType;
1334 /**
1335 * \brief True/False: PaRAM set is Static or not. A Static PaRAM set
1336 * is updated or linked after TR is submitted.
1337 */
1338 typedef enum
1339 {
1340 /**
1341 * PaRAM set is not Static. PaRAM set is updated or linked
1342 * after TR is submitted. A value of 0 should be used for
1343 * DMA channels and for nonfinal transfers in a linked list
1344 * of QDMA transfers
1345 */
1346 EDMA3_DRV_STATIC_DIS = 0,
1348 /**
1349 * PaRAM set is Static. PaRAM set is not updated or linked
1350 * after TR is submitted. A value of 1 should be used for
1351 * isolated QDMA transfers or for the final transfer in a
1352 * linked list of QDMA transfers.
1353 */
1354 EDMA3_DRV_STATIC_EN = 1
1355 } EDMA3_DRV_StaticMode;
1357 /**
1358 * \brief EDMA3 FIFO width.
1359 *
1360 * The user can set the width of the FIFO using this enum.
1361 * This is done via the OPT register.
1362 * This is valid only if the EDMA3_DRV_ADDR_MODE_FIFO value is used for the
1363 * enum EDMA3_DRV_AddrMode.
1364 */
1365 typedef enum
1366 {
1367 /** FIFO width is 8-bit. */
1368 EDMA3_DRV_W8BIT = 0,
1370 /** FIFO width is 16-bit. */
1371 EDMA3_DRV_W16BIT = 1,
1373 /** FIFO width is 32-bit. */
1374 EDMA3_DRV_W32BIT = 2,
1376 /** FIFO width is 64-bit. */
1377 EDMA3_DRV_W64BIT = 3,
1379 /** FIFO width is 128-bit. */
1380 EDMA3_DRV_W128BIT = 4,
1382 /** FIFO width is 256-bit. */
1383 EDMA3_DRV_W256BIT = 5
1385 } EDMA3_DRV_FifoWidth;
1387 /**
1388 * \brief Transfer complete code mode.
1389 * Indicates the point at which a transfer is considered completed for
1390 * chaining and interrupt generation
1391 */
1392 typedef enum
1393 {
1394 /** A transfer is considered completed after transfer of data */
1395 EDMA3_DRV_TCCMODE_NORMAL = 0,
1397 /**
1398 * A transfer is considered completed after the EDMA3CC submits a TR
1399 * to the EDMA3TC. TC may still be transferring data when interrupt/chain
1400 * is triggered.
1401 */
1402 EDMA3_DRV_TCCMODE_EARLY = 1
1403 } EDMA3_DRV_TccMode;
1405 /**
1406 * \brief Transfer complete interrupt enable.
1407 */
1408 typedef enum
1409 {
1410 /** Transfer complete interrupt is disabled */
1411 EDMA3_DRV_TCINTEN_DIS = 0,
1413 /**
1414 * Transfer complete interrupt is enabled.
1415 * When enabled, the interrupt pending register (IPR/IPRH) bit is set on
1416 * transfer completion (upon completion of the final TR in the PaRAM set).
1417 * The bit (position) set in IPR or IPRH is the TCC value specified. In
1418 * order to generate a completion interrupt to the CPU, the corresponding
1419 * IER [TCC] / IERH [TCC] bit must be set to 1.
1420 */
1421 EDMA3_DRV_TCINTEN_EN = 1
1422 } EDMA3_DRV_TcintEn;
1424 /**
1425 * \brief Intermediate Transfer complete interrupt enable.
1426 */
1427 typedef enum
1428 {
1429 /** Intermediate Transfer complete interrupt is disabled */
1430 EDMA3_DRV_ITCINTEN_DIS = 0,
1432 /**
1433 * Intermediate transfer complete interrupt is enabled.
1434 * When enabled, the interrupt pending register (IPR/IPRH) bit is set on
1435 * every intermediate transfer completion (upon completion of every
1436 * intermediate TR in the PaRAM set, except the final TR in the PaRAM set).
1437 * The bit (position) set in IPR or IPRH is the TCC value specified. In
1438 * order to generate a completion interrupt to the CPU, the corresponding
1439 * IER [TCC] / IERH [TCC] bit must be set to 1.
1440 */
1441 EDMA3_DRV_ITCINTEN_EN = 1
1442 } EDMA3_DRV_ItcintEn;
1444 /**
1445 * \brief Transfer complete chaining enable.
1446 */
1447 typedef enum
1448 {
1449 /** Transfer complete chaining is disabled */
1450 EDMA3_DRV_TCCHEN_DIS = 0,
1452 /**
1453 * Transfer complete chaining is enabled.
1454 * When enabled, the chained event register (CER/CERH) bit is set on final
1455 * chained transfer completion (upon completion of the final / last TR in
1456 * the PaRAM set). The bit (position) set in CER or CERH is the TCC value
1457 * specified.
1458 */
1459 EDMA3_DRV_TCCHEN_EN = 1
1460 } EDMA3_DRV_TcchEn;
1462 /**
1463 * \brief Intermediate Transfer complete chaining enable.
1464 */
1465 typedef enum
1466 {
1467 /** Intermediate Transfer complete chaining is disabled */
1468 EDMA3_DRV_ITCCHEN_DIS = 0,
1470 /**
1471 * Intermediate transfer complete chaining is enabled.
1472 * When enabled, the chained event register (CER/CERH) bit is set on every
1473 * intermediate chained transfer completion (upon completion of every
1474 * intermediate TR in the PaRAM set, except the final TR in the PaRAM set).
1475 * The bit (position) set in CER or CERH is the TCC value specified.
1476 */
1477 EDMA3_DRV_ITCCHEN_EN = 1
1478 } EDMA3_DRV_ItcchEn;
1480 /**
1481 @}
1482 */
1484 /** @addtogroup EDMA3_LLD_DRV_DATASTRUCT
1485 @{ */
1487 /**
1488 * \brief Structure to be used to configure interrupt generation
1489 * and chaining options.
1490 */
1491 typedef struct
1492 {
1493 /** Transfer complete chaining enable */
1494 EDMA3_DRV_TcchEn tcchEn;
1496 /** Intermediate Transfer complete chaining enable */
1497 EDMA3_DRV_ItcchEn itcchEn;
1499 /** Transfer complete interrupt enable */
1500 EDMA3_DRV_TcintEn tcintEn;
1502 /** Intermediate Transfer complete interrupt enable */
1503 EDMA3_DRV_ItcintEn itcintEn;
1504 } EDMA3_DRV_ChainOptions;
1506 /**
1507 @}
1508 */
1510 /** @addtogroup EDMA3_LLD_DRV_FUNCTION_BASIC
1511 @{ */
1513 /**
1514 * \brief Set a particular OPT field in the PaRAM set associated with the
1515 * logical channel 'lCh'.
1516 *
1517 * This API can be used to set various optional parameters for an EDMA3
1518 * transfer. Like enable/disable completion interrupts, enable/disable chaining,
1519 * setting the transfer mode (A/AB Sync), setting the FIFO width etc.
1520 *
1521 * \param hEdma [IN] Handle to the EDMA Driver Instance.
1522 * \param lCh [IN] Logical Channel, bound to which
1523 * PaRAM set OPT field needs to be set.
1524 * \param optField [IN] The particular field of OPT Word
1525 * that needs setting
1526 * \param newOptFieldVal [IN] The new OPT field value
1527 *
1528 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
1529 *
1530 * \note This function is re-entrant for unique lCh values. It is non-
1531 * re-entrant for same lCh value.
1532 */
1533 EDMA3_DRV_Result EDMA3_DRV_setOptField (EDMA3_DRV_Handle hEdma,
1534 uint32_t lCh,
1535 EDMA3_DRV_OptField optField,
1536 uint32_t newOptFieldVal);
1538 /**
1539 * \brief Get a particular OPT field in the PaRAM set associated with the
1540 * logical channel 'lCh'.
1541 *
1542 * This API can be used to read various optional parameters for an EDMA3
1543 * transfer. Like enable/disable completion interrupts, enable/disable chaining,
1544 * setting the transfer mode (A/AB Sync), setting the FIFO width etc.
1545 *
1546 * \param hEdma [IN] Handle to the EDMA Driver Instance.
1547 * \param lCh [IN] Logical Channel, bound to which
1548 * PaRAM set OPT field is required.
1549 * \param optField [IN] The particular field of OPT Word
1550 * that is needed
1551 * \param optFieldVal [IN/OUT] Value of the OPT field
1552 *
1553 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
1554 *
1555 * \note This function is re-entrant.
1556 */
1557 EDMA3_DRV_Result EDMA3_DRV_getOptField (EDMA3_DRV_Handle hEdma,
1558 uint32_t lCh,
1559 EDMA3_DRV_OptField optField,
1560 uint32_t *optFieldVal);
1562 /**
1563 * \brief DMA source parameters setup
1564 *
1565 * It is used to program the source address, source side addressing mode
1566 * (INCR or FIFO) and the FIFO width in case the addressing mode is FIFO.
1567 *
1568 * In FIFO Addressing mode, memory location must be 32 bytes aligned.
1569 *
1570 * \param hEdma [IN] Handle to the EDMA Driver Instance
1571 * \param lCh [IN] Logical Channel for which the source parameters
1572 * are to be configured
1573 * \param srcAddr [IN] Source address
1574 * \param addrMode [IN] Address mode [FIFO or Increment]
1575 * \param fifoWidth [IN] Width of FIFO (Valid only if addrMode is FIFO)
1576 * -# 0 - 8 bit
1577 * -# 1 - 16 bit
1578 * -# 2 - 32 bit
1579 * -# 3 - 64 bit
1580 * -# 4 - 128 bit
1581 * -# 5 - 256 bit
1582 *
1583 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
1584 *
1585 * \note This function is re-entrant for unique lCh values. It is non-
1586 * re-entrant for same lCh value.
1587 */
1588 EDMA3_DRV_Result EDMA3_DRV_setSrcParams ( EDMA3_DRV_Handle hEdma,
1589 uint32_t lCh,
1590 uint32_t srcAddr,
1591 EDMA3_DRV_AddrMode addrMode,
1592 EDMA3_DRV_FifoWidth fifoWidth);
1594 /**
1595 * \brief DMA Destination parameters setup
1596 *
1597 * It is used to program the destination address, destination side addressing
1598 * mode (INCR or FIFO) and the FIFO width in case the addressing mode is FIFO.
1599 *
1600 * In FIFO Addressing mode, memory location must be 32 bytes aligned.
1601 *
1602 * \param hEdma [IN] Handle to the EDMA Driver Instance
1603 * \param lCh [IN] Logical Channel for which the destination
1604 * parameters are to be configured
1605 * \param destAddr [IN] Destination address
1606 * \param addrMode [IN] Address mode [FIFO or Increment]
1607 * \param fifoWidth [IN] Width of FIFO (Valid only if addrMode is FIFO)
1608 * -# 0 - 8 bit
1609 * -# 1 - 16 bit
1610 * -# 2 - 32 bit
1611 * -# 3 - 64 bit
1612 * -# 4 - 128 bit
1613 * -# 5 - 256 bit
1614 *
1615 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
1616 *
1617 * \note This function is re-entrant for unique lCh values. It is non-
1618 * re-entrant for same lCh value.
1619 */
1620 EDMA3_DRV_Result EDMA3_DRV_setDestParams ( EDMA3_DRV_Handle hEdma,
1621 uint32_t lCh,
1622 uint32_t destAddr,
1623 EDMA3_DRV_AddrMode addrMode,
1624 EDMA3_DRV_FifoWidth fifoWidth );
1626 /**
1627 * \brief DMA source index setup
1628 *
1629 * It is used to program the source B index and source C index.
1630 *
1631 * SRCBIDX is a 16-bit signed value (2s complement) used for source address
1632 * modification between each array in the 2nd dimension. Valid values for
1633 * SRCBIDX are between -32768 and 32767. It provides a byte address offset
1634 * from the beginning of the source array to the beginning of the next source
1635 * array. It applies to both A-synchronized and AB-synchronized transfers.
1636 *
1637 * SRCCIDX is a 16-bit signed value (2s complement) used for source address
1638 * modification in the 3rd dimension. Valid values for SRCCIDX are between
1639 * -32768 and 32767. It provides a byte address offset from the beginning of
1640 * the current array (pointed to by SRC address) to the beginning of the first
1641 * source array in the next frame. It applies to both A-synchronized and
1642 * AB-synchronized transfers. Note that when SRCCIDX is applied, the current
1643 * array in an A-synchronized transfer is the last array in the frame, while
1644 * the current array in an AB-synchronized transfer is the first array in the
1645 * frame.
1646 *
1647 * \param hEdma [IN] Handle to the EDMA Driver Instance
1648 * \param lCh [IN] Logical Channel for which source
1649 * indices are to be configured
1650 * \param srcBIdx [IN] Source B index
1651 * \param srcCIdx [IN] Source C index
1652 *
1653 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
1654 *
1655 * \note This function is re-entrant for unique lCh values. It is non-
1656 * re-entrant for same lCh value.
1657 */
1658 EDMA3_DRV_Result EDMA3_DRV_setSrcIndex ( EDMA3_DRV_Handle hEdma,
1659 uint32_t lCh,
1660 int32_t srcBIdx,
1661 int32_t srcCIdx );
1663 /**
1664 * \brief DMA destination index setup
1665 *
1666 * It is used to program the destination B index and destination C index.
1667 *
1668 * DSTBIDX is a 16-bit signed value (2s complement) used for destination
1669 * address modification between each array in the 2nd dimension. Valid values
1670 * for DSTBIDX are between -32768 and 32767. It provides a byte address offset
1671 * from the beginning of the destination array to the beginning of the next
1672 * destination array within the current frame. It applies to both
1673 * A-synchronized and AB-synchronized transfers.
1674 *
1675 * DSTCIDX is a 16-bit signed value (2s complement) used for destination address
1676 * modification in the 3rd dimension. Valid values are between -32768 and 32767.
1677 * It provides a byte address offset from the beginning of the current array
1678 * (pointed to by DST address) to the beginning of the first destination array
1679 * TR in the next frame. It applies to both A-synchronized and AB-synchronized
1680 * transfers. Note that when DSTCIDX is applied, the current array in an
1681 * A-synchronized transfer is the last array in the frame, while the current
1682 * array in a AB-synchronized transfer is the first array in the frame
1683 *
1684 * \param hEdma [IN] Handle to the EDMA Driver Instance
1685 * \param lCh [IN] Logical Channel for which dest
1686 * indices are to be configured
1687 * \param destBIdx [IN] Destination B index
1688 * \param destCIdx [IN] Destination C index
1689 *
1690 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
1691 *
1692 * \note This function is re-entrant for unique lCh values. It is non-
1693 * re-entrant for same lCh value.
1694 */
1695 EDMA3_DRV_Result EDMA3_DRV_setDestIndex (EDMA3_DRV_Handle hEdma,
1696 uint32_t lCh,
1697 int32_t destBIdx,
1698 int32_t destCIdx);
1700 /**
1701 * \brief DMA transfer parameters setup
1702 *
1703 * It is used to specify the various counts (ACNT, BCNT and CCNT), B count
1704 * reload and the synchronization type
1705 *
1706 * ACNT represents the number of bytes within the 1st dimension of a transfer.
1707 * ACNT is a 16-bit unsigned value with valid values between 0 and 65535.
1708 * Therefore, the maximum number of bytes in an array is 65535 bytes (64K - 1
1709 * bytes). ACNT must be greater than or equal to 1 for a TR to be submitted to
1710 * EDMA3 Transfer Controller.
1711 * An ACNT equal to 0 is considered either a null or dummy transfer. A dummy or
1712 * null transfer generates a completion code depending on the settings of the
1713 * completion bit fields in OPT.
1715 * BCNT is a 16-bit unsigned value that specifies the number of arrays of length
1716 * ACNT. For normal operation, valid values for BCNT are between 1 and 65535.
1717 * Therefore, the maximum number of arrays in a frame is 65535 (64K - 1 arrays).
1718 * A BCNT equal to 0 is considered either a null or dummy transfer. A dummy or
1719 * null transfer generates a completion code depending on the settings of the
1720 * completion bit fields in OPT.
1721 *
1722 * CCNT is a 16-bit unsigned value that specifies the number of frames in a
1723 * block. Valid values for CCNT are between 1 and 65535. Therefore, the maximum
1724 * number of frames in a block is 65535 (64K - 1 frames). A CCNT equal to 0 is
1725 * considered either a null or dummy transfer. A dummy or null transfer
1726 * generates a completion code depending on the settings of the completion bit
1727 * fields in OPT. A CCNT value of 0 is considered either a null or dummy
1728 * transfer.
1729 *
1730 * BCNTRLD is a 16-bit unsigned value used to reload the BCNT field once the
1731 * last array in the 2nd dimension is transferred. This field is only used for
1732 * A-synchronized transfers. In this case, the EDMA3CC decrements the BCNT
1733 * value by 1 on each TR submission. When BCNT (conceptually) reaches 0, the
1734 * EDMA3CC decrements CCNT and uses the BCNTRLD value to reinitialize the BCNT
1735 * value.
1736 * For AB-synchronized transfers, the EDMA3CC submits the BCNT in the TR and the
1737 * EDMA3TC decrements BCNT appropriately. For AB-synchronized transfers,
1738 * BCNTRLD is not used.
1740 * \param hEdma [IN] Handle to the EDMA Driver Instance
1741 * \param lCh [IN] Logical Channel for which transfer
1742 * parameters are to be configured
1743 * \param aCnt [IN] Count for 1st Dimension.
1744 * \param bCnt [IN] Count for 2nd Dimension.
1745 * \param cCnt [IN] Count for 3rd Dimension.
1746 * \param bCntReload [IN] Reload value for bCnt.
1747 * \param syncType [IN] Transfer synchronization dimension
1748 * 0: A-synchronized. Each event triggers
1749 * the transfer of a single array of
1750 * ACNT bytes.
1751 * 1: AB-synchronized. Each event triggers
1752 * the transfer of BCNT arrays of ACNT
1753 * bytes.
1754 *
1755 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
1756 *
1757 * \note This function is re-entrant for unique lCh values. It is non-
1758 * re-entrant for same lCh value.
1759 */
1760 EDMA3_DRV_Result EDMA3_DRV_setTransferParams (
1761 EDMA3_DRV_Handle hEdma,
1762 uint32_t lCh,
1763 uint32_t aCnt,
1764 uint32_t bCnt,
1765 uint32_t cCnt,
1766 uint32_t bCntReload,
1767 EDMA3_DRV_SyncType syncType);
1769 /**
1770 @}
1771 */
1773 /** @addtogroup EDMA3_LLD_DRV_FUNCTION_ADVANCED
1774 @{ */
1776 /**
1777 * \brief Chain the two specified channels.
1778 *
1779 * This API is used to chain a DMA channel to a previously allocated DMA/QDMA
1780 * channel.
1781 *
1782 * Chaining is different from Linking. The EDMA3 link feature reloads the
1783 * current channel parameter set with the linked parameter set. The EDMA3
1784 * chaining feature does not modify or update any channel parameter set;
1785 * it provides a synchronization event (or trigger) to the chained DMA channel,
1786 * as soon as the transfer (final or intermediate) completes on the main
1787 * DMA/QDMA channel.
1788 *
1789 * \param hEdma [IN] Handle to the EDMA Driver Instance.
1790 *
1791 * \param lCh1 [IN] DMA/QDMA channel to which a particular
1792 * DMA channel will be chained.
1793 * \param lCh2 [IN] DMA channel which needs to be chained to
1794 * the first DMA/QDMA channel.
1795 * \param chainOptions [IN] Options such as intermediate interrupts
1796 * are required or not, intermediate/final
1797 * chaining is enabled or not etc.
1798 *
1799 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
1800 *
1801 * \note This function is re-entrant for unique lCh1 & lCh2 values. It is
1802 * non-re-entrant for same lCh1 & lCh2 values.
1803 */
1804 EDMA3_DRV_Result EDMA3_DRV_chainChannel (EDMA3_DRV_Handle hEdma,
1805 uint32_t lCh1,
1806 uint32_t lCh2,
1807 const EDMA3_DRV_ChainOptions *chainOptions);
1809 /**
1810 * \brief Unchain the two channels.
1811 *
1812 * \param hEdma [IN] Handle to the EDMA Driver Instance.
1813 * \param lCh [IN] Channel whose chaining with the other
1814 * channel has to be removed.
1815 *
1816 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
1817 *
1818 * \note This function is re-entrant for unique lCh values. It is non-
1819 * re-entrant for same lCh value.
1820 */
1821 EDMA3_DRV_Result EDMA3_DRV_unchainChannel (EDMA3_DRV_Handle hEdma,
1822 uint32_t lCh);
1824 /**
1825 @}
1826 */
1828 /** @addtogroup EDMA3_LLD_DRV_SYMBOL_ENUM
1829 @{ */
1831 /**
1832 * \brief EDMA Trigger Mode Selection
1833 *
1834 * Use this enum to select the EDMA trigger mode while enabling
1835 * the EDMA transfer
1836 */
1837 typedef enum
1838 {
1839 /**
1840 * Set the Trigger mode to Manual .
1841 * The CPU manually triggers a transfer by writing a 1 to the
1842 * corresponding bit in the event set register (ESR/ESRH).
1843 */
1844 EDMA3_DRV_TRIG_MODE_MANUAL = 0,
1846 /**
1847 * Set the Trigger mode to QDMA.
1848 * A QDMA transfer is triggered when a CPU (or other EDMA3
1849 * programmer) writes to the trigger word of the
1850 * QDMA channel parameter set (autotriggered) or when the
1851 * EDMA3CC performs a link update on a PaRAM
1852 * set that has been mapped to a QDMA channel (link triggered).
1853 */
1854 EDMA3_DRV_TRIG_MODE_QDMA = 1,
1856 /**
1857 * Set the Trigger mode to Event.
1858 * Allows for a peripheral, system, or externally-generated
1859 * event to trigger a transfer request.
1860 */
1861 EDMA3_DRV_TRIG_MODE_EVENT = 2,
1863 /** Used to specify the trigger mode NONE */
1864 EDMA3_DRV_TRIG_MODE_NONE = 3
1865 } EDMA3_DRV_TrigMode;
1867 /**
1868 @}
1869 */
1871 /** @addtogroup EDMA3_LLD_DRV_FUNCTION_BASIC
1872 @{ */
1874 /**
1875 * \brief Version information
1876 *
1877 * The function is used to get the version information of the EDMA LLD.
1878 *
1879 * \return Version Information.
1880 */
1881 uint32_t EDMA3_DRV_getVersion (void);
1883 /**
1884 * \brief Version string querry
1885 *
1886 * The function is used to get the version string for the EDMA LLD.
1887 *
1888 * \return Version Information.
1889 */
1890 const char* EDMA3_DRV_getVersionStr (void);
1892 /**
1893 * \brief Start EDMA transfer on the specified channel.
1894 *
1895 * There are multiple ways to trigger an EDMA3 transfer. The triggering mode
1896 * option allows choosing from the available triggering modes: Event,
1897 * Manual or QDMA.
1898 *
1899 * In event triggered, a peripheral or an externally generated event triggers
1900 * the transfer. This API clears the Secondary Event Register and Event Miss
1901 * Register and then enables the DMA channel by writing to the EESR.
1902 *
1903 * In manual triggered mode, CPU manually triggers a transfer by writing a 1
1904 * in the Event Set Register (ESR/ESRH). This API writes to the ESR/ESRH to
1905 * start the transfer.
1906 *
1907 * In QDMA triggered mode, a QDMA transfer is triggered when a CPU (or other
1908 * EDMA3 programmer) writes to the trigger word of the QDMA channel PaRAM set
1909 * (auto-triggered) or when the EDMA3CC performs a link update on a PaRAM set
1910 * that has been mapped to a QDMA channel (link triggered). This API enables
1911 * the QDMA channel by writing to the QEESR register.
1912 *
1913 * \param hEdma [IN] Handle to the EDMA Driver Instance
1914 * \param lCh [IN] Channel on which transfer has to be started
1915 * \param trigMode [IN] Mode of triggering start of transfer (Manual,
1916 * QDMA or Event)
1917 *
1918 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
1919 *
1920 * \note This function is re-entrant for unique lCh values. It is non-
1921 * re-entrant for same lCh value.
1922 */
1923 EDMA3_DRV_Result EDMA3_DRV_enableTransfer (EDMA3_DRV_Handle hEdma,
1924 uint32_t lCh,
1925 EDMA3_DRV_TrigMode trigMode);
1927 /**
1928 * \brief Disable DMA transfer on the specified channel
1929 *
1930 * There are multiple ways by which an EDMA3 transfer could be triggered.
1931 * The triggering mode option allows choosing from the available triggering
1932 * modes: Event, Manual or QDMA.
1933 *
1934 * To disable a channel which was previously triggered in manual mode,
1935 * this API clears the Secondary Event Register and Event Miss Register,
1936 * if set, for the specific DMA channel.
1937 *
1938 * To disable a channel which was previously triggered in QDMA mode, this
1939 * API clears the QDMA Event Enable Register, for the specific QDMA channel.
1940 *
1941 * To disable a channel which was previously triggered in event mode, this API
1942 * clears the Event Enable Register. It also clears Event Register, Secondary
1943 * Event Register and Event Miss Register, if set, for the specific DMA channel.
1944 *
1945 * \param hEdma [IN] Handle to the EDMA Driver Instance
1946 * \param lCh [IN] Channel on which transfer has to be stopped
1947 * \param trigMode [IN] Mode of triggering start of transfer
1948 *
1949 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
1950 *
1951 * \note This function is re-entrant for unique lCh values. It is non-
1952 * re-entrant for same lCh value.
1953 */
1954 EDMA3_DRV_Result EDMA3_DRV_disableTransfer (EDMA3_DRV_Handle hEdma,
1955 uint32_t lCh,
1956 EDMA3_DRV_TrigMode trigMode);
1958 /**
1959 * \brief Disable the event driven DMA channel or QDMA channel
1960 *
1961 * This API disables the DMA channel (which was previously triggered in event
1962 * mode) by clearing the Event Enable Register; it disables the QDMA channel by
1963 * clearing the QDMA Event Enable Register.
1964 *
1965 * This API should NOT be used for DMA channels which are not mapped to any
1966 * hardware events and are used for memory-to-memory copy based transfers. In
1967 * case of that, this API returns error.
1968 *
1969 * \param hEdma [IN] Handle to the EDMA Driver Instance
1970 * \param lCh [IN] DMA/QDMA Channel which needs to be disabled
1971 * \param trigMode [IN] Mode of triggering start of transfer
1972 *
1973 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
1974 *
1975 * \note This function is re-entrant for unique lCh values. It is non-
1976 * re-entrant for same lCh value.
1977 */
1978 EDMA3_DRV_Result EDMA3_DRV_disableLogicalChannel (
1979 EDMA3_DRV_Handle hEdma,
1980 uint32_t lCh,
1981 EDMA3_DRV_TrigMode trigMode);
1983 /**
1984 @}
1985 */
1987 /** @addtogroup EDMA3_LLD_DRV_SYMBOL_ENUM
1988 @{ */
1990 /**
1991 * \brief PaRAM Set Entry type
1992 *
1993 * Use this enum to set or get any of the
1994 * 8 DWords(uint32_t) within a Parameter RAM set
1995 */
1996 typedef enum
1997 {
1998 /**
1999 * The OPT field (Offset Address 0x0 Bytes)
2000 */
2001 EDMA3_DRV_PARAM_ENTRY_OPT = 0,
2003 /**
2004 * The SRC field (Offset Address 0x4 Bytes)
2005 */
2006 EDMA3_DRV_PARAM_ENTRY_SRC = 1,
2008 /**
2009 * The (ACNT+BCNT) field (Offset Address 0x8 Bytes)
2010 */
2011 EDMA3_DRV_PARAM_ENTRY_ACNT_BCNT = 2,
2013 /**
2014 * The DST field (Offset Address 0xC Bytes)
2015 */
2016 EDMA3_DRV_PARAM_ENTRY_DST = 3,
2018 /**
2019 * The (SRCBIDX+DSTBIDX) field (Offset Address 0x10 Bytes)
2020 */
2021 EDMA3_DRV_PARAM_ENTRY_SRC_DST_BIDX = 4,
2023 /**
2024 * The (LINK+BCNTRLD) field (Offset Address 0x14 Bytes)
2025 */
2026 EDMA3_DRV_PARAM_ENTRY_LINK_BCNTRLD = 5,
2028 /**
2029 * The (SRCCIDX+DSTCIDX) field (Offset Address 0x18 Bytes)
2030 */
2031 EDMA3_DRV_PARAM_ENTRY_SRC_DST_CIDX = 6,
2033 /**
2034 * The (CCNT+RSVD) field (Offset Address 0x1C Bytes)
2035 */
2036 EDMA3_DRV_PARAM_ENTRY_CCNT = 7
2038 } EDMA3_DRV_PaRAMEntry;
2040 /**
2041 * \brief PaRAM Set Field type
2042 *
2043 * Use this enum to set or get any of the PaRAM set fields
2044 */
2045 typedef enum
2046 {
2047 /** OPT field of PaRAM Set */
2048 EDMA3_DRV_PARAM_FIELD_OPT = 0,
2050 /**
2051 * \brief Starting byte address of Source
2052 * For FIFO mode, srcAddr must be a 256-bit aligned address.
2053 */
2054 EDMA3_DRV_PARAM_FIELD_SRCADDR = 1,
2056 /**
2057 * \brief Number of bytes in each Array (ACNT)
2058 */
2059 EDMA3_DRV_PARAM_FIELD_ACNT = 2,
2061 /**
2062 * \brief Number of Arrays in each Frame (BCNT)
2063 */
2064 EDMA3_DRV_PARAM_FIELD_BCNT = 3,
2066 /**
2067 * \brief Starting byte address of destination
2068 * For FIFO mode, destAddr must be a 256-bit aligned address.
2069 */
2070 EDMA3_DRV_PARAM_FIELD_DESTADDR = 4,
2072 /**
2073 * \brief Index between consec. arrays of a Source Frame (SRCBIDX)
2074 * If SAM is set to 1 (via channelOptions) then srcInterArrIndex should
2075 * be an even multiple of 32 bytes.
2076 */
2077 EDMA3_DRV_PARAM_FIELD_SRCBIDX = 5,
2079 /**
2080 * \brief Index between consec. arrays of a Destination Frame (DSTBIDX)
2081 * If DAM is set to 1 (via channelOptions) then destInterArrIndex should
2082 * be an even multiple of 32 bytes
2083 */
2084 EDMA3_DRV_PARAM_FIELD_DESTBIDX = 6,
2086 /**
2087 * \brief Address for linking (AutoReloading of a PaRAM Set)
2088 * This must point to a valid aligned 32-byte PaRAM set
2089 * A value of 0xFFFF means no linking
2090 * Linking is especially useful for use with ping-pong buffers and
2091 * circular buffers
2092 */
2093 EDMA3_DRV_PARAM_FIELD_LINKADDR = 7,
2095 /**
2096 * \brief Reload value of the numArrInFrame (BCNT)
2097 * Relevant only for A-sync transfers
2098 */
2099 EDMA3_DRV_PARAM_FIELD_BCNTRELOAD = 8,
2101 /**
2102 * \brief Index between consecutive frames of a Source Block (SRCCIDX)
2103 */
2104 EDMA3_DRV_PARAM_FIELD_SRCCIDX = 9,
2106 /**
2107 * \brief Index between consecutive frames of a Dest Block (DSTCIDX)
2108 */
2109 EDMA3_DRV_PARAM_FIELD_DESTCIDX = 10,
2111 /**
2112 * \brief Number of Frames in a block (CCNT)
2113 */
2114 EDMA3_DRV_PARAM_FIELD_CCNT = 11
2116 } EDMA3_DRV_PaRAMField;
2118 /**
2119 @}
2120 */
2122 /** @addtogroup EDMA3_LLD_DRV_DATASTRUCT
2123 @{ */
2125 /**
2126 * \brief EDMA3 PaRAM Set
2127 *
2128 * This is a mapping of the EDMA3 PaRAM set provided to the user
2129 * for ease of modification of the individual PaRAM words.
2130 */
2131 typedef struct {
2132 /** OPT field of PaRAM Set */
2133 volatile uint32_t OPT;
2135 /**
2136 * \brief Starting byte address of Source
2137 * For FIFO mode, srcAddr must be a 256-bit aligned address.
2138 */
2139 volatile uint32_t SRC;
2141 /**
2142 * Number of bytes in each Array (ACNT) (16 bits) and
2143 * Number of Arrays in each Frame (BCNT) (16 bits).
2144 */
2145 volatile uint32_t A_B_CNT;
2147 /**
2148 * \brief Starting byte address of destination
2149 * For FIFO mode, destAddr must be a 256-bit aligned address.
2150 * i.e. 5 LSBs should be 0.
2151 */
2152 volatile uint32_t DST;
2154 /**
2155 * Index between consec. arrays of a Source Frame (SRCBIDX) (16 bits) and
2156 * Index between consec. arrays of a Destination Frame (DSTBIDX) (16 bits).
2157 *
2158 * If SAM is set to 1 (via channelOptions) then srcInterArrIndex should
2159 * be an even multiple of 32 bytes.
2160 *
2161 * If DAM is set to 1 (via channelOptions) then destInterArrIndex should
2162 * be an even multiple of 32 bytes
2163 */
2164 volatile uint32_t SRC_DST_BIDX;
2166 /**
2167 * \brief Address for linking (AutoReloading of a PaRAM Set) (16 bits)
2168 * and Reload value of the numArrInFrame (BCNT) (16 bits).
2169 *
2170 * Link field must point to a valid aligned 32-byte PaRAM set
2171 * A value of 0xFFFF means no linking.
2172 *
2173 * B count reload field is relevant only for A-sync transfers.
2174 */
2175 volatile uint32_t LINK_BCNTRLD;
2177 /**
2178 * \brief Index between consecutive frames of a Source Block (SRCCIDX)
2179 * (16 bits) and Index between consecutive frames of a Dest Block
2180 * (DSTCIDX) (16 bits).
2181 */
2182 volatile uint32_t SRC_DST_CIDX;
2184 /**
2185 * \brief Number of Frames in a block (CCNT) (16 bits).
2186 */
2187 volatile uint32_t CCNT;
2189 } EDMA3_DRV_ParamentryRegs;
2191 /**
2192 * \brief EDMA3 Parameter RAM Set in User Configurable format
2193 *
2194 * This is a mapping of the EDMA3 PaRAM set provided to the user
2195 * for ease of modification of the individual fields
2196 */
2197 #ifndef _BIG_ENDIAN
2198 /* LITTLE_ENDIAN_MODE */
2199 typedef struct {
2200 /** OPT field of PaRAM Set */
2201 volatile uint32_t opt;
2203 /**
2204 * \brief Starting byte address of Source
2205 * For FIFO mode, srcAddr must be a 256-bit aligned address.
2206 */
2207 volatile uint32_t srcAddr;
2209 /**
2210 * \brief Number of bytes in each Array (ACNT)
2211 */
2212 volatile uint16_t aCnt;
2214 /**
2215 * \brief Number of Arrays in each Frame (BCNT)
2216 */
2217 volatile uint16_t bCnt;
2219 /**
2220 * \brief Starting byte address of destination
2221 * For FIFO mode, destAddr must be a 256-bit aligned address.
2222 * i.e. 5 LSBs should be 0.
2223 */
2224 volatile uint32_t destAddr;
2226 /**
2227 * \brief Index between consec. arrays of a Source Frame (SRCBIDX)
2228 * If SAM is set to 1 (via channelOptions) then srcInterArrIndex should
2229 * be an even multiple of 32 bytes.
2230 */
2231 volatile int16_t srcBIdx;
2233 /**
2234 * \brief Index between consec. arrays of a Destination Frame (DSTBIDX)
2235 * If DAM is set to 1 (via channelOptions) then destInterArrIndex should
2236 * be an even multiple of 32 bytes
2237 */
2238 volatile int16_t destBIdx;
2240 /**
2241 * \brief Address for linking (AutoReloading of a PaRAM Set)
2242 * This must point to a valid aligned 32-byte PaRAM set
2243 * A value of 0xFFFF means no linking
2244 * Linking is especially useful for use with ping-pong buffers and
2245 * circular buffers
2246 */
2247 volatile uint16_t linkAddr;
2249 /**
2250 * \brief Reload value of the numArrInFrame (BCNT)
2251 * Relevant only for A-sync transfers
2252 */
2253 volatile uint16_t bCntReload;
2255 /**
2256 * \brief Index between consecutive frames of a Source Block (SRCCIDX)
2257 */
2258 volatile int16_t srcCIdx;
2260 /**
2261 * \brief Index between consecutive frames of a Dest Block (DSTCIDX)
2262 */
2263 volatile int16_t destCIdx;
2265 /**
2266 * \brief Number of Frames in a block (CCNT)
2267 */
2268 volatile uint16_t cCnt;
2270 /**
2271 * \brief Reserved
2272 */
2273 volatile int16_t reserved;
2274 } EDMA3_DRV_PaRAMRegs;
2275 #else
2276 /* BIG_ENDIAN_MODE */
2277 typedef struct {
2278 /** OPT field of PaRAM Set */
2279 volatile uint32_t opt;
2281 /**
2282 * \brief Starting byte address of Source
2283 * For FIFO mode, srcAddr must be a 256-bit aligned address.
2284 */
2285 volatile uint32_t srcAddr;
2287 /**
2288 * \brief Number of Arrays in each Frame (BCNT)
2289 */
2290 volatile uint16_t bCnt;
2292 /**
2293 * \brief Number of bytes in each Array (ACNT)
2294 */
2295 volatile uint16_t aCnt;
2297 /**
2298 * \brief Starting byte address of destination
2299 * For FIFO mode, destAddr must be a 256-bit aligned address.
2300 * i.e. 5 LSBs should be 0.
2301 */
2302 volatile uint32_t destAddr;
2304 /**
2305 * \brief Index between consec. arrays of a Destination Frame (DSTBIDX)
2306 * If DAM is set to 1 (via channelOptions) then destInterArrIndex should
2307 * be an even multiple of 32 bytes
2308 */
2309 volatile int16_t destBIdx;
2311 /**
2312 * \brief Index between consec. arrays of a Source Frame (SRCBIDX)
2313 * If SAM is set to 1 (via channelOptions) then srcInterArrIndex should
2314 * be an even multiple of 32 bytes.
2315 */
2316 volatile int16_t srcBIdx;
2318 /**
2319 * \brief Reload value of the numArrInFrame (BCNT)
2320 * Relevant only for A-sync transfers
2321 */
2322 volatile uint16_t bCntReload;
2324 /**
2325 * \brief Address for linking (AutoReloading of a PaRAM Set)
2326 * This must point to a valid aligned 32-byte PaRAM set
2327 * A value of 0xFFFF means no linking
2328 * Linking is especially useful for use with ping-pong buffers and
2329 * circular buffers
2330 */
2331 volatile uint16_t linkAddr;
2333 /**
2334 * \brief Index between consecutive frames of a Dest Block (DSTCIDX)
2335 */
2336 volatile int16_t destCIdx;
2338 /**
2339 * \brief Index between consecutive frames of a Source Block (SRCCIDX)
2340 */
2341 volatile int16_t srcCIdx;
2343 /**
2344 * \brief Reserved
2345 */
2346 volatile int16_t reserved;
2348 /**
2349 * \brief Number of Frames in a block (CCNT)
2350 */
2351 volatile uint16_t cCnt;
2352 } EDMA3_DRV_PaRAMRegs;
2353 #endif /* #ifndef _BIG_ENDIAN */
2355 /**
2356 * \brief Event queue priorities setup
2357 *
2358 * It allows to change the priority of the individual queues and the
2359 * priority of the transfer request (TR) associated with the
2360 * events queued in the queue.
2361 */
2362 typedef struct
2363 {
2364 /**
2365 * \brief Event Queue Priorities
2366 */
2367 uint32_t evtQPri[EDMA3_MAX_EVT_QUE];
2368 }EDMA3_DRV_EvtQuePriority;
2370 /**
2371 @}
2372 */
2374 /** @addtogroup EDMA3_LLD_DRV_FUNCTION_ADVANCED
2375 @{ */
2377 /**
2378 * \brief Assign a Trigger Word to the specified QDMA channel
2379 *
2380 * This API sets the Trigger word for the specific QDMA channel in the QCHMAP
2381 * Register. Default QDMA trigger word is CCNT.
2382 *
2383 * \param hEdma [IN] Handle to the EDMA Instance object
2384 * \param lCh [IN] QDMA Channel which needs to be assigned
2385 * the Trigger Word
2386 * \param trigWord [IN] The Trigger Word for the QDMA channel.
2387 * Trigger Word is the word in the PaRAM
2388 * Register Set which, when written to by CPU,
2389 * will start the QDMA transfer automatically.
2390 *
2391 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2392 *
2393 * \note This function is re-entrant for unique lCh values. It is non-
2394 * re-entrant for same lCh value.
2395 */
2396 EDMA3_DRV_Result EDMA3_DRV_setQdmaTrigWord (EDMA3_DRV_Handle hEdma,
2397 uint32_t lCh,
2398 EDMA3_RM_QdmaTrigWord trigWord);
2400 /**
2401 * \brief Copy the user specified PaRAM Set onto the PaRAM Set
2402 * associated with the logical channel (DMA/QDMA/Link).
2403 *
2404 * This API takes a PaRAM Set as input and copies it onto the actual PaRAM Set
2405 * associated with the logical channel. OPT field of the PaRAM Set is written
2406 * first and the CCNT field is written last.
2407 *
2408 * Caution: It should be used carefully when programming the QDMA channels whose
2409 * trigger words are not CCNT field.
2410 *
2411 * \param hEdma [IN] Handle to the EDMA Instance object
2412 * \param lCh [IN] Logical Channel for which new PaRAM set is
2413 * specified
2414 * \param newPaRAM [IN] Parameter RAM set to be copied onto existing PaRAM
2415 *
2416 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2417 *
2418 * \note This function is re-entrant for unique lCh values. It is non-
2419 * re-entrant for same lCh value.
2420 */
2421 EDMA3_DRV_Result EDMA3_DRV_setPaRAM ( EDMA3_DRV_Handle hEdma,
2422 uint32_t lCh,
2423 const EDMA3_DRV_PaRAMRegs *newPaRAM);
2425 /**
2426 * \brief Retrieve existing PaRAM set associated with specified logical
2427 * channel (DMA/QDMA/Link).
2428 *
2429 * \param hEdma [IN] Handle to the EDMA Instance object
2430 * \param lCh [IN] Logical Channel whose PaRAM set is
2431 * requested
2432 * \param currPaRAM [IN/OUT] User gets the existing PaRAM here
2433 *
2434 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2435 *
2436 * \note This function is re-entrant.
2437 */
2438 EDMA3_DRV_Result EDMA3_DRV_getPaRAM (EDMA3_DRV_Handle hEdma,
2439 uint32_t lCh,
2440 EDMA3_DRV_PaRAMRegs *currPaRAM);
2442 /**
2443 * \brief Set a particular PaRAM set entry of the specified PaRAM set
2444 *
2445 *
2446 * \param hEdma [IN] Handle to the EDMA Driver Instance
2447 * \param lCh [IN] Logical Channel bound to the Parameter RAM set
2448 * whose specified field needs to be set
2449 * \param paRAMEntry [IN] Specify the PaRAM set entry which needs
2450 * to be set
2451 * \param newPaRAMEntryVal [IN] The new field setting
2452 *
2453 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2454 *
2455 * \note This API should be used while setting the PaRAM set entry
2456 * for QDMA channels. If EDMA3_DRV_setPaRAMField () used,
2457 * it will trigger the QDMA channel before complete
2458 * PaRAM set entry is written. For DMA channels, no such
2459 * constraint is there.
2460 *
2461 * This function is re-entrant for unique lCh values. It is non-
2462 * re-entrant for same lCh value.
2463 */
2464 EDMA3_DRV_Result EDMA3_DRV_setPaRAMEntry (EDMA3_DRV_Handle hEdma,
2465 uint32_t lCh,
2466 EDMA3_DRV_PaRAMEntry paRAMEntry,
2467 uint32_t newPaRAMEntryVal);
2469 /**
2470 * \brief Get a particular PaRAM set entry of the specified PaRAM set
2471 *
2472 *
2473 * \param hEdma [IN] Handle to the EDMA Driver Instance
2474 * \param lCh [IN] Logical Channel bound to the Parameter RAM set
2475 * whose specified field value is needed
2476 * \param paRAMEntry [IN] Specify the PaRAM set entry which needs
2477 * to be obtained
2478 * \param paRAMEntryVal [IN/OUT] The value of the field is returned here
2479 *
2480 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2481 *
2482 * \note This function is re-entrant.
2483 */
2484 EDMA3_DRV_Result EDMA3_DRV_getPaRAMEntry (EDMA3_DRV_Handle hEdma,
2485 uint32_t lCh,
2486 EDMA3_DRV_PaRAMEntry paRAMEntry,
2487 uint32_t *paRAMEntryVal);
2489 /**
2490 * \brief Set a particular PaRAM set field of the specified PaRAM set
2491 *
2492 *
2493 * \param hEdma [IN] Handle to the EDMA Driver Instance
2494 * \param lCh [IN] Logical Channel bound to the PaRAM set
2495 * whose specified field needs to be set
2496 * \param paRAMField [IN] Specify the PaRAM set field which needs
2497 * to be set
2498 * \param newPaRAMFieldVal [IN] The new field setting
2499 *
2500 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2501 *
2502 * \note This API CANNOT be used while setting the PaRAM set
2503 * field for QDMA channels. It can trigger the QDMA channel before
2504 * complete PaRAM set ENTRY (4-bytes field) is written (for eg, as
2505 * soon one sets the ACNT field for QDMA channel, transfer is started,
2506 * before one modifies the BCNT field). For DMA channels, no such
2507 * constraint is there.
2508 *
2509 * This function is re-entrant for unique lCh values. It is non-
2510 * re-entrant for same lCh value.
2511 */
2512 EDMA3_DRV_Result EDMA3_DRV_setPaRAMField (EDMA3_DRV_Handle hEdma,
2513 uint32_t lCh,
2514 EDMA3_DRV_PaRAMField paRAMField,
2515 uint32_t newPaRAMFieldVal);
2517 /**
2518 * \brief Get a particular PaRAM set field of the specified PaRAM set
2519 *
2520 *
2521 * \param hEdma [IN] Handle to the EDMA Driver Instance
2522 * \param lCh [IN] Logical Channel bound to the PaRAM set
2523 * whose specified field value is needed
2524 * \param paRAMField [IN] Specify the PaRAM set field which needs
2525 * to be obtained
2526 * \param currPaRAMFieldVal [IN/OUT] The value of the field is returned here
2527 *
2528 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2529 *
2530 * \note This function is re-entrant.
2531 */
2532 EDMA3_DRV_Result EDMA3_DRV_getPaRAMField (EDMA3_DRV_Handle hEdma,
2533 uint32_t lCh,
2534 EDMA3_DRV_PaRAMField paRAMField,
2535 uint32_t *currPaRAMFieldVal);
2537 /**
2538 * \brief Sets EDMA TC priority
2539 *
2540 * User can program the priority of the Event Queues at a system-wide level.
2541 * This means that the user can set the priority of an IO initiated by either
2542 * of the TCs (Transfer Ctrllers) relative to IO initiated by the other bus
2543 * masters on the device (ARM, DSP, USB, etc)
2544 *
2545 * \param hEdma [IN] Handle to the EDMA Driver Instance
2546 * \param evtQPriObj [IN] Priority of the Event Queues
2547 *
2548 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2549 *
2550 * \note This function disables the global interrupts while modifying
2551 * the global CC Registers, to make it re-entrant.
2552 */
2553 EDMA3_DRV_Result EDMA3_DRV_setEvtQPriority (EDMA3_DRV_Handle hEdma,
2554 const EDMA3_DRV_EvtQuePriority *evtQPriObj);
2556 /**
2557 * \brief Associate Channel to Event Queue
2558 *
2559 *
2560 * \param hEdma [IN] Handle to the EDMA Driver Instance
2561 * \param channelId [IN] Logical Channel to which the Event
2562 * Queue is to be mapped
2563 * \param eventQ [IN] The Event Queue which is to be mapped
2564 * to the DMA channel
2565 *
2566 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2567 *
2568 * \note There should not be any data transfer going on
2569 * while setting the mapping. Results could be unpredictable.
2570 *
2571 * This function disables the global interrupts while modifying
2572 * the global CC Registers, to make it re-entrant.
2573 */
2574 EDMA3_DRV_Result EDMA3_DRV_mapChToEvtQ (EDMA3_DRV_Handle hEdma,
2575 uint32_t channelId,
2576 EDMA3_RM_EventQueue eventQ);
2578 /**
2579 * \brief Get the Event Queue mapped to the specified DMA/QDMA channel.
2580 *
2581 * \param hEdma [IN] Handle to the EDMA Driver Instance
2582 * \param channelId [IN] Logical Channel whose associated
2583 * Event Queue is needed
2584 * \param mappedEvtQ [IN/OUT] The Event Queue which is mapped
2585 * to the DMA/QDMA channel
2586 *
2587 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2588 *
2589 * \note This function is re-entrant.
2590 */
2591 EDMA3_DRV_Result EDMA3_DRV_getMapChToEvtQ (EDMA3_DRV_Handle hEdma,
2592 uint32_t channelId,
2593 uint32_t *mappedEvtQ);
2595 /**
2596 * \brief Set the Channel Controller (CC) Register value
2597 *
2598 * \param hEdma [IN] Handle to the EDMA Driver Instance
2599 * \param regOffset [IN] CC Register offset whose value needs to be set
2600 * \param newRegValue [IN] New CC Register Value
2601 *
2602 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2603 *
2604 * \note This function is non re-entrant for users using the same
2605 * EDMA handle i.e. working on the same shadow region.
2606 * Before modifying a register, it tries to acquire a semaphore
2607 * (Driver instance specific), to protect simultaneous
2608 * modification of the same register by two different users.
2609 * After the successful change, it releases the semaphore.
2610 * For users working on different shadow regions, thus different
2611 * EDMA handles, this function is re-entrant.
2612 */
2613 EDMA3_DRV_Result EDMA3_DRV_setCCRegister (EDMA3_DRV_Handle hEdma,
2614 uint32_t regOffset,
2615 uint32_t newRegValue);
2617 /**
2618 * \brief Get the Channel Controller (CC) Register value
2619 *
2620 * \param hEdma [IN] Handle to the EDMA Driver Instance
2621 * \param regOffset [IN] CC Register offset whose value is needed
2622 * \param regValue [IN/OUT] CC Register Value
2623 *
2624 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2625 *
2626 * \note This function is re-entrant.
2627 */
2628 EDMA3_DRV_Result EDMA3_DRV_getCCRegister (EDMA3_DRV_Handle hEdma,
2629 uint32_t regOffset,
2630 uint32_t *regValue);
2632 /**
2633 * \brief Wait for a transfer completion interrupt to occur and clear it.
2634 *
2635 * This is a blocking function that returns when the IPR/IPRH bit corresponding
2636 * to the tccNo specified, is SET. It clears the corresponding bit while
2637 * returning also.
2638 *
2639 * This function waits for the specific bit indefinitely in a tight loop, with
2640 * out any delay in between. USE IT CAUTIOUSLY.
2641 *
2642 * \param hEdma [IN] Handle to the EDMA Driver Instance
2643 * \param tccNo [IN] TCC, specific to which the function
2644 * waits on a IPR/IPRH bit.
2645 *
2646 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2647 *
2648 * \note This function is re-entrant for different tccNo.
2649 */
2650 EDMA3_DRV_Result EDMA3_DRV_waitAndClearTcc (EDMA3_DRV_Handle hEdma,
2651 uint32_t tccNo);
2653 /**
2654 * \brief Returns the status of a previously initiated transfer.
2655 *
2656 * This is a non-blocking function that returns the status of a previously
2657 * initiated transfer, based on the IPR/IPRH bit. This bit corresponds to
2658 * the tccNo specified by the user. It clears the corresponding bit, if SET,
2659 * while returning also.
2660 *
2661 * \param hEdma [IN] Handle to the EDMA Driver Instance
2662 * \param tccNo [IN] TCC, specific to which the function
2663 * checks the status of the IPR/IPRH bit.
2664 * \param tccStatus [IN/OUT] Status of the transfer is returned here.
2665 * Returns "TRUE" if the transfer has
2666 * completed (IPR/IPRH bit SET),
2667 * "FALSE" if the transfer has not completed
2668 * successfully (IPR/IPRH bit NOT SET).
2669 *
2670 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2671 *
2672 * \note This function is re-entrant for different tccNo.
2673 */
2674 EDMA3_DRV_Result EDMA3_DRV_checkAndClearTcc (EDMA3_DRV_Handle hEdma,
2675 uint32_t tccNo,
2676 uint16_t *tccStatus);
2678 /**
2679 * \brief Get the PaRAM Set Physical Address associated with a logical channel
2680 *
2681 * This function returns the PaRAM Set Phy Address (unsigned 32 bits).
2682 * The returned address could be used by the advanced users to program the
2683 * PaRAM Set directly without using any APIs.
2684 *
2685 * Least significant 16 bits of this address could be used to program
2686 * the LINK field in the PaRAM Set.
2687 * Users which program the LINK field directly SHOULD use this API
2688 * to get the associated PaRAM Set address with the LINK channel.
2689 *
2690 *
2691 * \param hEdma [IN] Handle to the EDMA Driver Instance
2692 * \param lCh [IN] Logical Channel for which the PaRAM set
2693 * physical address is required
2694 * \param paramPhyAddr [IN/OUT] PaRAM Set physical address is returned
2695 * here.
2696 *
2697 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2698 *
2699 * \note This function is re-entrant.
2700 */
2701 EDMA3_DRV_Result EDMA3_DRV_getPaRAMPhyAddr(EDMA3_DRV_Handle hEdma,
2702 uint32_t lCh,
2703 uint32_t *paramPhyAddr);
2705 /**
2706 @}
2707 */
2709 /** @addtogroup EDMA3_LLD_DRV_SYMBOL_ENUM
2710 @{ */
2712 /**\enum EDMA3_DRV_IoctlCmd
2713 * \brief EDMA3 Driver IOCTL commands
2714 */
2715 typedef enum
2716 {
2717 /* Min IOCTL */
2718 EDMA3_DRV_IOCTL_MIN_IOCTL = 0,
2720 /**
2721 * PaRAM Sets will be cleared OR will not be cleared
2722 * during allocation, depending upon this option.
2723 *
2724 * For e.g.,
2725 * To clear the PaRAM Sets during allocation,
2726 * cmdArg = (void *)1;
2727 *
2728 * To NOT clear the PaRAM Sets during allocation,
2729 * cmdArg = (void *)0;
2730 *
2731 * For all other values, it will return error.
2732 *
2733 * By default, PaRAM Sets will be cleared during allocation.
2734 * Note: Since this enum can change the behavior how the resources are
2735 * initialized during their allocation, user is adviced to not use this
2736 * command while allocating the resources. User should first change the
2737 * behavior of resources' initialization and then should use start
2738 * allocating resources.
2739 */
2740 EDMA3_DRV_IOCTL_SET_PARAM_CLEAR_OPTION,
2742 /**
2743 * To check whether PaRAM Sets will be cleared or not
2744 * during allocation.
2745 * If the value read is '1', it means that PaRAM Sets are getting cleared
2746 * during allocation.
2747 * If the value read is '0', it means that PaRAM Sets are NOT getting cleared
2748 * during allocation.
2749 * For e.g.,
2750 * uint16_t isParamClearingDone;
2751 * cmdArg = ¶mClearingRequired;
2752 */
2753 EDMA3_DRV_IOCTL_GET_PARAM_CLEAR_OPTION,
2755 /* Max IOCTLs */
2756 EDMA3_DRV_IOCTL_MAX_IOCTL
2757 } EDMA3_DRV_IoctlCmd;
2759 /**
2760 @}
2761 */
2763 /** @addtogroup EDMA3_LLD_DRV_FUNCTION_ADVANCED
2764 @{ */
2766 /**
2767 * \brief EDMA3 Driver IOCTL
2768 *
2769 * This function provides IOCTL functionality for EDMA3 Driver.
2770 *
2771 * \param hEdma [IN] Handle to the EDMA Driver Instance
2772 * \param cmd [IN] IOCTL command to be performed
2773 * \param cmdArg [IN/OUT] IOCTL command argument (if any)
2774 * \param param [IN/OUT] Device/Cmd specific argument
2775 *
2776 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2777 *
2778 * \note For 'EDMA3_DRV_IOCTL_GET_PARAM_CLEAR_OPTION', this function is re-entrant.
2779 * For 'EDMA3_DRV_IOCTL_SET_PARAM_CLEAR_OPTION', this function is re-entrant for
2780 * different EDMA3 Driver Instances (handles).
2781 */
2782 EDMA3_DRV_Result EDMA3_DRV_Ioctl(
2783 EDMA3_DRV_Handle hEdma,
2784 EDMA3_DRV_IoctlCmd cmd,
2785 void *cmdArg,
2786 void *param
2787 );
2789 /**
2790 * \brief Return the previously opened EDMA3 Driver Instance handle
2791 *
2792 * This API is used to return the previously opened EDMA3 Driver's
2793 * Instance Handle (region specific), which could be used to call other
2794 * EDMA3 Driver APIs. Since EDMA3 Driver does not allow multiple instances,
2795 * for a single shadow region, this API is provided. This API is meant
2796 * for users who DO NOT want to / could not open a new Driver Instance and
2797 * hence re-use the existing Driver Instance to allocate EDMA3 resources
2798 * and use various other EDMA3 Driver APIs.
2799 *
2800 * In case the Driver Instance is not yet opened, NULL is returned as the
2801 * function return value whereas EDMA3_DRV_E_INST_NOT_OPENED is returned
2802 * in the errorCode.
2803 *
2804 * \param phyCtrllerInstId [IN] EDMA3 Controller Instance Id (Hardware
2805 * instance id, starting from 0).
2806 * \param regionId [IN] Shadow Region id for which the previously
2807 * opened driver's instance handle is
2808 * required.
2809 * \param errorCode [OUT] Error code while returning Driver Instance
2810 * Handle.
2811 *
2812 * \return EDMA3_DRV_Handle : If successful, this API will return the
2813 * driver's instance handle.
2814 *
2815 * \note 1) This API returns the previously opened EDMA3 Driver's Instance
2816 * handle. The instance, if exists, could have been opened by some other
2817 * user (most probably) or may be by the same user calling this API. If
2818 * it was opened by some other user, then that user can very well close
2819 * this instance anytime, without even knowing that the same instance
2820 * handle is being used by other users as well. In that case, the
2821 * handle becomes INVALID and user has to open a valid driver
2822 * instance for his/her use.
2823 *
2824 * 2) This function is re-entrant.
2825 */
2826 EDMA3_DRV_Handle EDMA3_DRV_getInstHandle(uint32_t phyCtrllerInstId,
2827 EDMA3_RM_RegionId regionId,
2828 EDMA3_DRV_Result *errorCode);
2830 /**
2831 * \brief Registers a transfer completion handler for a specific DMA/QDMA
2832 * channel
2833 *
2834 * This function registers a non-NULL callback function for a specific DMA or QDMA
2835 * channel and enables the completion interrupt for the TCC associated with
2836 * the underlying channel in the IER/IERH register. It also sets the DRAE/DRAEH
2837 * register for the TCC associated with the specified DMA/QDMA channel. If user
2838 * enables the transfer completion interrupts (intermediate or final) in the OPT
2839 * field of the associated PaRAM Set, the registered callback function will be
2840 * called by the EDMA3 Resource Manager.
2841 *
2842 * If a call-back function is already registered for the channel, the API fails
2843 * with the error code EDMA3_RM_E_CALLBACK_ALREADY_REGISTERED.
2844 *
2845 * \param hEdma [IN] Handle to the EDMA Driver Instance.
2846 * \param channelId [IN] DMA/QDMA channel for which the callback
2847 * function needs to be registered.
2848 * \param tccCb [IN] The callback function to be registered.
2849 * \param cbData [IN] Callback data to be passed while calling
2850 * the callback function.
2851 *
2852 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2853 *
2854 * \note This function is re-entrant for unique channelId values. It is non-
2855 * re-entrant for same channelId value.
2856 */
2857 EDMA3_DRV_Result EDMA3_DRV_registerTccCb(EDMA3_DRV_Handle hEdma,
2858 const uint32_t channelId,
2859 EDMA3_RM_TccCallback tccCb,
2860 void *cbData);
2862 /**
2863 * \brief Un-register the previously registered callback function against a
2864 * DMA/QDMA channel.
2865 *
2866 * This function un-registers the previously registered callback function for
2867 * the DMA/QDMA channel by removing any stored callback function. Moreover, it
2868 * clears the:
2869 * Interrupt Enable Register (IER/IERH) by writing to the IECR/IECRH
2870 * register, for the TCC associated with that particular channel,
2871 * DRA/DRAEH register for the TCC associated with the specified DMA/QDMA
2872 * channel
2873 *
2874 * \param hEdma [IN] Handle to the EDMA Driver Instance.
2875 * \param channelId [IN] DMA/QDMA channel for which the callback
2876 * function needs to be un-registered.
2877 *
2878 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
2879 *
2880 * \note This function is re-entrant for unique channelId. It is
2881 * non-re-entrant for same channelId.
2882 */
2883 EDMA3_DRV_Result EDMA3_DRV_unregisterTccCb(EDMA3_DRV_Handle hEdma,
2884 const uint32_t channelId);
2886 /**
2887 @}
2888 */
2890 /** @addtogroup EDMA3_LLD_DRV_SYMBOL_ENUM
2891 @{ */
2893 /**\enum EDMA3_DRV_Tc_Err
2894 * \brief TC Error Enablers
2895 *
2896 * Use this enum to enable/disable the specific EDMA3 Transfer Controller
2897 * Interrupts.
2898 */
2899 typedef enum
2900 {
2901 /**
2902 * Interrupt disable for bus error
2903 */
2904 EDMA3_DRV_TC_ERR_BUSERR_DIS = 0,
2906 /**
2907 * Interrupt enable for bus error
2908 */
2909 EDMA3_DRV_TC_ERR_BUSERR_EN,
2911 /**
2912 * Interrupt disable for transfer request error
2913 */
2914 EDMA3_DRV_TC_ERR_TRERR_DIS,
2916 /**
2917 * Interrupt enable for transfer request error
2918 */
2919 EDMA3_DRV_TC_ERR_TRERR_EN,
2921 /**
2922 * Interrupt disable for MMR address error
2923 */
2924 EDMA3_DRV_TC_ERR_MMRAERR_DIS,
2926 /**
2927 * Interrupt enable for MMR address error
2928 */
2929 EDMA3_DRV_TC_ERR_MMRAERR_EN,
2931 /**
2932 * Disable all TC error interrupts
2933 */
2934 EDMA3_DRV_TC_ERR_DIS,
2936 /**
2937 * Enable all TC error interrupts
2938 */
2939 EDMA3_DRV_TC_ERR_EN
2940 } EDMA3_DRV_Tc_Err;
2942 /**
2943 @}
2944 */
2946 /** @addtogroup EDMA3_LLD_DRV_FUNCTION_ADVANCED
2947 @{ */
2949 /**
2950 * \brief Enable/disable specific EDMA3 Transfer Controller Interrupts
2951 *
2952 * This function allows one to enable/disable specific EDMA3 Transfer Controller
2953 * Interrupts. Since these interrupts don't get enabled by default, this API can
2954 * be used to achieve the same.
2955 *
2956 * \param phyCtrllerInstId [IN] EDMA3 Controller Instance Id
2957 * (Hardware instance id, starting from 0).
2958 * \param tcId [IN] Transfer Controller Id. It starts from 0
2959 * for each EDMA3 hardware and can go upto
2960 * (TCs available on EDMA3 Hardware - 1).
2961 * \param tcErr [IN] TC Error Interrupts which need to be
2962 * enabled/disabled.
2963 *
2964 * \return EDMA3_DRV_SOK or EDMA3_DRV Error code
2965 *
2966 * \note This function is re-entrant for unique combination of EDMA3 hw and
2967 * TC. It is non-re-entrant for same combination.
2968 */
2969 EDMA3_DRV_Result EDMA3_DRV_setTcErrorInt(uint32_t phyCtrllerInstId,
2970 uint32_t tcId,
2971 EDMA3_DRV_Tc_Err tcErr);
2973 /**
2974 @}
2975 */
2977 /** @addtogroup EDMA3_LLD_DRV_SYMBOL_DEFINE
2978 @{ */
2980 /**
2981 * \brief Channel status defines
2982 * These defines suggest the current state of the DMA / QDMA channel. They
2983 * are used while returning the channel status from EDMA3_DRV_getChannelStatus().
2984 */
2985 /** Channel is clean; no pending event, completion interrupt and event miss interrupt */
2986 #define EDMA3_DRV_CHANNEL_CLEAN 0x0000u
2987 /** Pending event is detected on the DMA channel */
2988 #define EDMA3_DRV_CHANNEL_EVENT_PENDING 0x0001u
2989 /** Transfer completion interrupt is detected on the DMA/QDMA channel */
2990 #define EDMA3_DRV_CHANNEL_XFER_COMPLETE 0x0002u
2991 /** Event miss error interrupt is detected on the DMA/QDMA channel */
2992 #define EDMA3_DRV_CHANNEL_ERR 0x0004u
2994 /**
2995 @}
2996 */
2998 /** @addtogroup EDMA3_LLD_DRV_FUNCTION_ADVANCED
2999 @{ */
3001 /**
3002 * \brief Get the current status of the DMA/QDMA channel
3003 *
3004 * This function returns the current status of the specific DMA/QDMA channel.
3005 * For a DMA channel, it checks whether an event is pending in ER, transfer
3006 * completion interrupt is pending in IPR and event miss error interrupt is
3007 * pending in EMR or not. For a QDMA channel, it checks whether a transfer
3008 * completion interrupt is pending in IPR and event miss error interrupt is
3009 * pending in QEMR or not.
3010 *
3011 * \param hEdma [IN] Handle to the EDMA Driver Instance.
3012 * \param lCh [IN] DMA/QDMA channel for which the current
3013 * status is required.
3014 * \param lchStatus [IN/OUT]Status of the channel. Defines mentioned
3015 * above are used (and may be combined) to
3016 * return the actual status.
3017 *
3018 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
3019 *
3020 * \note This function is re-entrant.
3021 */
3022 EDMA3_DRV_Result EDMA3_DRV_getChannelStatus(EDMA3_DRV_Handle hEdma,
3023 uint32_t lCh, uint32_t *lchStatus);
3026 /**
3027 * \brief Associates a link channel and a TCC
3028 *
3029 * This API is used to map a TCC to a LINK channel. It should be used with LINK
3030 * channels ONLY else it will fail. It will copy the TCC code in the OPT field
3031 * of the param set associated with the link channel.
3032 *
3033 * \param hEdma [IN] Handle to the EDMA Driver Instance.
3034 * \param linkCh [IN] Link Channel to which a particular TCC
3035 * needs to be mapped.
3036 * \param tcc [IN] TCC which needs to be mapped.
3037 *
3038 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
3039 *
3040 * \note This function is re-entrant for unique linkCh values. It is
3041 * non-re-entrant for same linkCh values.
3042 */
3043 EDMA3_DRV_Result EDMA3_DRV_mapTccLinkCh (EDMA3_DRV_Handle hEdma,
3044 uint32_t linkCh,
3045 uint32_t tcc);
3047 #define EDMA3_DRV_MAX_XBAR_EVENTS (63u)
3049 /**\struct EDMA3_DRV_GblXbarToChanConfigParams
3050 * \brief Init-time Configuration structure for EDMA3
3051 * controller, to provide Global SoC specific Information.
3052 *
3053 * This configuration structure is used to specify the EDMA3 Driver
3054 * global settings, specific to the SoC.
3055 * This configuraion structure provides the details of the mapping of cross bar
3056 * events to available channels.
3057 * This configuration information is SoC specific and could be provided by the
3058 * user at run-time while creating the EDMA3 Driver Object, using API
3059 * EDMA3_DRV_initXbarEventMap. In case user doesn't provide it,
3060 * this information could be taken from the SoC specific configuration
3061 * file edma3_<SOC_NAME>_cfg.c, incase it is available.
3062 */
3063 typedef struct {
3064 /**
3065 * \brief Mapping from DMA channels to Hardware Events
3066 *
3067 * Each element in this array corresponds to one cross bar event and tells
3068 * whether this event is mapped to any DMA channel. That is whether any
3069 * free or unused DMA channel can be mapped to this event.
3070 * -1 means the cross bar event is not mapped to any DMA channel;
3071 * Any number from 0 to 63 means this event is mapped to specified channel.
3072 * All channels need not be mapped, some can be free also.
3073 * For the cross bar event mapped to DMA channel, appropriate Control Config
3074 * register of TPCC event mux register should be configured.
3075 */
3076 int32_t dmaMapXbarToChan [EDMA3_DRV_MAX_XBAR_EVENTS];
3077 } EDMA3_DRV_GblXbarToChanConfigParams;
3080 /**
3081 * \brief Associates cross bar mapped event to channel
3082 *
3083 * This function have to be defined in the configuration file.
3084 * This function will be called only if the channel requested for is beyond the
3085 * maximum number of channels.
3086 * This function should read from the global cross bar mapped configuration
3087 * data structure and return the mapped channel number to this event.
3088 *
3089 * \param eventNum [IN] Event number
3090 * \param chanNum [IN/OUT]Return the channel number to which the
3091 * request event is mapped to.
3092 * \param edmaGblXbarConfig [IN] This is the configuration data structure
3093 * for mapping the events to the channel
3094 *
3095 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
3096 *
3097 * \note This function is re-entrant for unique event values. It is
3098 * non-re-entrant for same event values.
3099 */
3100 typedef EDMA3_DRV_Result (*EDMA3_DRV_mapXbarEvtToChan) (uint32_t eventNum,
3101 uint32_t *chanNum,
3102 const EDMA3_DRV_GblXbarToChanConfigParams * edmaGblXbarConfig);
3104 /**
3105 * \brief Writes to the cross bar mapped event to channel to system
3106 * configuration register
3107 *
3108 * This function have to be defined in the configuration file.
3109 * This function will be called only if the event number requested for is
3110 * beyond the maximum number of channels and if any channel is allocated to this
3111 * event.
3112 * This function should read the cross bar mapped event number and write the
3113 * allocated channel number in Control Config Event Mux registers.
3114 *
3115 * \param eventNum [IN] Event number
3116 * \param chanNum [IN/OUT]Return the channel number to which the
3117 * request event is mapped to.
3118 *
3119 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
3120 *
3121 * \note This function is re-entrant for unique event values. It is
3122 * non-re-entrant for same event values.
3123 */
3124 typedef EDMA3_DRV_Result (*EDMA3_DRV_xbarConfigScr) (uint32_t eventNum,
3125 uint32_t chanNum);
3127 /**
3128 * \brief Initialize the cross bar mapped event to channel function
3129 *
3130 * This API provides interface to associate the cross bar mapped event to edma
3131 * channel in the driver.
3132 * This function will called by the application during initilization.
3133 * User could pass the application specific configuration structure
3134 * during init-time. In case user doesn't provide it, this information could
3135 * be taken from the SoC specific configuration file edma3_<SOC_NAME>_cfg.c,
3136 * in case it is available.
3137 * \param hEdma [IN] Handle to the EDMA Driver Instance.
3138 * \param edmaGblXbarConfig [IN] This is the configuration data structure
3139 * for mapping the events to the channel
3140 * \param mapXbarEvtFunc [IN] This is the user defined function for
3141 * mapping the cross bar event to channel.
3142 *
3143 * \return EDMA3_DRV_SOK or EDMA3_DRV Error Code
3144 *
3145 * \note This function disables the global interrupts (by calling API
3146 * edma3OsProtectEntry with protection level
3147 * EDMA3_OS_PROTECT_INTERRUPT) while modifying the global data
3148 * structures, to make it re-entrant.
3149 */
3150 EDMA3_DRV_Result EDMA3_DRV_initXbarEventMap (EDMA3_DRV_Handle hEdma,
3151 const EDMA3_DRV_GblXbarToChanConfigParams * edmaGblXbarConfig,
3152 EDMA3_DRV_mapXbarEvtToChan mapXbarEvtFunc,
3153 EDMA3_DRV_xbarConfigScr configXbarScr);
3157 /**
3158 @}
3159 */
3161 #ifdef __cplusplus
3162 }
3163 #endif /* extern "C" */
3165 #endif /* _EDMA3_DRV_H_ */