1 /*
2 * edma3_rm.h
3 *
4 * EDMA3 Controller Resource Manager Interface
5 *
6 * Copyright (C) 2009 Texas Instruments Incorporated - http://www.ti.com/
7 *
8 *
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions
11 * are met:
12 *
13 * Redistributions of source code must retain the above copyright
14 * notice, this list of conditions and the following disclaimer.
15 *
16 * Redistributions in binary form must reproduce the above copyright
17 * notice, this list of conditions and the following disclaimer in the
18 * documentation and/or other materials provided with the
19 * distribution.
20 *
21 * Neither the name of Texas Instruments Incorporated nor the names of
22 * its contributors may be used to endorse or promote products derived
23 * from this software without specific prior written permission.
24 *
25 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
26 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
27 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
28 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
29 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
30 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
31 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
35 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 *
37 */
39 /** @defgroup EDMA3_LLD_RM_API EDMA3 Resource Manager
40 *
41 * @section Introduction
42 *
43 * @subsection xxx Overview
44 * EDMA3 Resource Manager is a TI mandated library for all EDMA3 peripheral
45 * users to acquire and configure EDMA3 hardware resources (DMA/QDMA channels,
46 * PaRAM Sets, TCCs etc.) and DMA Interrupt Service Routines.
47 */
49 #ifndef _EDMA3_RM_H_
50 #define _EDMA3_RM_H_
52 #include <stdint.h>
53 /** Include common header file */
54 #include <ti/sdo/edma3/rm/edma3_common.h>
56 #ifdef __cplusplus
57 extern "C" {
58 #endif
60 /**
61 @defgroup EDMA3_LLD_RM_SYMBOL EDMA3 Resource Manager Symbols
62 @ingroup EDMA3_LLD_RM_API
63 */
64 /**
65 @defgroup EDMA3_LLD_RM_DATASTRUCT EDMA3 Resource Manager Data Structures
66 @ingroup EDMA3_LLD_RM_API
67 */
68 /**
69 @defgroup EDMA3_LLD_RM_FUNCTION EDMA3 Resource Manager APIs
70 @ingroup EDMA3_LLD_RM_API
71 */
73 /**
74 @defgroup EDMA3_LLD_RM_SYMBOL_DEFINE EDMA3 Resource Manager Defines
75 @ingroup EDMA3_LLD_RM_SYMBOL
76 */
77 /**
78 @defgroup EDMA3_LLD_RM_SYMBOL_ENUM EDMA3 Resource Manager Enums
79 @ingroup EDMA3_LLD_RM_SYMBOL
80 */
81 /**
82 @defgroup EDMA3_LLD_RM_SYMBOL_TYPEDEF EDMA3 Resource Manager Typedefs
83 @ingroup EDMA3_LLD_RM_SYMBOL
84 */
86 /**
87 @defgroup EDMA3_LLD_RM_FUNCTION_INIT EDMA3 Resource Manager Initialization APIs
88 @ingroup EDMA3_LLD_RM_FUNCTION
89 */
90 /**
91 @defgroup EDMA3_LLD_RM_FUNCTION_BASIC EDMA3 Resource Manager Basic APIs
92 @ingroup EDMA3_LLD_RM_FUNCTION
93 */
94 /**
95 @defgroup EDMA3_LLD_RM_FUNCTION_ADVANCED EDMA3 Resource Manager Advanced APIs
96 @ingroup EDMA3_LLD_RM_FUNCTION
97 */
99 /** @addtogroup EDMA3_LLD_RM_SYMBOL_ENUM
100 @{ */
102 /**\enum EDMA3_RM_TccStatus
103 * \brief This enum defines the channel specific status codes of
104 * an EDMA3 transfer. It is returned while calling the channel
105 * specific callback function to tell the status.
106 */
107 typedef enum
108 {
109 /**
110 * DMA Transfer successfully completed (true completion mode)
111 * or submitted to the TC (early completion mode).
112 */
113 EDMA3_RM_XFER_COMPLETE = 1,
115 /** Channel Controller has reported an error */
116 /**
117 * DMA missed events:- for all 64 DMA channels.
118 * These get latched in the event missed registers (EMR/EMRH).
119 */
120 EDMA3_RM_E_CC_DMA_EVT_MISS = 2,
122 /**
123 * QDMA missed events:- for all QDMA channels.
124 * These get latched in the QDMA event missed register (QEMR).
125 */
126 EDMA3_RM_E_CC_QDMA_EVT_MISS = 3
128 } EDMA3_RM_TccStatus;
130 /**\enum EDMA3_RM_GlobalError
131 * \brief This enum defines the global (not specific to any channel)
132 * error codes of completion of an EDMA3 transfer.
133 */
134 typedef enum
135 {
136 /**
137 * Threshold exceed:- for all event queues.
138 * These get latched in EDMA3CC error register (CCERR).
139 * This error has a direct relation with the setting of
140 * EDMA3_RM_GblConfigParams.evtQueueWaterMarkLvl
141 */
142 EDMA3_RM_E_CC_QUE_THRES_EXCEED = 1,
144 /**
145 * TCC error:- for outstanding transfer requests expected to return
146 * completion code (TCCHEN or TCINTEN bit in OPT is set to 1) exceeding
147 * the maximum limit of 63. This also gets latched in the CCERR.
148 */
149 EDMA3_RM_E_CC_TCC = 2,
151 /** Transfer Controller has reported an error */
152 /**
153 * Detection of a Read error signaled by the source or destination address
154 */
155 EDMA3_RM_E_TC_MEM_LOCATION_READ_ERROR = 3,
157 /**
158 * Detection of a Write error signaled by the source or destination address
159 */
160 EDMA3_RM_E_TC_MEM_LOCATION_WRITE_ERROR = 4,
162 /**
163 * Attempt to read or write to an invalid address in the configuration
164 * memory map.
165 */
166 EDMA3_RM_E_TC_INVALID_ADDR = 5,
168 /**
169 * Detection of a FIFO mode TR violating the FIFO mode transfer rules
170 * (the source/destination addresses and source/destination indexes must
171 * be aligned to 32 bytes).
172 */
173 EDMA3_RM_E_TC_TR_ERROR = 6
174 } EDMA3_RM_GlobalError;
176 /**
177 @}
178 */
180 /** @addtogroup EDMA3_LLD_RM_SYMBOL_TYPEDEF
181 @{ */
183 /**
184 * \brief Global Error callback - caters to module events like bus error etc
185 * which are not channel specific. Runs in ISR context.
186 *
187 * gblerrData is application provided data when open'ing the Resource Manager.
188 */
189 typedef void (* EDMA3_RM_GblErrCallback)(EDMA3_RM_GlobalError deviceStatus,
190 uint32_t instanceId,
191 void *gblerrData);
193 /**
194 @}
195 */
197 /** @addtogroup EDMA3_LLD_RM_DATASTRUCT
198 @{ */
200 /**\struct EDMA3_RM_GblErrCallbackParams
201 * \brief Global Error Callback parameters
202 *
203 * Consists of the Callback function and the data to be passed to it.
204 */
205 typedef struct {
206 /**
207 * Instance wide callback function to catch non-channel specific errors.
208 */
209 EDMA3_RM_GblErrCallback gblerrCb;
211 /** Application data to be passed back to the Global Error callback */
212 void *gblerrData;
214 } EDMA3_RM_GblErrCallbackParams;
216 /**
217 @}
218 */
220 /** @addtogroup EDMA3_LLD_RM_SYMBOL_TYPEDEF
221 @{ */
223 /**
224 * \brief TCC callback - caters to channel-specific events like
225 * "Event Miss Error" or "Transfer Complete". Runs in ISR context.
226 *
227 * appData is passed by the application during Register'ing of
228 * TCC Callback function.
229 */
230 typedef void (* EDMA3_RM_TccCallback)(uint32_t tcc,
231 EDMA3_RM_TccStatus status,
232 void *appData);
234 /**
235 @}
236 */
238 /** @addtogroup EDMA3_LLD_RM_SYMBOL_DEFINE
239 @{ */
241 /**\def EDMA3_RM_RES_ANY
242 * \brief Used to specify any available Resource Id (EDMA3_RM_ResDesc.resId)
243 */
244 #define EDMA3_RM_RES_ANY (1010u)
246 /**
247 @}
248 */
250 /** @addtogroup EDMA3_LLD_RM_SYMBOL_ENUM
251 @{ */
253 /**\enum EDMA3_RM_ResType
254 * \brief EDMA3 Resource Type
255 */
256 typedef enum
257 {
258 /** DMA Channel resource */
259 EDMA3_RM_RES_DMA_CHANNEL = 1,
261 /** QDMA Channel resource*/
262 EDMA3_RM_RES_QDMA_CHANNEL = 2,
264 /** TCC resource*/
265 EDMA3_RM_RES_TCC = 3,
267 /** Parameter RAM Set resource*/
268 EDMA3_RM_RES_PARAM_SET = 4
270 } EDMA3_RM_ResType;
272 /**
273 @}
274 */
276 /** @addtogroup EDMA3_LLD_RM_DATASTRUCT
277 @{ */
279 /**\struct EDMA3_RM_ResDesc
280 * \brief Handle to a Resource.
281 */
282 typedef struct
283 {
284 /** Resource Id */
285 /**
286 * Range of resId values :
287 * As an example, for resource Type = EDMA3_RM_RES_DMA_CHANNEL,
288 * resId can take values from 0 to EDMA3_MAX_DMA_CH
289 * Or
290 * resId can take the value EDMA3_RM_RES_ANY.
291 */
292 uint32_t resId;
294 /** Resource Type */
295 EDMA3_RM_ResType type;
296 } EDMA3_RM_ResDesc;
298 /**
299 @}
300 */
302 /** @addtogroup EDMA3_LLD_RM_FUNCTION_BASIC
303 @{ */
305 /**
306 * \brief Registers a transfer completion handler for a specific DMA/QDMA
307 * channel
308 *
309 * This function registers a non-NULL callback function for a specific DMA or QDMA
310 * channel and enables the completion interrupt for the TCC associated with
311 * the underlying channel in the IER/IERH register. It also sets the DRAE/DRAEH
312 * register for the TCC associated with the specified DMA/QDMA channel. If user
313 * enables the transfer completion interrupts (intermediate or final) in the OPT
314 * field of the associated PaRAM Set, the registered callback function will be
315 * called by the EDMA3 Resource Manager.
316 *
317 * If a call-back function is already registered for the channel, the API fails
318 * with the error code EDMA3_RM_E_CALLBACK_ALREADY_REGISTERED.
319 *
320 * \param hEdmaResMgr [IN] Handle to the previously opened
321 * EDMA3 Resource Manager Instance
322 * \param channelObj [IN] Channel ID and type (DMA or QDMA
323 * Channel), allocated earlier, and
324 * corresponding to which a callback
325 * function needs to be registered
326 * against the associated TCC.
327 * \param tcc [IN] TCC against which the handler needs to
328 * be registered.
329 * \param tccCb [IN] The Callback function to be registered
330 * against the TCC.
331 * \param cbData [IN] Callback data to be passed while calling
332 * the callback function.
333 *
334 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
335 *
336 * \note This function is re-entrant for unique tcc values. It is non-
337 * re-entrant for same tcc value.
338 */
339 EDMA3_RM_Result EDMA3_RM_registerTccCb(EDMA3_RM_Handle hEdmaResMgr,
340 const EDMA3_RM_ResDesc *channelObj,
341 uint32_t tcc,
342 EDMA3_RM_TccCallback tccCb,
343 void *cbData);
345 /**
346 * \brief Unregister the previously registered callback function against a
347 * DMA/QDMA channel.
348 *
349 * This function un-registers the previously registered callback function for
350 * the DMA/QDMA channel by removing any stored callback function. Moreover, it
351 * clears the:
352 * Interrupt Enable Register (IER/IERH) by writing to the IECR/IECRH
353 * register, for the TCC associated with that particular channel,
354 * DRA/DRAEH register for the TCC associated with the specified DMA/QDMA
355 * channel
356 *
357 * \param hEdmaResMgr [IN] Handle to the previously opened
358 * EDMA3 Resource Manager Instance
359 * \param channelObj [IN] Channel ID and type, allocated earlier
360 * (DMA or QDMA Channel ONLY), and
361 * corresponding to which a TCC is there.
362 * Against that TCC, the callback needs
363 * to be un-registered.
364 *
365 * \return EDMA3_RM_SOK or EDMA3_RM Error Code.
366 *
367 * \note This function is re-entrant for unique (channelObj->type +
368 * channelObj->resId) combination. It is non-re-entrant for same
369 * channelObj Resource.
370 */
371 EDMA3_RM_Result EDMA3_RM_unregisterTccCb(EDMA3_RM_Handle hEdmaResMgr,
372 const EDMA3_RM_ResDesc *channelObj);
374 /**
375 @}
376 */
378 /** @addtogroup EDMA3_LLD_RM_SYMBOL_DEFINE
379 @{ */
381 /** Resource Manager Error Codes base define */
382 #define EDMA3_RM_E_BASE (-155)
384 /**
385 * Resource Manager Object Not Deleted yet.
386 * So the object cannot be created.
387 */
388 #define EDMA3_RM_E_OBJ_NOT_DELETED (EDMA3_RM_E_BASE)
390 /**
391 * Resource Manager Object Not Closed yet.
392 * So the object cannot be deleted.
393 */
394 #define EDMA3_RM_E_OBJ_NOT_CLOSED (EDMA3_RM_E_BASE-1)
396 /**
397 * Resource Manager Object Not Opened yet
398 * So the object cannot be closed.
399 */
400 #define EDMA3_RM_E_OBJ_NOT_OPENED (EDMA3_RM_E_BASE-2)
402 /** Invalid Parameter passed to API */
403 #define EDMA3_RM_E_INVALID_PARAM (EDMA3_RM_E_BASE-3)
405 /** Resource requested for freeing is already free */
406 #define EDMA3_RM_E_RES_ALREADY_FREE (EDMA3_RM_E_BASE-4)
408 /** Resource requested for allocation/freeing is not owned */
409 #define EDMA3_RM_E_RES_NOT_OWNED (EDMA3_RM_E_BASE-5)
411 /** Resource is not available */
412 #define EDMA3_RM_E_SPECIFIED_RES_NOT_AVAILABLE (EDMA3_RM_E_BASE-6)
414 /** No Resource of specified type is available */
415 #define EDMA3_RM_E_ALL_RES_NOT_AVAILABLE (EDMA3_RM_E_BASE-7)
417 /** Invalid State of EDMA3 RM Obj */
418 #define EDMA3_RM_E_INVALID_STATE (EDMA3_RM_E_BASE-8)
420 /** Maximum no of Res Mgr Instances already Opened */
421 #define EDMA3_RM_E_MAX_RM_INST_OPENED (EDMA3_RM_E_BASE-9)
423 /**
424 * More than one Res Mgr Master Instance NOT supported.
425 * Only 1 master can exist.
426 */
427 #define EDMA3_RM_E_RM_MASTER_ALREADY_EXISTS (EDMA3_RM_E_BASE-10)
429 /** Callback function already registered. */
430 #define EDMA3_RM_E_CALLBACK_ALREADY_REGISTERED (EDMA3_RM_E_BASE-11)
432 /** Semaphore related error */
433 #define EDMA3_RM_E_SEMAPHORE (EDMA3_RM_E_BASE-12)
435 /** Hardware feature NOT supported */
436 #define EDMA3_RM_E_FEATURE_UNSUPPORTED (EDMA3_RM_E_BASE-13)
438 /** EDMA3 Resource NOT allocated */
439 #define EDMA3_RM_E_RES_NOT_ALLOCATED (EDMA3_RM_E_BASE-14)
441 /**
442 @}
443 */
445 /** @addtogroup EDMA3_LLD_RM_SYMBOL_TYPEDEF
446 @{ */
448 /**\typedef EDMA3_RM_RegionId
449 * \brief EDMA3 Region Id
450 *
451 * Use this to assign channels/PaRAM sets/TCCs to a particular Region.
452 */
453 typedef uint32_t EDMA3_RM_RegionId;
455 /**\typedef EDMA3_RM_EventQueue
456 * \brief EDMA3 Event Queue assignment
457 *
458 * There can be 8 Event Queues. Either of them can be assigned
459 * to a DMA/QDMA channel using this.
460 *
461 */
462 typedef uint32_t EDMA3_RM_EventQueue;
464 /**
465 @}
466 */
468 /** @addtogroup EDMA3_LLD_RM_DATASTRUCT
469 @{ */
471 /**\struct EDMA3_RM_GblConfigParams
472 * \brief Init-time Configuration structure for EDMA3
473 * controller, to provide Global SoC specific Information.
474 *
475 * This configuration structure is used to specify the EDMA3 Resource Manager
476 * global settings, specific to the SoC. For e.g. number of DMA/QDMA channels,
477 * number of PaRAM sets, TCCs, event queues, transfer controllers, base
478 * addresses of CC global registers and TC registers, interrupt number for
479 * EDMA3 transfer completion, CC error, event queues' priority, watermark
480 * threshold level etc.
481 * This configuration information is SoC specific and could be provided by the
482 * user at run-time while creating the EDMA3 RM Object, using API
483 * EDMA3_RM_create. In case user doesn't provide it, this information could be
484 * taken from the SoC specific configuration file edma3_<SOC_NAME>_cfg.c, in
485 * case it is available.
486 */
487 typedef struct {
488 /** Number of DMA Channels supported by the underlying EDMA3 Controller. */
489 uint32_t numDmaChannels;
491 /** Number of QDMA Channels supported by the underlying EDMA3 Controller */
492 uint32_t numQdmaChannels;
494 /**
495 * Number of Interrupt Channels supported by the underlying EDMA3
496 * Controller
497 */
498 uint32_t numTccs;
500 /** Number of PaRAM Sets supported by the underlying EDMA3 Controller */
501 uint32_t numPaRAMSets;
503 /** Number of Event Queues in the underlying EDMA3 Controller */
504 uint32_t numEvtQueue;
506 /**
507 * Number of Transfer Controllers (TCs) in the underlying EDMA3 Controller
508 */
509 uint32_t numTcs;
511 /** Number of Regions in the underlying EDMA3 Controller */
512 uint32_t numRegions;
514 /**
515 * \brief Channel mapping existence
516 *
517 * A value of 0 (No channel mapping) implies that there is fixed
518 * association between a DMA channel and a PaRAM Set or, in other words,
519 * DMA channel n can ONLY use PaRAM Set n (No availability of DCHMAP
520 * registers) for transfers to happen.
521 *
522 * A value of 1 implies the presence of DCHMAP registers for the DMA
523 * channels and hence the flexibility of associating any DMA channel to
524 * any PaRAM Set. In other words, ANY PaRAM Set can be used for ANY DMA
525 * channel (like QDMA Channels).
526 */
527 uint32_t dmaChPaRAMMapExists;
529 /** Existence of memory protection feature */
530 uint32_t memProtectionExists;
532 /** Base address of EDMA3 CC memory mapped registers. */
533 void *globalRegs;
535 /** Base address of EDMA3 TCs memory mapped registers. */
536 void *tcRegs[EDMA3_MAX_TC];
538 /**
539 * EDMA3 transfer completion interrupt line (could be different for ARM
540 * and DSP)
541 */
542 uint32_t xferCompleteInt;
544 /** EDMA3 CC error interrupt line (could be different for ARM and DSP) */
545 uint32_t ccError;
547 /** EDMA3 TCs error interrupt line (could be different for ARM and DSP) */
548 uint32_t tcError[EDMA3_MAX_TC];
550 /**
551 * \brief EDMA3 TC priority setting
552 *
553 * User can program the priority of the Event Queues
554 * at a system-wide level. This means that the user can set the
555 * priority of an IO initiated by either of the TCs (Transfer Controllers)
556 * relative to IO initiated by the other bus masters on the
557 * device (ARM, DSP, USB, etc)
558 */
559 uint32_t evtQPri [EDMA3_MAX_EVT_QUE];
561 /**
562 * \brief Event Queues Watermark Levels
564 * To Configure the Threshold level of number of events
565 * that can be queued up in the Event queues. EDMA3CC error register
566 * (CCERR) will indicate whether or not at any instant of time the
567 * number of events queued up in any of the event queues exceeds
568 * or equals the threshold/watermark value that is set
569 * in the queue watermark threshold register (QWMTHRA).
570 */
571 uint32_t evtQueueWaterMarkLvl [EDMA3_MAX_EVT_QUE];
573 /**
574 * \brief Default Burst Size (DBS) of TCs.
576 * An optimally-sized command is defined by the transfer controller
577 * default burst size (DBS). Different TCs can have different
578 * DBS values. It is defined in Bytes.
579 */
580 uint32_t tcDefaultBurstSize[EDMA3_MAX_TC];
582 /**
583 * \brief Mapping from DMA channels to PaRAM Sets
585 * If channel mapping exists (DCHMAP registers are present), this array
586 * stores the respective PaRAM Set for each DMA channel. User can
587 * initialize each array member with a specific PaRAM Set or with
588 * EDMA3_DRV_CH_NO_PARAM_MAP.
589 * If channel mapping doesn't exist, it is of no use as the EDMA3 RM
590 * automatically uses the right PaRAM Set for that DMA channel.
591 * Useful only if mapping exists, otherwise of no use.
592 */
593 uint32_t dmaChannelPaRAMMap [EDMA3_MAX_DMA_CH];
595 /**
596 * \brief Mapping from DMA channels to TCCs
597 *
598 * This array stores the respective TCC (interrupt channel) for each
599 * DMA channel. User can initialize each array member with a specific TCC
600 * or with EDMA3_DRV_CH_NO_TCC_MAP. This specific
601 * TCC code will be returned when the transfer is completed
602 * on the mapped DMA channel.
603 */
604 uint32_t dmaChannelTccMap [EDMA3_MAX_DMA_CH];
606 /**
607 * \brief Mapping from DMA channels to Hardware Events
608 *
609 * Each bit in this array corresponds to one DMA channel and tells whether
610 * this DMA channel is tied to any peripheral. That is whether any
611 * peripheral can send the synch event on this DMA channel or not.
612 * 1 means the channel is tied to some peripheral; 0 means it is not.
613 * DMA channels which are tied to some peripheral are RESERVED for that
614 * peripheral only. They are not allocated when user asks for 'ANY' DMA
615 * channel.
616 * All channels need not be mapped, some can be free also.
617 */
618 uint32_t dmaChannelHwEvtMap [EDMA3_MAX_DMA_CHAN_DWRDS];
619 } EDMA3_RM_GblConfigParams;
621 /**\struct EDMA3_RM_InstanceInitConfig
622 * \brief Init-time Region Specific Configuration structure for
623 * EDMA3 RM, to provide region specific Information.
624 *
625 * This configuration structure is used to specify which EDMA3 resources are
626 * owned and reserved by the EDMA3 RM instance. This configuration
627 * structure is shadow region specific and will be provided by the user at
628 * run-time while calling EDMA3_RM_open ().
629 *
630 * Owned resources:
631 * ****************
632 *
633 * EDMA3 RM Instances are tied to different shadow regions and hence different
634 * masters. Regions could be:
635 *
636 * a) ARM,
637 * b) DSP,
638 * c) IMCOP (Imaging Co-processor) etc.
639 *
640 * User can assign each EDMA3 resource to a shadow region using this structure.
641 * In this way, user specifies which resources are owned by the specific EDMA3
642 * RM Instance.
643 * This assignment should also ensure that the same resource is not assigned
644 * to more than one shadow regions (unless desired in that way). Any assignment
645 * not following the above mentioned approach may have catastrophic
646 * consequences.
647 *
648 *
649 * Reserved resources:
650 * *******************
651 *
652 * During EDMA3 RM initialization, user can reserve some of the EDMA3 resources
653 * for future use, by specifying which resources to reserve in the configuration
654 * data structure. These (critical) resources are reserved in advance so that
655 * they should not be allocated to someone else and thus could be used in
656 * future for some specific purpose.
657 *
658 * User can request different EDMA3 resources using two methods:
659 * a) By passing the resource type and the actual resource id,
660 * b) By passing the resource type and ANY as resource id
661 *
662 * For e.g. to request DMA channel 31, user will pass 31 as the resource id.
663 * But to request ANY available DMA channel (mainly used for memory-to-memory
664 * data transfer operations), user will pass EDMA3_DRV_DMA_CHANNEL_ANY as the
665 * resource id.
666 *
667 * During initialization, user may have reserved some of the DMA channels for
668 * some specific purpose (mainly for peripherals using EDMA). These reserved
669 * DMA channels then will not be returned when user requests ANY as the
670 * resource id.
671 *
672 * Same logic applies for QDMA channels and TCCs.
673 *
674 * For PaRAM Set, there is one difference. If the DMA channels are one-to-one
675 * tied to their respective PaRAM Sets (i.e. user cannot 'choose' the PaRAM Set
676 * for a particular DMA channel), EDMA3 RM automatically reserves all those
677 * PaRAM Sets which are tied to the DMA channels. Then those PaRAM Sets would
678 * not be returned when user requests for ANY PaRAM Set (specifically for
679 * linking purpose). This is done in order to avoid allocating the PaRAM Set,
680 * tied to a particular DMA channel, for linking purpose. If this constraint is
681 * not there, that DMA channel thus could not be used at all, because of the
682 * unavailability of the desired PaRAM Set.
683 */
684 typedef struct
685 {
686 /** PaRAM Sets owned by the EDMA3 RM Instance. */
687 uint32_t ownPaRAMSets[EDMA3_MAX_PARAM_DWRDS];
689 /** DMA Channels owned by the EDMA3 RM Instance. */
690 uint32_t ownDmaChannels[EDMA3_MAX_DMA_CHAN_DWRDS];
692 /** QDMA Channels owned by the EDMA3 RM Instance. */
693 uint32_t ownQdmaChannels[EDMA3_MAX_QDMA_CHAN_DWRDS];
695 /** TCCs owned by the EDMA3 RM Instance. */
696 uint32_t ownTccs[EDMA3_MAX_TCC_DWRDS];
698 /**
699 * \brief Reserved PaRAM Sets
700 *
701 * PaRAM Sets reserved during initialization for future use. These will not
702 * be given when user requests for ANY available PaRAM Set using
703 * 'EDMA3_RM_PARAM_ANY' as resource/channel id.
704 */
705 uint32_t resvdPaRAMSets[EDMA3_MAX_PARAM_DWRDS];
707 /**
708 * \brief Reserved DMA channels
709 *
710 * DMA channels reserved during initialization for future use. These will
711 * not be given when user requests for ANY available DMA channel using
712 * 'EDMA3_RM_DMA_CHANNEL_ANY' as resource/channel id.
713 */
714 uint32_t resvdDmaChannels[EDMA3_MAX_DMA_CHAN_DWRDS];
716 /**
717 * \brief Reserved QDMA channels
718 *
719 * QDMA channels reserved during initialization for future use. These will
720 * not be given when user requests for ANY available QDMA channel using
721 * 'EDMA3_RM_QDMA_CHANNEL_ANY' as resource/channel id.
722 */
723 uint32_t resvdQdmaChannels[EDMA3_MAX_QDMA_CHAN_DWRDS];
725 /**
726 * \brief Reserved TCCs
727 *
728 * TCCs reserved during initialization for future use. These will not
729 * be given when user requests for ANY available TCC using
730 * 'EDMA3_RM_TCC_ANY' as resource/channel id.
731 */
732 uint32_t resvdTccs[EDMA3_MAX_TCC_DWRDS];
733 }EDMA3_RM_InstanceInitConfig;
735 /**\struct EDMA3_RM_Param
736 * \brief Used to Initialize the Resource Manager Instance
737 *
738 * This configuration structure is used to initialize the EDMA3 RM Instance.
739 * This configuration information is passed while opening the RM instance.
740 */
741 typedef struct {
742 /** Shadow Region Identification */
743 EDMA3_RM_RegionId regionId;
745 /**
746 * It tells whether the EDMA3 RM instance is Master or not. Only the shadow
747 * region associated with this master instance will receive the EDMA3
748 * interrupts (if enabled).
749 */
750 uint32_t isMaster;
752 /**
753 * EDMA3 resources related shadow region specific information. Which all
754 * EDMA3 resources are owned and reserved by this particular instance are
755 * told in this configuration structure.
756 * User can also pass this structure as NULL. In that case, default static
757 * configuration would be taken from the platform specific configuration
758 * files (part of the Resource Manager), if available.
759 */
760 EDMA3_RM_InstanceInitConfig *rmInstInitConfig;
762 /**
763 * EDMA3 RM Instance specific semaphore handle.
764 * Used to share resources (DMA/QDMA channels, PaRAM Sets, TCCs etc)
765 * among different users.
766 */
767 void *rmSemHandle;
769 /**
770 * Whether initialization of Region Specific Registers is required or not?
771 */
772 uint32_t regionInitEnable;
774 /** Instance wide Global Error callback parameters */
775 EDMA3_RM_GblErrCallbackParams gblerrCbParams;
776 } EDMA3_RM_Param;
778 /**\struct EDMA3_RM_MiscParam
779 * \brief Used to specify the miscellaneous options during Resource
780 * Manager Initialization.
781 *
782 * This configuration structure is used to specify some misc options
783 * while creating the RM Object. New options may also be added into this
784 * structure in future.
785 */
786 typedef struct {
787 /**
788 * In a multi-master system (for e.g. ARM + DSP), this option is used to
789 * distinguish between Master and Slave. Only the Master is allowed to
790 * program the global EDMA3 registers (like Queue priority, Queue water-
791 * mark level, error registers etc).
792 */
793 uint16_t isSlave;
795 /** For future use **/
796 uint16_t param;
797 }EDMA3_RM_MiscParam;
799 /**
800 @}
801 */
803 /** @addtogroup EDMA3_LLD_RM_FUNCTION_INIT
804 @{ */
806 /**
807 * \brief Create EDMA3 Resource Manager Object
808 *
809 * This API is used to create the EDMA3 Resource Manager Object. It should be
810 * called only ONCE for each EDMA3 hardware instance.
811 *
812 * Init-time Configuration structure for EDMA3 hardware is provided to pass the
813 * SoC specific information. This configuration information could be provided
814 * by the user at init-time. In case user doesn't provide it, this information
815 * could be taken from the SoC specific configuration file
816 * edma3_<SOC_NAME>_cfg.c, in case it is available.
817 *
818 * This API clears the error specific registers (EMCR/EMCRh, QEMCR, CCERRCLR)
819 * and sets the TCs priorities and Event Queues' watermark levels, if the 'miscParam'
820 * argument is NULL. User can avoid these registers' programming (in some specific
821 * use cases) by SETTING the 'isSlave' field of 'EDMA3_RM_MiscParam' configuration
822 * structure and passing this structure as the third argument (miscParam).
823 *
824 * After successful completion of this API, Resource Manager Object's state
825 * changes to EDMA3_RM_CREATED from EDMA3_RM_DELETED.
826 *
827 * \param phyCtrllerInstId [IN] EDMA3 Controller Instance Id
828 * (Hardware instance id, starting from 0).
829 * \param gblCfgParams [IN] SoC specific configuration structure for the
830 * EDMA3 Hardware.
831 * \param miscParam [IN] Misc configuration options provided in the
832 * structure 'EDMA3_RM_MiscParam'.
833 * For default options, user can pass NULL
834 * in this argument.
835 *
836 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
837 */
838 EDMA3_RM_Result EDMA3_RM_create (uint32_t phyCtrllerInstId,
839 const EDMA3_RM_GblConfigParams *gblCfgParams,
840 const void *miscParam);
842 /**
843 * \brief Delete EDMA3 Resource Manager Object
844 *
845 * This API is used to delete the EDMA3 RM Object. It should be called
846 * once for each EDMA3 hardware instance, ONLY after closing all the
847 * previously opened EDMA3 RM Instances.
848 *
849 * After successful completion of this API, Resource Manager Object's state
850 * changes to EDMA3_RM_DELETED.
851 *
852 * \param phyCtrllerInstId [IN] EDMA3 Phy Controller Instance Id (Hardware
853 * instance id, starting from 0).
854 * \param param [IN] For possible future use.
855 *
856 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
857 */
858 EDMA3_RM_Result EDMA3_RM_delete (uint32_t phyCtrllerInstId,
859 const void *param);
861 /**
862 * \brief Open EDMA3 Resource Manager Instance
863 *
864 * This API is used to open an EDMA3 Resource Manager Instance. It could be
865 * called multiple times, for each possible EDMA3 shadow region. Maximum
866 * EDMA3_MAX_RM_INSTANCES instances are allowed for each EDMA3 hardware
867 * instance.
868 *
869 * Also, only ONE Master Resource Manager Instance is permitted. This master
870 * instance (and hence the region to which it belongs) will only receive the
871 * EDMA3 interrupts, if enabled.
872 *
873 * User could pass the instance specific configuration structure
874 * (initParam->rmInstInitConfig) as a part of the 'initParam' structure,
875 * during init-time. In case user doesn't provide it, this information could
876 * be taken from the SoC specific configuration file edma3_<SOC_NAME>_cfg.c,
877 * in case it is available.
878 *
879 * By default, this Resource Manager instance will clear the PaRAM Sets while
880 * allocating them. To change the default behavior, user should use the IOCTL
881 * interface appropriately.
882 *
883 * \param phyCtrllerInstId [IN] EDMA3 Controller Instance Id (Hardware
884 * instance id, starting from 0).
885 * \param initParam [IN] Used to Initialize the Resource Manager
886 * Instance (Master or Slave).
887 * \param errorCode [OUT] Error code while opening RM instance.
888 *
889 * \return Handle to the opened Resource Manager instance Or NULL in case of
890 * error.
891 *
892 * \note This function disables the global interrupts (by calling API
893 * edma3OsProtectEntry with protection level
894 * EDMA3_OS_PROTECT_INTERRUPT) while modifying the global RM data
895 * structures, to make it re-entrant.
896 */
897 EDMA3_RM_Handle EDMA3_RM_open (uint32_t phyCtrllerInstId,
898 const EDMA3_RM_Param *initParam,
899 EDMA3_RM_Result *errorCode);
901 /**
902 * \brief Close EDMA3 Resource Manager Instance
903 *
904 * This API is used to close a previously opened EDMA3 RM Instance.
905 *
906 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
907 * Manager Instance.
908 * \param param [IN] For possible future use.
909 *
910 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
911 *
912 * \note This function disables the global interrupts (by calling API
913 * edma3OsProtectEntry with protection level
914 * EDMA3_OS_PROTECT_INTERRUPT) while modifying the global RM data
915 * structures, to make it re-entrant.
916 */
917 EDMA3_RM_Result EDMA3_RM_close (EDMA3_RM_Handle hEdmaResMgr,
918 const void *param);
920 /**
921 @}
922 */
924 /** @addtogroup EDMA3_LLD_RM_FUNCTION_BASIC
925 @{ */
927 /**
928 * \brief This API is used to allocate specified EDMA3 Resources like
929 * DMA/QDMA channel, PaRAM Set or TCC.
930 *
931 * Note: To free the resources allocated by this API, user should call
932 * EDMA3_RM_freeResource () ONLY to de-allocate all the allocated resources.
933 *
934 * User can either request a specific resource by passing the resource id
935 * in 'resObj->resId' OR request ANY available resource of the type
936 * 'resObj->type'.
937 *
938 * ANY types of resources are those resources when user doesn't care about the
939 * actual resource allocated; user just wants a resource of the type specified.
940 * One use-case is to perform memory-to-memory data transfer operation. This
941 * operation can be performed using any available DMA or QDMA channel.
942 * User doesn't need any specific channel for the same.
943 *
944 * To allocate a specific resource, first this API checks whether that resource
945 * is OWNED by the Resource Manager instance. Then it checks the current
946 * availability of that resource.
947 *
948 * To allocate ANY available resource, this API tries to allocate a resource
949 * from the pool of (owned && non_reserved && available_right_now) resources.
950 *
951 * After allocating a DMA/QDMA channel, the same resource is enabled in
952 * the shadow region specific register (DRAE/DRAEH/QRAE). DRAE/DRAEH register
953 * for a TCC is updated only when user registers a callback function against
954 * that TCC using EDMA3_RM_registerTccCb().
955 *
956 * Allocated PaRAM Set is initialized to NULL before this API returns if user
957 * has requested for one.
958 *
959 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
960 * Manager Instance.
961 * \param resObj [IN/OUT] Handle to the resource descriptor
962 * object, which needs to be allocated.
963 * In case user passes a specific resource
964 * Id, resObj value is left unchanged.
965 * In case user requests ANY available
966 * resource, the allocated resource id is
967 * returned in resObj.
968 *
969 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
970 *
971 * \note This function acquires a RM Instance specific semaphore
972 * to prevent simultaneous access to the global pool of resources.
973 * It is re-entrant, but should not be called from the user callback
974 * function (ISR context).
975 */
976 EDMA3_RM_Result EDMA3_RM_allocResource (EDMA3_RM_Handle hEdmaResMgr,
977 EDMA3_RM_ResDesc *resObj);
979 /**
980 * \brief This API is used to free previously allocated EDMA3 Resources like
981 * DMA/QDMA channel, PaRAM Set or TCC.
982 *
983 * To free a specific resource, first this API checks whether that resource is
984 * OWNED by the Resource Manager Instance. Then it checks whether that resource
985 * has been allocated by the Resource Manager instance or not.
986 *
987 * After freeing a DMA/QDMA channel, the same resource is disabled in
988 * the shadow region specific register (DRAE/DRAEH/QRAE). This operation is
989 * performed for TCC while unregistering the callback function.
990 *
991 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
992 * Manager Instance.
993 * \param resObj [IN] Handle to the resource descriptor
994 * object, which needs to be freed.
995 *
996 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
997 *
998 * \note This function disables the global interrupts to prevent
999 * simultaneous access to the global pool of resources.
1000 * It is re-entrant.
1001 */
1002 EDMA3_RM_Result EDMA3_RM_freeResource(EDMA3_RM_Handle hEdmaResMgr,
1003 const EDMA3_RM_ResDesc *resObj);
1005 /**
1006 * \brief Allocate a contiguous region of specified EDMA3 Resource
1007 * like DMA channel, QDMA channel, PaRAM Set or TCC.
1008 *
1009 * This API is used to allocate a contiguous region of specified EDMA3
1010 * Resources like DMA channel, QDMA channel, PaRAM Set or TCC.
1011 *
1012 * User can specify a particular resource Id to start with and go up to the
1013 * number of resources requested. The specific resource id to start from could
1014 * be passed in 'firstResIdObject->resId' and the number of resources requested
1015 * in 'numResources'.
1016 *
1017 * User can also request ANY available resource(s) of the type
1018 * 'firstResIdObject->type' by specifying 'firstResIdObject->resId' as
1019 * EDMA3_RM_RES_ANY.
1020 *
1021 * ANY types of resources are those resources when user doesn't care about the
1022 * actual resource allocated; user just wants a resource of the type specified.
1023 * One use-case is to perform memory-to-memory data transfer operation. This
1024 * operation can be performed using any available DMA or QDMA channel. User
1025 * doesn't need any specific channel for the same.
1026 *
1027 * To allocate specific contiguous resources, first this API checks whether
1028 * those requested resources are OWNED by the Resource Manager instance. Then
1029 * it checks the current availability of those resources.
1030 *
1031 * To allocate ANY available contiguous resources, this API tries to allocate
1032 * resources from the pool of (owned && non_reserved && available_right_now)
1033 * resources.
1034 *
1035 * After allocating DMA/QDMA channels, the same resources are enabled in
1036 * the shadow region specific register (DRAE/DRAEH/QRAE). DRAE/DRAEH register
1037 * for a TCC is updated only when user registers a callback function against
1038 * that TCC using EDMA3_RM_registerTccCb(). Allocated PaRAM Sets are initialized
1039 * to NULL before this API returns.
1040 *
1041 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
1042 * Manager Instance.
1043 * \param firstResIdObj [IN] Handle to the first resource descriptor
1044 * object, which needs to be allocated.
1045 * firstResIdObject->resId could be a valid
1046 * resource id in case user wants to
1047 * allocate specific resources OR it could
1048 * be EDMA3_RM_RES_ANY in case user wants
1049 * only the required number of resources
1050 * and doesn't care about which resources
1051 * were allocated.
1052 * \param numResources [IN] Number of contiguous resources user
1053 * wants to allocate.
1054 *
1055 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
1056 *
1057 * \note This function acquires a RM Instance specific semaphore
1058 * to prevent simultaneous access to the global pool of resources.
1059 * It is re-entrant, but should not be called from the user callback
1060 * function (ISR context).
1061 */
1062 EDMA3_RM_Result EDMA3_RM_allocContiguousResource(EDMA3_RM_Handle hEdmaResMgr,
1063 EDMA3_RM_ResDesc *firstResIdObj,
1064 uint32_t numResources);
1066 /**
1067 * \brief Free a contiguous region of specified EDMA3 Resource
1068 * like DMA channel, QDMA channel, PaRAM Set or TCC, previously allocated.
1069 *
1070 * This API frees a contiguous region of specified EDMA3 Resources
1071 * like DMA channel, QDMA channel, PaRAM Set or TCC, which have been previously
1072 * allocated. In case of an error during the freeing of any specific resource,
1073 * user can check the 'firstResIdObj' object to know the last resource id
1074 * whose freeing has failed. In case of success, there is no need to check this
1075 * object.
1076 *
1077 * \param hEdmaResMgr [IN] Handle to the previously opened
1078 * Resource Manager Instance.
1079 * \param firstResIdObj [IN/OUT] Handle to the first resource
1080 * descriptor object, which needs to be
1081 * freed. In case of an error while
1082 * freeing any particular resource,
1083 * the last resource id whose freeing has
1084 * failed is returned in this resource
1085 * descriptor object.
1086 * \param numResources [IN] Number of contiguous resources allocated
1087 * previously which user wants to release
1088 *
1089 * \note This is a re-entrant function which internally calls
1090 * EDMA3_RM_freeResource() for resource de-allocation.
1091 */
1092 EDMA3_RM_Result EDMA3_RM_freeContiguousResource(EDMA3_RM_Handle hEdmaResMgr,
1093 EDMA3_RM_ResDesc *firstResIdObj,
1094 uint32_t numResources);
1096 /**
1097 @}
1098 */
1100 /** @addtogroup EDMA3_LLD_RM_SYMBOL_DEFINE
1101 @{ */
1103 /* Defines for Logical Channel Values */
1104 /*---------------------------------------------------------------------------*/
1105 /**
1106 * Used to specify any available DMA Channel while requesting
1107 * one. Used in the API EDMA3_RM_allocLogicalChannel ().
1108 * DMA channel from the pool of (owned && non_reserved && available_right_now)
1109 * DMA channels will be chosen and returned.
1110 */
1111 #define EDMA3_RM_DMA_CHANNEL_ANY (1011u)
1113 /**
1114 * Used to specify any available QDMA Channel while requesting
1115 * one. Used in the API EDMA3_RM_allocLogicalChannel().
1116 * QDMA channel from the pool of (owned && non_reserved && available_right_now)
1117 * QDMA channels will be chosen and returned.
1118 */
1119 #define EDMA3_RM_QDMA_CHANNEL_ANY (1012u)
1121 /**
1122 * Used to specify any available TCC while requesting
1123 * one. Used in the API EDMA3_RM_allocLogicalChannel(), for
1124 * both DMA and QDMA channels.
1125 * TCC from the pool of (owned && non_reserved && available_right_now)
1126 * TCCs will be chosen and returned.
1127 */
1128 #define EDMA3_RM_TCC_ANY (1013u)
1130 /**
1131 * Used to specify any available PaRAM Set while requesting
1132 * one. Used in the API EDMA3_RM_allocLogicalChannel(), for
1133 * both DMA/QDMA and Link channels.
1134 * PaRAM Set from the pool of (owned && non_reserved && available_right_now)
1135 * PaRAM Sets will be chosen and returned.
1136 */
1137 #define EDMA3_RM_PARAM_ANY (1014u)
1139 /**
1140 * This define is used to specify that a DMA channel is NOT tied to any PaRAM
1141 * Set and hence any available PaRAM Set could be used for that DMA channel.
1142 * It could be used in dmaChannelPaRAMMap [EDMA3_MAX_DMA_CH], in global
1143 * configuration structure EDMA3_RM_GblConfigParams.
1144 *
1145 * This value should mandatorily be used to mark DMA channels with no initial
1146 * mapping to specific PaRAM Sets.
1147 */
1148 #define EDMA3_RM_CH_NO_PARAM_MAP (1015u)
1150 /**
1151 * This define is used to specify that the DMA/QDMA channel is not tied to any
1152 * TCC and hence any available TCC could be used for that DMA/QDMA channel.
1153 * It could be used in dmaChannelTccMap [EDMA3_MAX_DMA_CH], in global
1154 * configuration structure EDMA3_RM_GblConfigParams.
1155 *
1156 * This value should mandatorily be used to mark DMA channels with no initial
1157 * mapping to specific TCCs.
1158 */
1159 #define EDMA3_RM_CH_NO_TCC_MAP (1016u)
1161 /**
1162 @}
1163 */
1165 /** @addtogroup EDMA3_LLD_RM_SYMBOL_ENUM
1166 @{ */
1168 /**
1169 * \brief DMA Channels assigned to different Hardware Events.
1170 *
1171 * They should be used while requesting a specific DMA channel.
1172 * One possible usage is to maintain a SoC specific file, which will
1173 * contain the mapping of these hardware events to the respective
1174 * peripherals for better understanding and lesser probability of
1175 * errors. Also, if any event associated with a particular peripheral
1176 * gets changed, only that SoC specific file needs to be changed.
1177 * for eg, the sample SoC specific file "soc.h" can have these defines:
1178 *
1179 * #define EDMA3_RM_HW_CHANNEL_MCBSP_TX EDMA3_RM_HW_CHANNEL_EVENT_2
1180 * #define EDMA3_RM_HW_CHANNEL_MCBSP_RX EDMA3_RM_HW_CHANNEL_EVENT_3
1181 *
1182 * These defines will be used by the MCBSP driver. The same event
1183 * EDMA3_RM_HW_CHANNEL_EVENT_2/3 could be mapped to some other
1184 * peripheral also.
1185 */
1186 typedef enum
1187 {
1188 /** Channel assigned to EDMA3 Event 0 */
1189 EDMA3_RM_HW_CHANNEL_EVENT_0 = 0,
1190 /** Channel assigned to EDMA3 Event 1 */
1191 EDMA3_RM_HW_CHANNEL_EVENT_1,
1192 /** Channel assigned to EDMA3 Event 2 */
1193 EDMA3_RM_HW_CHANNEL_EVENT_2,
1194 /** Channel assigned to EDMA3 Event 3 */
1195 EDMA3_RM_HW_CHANNEL_EVENT_3,
1196 /** Channel assigned to EDMA3 Event 4 */
1197 EDMA3_RM_HW_CHANNEL_EVENT_4,
1198 /** Channel assigned to EDMA3 Event 5 */
1199 EDMA3_RM_HW_CHANNEL_EVENT_5,
1200 /** Channel assigned to EDMA3 Event 6 */
1201 EDMA3_RM_HW_CHANNEL_EVENT_6,
1202 /** Channel assigned to EDMA3 Event 7 */
1203 EDMA3_RM_HW_CHANNEL_EVENT_7,
1204 /** Channel assigned to EDMA3 Event 8 */
1205 EDMA3_RM_HW_CHANNEL_EVENT_8,
1206 /** Channel assigned to EDMA3 Event 9 */
1207 EDMA3_RM_HW_CHANNEL_EVENT_9,
1208 /** Channel assigned to EDMA3 Event 10 */
1209 EDMA3_RM_HW_CHANNEL_EVENT_10,
1210 /** Channel assigned to EDMA3 Event 11 */
1211 EDMA3_RM_HW_CHANNEL_EVENT_11,
1212 /** Channel assigned to EDMA3 Event 12 */
1213 EDMA3_RM_HW_CHANNEL_EVENT_12,
1214 /** Channel assigned to EDMA3 Event 13 */
1215 EDMA3_RM_HW_CHANNEL_EVENT_13,
1216 /** Channel assigned to EDMA3 Event 14 */
1217 EDMA3_RM_HW_CHANNEL_EVENT_14,
1218 /** Channel assigned to EDMA3 Event 15 */
1219 EDMA3_RM_HW_CHANNEL_EVENT_15,
1220 /** Channel assigned to EDMA3 Event 16 */
1221 EDMA3_RM_HW_CHANNEL_EVENT_16,
1222 /** Channel assigned to EDMA3 Event 17 */
1223 EDMA3_RM_HW_CHANNEL_EVENT_17,
1224 /** Channel assigned to EDMA3 Event 18 */
1225 EDMA3_RM_HW_CHANNEL_EVENT_18,
1226 /** Channel assigned to EDMA3 Event 19 */
1227 EDMA3_RM_HW_CHANNEL_EVENT_19,
1228 /** Channel assigned to EDMA3 Event 20 */
1229 EDMA3_RM_HW_CHANNEL_EVENT_20,
1230 /** Channel assigned to EDMA3 Event 21 */
1231 EDMA3_RM_HW_CHANNEL_EVENT_21,
1232 /** Channel assigned to EDMA3 Event 22 */
1233 EDMA3_RM_HW_CHANNEL_EVENT_22,
1234 /** Channel assigned to EDMA3 Event 23 */
1235 EDMA3_RM_HW_CHANNEL_EVENT_23,
1236 /** Channel assigned to EDMA3 Event 24 */
1237 EDMA3_RM_HW_CHANNEL_EVENT_24,
1238 /** Channel assigned to EDMA3 Event 25 */
1239 EDMA3_RM_HW_CHANNEL_EVENT_25,
1240 /** Channel assigned to EDMA3 Event 26 */
1241 EDMA3_RM_HW_CHANNEL_EVENT_26,
1242 /** Channel assigned to EDMA3 Event 27 */
1243 EDMA3_RM_HW_CHANNEL_EVENT_27,
1244 /** Channel assigned to EDMA3 Event 28 */
1245 EDMA3_RM_HW_CHANNEL_EVENT_28,
1246 /** Channel assigned to EDMA3 Event 29 */
1247 EDMA3_RM_HW_CHANNEL_EVENT_29,
1248 /** Channel assigned to EDMA3 Event 30 */
1249 EDMA3_RM_HW_CHANNEL_EVENT_30,
1250 /** Channel assigned to EDMA3 Event 31 */
1251 EDMA3_RM_HW_CHANNEL_EVENT_31,
1252 /** Channel assigned to EDMA3 Event 32 */
1253 EDMA3_RM_HW_CHANNEL_EVENT_32,
1254 /** Channel assigned to EDMA3 Event 33 */
1255 EDMA3_RM_HW_CHANNEL_EVENT_33,
1256 /** Channel assigned to EDMA3 Event 34 */
1257 EDMA3_RM_HW_CHANNEL_EVENT_34,
1258 /** Channel assigned to EDMA3 Event 35 */
1259 EDMA3_RM_HW_CHANNEL_EVENT_35,
1260 /** Channel assigned to EDMA3 Event 36 */
1261 EDMA3_RM_HW_CHANNEL_EVENT_36,
1262 /** Channel assigned to EDMA3 Event 37 */
1263 EDMA3_RM_HW_CHANNEL_EVENT_37,
1264 /** Channel assigned to EDMA3 Event 38 */
1265 EDMA3_RM_HW_CHANNEL_EVENT_38,
1266 /** Channel assigned to EDMA3 Event 39 */
1267 EDMA3_RM_HW_CHANNEL_EVENT_39,
1268 /** Channel assigned to EDMA3 Event 40 */
1269 EDMA3_RM_HW_CHANNEL_EVENT_40,
1270 /** Channel assigned to EDMA3 Event 41 */
1271 EDMA3_RM_HW_CHANNEL_EVENT_41,
1272 /** Channel assigned to EDMA3 Event 42 */
1273 EDMA3_RM_HW_CHANNEL_EVENT_42,
1274 /** Channel assigned to EDMA3 Event 43 */
1275 EDMA3_RM_HW_CHANNEL_EVENT_43,
1276 /** Channel assigned to EDMA3 Event 44 */
1277 EDMA3_RM_HW_CHANNEL_EVENT_44,
1278 /** Channel assigned to EDMA3 Event 45 */
1279 EDMA3_RM_HW_CHANNEL_EVENT_45,
1280 /** Channel assigned to EDMA3 Event 46 */
1281 EDMA3_RM_HW_CHANNEL_EVENT_46,
1282 /** Channel assigned to EDMA3 Event 47 */
1283 EDMA3_RM_HW_CHANNEL_EVENT_47,
1284 /** Channel assigned to EDMA3 Event 48 */
1285 EDMA3_RM_HW_CHANNEL_EVENT_48,
1286 /** Channel assigned to EDMA3 Event 49 */
1287 EDMA3_RM_HW_CHANNEL_EVENT_49,
1288 /** Channel assigned to EDMA3 Event 50 */
1289 EDMA3_RM_HW_CHANNEL_EVENT_50,
1290 /** Channel assigned to EDMA3 Event 51 */
1291 EDMA3_RM_HW_CHANNEL_EVENT_51,
1292 /** Channel assigned to EDMA3 Event 52 */
1293 EDMA3_RM_HW_CHANNEL_EVENT_52,
1294 /** Channel assigned to EDMA3 Event 53 */
1295 EDMA3_RM_HW_CHANNEL_EVENT_53,
1296 /** Channel assigned to EDMA3 Event 54 */
1297 EDMA3_RM_HW_CHANNEL_EVENT_54,
1298 /** Channel assigned to EDMA3 Event 55 */
1299 EDMA3_RM_HW_CHANNEL_EVENT_55,
1300 /** Channel assigned to EDMA3 Event 56 */
1301 EDMA3_RM_HW_CHANNEL_EVENT_56,
1302 /** Channel assigned to EDMA3 Event 57 */
1303 EDMA3_RM_HW_CHANNEL_EVENT_57,
1304 /** Channel assigned to EDMA3 Event 58 */
1305 EDMA3_RM_HW_CHANNEL_EVENT_58,
1306 /** Channel assigned to EDMA3 Event 59 */
1307 EDMA3_RM_HW_CHANNEL_EVENT_59,
1308 /** Channel assigned to EDMA3 Event 60 */
1309 EDMA3_RM_HW_CHANNEL_EVENT_60,
1310 /** Channel assigned to EDMA3 Event 61 */
1311 EDMA3_RM_HW_CHANNEL_EVENT_61,
1312 /** Channel assigned to EDMA3 Event 62 */
1313 EDMA3_RM_HW_CHANNEL_EVENT_62,
1314 /** Channel assigned to EDMA3 Event 63 */
1315 EDMA3_RM_HW_CHANNEL_EVENT_63
1316 } EDMA3_RM_HW_CHANNEL_EVENT;
1318 /**
1319 @}
1320 */
1322 /** @addtogroup EDMA3_LLD_RM_FUNCTION_ADVANCED
1323 @{ */
1325 /**
1326 * \brief Request a DMA/QDMA/Link channel.
1327 *
1328 * This API is used to allocate a logical channel (DMA/QDMA/Link) along with
1329 * the associated resources. For DMA and QDMA channels, TCC and PaRAM Set are
1330 * also allocated along with the requested channel. For Link channel, ONLY a
1331 * PaRAM Set is allocated.
1332 *
1333 * Note: To free the logical channel allocated by this API, user should call
1334 * EDMA3_RM_freeLogicalChannel () ONLY to de-allocate all the allocated resources
1335 * and remove certain mappings.
1336 *
1337 * User can request a specific logical channel by passing the channel id in
1338 * 'lChObj->resId' and channel type in 'lChObj->type'. Note that the channel
1339 * id is the same as the actual resource id. For e.g. in the case of QDMA
1340 * channels, valid channel ids are from 0 to 7 only.
1341 *
1342 * User can also request ANY available logical channel of the type
1343 * 'lChObj->type' by specifying 'lChObj->resId' as:
1344 * a) EDMA3_RM_DMA_CHANNEL_ANY: For DMA channels
1345 * b) EDMA3_RM_QDMA_CHANNEL_ANY: For QDMA channels, and
1346 * c) EDMA3_RM_PARAM_ANY: For Link channels. Normally user should use this
1347 * value to request link channels (PaRAM Sets used for linking purpose
1348 * only), unless he wants to use some specific link channels (PaRAM Sets)
1349 * which is also allowed.
1350 *
1351 * This API internally uses EDMA3_RM_allocResource () to allocate the desired
1352 * resources (DMA/QDMA channel, PaRAM Set and TCC).
1353 *
1354 * For DMA/QDMA channels, after allocating all the EDMA3 resources, this API
1355 * sets the TCC field of the OPT PaRAM Word with the allocated TCC.
1356 *
1357 * For DMA channel, it also sets the DCHMAP register, if required.
1358 *
1359 * For QDMA channel, it sets the QCHMAP register and CCNT as trigger word and
1360 * enables the QDMA channel by writing to the QEESR register.
1361 *
1362 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
1363 * Manager Instance.
1364 * \param lChObj [IN/OUT] Handle to the requested logical channel
1365 * object, which needs to be allocated.
1366 * It could be a specific logical channel
1367 * or ANY available logical channel of the
1368 * requested type.
1369 * In case user passes a specific resource
1370 * Id, lChObj value is left unchanged. In
1371 * case user requests ANY available
1372 * resource, the allocated resource id is
1373 * returned in lChObj->resId.
1374 *
1375 * \param pParam [IN/OUT] PaRAM Set for a particular logical
1376 * (DMA/QDMA) channel. Not used if user
1377 * requested for a Link channel.
1378 * In case user passes a specific PaRAM
1379 * Set value, pParam value is left
1380 * unchanged. In case user requests ANY
1381 * available PaRAM Set by passing
1382 * 'EDMA3_RM_PARAM_ANY' in pParam,
1383 * the allocated one is returned in pParam.
1384 *
1385 * \param pTcc [IN/OUT] TCC for a particular logical (DMA/QDMA)
1386 * channel. Not used if user requested for
1387 * a Link channel.
1388 * In case user passes a specific TCC
1389 * value, pTcc value is left unchanged.
1390 * In case user requests ANY
1391 * available TCC by passing
1392 * 'EDMA3_RM_TCC_ANY' in pTcc,
1393 * the allocated one is returned in pTcc.
1394 *
1395 * \return EDMA3_RM_SOK or EDMA_RM Error Code
1396 *
1397 * \note This function internally calls EDMA3_RM_allocResource (), which
1398 * acquires a RM Instance specific semaphore to prevent simultaneous
1399 * access to the global pool of resources. It is re-entrant for unique
1400 * logical channel values, but SHOULD NOT be called from the user
1401 * callback function (ISR context).
1402 */
1403 EDMA3_RM_Result EDMA3_RM_allocLogicalChannel(EDMA3_RM_Handle hEdmaResMgr,
1404 EDMA3_RM_ResDesc *lChObj,
1405 uint32_t *pParam,
1406 uint32_t *pTcc);
1408 /** \fn EDMA3_RM_Result EDMA3_RM_freeLogicalChannel (EDMA3_RM_Handle
1409 * hEdmaResMgr, EDMA3_RM_ResDesc *lChObj)
1410 * \brief This API is used to free the specified channel (DMA/QDMA/Link) and
1411 * its associated resources (PaRAM Set, TCC etc).
1412 *
1413 * This API internally uses EDMA3_RM_freeResource () to free the desired
1414 * resources.
1415 *
1416 * For DMA/QDMA channels, it also clears the DCHMAP/QCHMAP registers
1417 *
1418 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
1419 * Manager Instance.
1420 * \param lChObj [IN] Handle to the logical channel object,
1421 * which needs to be freed
1422 *
1423 * \return EDMA3_RM_SOK or EDMA_RM Error Code
1424 *
1425 * \note This is a re-entrant function which internally calls
1426 * EDMA3_RM_freeResource () for resource de-allocation.
1427 */
1428 EDMA3_RM_Result EDMA3_RM_freeLogicalChannel (EDMA3_RM_Handle hEdmaResMgr,
1429 EDMA3_RM_ResDesc *lChObj);
1431 /**
1432 @}
1433 */
1435 /** @addtogroup EDMA3_LLD_RM_DATASTRUCT
1436 @{ */
1438 /**\struct EDMA3_RM_ParamentryRegs
1439 * \brief EDMA3 PaRAM Set
1440 *
1441 * This is a mapping of the EDMA3 PaRAM set provided to the user
1442 * for ease of modification of the individual PaRAM words.
1443 *
1444 * It could be used by the advanced users to program the PaRAM Set directly,
1445 * without using any API.
1446 */
1447 typedef struct {
1448 /** OPT field of PaRAM Set */
1449 volatile uint32_t OPT;
1451 /**
1452 * \brief Starting byte address of Source
1453 * For FIFO mode, srcAddr must be a 256-bit aligned address.
1454 */
1455 volatile uint32_t SRC;
1457 /**
1458 * Number of bytes in each Array (ACNT) (16 bits) and
1459 * Number of Arrays in each Frame (BCNT) (16 bits).
1460 */
1461 volatile uint32_t A_B_CNT;
1463 /**
1464 * \brief Starting byte address of destination
1465 * For FIFO mode, destAddr must be a 256-bit aligned address.
1466 * i.e. 5 LSBs should be 0.
1467 */
1468 volatile uint32_t DST;
1470 /**
1471 * Index between consec. arrays of a Source Frame (SRCBIDX) (16 bits) and
1472 * Index between consec. arrays of a Destination Frame (DSTBIDX) (16 bits).
1473 *
1474 * If SAM is set to 1 (via channelOptions) then srcInterArrIndex should
1475 * be an even multiple of 32 bytes.
1476 *
1477 * If DAM is set to 1 (via channelOptions) then destInterArrIndex should
1478 * be an even multiple of 32 bytes
1479 */
1480 volatile uint32_t SRC_DST_BIDX;
1482 /**
1483 * \brief Address for linking (AutoReloading of a PaRAM Set) (16 bits)
1484 * and Reload value of the numArrInFrame (BCNT) (16 bits).
1485 *
1486 * Link field must point to a valid aligned 32-byte PaRAM set
1487 * A value of 0xFFFF means no linking.
1488 *
1489 * B count reload field is relevant only for A-sync transfers.
1490 */
1491 volatile uint32_t LINK_BCNTRLD;
1493 /**
1494 * \brief Index between consecutive frames of a Source Block (SRCCIDX)
1495 * (16 bits) and Index between consecutive frames of a Dest Block
1496 * (DSTCIDX) (16 bits).
1497 */
1498 volatile uint32_t SRC_DST_CIDX;
1500 /**
1501 * \brief Number of Frames in a block (CCNT) (16 bits).
1502 */
1503 volatile uint32_t CCNT;
1504 } EDMA3_RM_ParamentryRegs;
1506 /**\struct EDMA3_RM_PaRAMRegs
1507 * \brief EDMA3 PaRAM Set in User Configurable format
1508 *
1509 * This is a mapping of the EDMA3 PaRAM set provided to the user
1510 * for ease of modification of the individual fields.
1511 */
1512 #ifndef _BIG_ENDIAN
1513 /* LITTLE_ENDIAN_MODE */
1514 typedef struct {
1515 /** OPT field of PaRAM Set */
1516 volatile uint32_t opt;
1518 /**
1519 * \brief Starting byte address of Source
1520 * For FIFO mode, srcAddr must be a 256-bit aligned address.
1521 */
1522 volatile uint32_t srcAddr;
1524 /**
1525 * \brief Number of bytes in each Array (ACNT)
1526 */
1527 volatile uint16_t aCnt;
1529 /**
1530 * \brief Number of Arrays in each Frame (BCNT)
1531 */
1532 volatile uint16_t bCnt;
1534 /**
1535 * \brief Starting byte address of destination
1536 * For FIFO mode, destAddr must be a 256-bit aligned address.
1537 * i.e. 5 LSBs should be 0.
1538 */
1539 volatile uint32_t destAddr;
1541 /**
1542 * \brief Index between consec. arrays of a Source Frame (SRCBIDX)
1543 * If SAM is set to 1 (via channelOptions) then srcInterArrIndex should
1544 * be an even multiple of 32 bytes.
1545 */
1546 volatile int16_t srcBIdx;
1548 /**
1549 * \brief Index between consec. arrays of a Destination Frame (DSTBIDX)
1550 * If DAM is set to 1 (via channelOptions) then destInterArrIndex should
1551 * be an even multiple of 32 bytes
1552 */
1553 volatile int16_t destBIdx;
1555 /**
1556 * \brief Address for linking (AutoReloading of a PaRAM Set)
1557 * This must point to a valid aligned 32-byte PaRAM set
1558 * A value of 0xFFFF means no linking
1559 * Linking is especially useful for use with ping-pong buffers and
1560 * circular buffers
1561 */
1562 volatile uint16_t linkAddr;
1564 /**
1565 * \brief Reload value of the numArrInFrame (BCNT)
1566 * Relevant only for A-sync transfers
1567 */
1568 volatile uint16_t bCntReload;
1570 /**
1571 * \brief Index between consecutive frames of a Source Block (SRCCIDX)
1572 */
1573 volatile int16_t srcCIdx;
1575 /**
1576 * \brief Index between consecutive frames of a Dest Block (DSTCIDX)
1577 */
1578 volatile int16_t destCIdx;
1580 /**
1581 * \brief Number of Frames in a block (CCNT)
1582 */
1583 volatile uint16_t cCnt;
1585 /**
1586 * \brief Reserved
1587 */
1588 volatile int16_t reserved;
1589 } EDMA3_RM_PaRAMRegs;
1590 #else
1591 /* BIG_ENDIAN_MODE */
1592 typedef struct {
1593 /** OPT field of PaRAM Set */
1594 volatile uint32_t opt;
1596 /**
1597 * \brief Starting byte address of Source
1598 * For FIFO mode, srcAddr must be a 256-bit aligned address.
1599 */
1600 volatile uint32_t srcAddr;
1602 /**
1603 * \brief Number of Arrays in each Frame (BCNT)
1604 */
1605 volatile uint16_t bCnt;
1607 /**
1608 * \brief Number of bytes in each Array (ACNT)
1609 */
1610 volatile uint16_t aCnt;
1612 /**
1613 * \brief Starting byte address of destination
1614 * For FIFO mode, destAddr must be a 256-bit aligned address.
1615 * i.e. 5 LSBs should be 0.
1616 */
1617 volatile uint32_t destAddr;
1619 /**
1620 * \brief Index between consec. arrays of a Destination Frame (DSTBIDX)
1621 * If DAM is set to 1 (via channelOptions) then destInterArrIndex should
1622 * be an even multiple of 32 bytes
1623 */
1624 volatile int16_t destBIdx;
1626 /**
1627 * \brief Index between consec. arrays of a Source Frame (SRCBIDX)
1628 * If SAM is set to 1 (via channelOptions) then srcInterArrIndex should
1629 * be an even multiple of 32 bytes.
1630 */
1631 volatile int16_t srcBIdx;
1633 /**
1634 * \brief Reload value of the numArrInFrame (BCNT)
1635 * Relevant only for A-sync transfers
1636 */
1637 volatile uint16_t bCntReload;
1639 /**
1640 * \brief Address for linking (AutoReloading of a PaRAM Set)
1641 * This must point to a valid aligned 32-byte PaRAM set
1642 * A value of 0xFFFF means no linking
1643 * Linking is especially useful for use with ping-pong buffers and
1644 * circular buffers
1645 */
1646 volatile uint16_t linkAddr;
1648 /**
1649 * \brief Index between consecutive frames of a Dest Block (DSTCIDX)
1650 */
1651 volatile int16_t destCIdx;
1653 /**
1654 * \brief Index between consecutive frames of a Source Block (SRCCIDX)
1655 */
1656 volatile int16_t srcCIdx;
1658 /**
1659 * \brief Reserved
1660 */
1661 volatile int16_t reserved;
1663 /**
1664 * \brief Number of Frames in a block (CCNT)
1665 */
1666 volatile uint16_t cCnt;
1667 } EDMA3_RM_PaRAMRegs;
1668 #endif /* #ifndef _BIG_ENDIAN */
1670 /**
1671 @}
1672 */
1674 /** @addtogroup EDMA3_LLD_RM_SYMBOL_ENUM
1675 @{ */
1677 /**\enum EDMA3_RM_QdmaTrigWord
1678 * \brief QDMA Trigger Word
1679 *
1680 * Use this enum to set the QDMA trigger word to any of the
1681 * 8 DWords(uint32_t) within a Parameter RAM set
1682 */
1683 typedef enum
1684 {
1685 /**
1686 * Set the OPT field (Offset Address 0h Bytes)
1687 * as the QDMA trigger word
1688 */
1689 EDMA3_RM_QDMA_TRIG_OPT = 0,
1690 /**
1691 * Set the SRC field (Offset Address 4h Bytes)
1692 * as the QDMA trigger word
1693 */
1694 EDMA3_RM_QDMA_TRIG_SRC = 1,
1695 /**
1696 * Set the (ACNT + BCNT) field (Offset Address 8h Bytes)
1697 * as the QDMA trigger word
1698 */
1699 EDMA3_RM_QDMA_TRIG_ACNT_BCNT = 2,
1700 /**
1701 * Set the DST field (Offset Address Ch Bytes)
1702 * as the QDMA trigger word
1703 */
1704 EDMA3_RM_QDMA_TRIG_DST = 3,
1705 /**
1706 * Set the (SRCBIDX + DSTBIDX) field (Offset Address 10h Bytes)
1707 * as the QDMA trigger word
1708 */
1709 EDMA3_RM_QDMA_TRIG_SRC_DST_BIDX = 4,
1710 /**
1711 * Set the (LINK + BCNTRLD) field (Offset Address 14h Bytes)
1712 * as the QDMA trigger word
1713 */
1714 EDMA3_RM_QDMA_TRIG_LINK_BCNTRLD = 5,
1715 /**
1716 * Set the (SRCCIDX + DSTCIDX) field (Offset Address 18h Bytes)
1717 * as the QDMA trigger word
1718 */
1719 EDMA3_RM_QDMA_TRIG_SRC_DST_CIDX = 6,
1720 /**
1721 * Set the (CCNT + RSVD) field (Offset Address 1Ch Bytes)
1722 * as the QDMA trigger word
1723 */
1724 EDMA3_RM_QDMA_TRIG_CCNT = 7,
1725 /** Default Trigger Word */
1726 EDMA3_RM_QDMA_TRIG_DEFAULT = 7
1727 } EDMA3_RM_QdmaTrigWord;
1729 /**\enum EDMA3_RM_Cntrlr_PhyAddr
1730 * \brief CC/TC Physical Address
1731 *
1732 * Use this enum to get the physical address of the Channel Controller or the
1733 * Transfer Controller. The address returned could be used by the advanced
1734 * users to set/get some specific registers direclty.
1735 */
1736 typedef enum
1737 {
1738 /** Channel Controller Physical Address */
1739 EDMA3_RM_CC_PHY_ADDR = 0,
1740 /** Transfer Controller 0 Physical Address */
1741 EDMA3_RM_TC0_PHY_ADDR,
1742 /** Transfer Controller 1 Physical Address */
1743 EDMA3_RM_TC1_PHY_ADDR,
1744 /** Transfer Controller 2 Physical Address */
1745 EDMA3_RM_TC2_PHY_ADDR,
1746 /** Transfer Controller 3 Physical Address */
1747 EDMA3_RM_TC3_PHY_ADDR,
1748 /** Transfer Controller 4 Physical Address */
1749 EDMA3_RM_TC4_PHY_ADDR,
1750 /** Transfer Controller 5 Physical Address */
1751 EDMA3_RM_TC5_PHY_ADDR,
1752 /** Transfer Controller 6 Physical Address */
1753 EDMA3_RM_TC6_PHY_ADDR,
1754 /** Transfer Controller 7 Physical Address */
1755 EDMA3_RM_TC7_PHY_ADDR
1756 }EDMA3_RM_Cntrlr_PhyAddr;
1758 /**
1759 @}
1760 */
1762 /** @addtogroup EDMA3_LLD_RM_FUNCTION_ADVANCED
1763 @{ */
1765 /**
1766 * \brief Bind the resources DMA Channel and PaRAM Set. Both the DMA channel
1767 * and the PaRAM set should be previously allocated. If they are not,
1768 * this API will result in error.
1769 *
1770 * This API sets the DCHMAP register for a specific DMA channel. This register
1771 * is used to specify the PaRAM Set associated with that particular DMA Channel.
1772 *
1773 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
1774 * Manager Instance.
1775 * \param channelId [IN] Previously allocated DMA Channel on which
1776 * Transfer will occur.
1777 * \param paRAMId [IN] Previously allocated PaRAM Set which
1778 * needs to be associated with the dma channel.
1779 *
1780 * \return EDMA3_RM_SOK or EDMA_RM Error Code
1781 *
1782 * \note This API is useful only for the EDMA3 Controllers which have a
1783 * register for mapping a DMA Channel to a particular PaRAM Set
1784 * (DCHMAP register).
1785 * On platforms where this feature is not supported, this API
1786 * returns error code: EDMA3_RM_E_FEATURE_UNSUPPORTED.
1787 * This function is re-entrant for unique channelId. It is
1788 * non-re-entrant for same channelId values.
1789 */
1790 EDMA3_RM_Result EDMA3_RM_mapEdmaChannel (EDMA3_RM_Handle hEdmaResMgr,
1791 uint32_t channelId,
1792 uint32_t paRAMId);
1794 /**
1795 * \brief Bind the resources QDMA Channel and PaRAM Set. Also, Set the
1796 * trigger word for the QDMA channel. Both the QDMA channel and the PaRAM set
1797 * should be previously allocated. If they are not, this API will result in error.
1798 *
1799 * This API sets the QCHMAP register for a specific QDMA channel. This register
1800 * is used to specify the PaRAM Set associated with that particular QDMA
1801 * Channel along with the trigger word.
1802 *
1803 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
1804 * Manager Instance.
1805 * \param channelId [IN] Previously allocated QDMA Channel on which
1806 * Transfer will occur.
1807 * \param paRAMId [IN] Previously allocated PaRAM Set, which needs to
1808 * be associated with channelId
1809 * \param trigWord [IN] The Trigger Word for the channel.
1810 * Trigger Word is the word in the PaRAM
1811 * Register Set which - when written to by CPU
1812 * -will start the QDMA transfer automatically
1813 *
1814 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
1815 *
1816 * \note This function is re-entrant for unique channelId. It is non-re-entrant
1817 * for same channelId values.
1818 */
1819 EDMA3_RM_Result EDMA3_RM_mapQdmaChannel (EDMA3_RM_Handle hEdmaResMgr,
1820 uint32_t channelId,
1821 uint32_t paRAMId,
1822 EDMA3_RM_QdmaTrigWord trigWord);
1824 /**
1825 * \brief Set the Channel Controller (CC) Register value
1826 *
1827 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
1828 * Manager Instance.
1829 * \param regOffset [IN] CC Register offset whose value needs to be
1830 * set. It should be word-aligned.
1831 * \param newRegValue [IN] New CC Register Value
1832 *
1833 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
1834 *
1835 * \note This function is non re-entrant for users using the same
1836 * Resource Manager handle.
1837 * Before modifying a register, it tries to acquire a semaphore
1838 * (RM instance specific), to protect simultaneous
1839 * modification of the same register by two different users.
1840 * After the successful change, it releases the semaphore.
1841 * For users using different RM handles, this function is re-entrant.
1842 */
1843 EDMA3_RM_Result EDMA3_RM_setCCRegister (EDMA3_RM_Handle hEdmaResMgr,
1844 uint32_t regOffset,
1845 uint32_t newRegValue);
1847 /**
1848 * \brief Get the Channel Controller (CC) Register value
1849 *
1850 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
1851 * Manager Instance.
1852 * \param regOffset [IN] CC Register offset whose value is
1853 * needed. It should be word-aligned.
1854 * \param regValue [IN/OUT] Fetched CC Register Value
1855 *
1856 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
1857 *
1858 * \note This function is re-entrant.
1859 */
1860 EDMA3_RM_Result EDMA3_RM_getCCRegister (EDMA3_RM_Handle hEdmaResMgr,
1861 uint32_t regOffset,
1862 uint32_t *regValue);
1864 /**
1865 * \brief Wait for a transfer completion interrupt to occur and clear it.
1866 *
1867 * This is a blocking function that returns when the IPR/IPRH bit corresponding
1868 * to the tccNo specified, is SET. It clears the corresponding bit while
1869 * returning also.
1870 *
1871 * This function waits for the specific bit indefinitely in a tight loop, with
1872 * out any delay in between. USE IT CAUTIOUSLY.
1873 *
1874 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
1875 * Manager Instance.
1876 * \param tccNo [IN] TCC, specific to which the function
1877 * waits on a IPR/IPRH bit.
1878 *
1879 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
1880 *
1881 * \note This function is re-entrant for different tccNo.
1882 *
1883 */
1884 EDMA3_RM_Result EDMA3_RM_waitAndClearTcc (EDMA3_RM_Handle hEdmaResMgr,
1885 uint32_t tccNo);
1887 /**
1888 * \brief Returns the status of a previously initiated transfer.
1889 *
1890 * This is a non-blocking function that returns the status of a previously
1891 * initiated transfer, based on the IPR/IPRH bit. This bit corresponds to
1892 * the tccNo specified by the user. It clears the corresponding bit, if SET,
1893 * while returning also.
1894 *
1895 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
1896 * Manager Instance.
1897 * \param tccNo [IN] TCC, specific to which the function
1898 * checks the status of the IPR/IPRH bit.
1899 * \param tccStatus [IN/OUT] Status of the transfer is returned here.
1900 * Returns "TRUE" if the transfer has
1901 * completed (IPR/IPRH bit SET),
1902 * "FALSE" if the transfer has not
1903 * completed successfully (IPR/IPRH bit
1904 * NOT SET).
1905 *
1906 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
1907 *
1908 * \note This function is re-entrant for different tccNo.
1909 */
1910 EDMA3_RM_Result EDMA3_RM_checkAndClearTcc (EDMA3_RM_Handle hEdmaResMgr,
1911 uint32_t tccNo,
1912 uint16_t *tccStatus);
1914 /**
1915 * \brief Copy the user specified PaRAM Set onto the PaRAM Set
1916 * associated with the logical channel (DMA/QDMA/Link).
1917 *
1918 * This API takes a PaRAM Set as input and copies it onto the actual PaRAM Set
1919 * associated with the logical channel. OPT field of the PaRAM Set is written
1920 * first and the CCNT field is written last.
1921 *
1922 * Caution: It should be used carefully when programming the QDMA channels whose
1923 * trigger words are not CCNT field.
1924 *
1925 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
1926 * Manager Instance.
1927 * \param lChObj [IN] Logical Channel object for which new
1928 * PaRAM set is specified. User should pass
1929 * the resource type and id in this object.
1930 * \param newPaRAM [IN] PaRAM set to be copied onto existing one
1931 *
1932 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
1933 *
1934 * \note This function is re-entrant for unique lChObj values. It is non-
1935 * re-entrant for same lChObj value.
1936 */
1937 EDMA3_RM_Result EDMA3_RM_setPaRAM (EDMA3_RM_Handle hEdmaResMgr,
1938 EDMA3_RM_ResDesc *lChObj,
1939 const EDMA3_RM_PaRAMRegs *newPaRAM);
1941 /**
1942 * \brief Retrieve existing PaRAM set associated with specified logical
1943 * channel (DMA/QDMA/Link).
1944 *
1945 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
1946 * Manager Instance.
1947 * \param lChObj [IN] Logical Channel object for which the
1948 * PaRAM set is requested. User should pass
1949 * the resource type and id in this object.
1950 * \param currPaRAM [IN/OUT] User gets the existing PaRAM here.
1951 *
1952 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
1953 *
1954 * \note This function is re-entrant.
1955 */
1956 EDMA3_RM_Result EDMA3_RM_getPaRAM (EDMA3_RM_Handle hEdmaResMgr,
1957 EDMA3_RM_ResDesc *lChObj,
1958 EDMA3_RM_PaRAMRegs *currPaRAM);
1960 /**
1961 * \brief Get the PaRAM Set Physical Address associated with a logical channel
1962 *
1963 * This function returns the PaRAM Set Phy Address (unsigned 32 bits).
1964 * The returned address could be used by the advanced users to program the
1965 * PaRAM Set directly without using any APIs.
1966 *
1967 * Least significant 16 bits of this address could be used to program
1968 * the LINK field in the PaRAM Set.
1969 * Users which program the LINK field directly SHOULD use this API
1970 * to get the associated PaRAM Set address with the LINK channel.
1971 *
1972 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
1973 * Manager Instance.
1974 * \param lChObj [IN] Logical Channel object for which the
1975 * PaRAM set physical address is required.
1976 * User should pass the resource type and
1977 * id in this object.
1978 * \param paramPhyAddr [IN/OUT] PaRAM Set physical address is returned
1979 * here.
1980 *
1981 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
1982 *
1983 * \note This function is re-entrant.
1984 */
1985 EDMA3_RM_Result EDMA3_RM_getPaRAMPhyAddr(EDMA3_RM_Handle hEdmaResMgr,
1986 EDMA3_RM_ResDesc *lChObj,
1987 uint32_t *paramPhyAddr);
1989 /**
1990 * \brief Get the Channel Controller or Transfer Controller (n) Physical
1991 * Address.
1992 *
1993 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
1994 * Manager Instance.
1995 * \param controllerId [IN] Channel Controller or Transfer
1996 * Controller (n) for which the physical
1997 * address is required.
1998 * \param phyAddress [IN/OUT] Physical address is returned here.
1999 *
2000 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
2001 *
2002 * \note This function is re-entrant.
2003 */
2004 EDMA3_RM_Result EDMA3_RM_getBaseAddress (EDMA3_RM_Handle hEdmaResMgr,
2005 EDMA3_RM_Cntrlr_PhyAddr controllerId,
2006 uint32_t *phyAddress);
2008 /**
2009 * \brief Get the SoC specific configuration structure for the EDMA3 Hardware.
2010 *
2011 * This API is used to fetch the global SoC specific configuration structure
2012 * for the EDMA3 Hardware. It is useful for the user who has not passed
2013 * this information during EDMA3_RM_create() and taken the default configuration
2014 * coming along with the package.
2015 *
2016 * \param phyCtrllerInstId [IN] EDMA3 Controller Instance Id
2017 * (Hardware instance id, starting from 0).
2018 * \param gblCfgParams [IN/OUT] SoC specific configuration structure for the
2019 * EDMA3 Hardware will be returned here.
2020 *
2021 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
2022 *
2023 * \note This function is re-entrant.
2024 */
2025 EDMA3_RM_Result EDMA3_RM_getGblConfigParams (uint32_t phyCtrllerInstId,
2026 EDMA3_RM_GblConfigParams *gblCfgParams);
2028 /**
2029 * \brief Get the RM Instance specific configuration structure for different
2030 * EDMA3 resources' usage (owned resources, reserved resources etc).
2031 *
2032 * This API is used to fetch the Resource Manager Instance specific configuration
2033 * structure, for a specific shadow region. It is useful for the user who has not passed
2034 * this information during EDMA3_RM_opn() and taken the default configuration
2035 * coming along with the package. EDMA3 resources, owned and reserved by this RM
2036 * instance, will be returned from this API.
2037 *
2038 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
2039 * Manager Instance.
2040 * \param instanceInitConfig [IN/OUT] RM Instance specific configuration
2041 * structure will be returned here.
2042 *
2043 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
2044 *
2045 * \note This function is re-entrant.
2046 */
2047 EDMA3_RM_Result EDMA3_RM_getInstanceInitCfg (EDMA3_RM_Handle hEdmaResMgr,
2048 EDMA3_RM_InstanceInitConfig *instanceInitConfig);
2050 /**
2051 @}
2052 */
2054 /** @addtogroup EDMA3_LLD_RM_SYMBOL_ENUM
2055 @{ */
2057 /**\enum EDMA3_RM_IoctlCmd
2058 * \brief EDMA3 Resource Manager IOCTL commands
2059 */
2060 typedef enum
2061 {
2062 /* Min IOCTL */
2063 EDMA3_RM_IOCTL_MIN_IOCTL = 0,
2065 /**
2066 * PaRAM Sets will be cleared OR will not be cleared
2067 * during allocation, depending upon this option.
2068 *
2069 * For e.g.,
2070 * To clear the PaRAM Sets during allocation,
2071 * cmdArg = (void *)1;
2072 *
2073 * To NOT clear the PaRAM Sets during allocation,
2074 * cmdArg = (void *)0;
2075 *
2076 * For all other values, it will return error.
2077 *
2078 * By default, PaRAM Sets will be cleared during allocation.
2079 *
2080 * Note: Since this enum can change the behavior how the resources are
2081 * initialized during their allocation, user is adviced to not use this
2082 * command while allocating the resources. User should first change the
2083 * behavior of resources' initialization and then should use start
2084 * allocating resources.
2085 */
2086 EDMA3_RM_IOCTL_SET_PARAM_CLEAR_OPTION,
2088 /**
2089 * To check whether PaRAM Sets will be cleared or not
2090 * during allocation.
2091 * If the value read is '1', it means that PaRAM Sets are getting cleared
2092 * during allocation.
2093 * If the value read is '0', it means that PaRAM Sets are NOT getting cleared
2094 * during allocation.
2095 *
2096 * For e.g.,
2097 * uint32_t *isParamClearingDone = (uint32_t *)cmdArg;
2098 * (*isParamClearingDone) = paramClearingRequired;
2099 */
2100 EDMA3_RM_IOCTL_GET_PARAM_CLEAR_OPTION,
2102 /**
2103 * Global EDMA3 registers (DCHMAP/QCHMAP) and PaRAM Sets will be modified
2104 * OR will not be modified during EDMA3_RM_allocLogicalChannel (), depending
2105 * upon this option.
2106 *
2107 * For e.g.,
2108 * To modify the Registers or PaRAM Sets during allocation,
2109 * cmdArg = (void *)1;
2110 *
2111 * To NOT modify the Registers or PaRAM Sets during allocation,
2112 * cmdArg = (void *)0;
2113 *
2114 * For all other values, it will return error.
2115 *
2116 * By default, Registers or PaRAM Sets will be programmed during allocation.
2117 *
2118 * Note: Since this enum can change the behavior how the resources are
2119 * initialized during their allocation, user is adviced to not use this
2120 * command while allocating the resources. User should first change the
2121 * behavior of resources' initialization and then should use start
2122 * allocating resources.
2123 */
2124 EDMA3_RM_IOCTL_SET_GBL_REG_MODIFY_OPTION,
2126 /**
2127 * To check whether Global EDMA3 registers (DCHMAP/QCHMAP) and PaRAM Sets
2128 * will be programmed or not during allocation (EDMA3_RM_allocLogicalChannel ()).
2129 * If the value read is '1', it means that the registers/PaRAMs are getting programmed
2130 * during allocation.
2131 * If the value read is '0', it means that the registers/PaRAMs are NOT getting programmed
2132 * during allocation.
2133 *
2134 * For e.g.,
2135 * uint32_t *isParamClearingDone = (uint32_t *)cmdArg;
2136 * (*isParamClearingDone) = paramClearingRequired;
2137 */
2138 EDMA3_RM_IOCTL_GET_GBL_REG_MODIFY_OPTION,
2140 /* Max IOCTLs */
2141 EDMA3_RM_IOCTL_MAX_IOCTL
2142 } EDMA3_RM_IoctlCmd;
2144 /**
2145 @}
2146 */
2148 /** @addtogroup EDMA3_LLD_RM_FUNCTION_ADVANCED
2149 @{ */
2151 /**
2152 * \brief EDMA3 Resource Manager IOCTL
2153 *
2154 * This function provides IOCTL functionality for EDMA3 Resource Manager
2155 *
2156 * \param hEdmaResMgr [IN] Handle to the previously opened Resource
2157 * Manager Instance.
2158 * \param cmd [IN] IOCTL command to be performed
2159 * \param cmdArg [IN/OUT] IOCTL command argument (if any)
2160 * \param param [IN/OUT] Device/Cmd specific argument.
2161 *
2162 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
2163 *
2164 * \note For 'EDMA3_RM_IOCTL_GET_PARAM_CLEAR_OPTION', this function is re-entrant.
2165 * For 'EDMA3_RM_IOCTL_SET_PARAM_CLEAR_OPTION', this function is re-entrant for
2166 * different Resource Manager Instances (handles).
2167 */
2168 EDMA3_RM_Result EDMA3_RM_Ioctl(
2169 EDMA3_RM_Handle hEdmaResMgr,
2170 EDMA3_RM_IoctlCmd cmd,
2171 void *cmdArg,
2172 void *param
2173 );
2175 #define EDMA3_RM_MAX_XBAR_EVENTS (31u)
2177 /**\struct EDMA3_RM_GblXbarToChanConfigParams
2178 * \brief Init-time Configuration structure for EDMA3
2179 * controller, to provide Global SoC specific Information.
2180 *
2181 * This configuration structure is used to specify the EDMA3 Driver
2182 * global settings, specific to the SoC.
2183 * This configuraion structure provides the details of the mapping of cross bar
2184 * events to available channels.
2185 * This configuration information is SoC specific and could be provided by the
2186 * user at run-time while creating the EDMA3 Driver Object, using API
2187 * EDMA3_RM_initXbarEventMap. In case user doesn't provide it,
2188 * this information could be taken from the SoC specific configuration
2189 * file edma3_<SOC_NAME>_cfg.c, incase it is available.
2190 */
2191 typedef struct {
2192 /**
2193 * \brief Mapping from DMA channels to Hardware Events
2194 *
2195 * Each element in this array corresponds to one cross bar event and tells
2196 * whether this event is mapped to any DMA channel. That is whether any
2197 * free or unused DMA channel can be mapped to this event.
2198 * -1 means the cross bar event is not mapped to any DMA channel;
2199 * Any number from 0 to 63 means this event is mapped to specified channel.
2200 * All channels need not be mapped, some can be free also.
2201 * For the cross bar event mapped to DMA channel, appropriate Control Config
2202 * register of TPCC event mux register should be configured.
2203 */
2204 int32_t dmaMapXbarToChan [EDMA3_RM_MAX_XBAR_EVENTS];
2205 } EDMA3_RM_GblXbarToChanConfigParams;
2208 /**
2209 * \brief Associates cross bar mapped event to channel
2210 *
2211 * This function have to be defined in the configuration file.
2212 * This function will be called only if the channel requested for is beyond the
2213 * maximum number of channels.
2214 * This function should read from the global cross bar mapped configuration
2215 * data structure and return the mapped channel number to this event.
2216 *
2217 * \param eventNum [IN] Event number
2218 * \param chanNum [IN/OUT]Return the channel number to which the
2219 * request event is mapped to.
2220 * \param edmaGblXbarConfig [IN] This is the configuration data structure
2221 * for mapping the events to the channel
2222 *
2223 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
2224 *
2225 * \note This function is re-entrant for unique event values. It is
2226 * non-re-entrant for same event values.
2227 */
2228 typedef EDMA3_RM_Result (*EDMA3_RM_mapXbarEvtToChan) (uint32_t eventNum,
2229 uint32_t *chanNum,
2230 const EDMA3_RM_GblXbarToChanConfigParams * edmaGblXbarConfig);
2232 /**
2233 * \brief Writes to the cross bar mapped event to channel to system
2234 * configuration register
2235 *
2236 * This function have to be defined in the configuration file.
2237 * This function will be called only if the event number requested for is
2238 * beyond the maximum number of channels and if any channel is allocated to this
2239 * event.
2240 * This function should read the cross bar mapped event number and write the
2241 * allocated channel number in Control Config Event Mux registers.
2242 *
2243 * \param eventNum [IN] Event number
2244 * \param chanNum [IN/OUT]Return the channel number to which the
2245 * request event is mapped to.
2246 *
2247 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
2248 *
2249 * \note This function is re-entrant for unique event values. It is
2250 * non-re-entrant for same event values.
2251 */
2252 typedef EDMA3_RM_Result (*EDMA3_RM_xbarConfigScr) (uint32_t eventNum,
2253 uint32_t chanNum);
2255 /**
2256 * \brief Initialize the cross bar mapped event to channel function
2257 *
2258 * This API provides interface to associate the cross bar mapped event to edma
2259 * channel in the driver.
2260 * This function will called by the application during initilization.
2261 * User could pass the application specific configuration structure
2262 * during init-time. In case user doesn't provide it, this information could
2263 * be taken from the SoC specific configuration file edma3_<SOC_NAME>_cfg.c,
2264 * in case it is available.
2265 * \param hEdma [IN] Handle to the EDMA Driver Instance.
2266 * \param edmaGblXbarConfig [IN] This is the configuration data structure
2267 * for mapping the events to the channel
2268 * \param mapXbarEvtFunc [IN] This is the user defined function for
2269 * mapping the cross bar event to channel.
2270 *
2271 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
2272 *
2273 * \note This function disables the global interrupts (by calling API
2274 * edma3OsProtectEntry with protection level
2275 * EDMA3_OS_PROTECT_INTERRUPT) while modifying the global data
2276 * structures, to make it re-entrant.
2277 */
2278 EDMA3_RM_Result EDMA3_RM_initXbarEventMap (EDMA3_RM_Handle hEdma,
2279 const EDMA3_RM_GblXbarToChanConfigParams * edmaGblXbarConfig,
2280 EDMA3_RM_mapXbarEvtToChan mapXbarEvtFunc,
2281 EDMA3_RM_xbarConfigScr configXbarScr);
2285 /**
2286 @}
2287 */
2289 #ifdef __cplusplus
2290 }
2291 #endif /* extern "C" */
2293 #endif /* _EDMA3_RM_H_ */