8b4dc22d8c0dd1099c5e3397cac9888c00b6ea72
1 /*
2 * Copyright (c) 2012, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 *
32 */
33 /**
34 * @file ti/sdo/fc/ecpy/ecpy.h
35 *
36 * @brief ECPY Definitions (C64P) - Functional DMA Library for use
37 * with the EDMA3 DMA peripheral.
38 * Provides a comprehensive list of DMA operations an algorithm
39 * can perform on logical DMA channels it acquires through the
40 * IRES_EDMA3CHAN protocol.
41 *
42 * @remark ECPY library contains two sets of functions: direct and
43 * non-direct.
44 * The direct APIs are functions prefixed with 'ECPY_direct' and
45 * are faster due to less state maintanence, fewer checks and/or
46 * lack of PaRAM shadowing of the 1st transfer. As a result they
47 * are slightly harder and require the caller to ensure integrity
48 * of state, for example, to make sure each ECPY_directStart call
49 * is matched with exactly one ECPY_directWait call. Another
50 * example is the need to remember to re-configure first transfer
51 * following a linked transfer or single 3D transfer.
52 *
53 * The non-direct APIs are slightly easier to use and maintain
54 * state and persistence of 1st transfer's settings across
55 * transfers.
56 *
57 * It is important to *not* mix and match direct and non-direct
58 * functions for any given channel, as this may result in
59 * unexpected behavior.
60 */
62 /**
63 * @defgroup ti_sdo_fc_ecpy_ECPY ECPY (C64P)
64 *
65 * The ECPY module provides a comprehensive list of DMA operations
66 * applications or algorithms can perform on logical DMA channels
67 * it acquires through the IRES_EDMA3CHAN protocol. Example of ECPY
68 * operations include channel configuration, DMA transfer
69 * scheduling, and DMA transfer synchronization.
70 *
71 * @remark For additional information, please refer to the
72 * "Using DMA with Framework Components for 'C64x+" document.
73 */
74 #ifndef ti_sdo_fc_ecpy_ECPY_
75 #define ti_sdo_fc_ecpy_ECPY_
78 #ifdef __cplusplus
79 extern "C" {
80 #endif
82 /** @ingroup ti_sdo_fc_ecpy_ECPY */
83 /*@{*/
85 #define ti_sdo_fc_ires_NOPROTOCOLREV
86 #include <ti/sdo/fc/ires/edma3chan/ires_edma3Chan.h>
88 #define ECPY_GTNAME "ti.sdo.fc.ecpy"
90 /**
91 * @brief Name to pass to Diags_setMask() to enable logging for ECPY
92 * functions. For example,
93 * Diags_setMask(ECPY_MODNAME"+EX1234567");
94 * turns on all Log statements in this module.
95 * Diags_setMask() must be called after initialization to take
96 * effect.
97 */
98 #define ECPY_MODNAME "ti.sdo.fc.ecpy"
101 /**
102 * @brief ECPY 16-bit param field structure. These values are passed to
103 * ECPY_configure16() to indicate the field of the
104 * ECPY_Params structure to be changed.
105 */
106 typedef enum ECPY_ParamField16b {
108 ECPY_PARAMFIELD_ELEMENTSIZE = 8,
109 ECPY_PARAMFIELD_NUMELEMENTS = 10 ,
110 ECPY_PARAMFIELD_ELEMENTINDEX_SRC = 16,
111 ECPY_PARAMFIELD_ELEMENTINDEX_DST = 18,
112 ECPY_PARAMFIELD_FRAMEINDEX_SRC = 24,
113 ECPY_PARAMFIELD_FRAMEINDEX_DST = 26,
114 ECPY_PARAMFIELD_NUMFRAMES = 28
116 } ECPY_ParamField16b;
118 /**
119 * @brief ECPY 32-bit param field structure. These values are passed to
120 * ECPY_configure32() to indicate the field of the
121 * ECPY_Params structure to be changed.
122 */
123 typedef enum ECPY_ParamField32b {
125 ECPY_PARAMFIELD_SRCADDR = 4,
126 ECPY_PARAMFIELD_DSTADDR = 12,
127 ECPY_PARAMFIELD_ELEMENTINDEXES = 16,
128 ECPY_PARAMFIELD_FRAMEINDEXES = 24
130 } ECPY_ParamField32b;
132 /**
133 * @brief ECPY DMA Transfer Types:
134 *
135 * Note that all transfers can be specified using the ECPY_2D2D transfer
136 * type, and providing element and frame indices for both source and
137 * destination. However, the other transfer types are provided to simplify
138 * configuration when applicable. For example, when using the ECPY_1D2D
139 * transfer type, you do not need to set the source element and frame
140 * indices in the ECPY_Params structure.
141 */
142 typedef enum ECPY_TransferType {
144 /**
145 * Only one element is copied from source to destination.
146 * The size of the element is specified in the elementSize field of
147 * ECPY_Params
148 */
149 ECPY_1D1D,
151 /**
152 * After each element is copied to destination, the source
153 * and destination of the next element to copy is updated
154 * as follows:
155 * - src = src + element size
156 * - dst = dst + destination element index
157 *
158 * After an entire frame is copied (the frame size specified by the
159 * numElements field of ECPY_Params), the source and destination of
160 * the next frame to copy are given by:
161 * - src = src + element size
162 * - dst = start of frame + destination frame index
163 */
164 ECPY_1D2D,
166 /**
167 * This is similar to ECPY_1D2D, except that source and
168 * destination are updated after an element is copied,
169 * as follows:
170 * - src = src + source element index
171 * - dst = dst + element size
172 *
173 * After an entire frame is copied by:
174 * - src = start of frame + source frame index
175 * - dst = dst + element size
176 */
177 ECPY_2D1D,
179 /**
180 * This transfer type combines ECPY_1D2D and ECPY_2D1D,
181 * so that source and destination are updated after an
182 * element is copied by:
183 * - src = src + source element index
184 * - dst = dst + destination element index
185 *
186 * After a frame is copied by:
187 * - src = start of frame + source frame index
188 * - dst = start of frame + destination frame index
189 */
190 ECPY_2D2D
191 } ECPY_TransferType;
193 /**
194 * @brief Handle to "logical" ECPY Channel
195 */
196 typedef struct ECPY_Obj *ECPY_Handle;
199 /**
200 * @brief DMA transfer specific parameters. Defines the configuration
201 * of a logical channel.
202 */
203 typedef struct ECPY_Params {
205 /** 1D1D, 1D2D, 2D1D or 2D2D */
206 ECPY_TransferType transferType;
208 /** Source Address of the DMA transfer */
209 Void * srcAddr;
211 /** Destination Address of the DMA transfer */
212 Void * dstAddr;
214 /** Number of consecutive bytes in each 1D transfer vector (ACNT) */
215 unsigned short elementSize;
217 /** Number of 1D vectors in 2D transfers (BCNT) */
218 unsigned short numElements;
220 /** Number of 1D1D, 1D2D, 2D1D or 2D2D frames to transfer (CCNT) */
221 unsigned short numFrames ;
223 /**
224 * Offset in number of bytes from beginning of each 1D vector to the
225 * beginning of the next 1D vector. (SBIDX)
226 */
227 short srcElementIndex;
229 /**
230 * Offset in number of bytes from beginning of each 1D vector to the
231 * beginning of the next 1D vector. (DBIDX)
232 */
233 short dstElementIndex;
235 /**
236 * Offset in number of bytes from beginning of 1D vector of current
237 * (source) frame to the beginning of next frame's first 1D vector.
238 * (SCIDX): signed value between -32768 and 32767.
239 */
240 short srcFrameIndex;
242 /**
243 * Offset in number of bytes from beginning of 1D vector of current
244 * (destination) frame to the beginning of next frame's first 1D vector.
245 * (DCIDX): signed value between -32768 and 32767.
246 */
247 short dstFrameIndex;
249 } ECPY_Params;
252 /**
253 * @brief Configures the DMA transfer settings for the transfer=transferNo
254 * of the logical channel. Except for transferNo==1, the physical
255 * EDMA3 PaRAM associated with the transfer is modified. For
256 * transferNo==1 a "shadow" of the PaRAM registers gets configured,
257 * so that the configuration of 1st transfer remains persistent
258 * following ECPY_startEdma() calls.
259 *
260 * @param[in] handle ECPY channel handle.
261 * @param[in] params DMA transfer specific parameters used to
262 * configure this logical DMA channel.
263 * @param[in] transferNo Indicates the individual transfer to be
264 * configured using the passed 'params'
265 *
266 * @pre channel must be in active state
267 * @pre valid ECPY_Handle handle
268 * @pre 1 <= transferNo <= originally requested number of transfers
269 * @post Intermediate transfers are programmed with TCCMODE set to Early
270 * (default mode when channel is created ) or Normal Completion
271 * depending on the most recently configured Transfer Completion
272 * mode.
273 *
274 * @remarks Both an inlined version and a non-inlined version of this
275 * function are supported. To use the inlined version, add the
276 * line \#define ECPY_CONFIGURE_INLINE or
277 * \#define ECPY_INLINE_ALL to the source file where this
278 * function is used. The \#define must go above the line,
279 * \#include <ecpy.h>. By default, this function will not be
280 * inlined. Another alternative is to define the macro in the
281 * build option of the file or of the project file.
282 */
283 #if defined(ECPY_CONFIGURE_INLINE) || defined(ECPY_INLINE_ALL)
284 #include <ti/sdo/fc/ecpy/ecpy_configure.h>
285 #else
286 Void ECPY_configure(ECPY_Handle handle, ECPY_Params * restrict params,
287 short transferNo);
288 #endif
290 /**
291 * @brief Configure the DMA transfer settings of handle's 'transferNo'
292 * transfer. This function always directly configures the physical
293 * EDMA3 PaRAM associated with the transfer. Since no shadow is
294 * used for the 1st transfer, the configuration settings of the
295 * 1st transfer gets lost following linked transfers or when the
296 * 1st transfer is a 3D transfer (numFrames > 1).
297 *
298 * @param[in] handle ECPY channel handle.
299 * @param[in] params DMA transfer specific parameters used to
300 * configure this logical DMA channel.
301 * @param[in] transferNo Indicates the individual transfer to be
302 * configured using the passed 'params'
303 *
304 * @pre channel must be in active state
305 * @pre valid ECPY_Handle handle
306 * @pre 1 <= transferNo <= originally requested number of transfers
307 * @post Intermediate transfers are programmed with TCCMODE set to Early
308 * (default mode when channel is created ) or Normal Completion
309 * depending on the most recently configured Transfer Completion
310 * mode.
311 *
312 * @remarks Both an inlined version and a non-inlined version of this
313 * function are supported. To use the inlined version, add the
314 * line \#define ECPY_DIRECTCONFIGURE_INLINE or
315 * \#define ECPY_INLINE_ALL to the source file where this
316 * function is used. The \#define must go above the line,
317 * \#include <ecpy.h>. By default, this function will not be
318 * inlined. Another alternative is to define the macro in the
319 * build option of the file or of the project file.
320 */
321 #if defined(ECPY_DIRECTCONFIGURE_INLINE) || defined(ECPY_INLINE_ALL)
322 #include <ti/sdo/fc/ecpy/ecpy_directconfigure.h>
323 #else
324 Void ECPY_directConfigure(ECPY_Handle handle, ECPY_Params * restrict params,
325 short transferNo);
326 #endif
329 /**
330 * @brief Modify the 16-bit DMA transfer parameter, indicated by the
331 * parameter field id, fieldId, of the current channel settings.
332 *
333 * @param[in] handle IRES_EDMA3CHAN channel handle.
334 * @param[in] fieldId Indicates which of the parameters is to be
335 * modified.
336 * @param[in] value New value of the parameter to be modified.
337 * @param[in] transferNo Indicates which transfer the parameters correspond
338 * to (same value that would be passed to
339 * ECPY_configure()).
340 *
341 * @pre Algorithm instance must be in "active" state using IALG
342 * interface.
343 *
344 * @pre Channel must be in "active" state.
345 *
346 * @pre ECPY_configure() must have previously been called at least once
347 * since channel activation.
348 * @pre 1 <= transferNo <= originally requested number of transfers
349 *
350 * @remarks Both an inlined version and a non-inlined version of this
351 * function are supported. To use the inlined version, add the
352 * line \#define ECPY_CONFIGURE16_INLINE or
353 * \#define ECPY_INLINE_ALL to the source file where this
354 * function is used. The \#define must go above the line,
355 * \#include <ecpy.h>. By default, this function will not be
356 * inlined. Another alternative is to define the macro in the
357 * build option of the file or of the project file.
358 *
359 * @remarks Once a channel has been configured once with ECPY_configure(),
360 * ECPY_configure16() can be used to update any of the
361 * 16-bit parameter fields, for example, the number of elements
362 * in a frame to be transferred.
363 *
364 */
365 #if defined(ECPY_CONFIGURE16_INLINE) || defined(ECPY_INLINE_ALL)
366 #include <ti/sdo/fc/ecpy/ecpy_configure16.h>
367 #else
368 Void ECPY_configure16(ECPY_Handle handle, ECPY_ParamField16b fieldId,
369 unsigned short value, short transferNo);
370 #endif
372 /**
373 * @brief Modify the 16-bit DMA transfer parameter, indicated by the
374 * parameter field id, fieldId, of the current channel settings.
375 * This function always directly configures the physical
376 * EDMA3 PaRAM's 16-bit half of the 32-bit registered associated
377 * with the transfer & field . No shadow is used.
378 *
379 * @param[in] handle IRES_EDMA3CHAN channel handle.
380 * @param[in] fieldId Indicates which of the parameters is to be
381 * modified.
382 * @param[in] value New value of the parameter to be modified.
383 * @param[in] transferNo Indicates which transfer the parameters correspond
384 * to (same value that would be passed to
385 * ECPY_directConfigure()).
386 *
387 * @pre Algorithm instance must be in "active" state using IALG
388 * interface.
389 *
390 * @pre Channel must be in "active" state.
391 * @pre ECPY_directConfigure() must have been called at least once
392 * since channel activation.
393 * @pre 1 <= transferNo <= originally requested number of transfers
394 *
395 * @remarks Both an inlined version and a non-inlined version of this
396 * function are supported. To use the inlined version, add the
397 * line \#define ECPY_DIRECTCONFIGURE16_INLINE or
398 * \#define ECPY_INLINE_ALL to the source file where this
399 * function is used. The \#define must go above the line,
400 * \#include <ecpy.h>. By default, this function will not be
401 * inlined. Another alternative is to define the macro in the
402 * build option of the file or of the project file.
403 *
404 * @remarks Once a channel has been configured with ECPY_directConfigure(),
405 * ECPY_directConfigure16() can be used to update any of the
406 * 16-bit parameter fields, for example, the number of elements
407 * in a frame to be transferred.
408 *
409 */
410 #if defined(ECPY_DIRECTCONFIGURE16_INLINE) || defined(ECPY_INLINE_ALL)
411 #include <ti/sdo/fc/ecpy/ecpy_directconfigure16.h>
412 #else
413 Void ECPY_directConfigure16(ECPY_Handle handle, ECPY_ParamField16b fieldId,
414 unsigned short value, short transferNo);
415 #endif
417 /**
418 * @brief Modify the 32-bit DMA transfer parameter, indicated by the
419 * parameter field id, fieldId, of the current channel settings.
420 *
421 * @param[in] handle ECPY channel handle.
422 * @param[in] fieldId Indicates which of the parameters is to be modified.
423 * @param[in] value New value of the parameter to be modified.
424 * @param[in] transferNo Indicates which transfer the parameters correspond
425 * to (same value that would be passed to
426 * ECPY_configure()).
427 *
428 * @pre @c handle must be a valid channel handle.
429 *
430 * @pre Algorithm instance must be in "active" state using IALG
431 * interface.
432 *
433 * @pre Channel must be in 'active' state.
434 *
435 * @pre ECPY_configure() must have previously been called at least once
436 * since channel activation.
437 * @pre 1 <= transferNo <= originally requested number of transfers
438 *
439 * @remarks Once a channel has been configured once with ECPY_configure(),
440 * ECPY_configure32() can be used to update any of the
441 * 32-bit parameter fields, for example, the source address of
442 * the data to be transferred.
443 *
444 * @remarks Both an inlined version and a non-inlined version of this
445 * function are supported. To use the inlined version, add the
446 * line \#define ECPY_CONFIGURE32_INLINE or
447 * \#define ECPY_INLINE_ALL to the source file where this
448 * function is used. The \#define must go above the line,
449 * \#include <ecpy.h>. By default, this function will not be
450 * inlined. Another alternative is to define the macro in the
451 * build option of the file or of the project file.
452 *
453 */
454 #if defined(ECPY_CONFIGURE32_INLINE) || defined(ECPY_INLINE_ALL)
455 #include <ti/sdo/fc/ecpy/ecpy_configure32.h>
456 #else
457 Void ECPY_configure32(ECPY_Handle handle, ECPY_ParamField32b fieldId,
458 unsigned int value, short transferNo);
459 #endif
461 /**
462 * @brief Modify the 32-bit DMA transfer parameter, indicated by the
463 * parameter field id, fieldId, of the current channel settings.
464 *
465 * @param[in] handle ECPY channel handle.
466 * @param[in] fieldId Indicates which of the parameters is to be
467 * modified.
468 * @param[in] value New value of the parameter to be modified.
469 * @param[in] transferNo Indicates which transfer the parameters correspond
470 * to (same value that would be passed to
471 * ECPY_configure()).
472 *
473 * @pre @c handle must be a valid channel handle.
474 *
475 * @pre Algorithm instance must be in "active" state using IALG
476 * interface.
477 *
478 * @pre Channel must be in 'active' state.
479 *
480 * @pre ECPY_directConfigure() must have previously been called at
481 * least once since channel activation.
482 * @pre 1 <= transferNo <= originally requested number of transfers
483 *
484 * @remarks Once a channel has been configured once with
485 * ECPY_directConfigure(), the ECPY_directConfigure32() functino
486 * can be called to update any of the 32-bit parameter fields,
487 * for example, the source address of the data to be transferred.
488 *
489 * @remarks Both an inlined version and a non-inlined version of this
490 * function are supported. To use the inlined version, add the
491 * line \#define ECPY_DIRECTCONFIGURE32_INLINE or
492 * \#define ECPY_INLINE_ALL to the source file where this
493 * function is used. The \#define must go above the line,
494 * \#include <ecpy.h>. By default, this function will not be
495 * inlined. Another alternative is to define the macro in the
496 * build option of the file or of the project file.
497 *
498 */
499 #if defined(ECPY_DIRECTCONFIGURE32_INLINE) || defined(ECPY_INLINE_ALL)
500 #include <ti/sdo/fc/ecpy/ecpy_directconfigure32.h>
501 #else
502 Void ECPY_directConfigure32(ECPY_Handle handle, ECPY_ParamField32b fieldId,
503 unsigned int value, short transferNo);
504 #endif
506 /**
507 * @brief Indicate that a given transfer will be the last in a sequence
508 * of linked transfers.
509 *
510 * This API can be used to dynamically change the number of
511 * transfers in a linked transfers.
512 *
513 * @param[in] handle ECPY channel handle.
514 * @param[in] transferNo Indicates the transfer number that will be the last
515 * one of the set of linked transfers.
516 *
517 * @pre Valid channel handle.
518 * @pre Channel must be in 'active' state.
519 * @pre 1 <= transferNo <= originally requested number of transfers
520 * @pre ECPY_cnfigure() must have previously been called at least
521 * once since channel activation.
522 *
523 * @remarks This API can be used if a channel was created to transfer
524 * 'numTransfers' linked transfers, but at some point, it will be
525 * used to transfer a different number of transfers.
526 *
527 * @remarks Both an inlined version and a non-inlined version of this
528 * function are supported. To use the inlined version, add the
529 * line \#define ECPY_SETFINAL_INLINE or
530 * \#define ECPY_INLINE_ALL to the source file where this
531 * function is used. The \#define must go above the line,
532 * \#include <ecpy.h>. By default, this function will not be
533 * inlined. Another alternative is to define the macro in the
534 * build option of the file or of the project file.
535 *
536 */
537 #if defined(ECPY_SETFINAL_INLINE) || defined(ECPY_INLINE_ALL)
538 #include <ti/sdo/fc/ecpy/ecpy_setfinal.h>
539 #else
540 Void ECPY_setFinal(ECPY_Handle handle, short transferNo);
541 #endif
543 /**
544 * @brief Indicate that a given transfer will be the last in a sequence
545 * of linked transfers.
546 *
547 * This API can be used to dynamically change the number of
548 * transfers in a linked transfers.
549 *
550 * @param[in] handle ECPY channel handle.
551 * @param[in] transferNo Indicates the transfer number that will be the last
552 * one of the set of linked transfers.
553 *
554 * @pre Valid channel handle.
555 * @pre Channel must be in 'active' state.
556 * @pre 1 <= transferNo <= originally requested number of transfers
557 * @pre ECPY_directConfigure() must have previously been called at
558 * least once since channel activation.
559 *
560 * @remarks This API can be used if a channel was created to transfer
561 * 'numTransfers' linked transfers, but at some point, it will be
562 * used to transfer a different number of transfers.
563 *
564 * @remarks Both an inlined version and a non-inlined version of this
565 * function are supported. To use the inlined version, add the
566 * line \#define ECPY_DIRECTSETFINAL_INLINE or
567 * \#define ECPY_INLINE_ALL to the source file where this
568 * function is used. The \#define must go above the line,
569 * \#include <ecpy.h>. By default, this function will not be
570 * inlined. Another alternative is to define the macro in the
571 * build option of the file or of the project file.
572 *
573 */
574 #if defined(ECPY_DIRECTSETFINAL_INLINE) || defined(ECPY_INLINE_ALL)
575 #include <ti/sdo/fc/ecpy/ecpy_directsetfinal.h>
576 #else
577 Void ECPY_directSetFinal(ECPY_Handle handle, short transferNo);
578 #endif
580 /**
581 * @brief Indicate the memory space that DMA transfers submitted to
582 * the channel associated with the handle will modify.
583 * This information can be used for channel to TC Queue mapping
584 * for avoiding known Silicon GEM lockup issues or for
585 * performance improvements.
586 *
587 * @param[in] handle ECPY channel handle.
588 * @param[in] mode DMA destination description of type
589 * IRES_EDMA3CHAN_DmaDestType.
590 */
591 Void ECPY_setDestinationMemoryMode(ECPY_Handle handle, short mode);
593 /**
594 * @brief Submit a single or linked transfer using the most recently
595 * configured transfer parameter settings.
596 *
597 * @param[in] handle ECPY channel handle.
598 *
599 * @pre Valid channel handle.
600 * @pre Channel must be in 'active' state.
601 *
602 * @pre Channel must be in 'configured' state.
603 * @pre ECPY_configure() must be called at least once for each transfer
604 * that will be started.
605 *
606 * @remarks Most recent ECPY_configure(), ECPY_configure16 and
607 * ECPY_configure32 settings will be in effect for each transfer.
608 *
609 * @pre When the number of transfers assigned to the channel are > 1,
610 * this function will submit a set of linked EDMA transfers,
611 * ordered by the transferNo's of the channel.
612 * The final transfer of the linked set will be the transfer
613 * indicated by the most recent ECPY_setFinal() call.
614 * If no ECPY_setFinal has been previously called, then
615 * all transfers assigned to the channel will be linked together.
616 *
617 * @post handle->transferPending = TRUE
618 *
619 * @remarks Both an inlined version and a non-inlined version of this
620 * function are supported. To use the inlined version, add the
621 * line \#define ECPY_START_INLINE or
622 * \#define ECPY_INLINE_ALL to the source file where this
623 * function is used. The \#define must go above the line,
624 * \#include <ecpy.h>. By default, this function will not be
625 * inlined. Another alternative is to define the macro in the
626 * build option of the file or of the project file.
627 *
628 */
629 #if defined(ECPY_START_INLINE) || defined(ECPY_INLINE_ALL)
630 #include <ti/sdo/fc/ecpy/ecpy_start.h>
631 #else
632 Void ECPY_start(ECPY_Handle handle);
633 #endif
636 /**
637 * @brief Submit a single or linked transfer using the most recently
638 * 'direct' configured transfer parameter settings.
639 *
640 * @param[in] handle ECPY channel handle.
641 *
642 * @pre Valid channel handle.
643 * @pre Channel must be in 'active' state.
644 *
645 * @pre Channel must be in 'direct configured' state.
646 * @pre ECPY_directConfigure() must be called at least once for each
647 * transfer that will be started.
648 * @pre 1st Transfer of the channel must always be re-configured via
649 * direct configure APIs following a (linked) ECPY_directStartEdma
650 * i.e. when the number of the most recent start > 1) or when the
651 * 1st transfer of the previous start was a 3D transfer
652 * (numFrames > 1).
653 *
654 * @remarks Most recent ECPY_directConfigure(), ECPY_directConfigure16 and
655 * ECPY_directConfigure32 settings will always be in effect for
656 * each transfer w/transferNo > 1.
657 * Transfer settings of transferNo=1 will be only preserved if the
658 * most recent ECPY_directStartEdma resulted in a single
659 * (non-linked) transfer with numFrames == 1.
660 *
661 * @pre When the number of transfers assigned to the channel are > 1,
662 * this function will submit a set of linked EDMA transfers,
663 * ordered by the transferNo's of the channel.
664 * The final transfer of the linked set will be the transfer
665 * indicated by the most recent ECPY_directSetFinal() call.
666 * If no ECPY_setFinal has been previously called, then
667 * all transfers assigned to the channel will be linked together.
668 *
669 * @remarks Both an inlined version and a non-inlined version of this
670 * function are supported. To use the inlined version, add the
671 * line \#define ECPY_DIRECTSTARTEDMA_INLINE or
672 * \#define ECPY_INLINE_ALL to the source file where this
673 * function is used. The \#define must go above the line,
674 * \#include <ecpy.h>. By default, this function will not be
675 * inlined. Another alternative is to define the macro in the
676 * build option of the file or of the project file.
677 */
678 #if defined(ECPY_DIRECTSTARTEDMA_INLINE) || defined(ECPY_INLINE_ALL)
679 #include <ti/sdo/fc/ecpy/ecpy_directstartedma.h>
680 #else
681 Void ECPY_directStartEdma(ECPY_Handle handle);
682 #endif
684 /**
685 * @brief ECPY_directStartQdma has not been implemented.
686 */
687 Void ECPY_directStartQdma(ECPY_Handle handle);
690 /**
691 * @brief Wait for all data transfers on a logical channel to complete.
692 *
693 *
694 * @param[in] handle ECPY channel handle.
695 *
696 * @pre Valid channel handle
697 * @pre Channel must be in 'active' state.
698 * @pre ECPY_wait can be called back to back or without having submitted
699 * transfers to the channel. For the case there is no pending
700 * transfer on the channel it will return immediately.
701 *
702 * @post ECPY_wait will reset channel handle's transferPending flag to 0
703 *
704 * @remarks This function will not return until all the previously submitted
705 * EDMA transfers on the channel have completed.
706 *
707 * @remarks Both an inlined version and a non-inlined version of this
708 * function are supported. To use the inlined version, add the
709 * line \#define ECPY_WAIT_INLINE or
710 * \#define ECPY_INLINE_ALL to the source file where this
711 * function is used. The \#define must go above the line,
712 * \#include <ecpy.h>. By default, this function will not be
713 * inlined. Another alternative is to define the macro in the
714 * build option of the file or of the project file.
715 */
716 #if defined(ECPY_WAIT_INLINE) || defined(ECPY_INLINE_ALL)
717 #include <ti/sdo/fc/ecpy/ecpy_wait.h>
718 #else
719 Void ECPY_wait(ECPY_Handle handle);
720 #endif
722 /**
723 * @brief Wait for all EDMA data transfers submitted to the logical
724 * channel via ECPY_directStartEdma to complete.
725 *
726 *
727 * @param[in] handle ECPY channel handle.
728 *
729 * @pre Valid channel handle
730 * @pre Channel must be in 'active' state.
731 *
732 * @pre ECPY_directWait requires that a transfer has been submitted
733 * to the channel using ECPY_directStartEdma. Otherwise it will
734 * block indefinitely.
735 *
736 * @pre ECPY_directWait can not be called back to back or without
737 * having started EDMA transfers on the channel.
738 *
739 * @remarks ECPY_directWait will not maintain channel handle's
740 * transferPending state.
741 *
742 * @remarks This function will not return until all the data
743 * transfers on the given channel have completed.
744 *
745 * @remarks Both an inlined version and a non-inlined version of this
746 * function are supported. To use the inlined version, add the
747 * line \#define ECPY_DIRECTWAIT_INLINE or
748 * \#define ECPY_INLINE_ALL to the source file where this
749 * function is used. The \#define must go above the line,
750 * \#include <ecpy.h>. By default, this function will not be
751 * inlined. Another alternative is to define the macro in the
752 * build option of the file or of the project file.
753 */
754 #if defined(ECPY_DIRECTWAIT_INLINE) || defined(ECPY_INLINE_ALL)
755 #include <ti/sdo/fc/ecpy/ecpy_directwait.h>
756 #else
757 Void ECPY_directWait(ECPY_Handle handle);
758 #endif
760 /**
761 * @brief Activate the given channel.
762 *
763 * @param[in] handle ECPY channel handle.
764 *
765 * @pre @c handle must be a valid channel handle.
766 *
767 * @pre Algorithm instance must be in "active" state using IALG
768 * interface.
769 *
770 * @pre @c handle must be a valid handle obtained by ECPY_createHandle.
771 *
772 * @post Channel is in 'active' state, any ECPY APIs can be called
773 * using this handle.
774 */
775 Void ECPY_activate(ECPY_Handle handle);
777 /**
778 * @brief Create an ECPY Handle using the supplied IRES_EDMA3CHAN handle
779 *
780 * @param[in] handle IRES_EDMA3CHAN channel handle.
781 * @param[in] alg IALG handle.
782 *
783 * @pre @c handle must be a valid handle.
784 *
785 * @post Early Completion Mode is enabled for all Intermediate Transfers.
786 * Early Completion Transfer completion mode can be disabled if
787 * needed via the ECPY_setEarlyCompletionMode() API.
788 *
789 */
790 ECPY_Handle ECPY_createHandle(IRES_EDMA3CHAN2_Handle handle, IALG_Handle alg);
792 /**
793 * @brief Delete ECPY_Handle
794 *
795 * @param[in] handle ECPY channel handle.
796 *
797 * @pre @c handle must be a valid handle obtained by ECPY_createHandle.
798 *
799 */
800 Void ECPY_deleteHandle(ECPY_Handle handle);
802 /**
803 * @brief Deactivates the given channel.
804 *
805 * @param[in] handle ECPY channel handle.
806 *
807 * @pre @c handle must be a valid channel handle.
808 *
809 * @pre Channel must be in 'active' state.
810 *
811 * @pre Algorithm instance must be in 'active' state using IALG
812 * interface
813 *
814 * @post Channel is in 'deactivated' state.
815 */
816 Void ECPY_deactivate(ECPY_Handle handle);
818 /**
819 * @brief Setting the TCCMODE (Early or Normal) affects only the
820 * 'intermediate transfers' of the linked transfers submitted
821 * using this channel.
822 * All subsequent direct and non-direct ECPY_configure* calls
823 * using this ecpyHandle will program the OPT's TCCMODE to select
824 * Early or Normal completion mode based on the 'enabled' argument.
825 *
826 * Selecting the Early Completion mode may lead to performance
827 * improvements by increasing the EDMA throughput of linked
828 * transfers by submitting each transfer request from the EDMA
829 * Channel Controller to the Transfer Controller without waiting
830 * for the completion of the previous transfer from the Transfer
831 * Controller.
832 *
833 * @param[in] handle ECPY channel handle.
834 * @param[in] enabled 1/TRUE to set TCCMODE to 1 (Early Completion)
835 * 0/FALSE to set TCCMODE to 1 (Normal Completion)
836 *
837 * @post Channel Intermediate Transfer Completion Mode is set according
838 * to the 'enabled' parameter. The selected mode applies to all
839 * subsequent configure operations of the intermediate transfers.
840 */
841 Void ECPY_setEarlyCompletionMode(ECPY_Handle handle, short enabled);
843 /**
844 * @brief Initialize the ECPY module. Called by framework.
845 */
846 Void ECPY_init(Void);
848 /**
849 * @brief Finalization of the ECPY module.
850 */
851 Void ECPY_exit(Void);
853 /**
854 * @brief Memory allocation function signature for module configuration.
855 */
856 typedef Bool (ECPY_PersistentAllocFxn)(IALG_MemRec *memTab, Int numRecs);
858 /**
859 * @brief Memory deallocation function signature for module configuration.
860 */
861 typedef Void (ECPY_PersistentFreeFxn)(IALG_MemRec *memTab, Int numRecs);
863 /**
864 * @brief Scratch Memory allocation function for all shared scratch
865 * ECPY handle state.
866 */
867 typedef Bool (ECPY_ScratchAllocFxn)(IALG_Handle alg, Int scratchId,
868 IALG_MemRec *memTab, Int numRecs);
869 /**
870 * @brief Scratch Memory free function for all scratch allocated
871 * memory in ECPY Handle.
872 */
873 typedef Void (ECPY_ScratchFreeFxn)(Int mutexId, Void *addr, UInt size);
875 /**
876 * @brief Function, when supplied, returns the scratchId associated
877 * with the algorithm instance whose handle is passed.
878 */
879 typedef Int (ECPY_getScratchIdFxn)(IALG_Handle alg);
882 /**
883 * @brief The module configuration structure for ECPY.
884 * It is set at design time by the system integrator to register
885 * customize memory allocation/free implementations.
886 *
887 * @remarks Typically, system integrators configure these settings using
888 * XDC config scripts. System integrators that use that method
889 * of configuration can ignore this structure definition. It's
890 * auto-generated during the config step by the XDC Tools.
891 */
892 typedef struct ECPY_CfgParams {
894 /**
895 * @brief Memory allocation function for all ECPY memory requirements
896 */
897 ECPY_PersistentAllocFxn * allocFxn;
899 /**
900 * @brief Memory free function for all ECPY memory requirements
901 */
902 ECPY_PersistentFreeFxn * freeFxn;
904 /**
905 * @brief Scratch Memory allocation function for all shared scratch
906 * ECPY handle state.
907 */
908 ECPY_ScratchAllocFxn * scratchAllocFxn;
910 /**
911 * @brief Scratch Memory free function for all scratch allocated
912 * memory in ECPY Handle.
913 */
914 ECPY_ScratchFreeFxn * scratchFreeFxn;
916 /**
917 * @brief Function, when supplied, returns the scratchId associated
918 * with the algorithm instance whose handle is passed.
919 */
920 ECPY_getScratchIdFxn *getScratchIdFxn;
921 } ECPY_CfgParams;
923 /**
924 * @brief Initialization parameters for the ECPY module
925 */
926 extern __FAR__ ECPY_CfgParams ECPY_CFG_PARAMS;
928 /*@}*/
930 #ifdef __cplusplus
931 }
932 #endif /* extern "C" */
935 #endif /* ti_sdo_fc_ecpy_ECPY_ */