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