38cc60daa0ee9c4b827aec6662e259f6c8aa0282
[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 {
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 } EdmaMgr_Channel;
85 /** @endcond */
87 #define EdmaMgr_SUCCESS           0  /**< Success */
88 #define EdmaMgr_ERROR_INVARG     -1  /**< Failure, Invalid Argument */
89 #define EdmaMgr_ERROR_INVCFG     -2  /**< Failure, Invalid Configuration */
90 #define EdmaMgr_ERROR_RMANINIT   -3  /**< Failure, RMAN initialization */
91 #define EdmaMgr_ERROR_INVHANDLE  -4  /**< Failure, Invalid Handle */
92 #define EdmaMgr_ERROR_FREE       -5  /**< Failure to free a resource */
94 /**
95  *  @brief      Initialize EdmaMgr
96  *
97  *  @param[in]  proc_id         Processor ID. This ID is used to index into the
98  *                              EDMA3_InstanceInitConfig array pointed to by the
99  *                              ti_sdo_fc_edmamgr_edma3RegionConfig variable.
100  *
101  *  @param[in]  edma3_config    Optional edma3_config which will override the
102  *                              configuration which is pointed to by
103  *                              ti_sdo_fc_edmamgr_edma3RegionConfig.
104  *
105  *  @retval     EdmaMgr_SUCCESS         @copydoc EdmaMgr_SUCCESS
106  *  @retval     EdmaMgr_ERROR_INVARG    @copydoc EdmaMgr_ERROR_INVARG
107  *  @retval     EdmaMgr_ERROR_INVCFG    @copydoc EdmaMgr_ERROR_INVCFG
108  *  @retval     EdmaMgr_ERROR_RMANINIT  @copydoc EdmaMgr_ERROR_RMANINIT
109  *
110  *  @remarks    @c edma3_config may be NULL to accept default values.
111  *
112  *  @remarks    The FC product includes an example (ex23_edmamgr) which
113  *              demonstrates how to set up a @c ti_sdo_fc_edma3RegionConfig
114  *              variable.
115  */
116 int32_t EdmaMgr_init
118   int32_t  proc_id,
119   void    *edma3_config
120 );
123 /**
124  *  @brief      Allocate an EdmaMgr channel
125  *
126  *  @param[in]  max_linked_transfers    Maximum linked transfers
127  *
128  *  @retval     NULL        Failure to allocate the channel
129  *  @retval     non-NULL    Success
130  *
131  *  @pre        EdmaMgr_init() must have first been called.
132  *
133  */
134 EdmaMgr_Handle EdmaMgr_alloc
136   int32_t max_linked_transfers
137 );
140 /**
141  *  @brief      Frees an EdmaMgr channel.
142  *
143  *  @param[in]  h       Handle returned from EdmaMgr_alloc().
144  *
145  *  @retval     EdmaMgr_SUCCESS         @copydoc EdmaMgr_SUCCESS
146  *  @retval     EdmaMgr_ERROR_INVHANDLE @copydoc EdmaMgr_ERROR_INVHANDLE
147  *  @retval     EdmaMgr_ERROR_FREE      @copydoc EdmaMgr_ERROR_FREE
148  *
149  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
150  */
151 int32_t EdmaMgr_free
153   EdmaMgr_Handle    h
154 );
157 /*
158  *  The below declarations are placed here as only a reference
159  *  (hence the comment block).
160  *
161  *  These functions are defined further below.
162  */
163 #if defined(EDMAMGR_INLINE_ALL)
164 #include <ti/sdo/fc/edmamgr/edmamgr_xfer.h>
165 #else
166 /**
167  *  @brief      Wait for transfers to complete
168  *
169  *  @param[in]  h       Handle returned from EdmaMgr_alloc().
170  *
171  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
172  *
173  *  @remarks    This function waits for all transfers on a specific channel
174  *              to complete.  It is a blocking call.
175  */
176 void EdmaMgr_wait
178   EdmaMgr_Handle    h
179 );
182 /**
183  *  @brief      Perform a single 1D->1D transfer
184  *
185  *  @param[in]  h           Handle returned from EdmaMgr_alloc().
186  *  @param[in]  src         Source address
187  *  @param[in]  dst         Destination address
188  *  @param[in]  num_bytes   Number of bytes to transfer
189  *
190  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
191  *
192  *  @remarks    Perform a single 1D->1D transfer of @c num_bytes bytes from
193  *              @c src address to @c dst address.
194  *
195  *  @sa EdmaMgr_copy1D1DLinked
196  */
197 int32_t EdmaMgr_copy1D1D
199   EdmaMgr_Handle    h,
200   void *restrict    src,
201   void *restrict    dst,
202   int32_t           num_bytes
203 );
205 /**
206  *  @brief      Perform a 1D->2D transfer
207  *
208  *  @param[in]  h           Handle returned from EdmaMgr_alloc().
209  *  @param[in]  src         Source address
210  *  @param[in]  dst         Destination address
211  *  @param[in]  num_bytes   Number of bytes to transfer
212  *  @param[in]  num_lines   Number of lines
213  *  @param[in]  pitch       Pitch
214  *
215  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
216  *
217  *  @remarks    Perform a 1D->2D transfer of @c num_bytes bytes.  The source
218  *              is one dimensional, and the destination is two dimensional.
219  *
220  *  @remarks    After every line of @c num_bytes is transferred, the @c src
221  *              address is incremented by @c num_bytes and the @c dst address
222  *              is incremented by @c pitch bytes.
223  */
224 int32_t EdmaMgr_copy1D2D
226   EdmaMgr_Handle    h,
227   void *restrict    src,
228   void *restrict    dst,
229   int32_t           num_bytes,
230   int32_t           num_lines,
231   int32_t           pitch
232 );
234 /**
235  *  @brief      Perform a 2D->1D transfer
236  *
237  *  @param[in]  h           Handle returned from EdmaMgr_alloc().
238  *  @param[in]  src         Source address
239  *  @param[in]  dst         Destination address
240  *  @param[in]  num_bytes   Number of bytes to transfer
241  *  @param[in]  num_lines   Number of lines
242  *  @param[in]  pitch       Pitch
243  *
244  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
245  *
246  *  @remarks    Perform a 2D->1D transfer of @c num_bytes bytes.  The source
247  *              is two dimensional, and the destination is one dimensional.
248  *
249  *  @remarks    After every line of @c num_bytes is transferred, the @c src
250  *              address is incremented by @c pitch and the @c dst address
251  *              is incremented by @c num_bytes bytes.
252  */
253 int32_t EdmaMgr_copy2D1D
255   EdmaMgr_Handle    h,
256   void *restrict    src,
257   void *restrict    dst,
258   int32_t           num_bytes,
259   int32_t           num_lines,
260   int32_t           pitch
261 );
263 /**
264  *  @brief      Perform a 2D->2D transfer of buffers with the same pitch
265  *
266  *  @param[in]  h           Handle returned from EdmaMgr_alloc().
267  *  @param[in]  src         Source address
268  *  @param[in]  dst         Destination address
269  *  @param[in]  num_bytes   Number of bytes to transfer
270  *  @param[in]  num_lines   Number of lines
271  *  @param[in]  pitch       Pitch
272  *
273  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
274  *
275  *  @remarks    Perform a 2D->2D transfer of @c num_bytes bytes.  The source
276  *              and destination are two dimensional.
277  *
278  *  @remarks    After every line of @c num_bytes is transferred, the @c src
279  *              address and @c dst address is incremented by @c pitch bytes.
280  */
281 int32_t EdmaMgr_copy2D2D
283   EdmaMgr_Handle    h,
284   void *restrict    src,
285   void *restrict    dst,
286   int32_t           num_bytes,
287   int32_t           num_lines,
288   int32_t           pitch
289 );
291 /**
292  *  @brief      Perform a 2D->2D transfer of buffers with different pitches
293  *
294  *  @param[in]  h           Handle returned from EdmaMgr_alloc().
295  *  @param[in]  src         Source address
296  *  @param[in]  dst         Destination address
297  *  @param[in]  num_bytes   Number of bytes to transfer
298  *  @param[in]  num_lines   Number of lines
299  *  @param[in]  src_pitch   Source buffer pitch
300  *  @param[in]  dst_pitch   Destination buffer pitch
301  *
302  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
303  *
304  *  @remarks    Perform a 2D->2D transfer of @c num_bytes bytes.  The source
305  *              and destination are two dimensional.
306  *
307  *  @remarks    After every line of @c num_bytes is transferred, the @c src
308  *              address is incremented by @c src_pitch bytes and the @c dst
309  *              address is incremented by @c dst_pitch bytes.
310  */
311 int32_t EdmaMgr_copy2D2DSep
313   EdmaMgr_Handle    h,
314   void *restrict    src,
315   void *restrict    dst,
316   int32_t           num_bytes,
317   int32_t           num_lines,
318   int32_t           src_pitch,
319   int32_t           dst_pitch
320 );
322 /**
323  *  @brief      Perform a group of linked 1D->1D transfers
324  *
325  *  @param[in]  h               Handle returned from EdmaMgr_alloc().
326  *  @param[in]  src[]           Array of source addresses
327  *  @param[in]  dst[]           Array of destination addresses
328  *  @param[in]  num_bytes[]     Array of number of bytes to transfer
329  *  @param[in]  num_transfers   Number of transfers
330  *
331  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
332  *
333  *  @sa EdmaMgr_copy1D1D
334  */
335 int32_t EdmaMgr_copy1D1DLinked
337   EdmaMgr_Handle    h,
338   void *restrict    src[],
339   void *restrict    dst[],
340   int32_t           num_bytes[],
341   int32_t           num_transfers
342 );
344 /**
345  *  @brief      Perform a group of linked 1D->2D transfers
346  *
347  *  @param[in]  h               Handle returned from EdmaMgr_alloc().
348  *  @param[in]  src[]           Array of source addresses
349  *  @param[in]  dst[]           Array of destination addresses
350  *  @param[in]  num_bytes[]     Array of number of bytes to transfer
351  *  @param[in]  num_lines[]     Array of lines to transfer
352  *  @param[in]  pitch[]         Array of pitches
353  *  @param[in]  num_transfers   Number of transfers
354  *
355  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
356  *
357  *  @sa EdmaMgr_copy1D2D
358  */
359 int32_t EdmaMgr_copy1D2DLinked
361   EdmaMgr_Handle    h,
362   void *restrict    src[],
363   void *restrict    dst[],
364   int32_t           num_bytes[],
365   int32_t           num_lines[],
366   int32_t           pitch[],
367   int32_t           num_transfers
368 );
370 /**
371  *  @brief      Perform a group of linked 2D->1D transfers
372  *
373  *  @param[in]  h               Handle returned from EdmaMgr_alloc().
374  *  @param[in]  src[]           Array of source addresses
375  *  @param[in]  dst[]           Array of destination addresses
376  *  @param[in]  num_bytes[]     Array of number of bytes to transfer
377  *  @param[in]  num_lines[]     Array of lines to transfer
378  *  @param[in]  pitch[]         Array of pitches
379  *  @param[in]  num_transfers   Number of transfers
380  *
381  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
382  *
383  *  @sa EdmaMgr_copy2D1D
384  */
385 int32_t EdmaMgr_copy2D1DLinked
387   EdmaMgr_Handle    h,
388   void *restrict    src[],
389   void *restrict    dst[],
390   int32_t           num_bytes[],
391   int32_t           num_lines[],
392   int32_t           pitch[],
393   int32_t           num_transfers
394 );
396 /**
397  *  @brief      Perform a group of linked 2D->2D transfers
398  *
399  *  @param[in]  h               Handle returned from EdmaMgr_alloc().
400  *  @param[in]  src[]           Array of source addresses
401  *  @param[in]  dst[]           Array of destination addresses
402  *  @param[in]  num_bytes[]     Array of number of bytes to transfer
403  *  @param[in]  num_lines[]     Array of lines to transfer
404  *  @param[in]  pitch[]         Array of pitches
405  *  @param[in]  num_transfers   Number of transfers
406  *
407  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
408  *
409  *  @sa EdmaMgr_copy2D2D
410  */
411 int32_t EdmaMgr_copy2D2DLinked
413   EdmaMgr_Handle    h,
414   void *restrict    src[],
415   void *restrict    dst[],
416   int32_t           num_bytes[],
417   int32_t           num_lines[],
418   int32_t           pitch[],
419   int32_t           num_transfers
420 );
422 /**
423  *  @brief      Perform a group of linked 2D->2D transfers with different
424  *              pitches
425  *
426  *  @param[in]  h               Handle returned from EdmaMgr_alloc().
427  *  @param[in]  src[]           Array of source addresses
428  *  @param[in]  dst[]           Array of destination addresses
429  *  @param[in]  num_bytes[]     Array of number of bytes to transfer
430  *  @param[in]  num_lines[]     Array of lines to transfer
431  *  @param[in]  src_pitch[]     Array of source pitches
432  *  @param[in]  dst_pitch[]     Array of destination pitches
433  *  @param[in]  num_transfers   Number of transfers
434  *
435  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
436  *
437  *  @sa EdmaMgr_copy2D2DSep
438  */
439 int32_t EdmaMgr_copy2D2DSepLinked
441   EdmaMgr_Handle    h,
442   void *restrict    src[],
443   void *restrict    dst[],
444   int32_t           num_bytes[],
445   int32_t           num_lines[],
446   int32_t           src_pitch[],
447   int32_t           dst_pitch[],
448   int32_t           num_transfers
449 );
451 /**
452  *  @brief      Perform a fast copy. This API inherits the transfer configuration
453  *              of a previous transfer and only modifies the @c src and @c dst
454  *              addresses.
455  *
456  *  @param[in]  h     Handle returned from EdmaMgr_alloc().
457  *  @param[in]  src   Source address
458  *  @param[in]  dst   Destination address
459  *
460  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
461  *
462  *  @pre        A non-linked transfer must have been completed on handle @c h
463  *              before calling this function.
464  *
465  *  @sa EdmaMgr_copyLinkedFast
466  */
467 int32_t EdmaMgr_copyFast
469   EdmaMgr_Handle    h,
470   void *restrict    src,
471   void *restrict    dst
472 );
474 /**
475  *  @brief      Perform a linked fast copy. This API inherits the transfer
476  *              configuration of a previous transfer and only modifies the
477  *              @c src and @c dst addresses.
478  *
479  *  @param[in]  h     Handle returned from EdmaMgr_alloc().
480  *  @param[in]  src[] Array of source addresses
481  *  @param[in]  dst[] Array of destination addresses
482  *  @param[in]  num_transfers Number of transfers
483  *
484  *  @pre        @c h must be a handle successfully returned from EdmaMgr_alloc().
485  *
486  *  @pre        A linked transfer must have been completed on handle @c h
487  *              before calling this function.
488  *
489  *  @sa EdmaMgr_copyLinkedFast
490  */
491 int32_t EdmaMgr_copyLinkedFast
493   EdmaMgr_Handle    h,
494   void *restrict    src[],
495   void *restrict    dst[],
496   int32_t           num_transfers
497 );
498 #endif
500 /*@}*/
502 #endif /* ti_sdo_fc_edmamgr_EdmaMgr_ */