EdmaMgr : Added support for transfers with large pitch.
[mfp/fcdev.git] / packages / ti / sdo / fc / edmamgr / edmamgr.h
1 /*
2  * Copyright (c) 2013-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/edmamgr/edmamgr.h
34  *
35  *  @brief      EdmaMgr Definitions - Functional library for use
36  *              with the EDMA3 DMA peripheral.
37  *
38  *  The intent of the EdmaMgr component is to provide a simple and intuitive
39  *  interface for acquiring and using EDMA3 resources for asynchronous data
40  *  transfers.
41  *
42  *  Once the framework provides the initial configuration to EdmaMgr_init(),
43  *  malloc/free style APIs are used to obtain/release resources. The actual
44  *  transfer has been abstracted to multiple APIs which can transfer data of
45  *  various dimensions.
46  */
48 /**
49  *  @defgroup   ti_sdo_fc_edmamgr_EdmaMgr EdmaMgr
50  *
51  *  @brief      EDMA3 Functional library
52  */
53 #ifndef ti_sdo_fc_edmamgr_EdmaMgr_
54 #define ti_sdo_fc_edmamgr_EdmaMgr_
56 /** @ingroup    ti_sdo_fc_ecpy_EdmaMgr */
57 /*@{*/
59 #include <stdint.h>
60 #include <string.h>
62 #include <ti/sdo/fc/ecpy/ecpy.h>
63 #include <ti/xdais/ires.h>
64 #include <ti/sdo/fc/ires/edma3chan/ires_edma3Chan.h>
65 #include <ti/sdo/fc/edma3/edma3_config.h>
68 /**
69  *  @brief      Handle to an EdmaMgr instance.
70  */
71 typedef void *EdmaMgr_Handle;
74 /** @cond INTERNAL */
75 typedef struct _EdmaMgr_Channel {
76   IRES_EDMA3CHAN_Handle        edmaHandle;
77   ECPY_Handle                  ecpyHandle;
78   IRES_EDMA3CHAN_ProtocolArgs  edmaArgs;
79   Bool                         resActive;
80   Bool                         xferPending;
81   IRES_YieldFxn                yieldFxn;
82   IRES_YieldArgs               yieldArgs;
83   IRES_YieldContext            yieldContext;
84   uint32_t                     optChained;
85   IALG_MemRec                  addrTable;
86   struct _EdmaMgr_Channel     *chainedChannel;
87 } EdmaMgr_Channel;
88 /** @endcond */
90 #define EdmaMgr_SUCCESS           0  /**< Success */
91 #define EdmaMgr_ERROR_INVARG     -1  /**< Failure, Invalid Argument */
92 #define EdmaMgr_ERROR_INVCFG     -2  /**< Failure, Invalid Configuration */
93 #define EdmaMgr_ERROR_RMANINIT   -3  /**< Failure, RMAN initialization */
94 #define EdmaMgr_ERROR_INVHANDLE  -4  /**< Failure, Invalid Handle */
95 #define EdmaMgr_ERROR_FREE       -5  /**< Failure to free a resource */
97 /**
98  *  @brief      Initialize EdmaMgr
99  *
100  *  @param[in]  proc_id         Processor ID. This ID is used to index into the
101  *                              EDMA3_InstanceInitConfig array pointed to by the
102  *                              ti_sdo_fc_edmamgr_edma3RegionConfig variable.
103  *
104  *  @param[in]  edma3_config    Optional edma3_config which will override the
105  *                              configuration which is pointed to by
106  *                              ti_sdo_fc_edmamgr_edma3RegionConfig.
107  *
108  *  @retval     EdmaMgr_SUCCESS         @copydoc EdmaMgr_SUCCESS
109  *  @retval     EdmaMgr_ERROR_INVARG    @copydoc EdmaMgr_ERROR_INVARG
110  *  @retval     EdmaMgr_ERROR_INVCFG    @copydoc EdmaMgr_ERROR_INVCFG
111  *  @retval     EdmaMgr_ERROR_RMANINIT  @copydoc EdmaMgr_ERROR_RMANINIT
112  *
113  *  @remarks    @c edma3_config may be NULL to accept default values.
114  *
115  *  @remarks    The FC product includes an example (ex23_edmamgr) which
116  *              demonstrates how to set up a @c ti_sdo_fc_edma3RegionConfig
117  *              variable.
118  */
119 int32_t EdmaMgr_init
121   int32_t  proc_id,
122   void    *edma3_config
123 );
126 /**
127  *  @brief      Allocate an EdmaMgr channel
128  *
129  *  @param[in]  max_linked_transfers    Maximum linked transfers
130  *
131  *  @retval     NULL        Failure to allocate the channel
132  *  @retval     non-NULL    Success
133  *
134  *  @pre        EdmaMgr_init() must have first been called.
135  *
136  */
137 EdmaMgr_Handle EdmaMgr_alloc
139   int32_t max_linked_transfers
140 );
143 /**
144  *  @brief      Allocate an EdmaMgr channel for "Large" 1D2D or 2D1D transfers
145  *              which have a pitch outside the range [-32768,32768].
146  *
147  *  @param[in]  max_num_lines    Maximum number of lines to be transfered.
148  *
149  *  @retval     NULL        Failure to allocate the channel
150  *  @retval     non-NULL    Success
151  *
152  *  @pre        EdmaMgr_init() must have first been called.
153  *
154  */
155 EdmaMgr_Handle EdmaMgr_allocLarge
157   int32_t max_num_lines
158 );
161 /**
162  *  @brief      Frees an EdmaMgr channel.
163  *
164  *  @param[in]  h       Handle returned from EdmaMgr_alloc().
165  *
166  *  @retval     EdmaMgr_SUCCESS         @copydoc EdmaMgr_SUCCESS
167  *  @retval     EdmaMgr_ERROR_INVHANDLE @copydoc EdmaMgr_ERROR_INVHANDLE
168  *  @retval     EdmaMgr_ERROR_FREE      @copydoc EdmaMgr_ERROR_FREE
169  *
170  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
171  */
172 int32_t EdmaMgr_free
174   EdmaMgr_Handle    h
175 );
178 /*
179  *  The below declarations are placed here as only a reference
180  *  (hence the comment block).
181  *
182  *  These functions are defined further below.
183  */
184 #if defined(EDMAMGR_INLINE_ALL)
185 #include <ti/sdo/fc/edmamgr/edmamgr_xfer.h>
186 #else
187 /**
188  *  @brief      Wait for transfers to complete
189  *
190  *  @param[in]  h       Handle returned from EdmaMgr_alloc().
191  *
192  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
193  *
194  *  @remarks    This function waits for all transfers on a specific channel
195  *              to complete.  It is a blocking call.
196  */
197 void EdmaMgr_wait
199   EdmaMgr_Handle    h
200 );
203 /**
204  *  @brief      Perform a single 1D->1D transfer
205  *
206  *  @param[in]  h           Handle returned from EdmaMgr_alloc().
207  *  @param[in]  src         Source address
208  *  @param[in]  dst         Destination address
209  *  @param[in]  num_bytes   Number of bytes to transfer
210  *
211  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
212  *
213  *  @remarks    Perform a single 1D->1D transfer of @c num_bytes bytes from
214  *              @c src address to @c dst address.
215  *
216  *  @sa EdmaMgr_copy1D1DLinked
217  */
218 int32_t EdmaMgr_copy1D1D
220   EdmaMgr_Handle    h,
221   void *restrict    src,
222   void *restrict    dst,
223   int32_t           num_bytes
224 );
226 /**
227  *  @brief      Perform a 1D->2D transfer
228  *
229  *  @param[in]  h           Handle returned from EdmaMgr_alloc().
230  *  @param[in]  src         Source address
231  *  @param[in]  dst         Destination address
232  *  @param[in]  num_bytes   Number of bytes to transfer
233  *  @param[in]  num_lines   Number of lines
234  *  @param[in]  pitch       Pitch
235  *
236  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
237  *
238  *  @remarks    Perform a 1D->2D transfer of @c num_bytes bytes.  The source
239  *              is one dimensional, and the destination is two dimensional.
240  *
241  *  @remarks    After every line of @c num_bytes is transferred, the @c src
242  *              address is incremented by @c num_bytes and the @c dst address
243  *              is incremented by @c pitch bytes.
244  */
245 int32_t EdmaMgr_copy1D2D
247   EdmaMgr_Handle    h,
248   void *restrict    src,
249   void *restrict    dst,
250   int32_t           num_bytes,
251   int32_t           num_lines,
252   int32_t           pitch
253 );
255 /**
256  *  @brief      Perform a 2D->1D transfer
257  *
258  *  @param[in]  h           Handle returned from EdmaMgr_alloc().
259  *  @param[in]  src         Source address
260  *  @param[in]  dst         Destination address
261  *  @param[in]  num_bytes   Number of bytes to transfer
262  *  @param[in]  num_lines   Number of lines
263  *  @param[in]  pitch       Pitch
264  *
265  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
266  *
267  *  @remarks    Perform a 2D->1D transfer of @c num_bytes bytes.  The source
268  *              is two dimensional, and the destination is one dimensional.
269  *
270  *  @remarks    After every line of @c num_bytes is transferred, the @c src
271  *              address is incremented by @c pitch and the @c dst address
272  *              is incremented by @c num_bytes bytes.
273  */
274 int32_t EdmaMgr_copy2D1D
276   EdmaMgr_Handle    h,
277   void *restrict    src,
278   void *restrict    dst,
279   int32_t           num_bytes,
280   int32_t           num_lines,
281   int32_t           pitch
282 );
284 /**
285  *  @brief      Perform a 2D->2D transfer of buffers with the same pitch
286  *
287  *  @param[in]  h           Handle returned from EdmaMgr_alloc().
288  *  @param[in]  src         Source address
289  *  @param[in]  dst         Destination address
290  *  @param[in]  num_bytes   Number of bytes to transfer
291  *  @param[in]  num_lines   Number of lines
292  *  @param[in]  pitch       Pitch
293  *
294  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
295  *
296  *  @remarks    Perform a 2D->2D transfer of @c num_bytes bytes.  The source
297  *              and destination are two dimensional.
298  *
299  *  @remarks    After every line of @c num_bytes is transferred, the @c src
300  *              address and @c dst address is incremented by @c pitch bytes.
301  */
302 int32_t EdmaMgr_copy2D2D
304   EdmaMgr_Handle    h,
305   void *restrict    src,
306   void *restrict    dst,
307   int32_t           num_bytes,
308   int32_t           num_lines,
309   int32_t           pitch
310 );
312 /**
313  *  @brief      Perform a 2D->2D transfer of buffers with different pitches
314  *
315  *  @param[in]  h           Handle returned from EdmaMgr_alloc().
316  *  @param[in]  src         Source address
317  *  @param[in]  dst         Destination address
318  *  @param[in]  num_bytes   Number of bytes to transfer
319  *  @param[in]  num_lines   Number of lines
320  *  @param[in]  src_pitch   Source buffer pitch
321  *  @param[in]  dst_pitch   Destination buffer pitch
322  *
323  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
324  *
325  *  @remarks    Perform a 2D->2D transfer of @c num_bytes bytes.  The source
326  *              and destination are two dimensional.
327  *
328  *  @remarks    After every line of @c num_bytes is transferred, the @c src
329  *              address is incremented by @c src_pitch bytes and the @c dst
330  *              address is incremented by @c dst_pitch bytes.
331  */
332 int32_t EdmaMgr_copy2D2DSep
334   EdmaMgr_Handle    h,
335   void *restrict    src,
336   void *restrict    dst,
337   int32_t           num_bytes,
338   int32_t           num_lines,
339   int32_t           src_pitch,
340   int32_t           dst_pitch
341 );
343 /**
344  *  @brief      Perform a group of linked 1D->1D transfers
345  *
346  *  @param[in]  h               Handle returned from EdmaMgr_alloc().
347  *  @param[in]  src[]           Array of source addresses
348  *  @param[in]  dst[]           Array of destination addresses
349  *  @param[in]  num_bytes[]     Array of number of bytes to transfer
350  *  @param[in]  num_transfers   Number of transfers
351  *
352  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
353  *
354  *  @sa EdmaMgr_copy1D1D
355  */
356 int32_t EdmaMgr_copy1D1DLinked
358   EdmaMgr_Handle    h,
359   void *restrict    src[],
360   void *restrict    dst[],
361   int32_t           num_bytes[],
362   int32_t           num_transfers
363 );
365 /**
366  *  @brief      Perform a group of linked 1D->2D transfers
367  *
368  *  @param[in]  h               Handle returned from EdmaMgr_alloc().
369  *  @param[in]  src[]           Array of source addresses
370  *  @param[in]  dst[]           Array of destination addresses
371  *  @param[in]  num_bytes[]     Array of number of bytes to transfer
372  *  @param[in]  num_lines[]     Array of lines to transfer
373  *  @param[in]  pitch[]         Array of pitches
374  *  @param[in]  num_transfers   Number of transfers
375  *
376  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
377  *
378  *  @sa EdmaMgr_copy1D2D
379  */
380 int32_t EdmaMgr_copy1D2DLinked
382   EdmaMgr_Handle    h,
383   void *restrict    src[],
384   void *restrict    dst[],
385   int32_t           num_bytes[],
386   int32_t           num_lines[],
387   int32_t           pitch[],
388   int32_t           num_transfers
389 );
391 /**
392  *  @brief      Perform a group of linked 2D->1D transfers
393  *
394  *  @param[in]  h               Handle returned from EdmaMgr_alloc().
395  *  @param[in]  src[]           Array of source addresses
396  *  @param[in]  dst[]           Array of destination addresses
397  *  @param[in]  num_bytes[]     Array of number of bytes to transfer
398  *  @param[in]  num_lines[]     Array of lines to transfer
399  *  @param[in]  pitch[]         Array of pitches
400  *  @param[in]  num_transfers   Number of transfers
401  *
402  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
403  *
404  *  @sa EdmaMgr_copy2D1D
405  */
406 int32_t EdmaMgr_copy2D1DLinked
408   EdmaMgr_Handle    h,
409   void *restrict    src[],
410   void *restrict    dst[],
411   int32_t           num_bytes[],
412   int32_t           num_lines[],
413   int32_t           pitch[],
414   int32_t           num_transfers
415 );
417 /**
418  *  @brief      Perform a group of linked 2D->2D transfers
419  *
420  *  @param[in]  h               Handle returned from EdmaMgr_alloc().
421  *  @param[in]  src[]           Array of source addresses
422  *  @param[in]  dst[]           Array of destination addresses
423  *  @param[in]  num_bytes[]     Array of number of bytes to transfer
424  *  @param[in]  num_lines[]     Array of lines to transfer
425  *  @param[in]  pitch[]         Array of pitches
426  *  @param[in]  num_transfers   Number of transfers
427  *
428  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
429  *
430  *  @sa EdmaMgr_copy2D2D
431  */
432 int32_t EdmaMgr_copy2D2DLinked
434   EdmaMgr_Handle    h,
435   void *restrict    src[],
436   void *restrict    dst[],
437   int32_t           num_bytes[],
438   int32_t           num_lines[],
439   int32_t           pitch[],
440   int32_t           num_transfers
441 );
443 /**
444  *  @brief      Perform a group of linked 2D->2D transfers with different
445  *              pitches
446  *
447  *  @param[in]  h               Handle returned from EdmaMgr_alloc().
448  *  @param[in]  src[]           Array of source addresses
449  *  @param[in]  dst[]           Array of destination addresses
450  *  @param[in]  num_bytes[]     Array of number of bytes to transfer
451  *  @param[in]  num_lines[]     Array of lines to transfer
452  *  @param[in]  src_pitch[]     Array of source pitches
453  *  @param[in]  dst_pitch[]     Array of destination pitches
454  *  @param[in]  num_transfers   Number of transfers
455  *
456  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
457  *
458  *  @sa EdmaMgr_copy2D2DSep
459  */
460 int32_t EdmaMgr_copy2D2DSepLinked
462   EdmaMgr_Handle    h,
463   void *restrict    src[],
464   void *restrict    dst[],
465   int32_t           num_bytes[],
466   int32_t           num_lines[],
467   int32_t           src_pitch[],
468   int32_t           dst_pitch[],
469   int32_t           num_transfers
470 );
472 /**
473  *  @brief      Perform a 1D->2D large transfer
474  *
475  *  @param[in]  h           Handle returned from EdmaMgr_alloc().
476  *  @param[in]  src         Source address
477  *  @param[in]  dst         Destination address
478  *  @param[in]  num_bytes   Number of bytes to transfer
479  *  @param[in]  num_lines   Number of lines
480  *  @param[in]  pitch       Pitch
481  *
482  *  @pre        @c h must be a handle successfully returned from
483  *              EdmaMgr_allocLarge().
484  *
485  *  @remarks    Perform a 1D->2D transfer of @c num_bytes bytes.  The source
486  *              is one dimensional, and the destination is two dimensional.
487  *
488  *  @remarks    After every line of @c num_bytes is transferred, the @c src
489  *              address is incremented by @c num_bytes and the @c dst address
490  *              is incremented by @c pitch bytes.
491  *
492  *  @remarks    This should be used when the pitch is outside the range of
493  *              [-32768,32767].
494  */
495 int32_t EdmaMgr_copy1D2DLarge
497   EdmaMgr_Handle    h,
498   void *restrict    src,
499   void *restrict    dst,
500   int32_t           num_bytes,
501   int32_t           num_lines,
502   int32_t           pitch
503 );
505 /**
506  *  @brief      Perform a 2D->1D large transfer
507  *
508  *  @param[in]  h           Handle returned from EdmaMgr_alloc().
509  *  @param[in]  src         Source address
510  *  @param[in]  dst         Destination address
511  *  @param[in]  num_bytes   Number of bytes to transfer
512  *  @param[in]  num_lines   Number of lines
513  *  @param[in]  pitch       Pitch
514  *
515  *  @pre        @c h must be a handle successfully returned from
516  *              EdmaMgr_allocLarge().
517  *
518  *  @remarks    Perform a 2D->1D transfer of @c num_bytes bytes.  The source
519  *              is two dimensional, and the destination is one dimensional.
520  *
521  *  @remarks    After every line of @c num_bytes is transferred, the @c src
522  *              address is incremented by @c pitch and the @c dst address
523  *              is incremented by @c num_bytes bytes.
524  *
525  *  @remarks    This should be used when the pitch is outside the range of
526  *              [-32768,32767].
527  */
528 int32_t EdmaMgr_copy2D1DLarge
530   EdmaMgr_Handle    h,
531   void *restrict    src,
532   void *restrict    dst,
533   int32_t           num_bytes,
534   int32_t           num_lines,
535   int32_t           pitch
536 );
539 /**
540  *  @brief      Perform a fast copy. This API inherits the transfer configuration
541  *              of a previous transfer and only modifies the @c src and @c dst
542  *              addresses.
543  *
544  *  @param[in]  h     Handle returned from EdmaMgr_alloc().
545  *  @param[in]  src   Source address
546  *  @param[in]  dst   Destination address
547  *
548  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
549  *
550  *  @pre        A non-linked transfer must have been completed on handle @c h
551  *              before calling this function.
552  *
553  *  @sa EdmaMgr_copyLinkedFast
554  */
555 int32_t EdmaMgr_copyFast
557   EdmaMgr_Handle    h,
558   void *restrict    src,
559   void *restrict    dst
560 );
562 /**
563  *  @brief      Perform a linked fast copy. This API inherits the transfer
564  *              configuration of a previous transfer and only modifies the
565  *              @c src and @c dst addresses.
566  *
567  *  @param[in]  h     Handle returned from EdmaMgr_alloc().
568  *  @param[in]  src[] Array of source addresses
569  *  @param[in]  dst[] Array of destination addresses
570  *  @param[in]  num_transfers Number of transfers
571  *
572  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
573  *
574  *  @pre        A linked transfer must have been completed on handle @c h
575  *              before calling this function.
576  *
577  *  @sa EdmaMgr_copyLinkedFast
578  */
579 int32_t EdmaMgr_copyLinkedFast
581   EdmaMgr_Handle    h,
582   void *restrict    src[],
583   void *restrict    dst[],
584   int32_t           num_transfers
585 );
586 #endif
588 /*@}*/
590 #endif /* ti_sdo_fc_edmamgr_EdmaMgr_ */