Bumped minor version to 02.12.01.24
[keystone-rtos/edma3_lld.git] / packages / ti / sdo / edma3 / drv / edma3_drv.h
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-2013 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                   (0x020C0118U)
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.12.01.24"
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
1998     /**
1999      * The OPT field (Offset Address 0x0 Bytes)
2000      */
2001     EDMA3_DRV_PARAM_ENTRY_OPT                       = 0U,
2003     /**
2004      * The SRC field (Offset Address 0x4 Bytes)
2005      */
2006     EDMA3_DRV_PARAM_ENTRY_SRC                       = 1U,
2008     /**
2009      * The (ACNT+BCNT) field (Offset Address 0x8 Bytes)
2010      */
2011     EDMA3_DRV_PARAM_ENTRY_ACNT_BCNT                 = 2U,
2013     /**
2014      * The DST field (Offset Address 0xC Bytes)
2015      */
2016     EDMA3_DRV_PARAM_ENTRY_DST                       = 3U,
2018     /**
2019      * The (SRCBIDX+DSTBIDX) field (Offset Address 0x10 Bytes)
2020      */
2021     EDMA3_DRV_PARAM_ENTRY_SRC_DST_BIDX              = 4U,
2023     /**
2024      * The (LINK+BCNTRLD) field (Offset Address 0x14 Bytes)
2025      */
2026     EDMA3_DRV_PARAM_ENTRY_LINK_BCNTRLD              = 5U,
2028     /**
2029      * The (SRCCIDX+DSTCIDX) field (Offset Address 0x18 Bytes)
2030      */
2031     EDMA3_DRV_PARAM_ENTRY_SRC_DST_CIDX              = 6U,
2033     /**
2034      * The (CCNT+RSVD) field (Offset Address 0x1C Bytes)
2035      */
2036     EDMA3_DRV_PARAM_ENTRY_CCNT                      = 7U
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
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
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
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 = &paramClearingRequired;
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
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