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