f6776fd5b01d2f2f8b34d693fab57d4c7d11018c
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/ialg.h>
64 #include <ti/xdais/ires.h>
65 #include <ti/sdo/fc/ires/edma3chan/ires_edma3Chan.h>
66 #include <ti/sdo/fc/edma3/edma3_config.h>
69 /**
70 * @brief Handle to an EdmaMgr instance.
71 */
72 typedef void *EdmaMgr_Handle;
75 /** @cond INTERNAL */
76 typedef struct _EdmaMgr_Channel {
77 IRES_EDMA3CHAN_Handle edmaHandle;
78 ECPY_Handle ecpyHandle;
79 IRES_EDMA3CHAN_ProtocolArgs edmaArgs;
80 Bool resActive;
81 Bool xferPending;
82 IRES_YieldFxn yieldFxn;
83 IRES_YieldArgs yieldArgs;
84 IRES_YieldContext yieldContext;
85 uint32_t optChained;
86 IALG_MemRec addrTable;
87 struct _EdmaMgr_Channel *chainedChannel;
88 } EdmaMgr_Channel;
89 /** @endcond */
91 #define EdmaMgr_SUCCESS 0 /**< Success */
92 #define EdmaMgr_ERROR_INVARG -1 /**< Failure, Invalid Argument */
93 #define EdmaMgr_ERROR_INVCFG -2 /**< Failure, Invalid Configuration */
94 #define EdmaMgr_ERROR_RMANINIT -3 /**< Failure, RMAN initialization */
95 #define EdmaMgr_ERROR_INVHANDLE -4 /**< Failure, Invalid Handle */
96 #define EdmaMgr_ERROR_FREE -5 /**< Failure to free a resource */
98 /**
99 * @brief Initialize EdmaMgr
100 *
101 * @param[in] proc_id Processor ID. This ID is used to index into the
102 * EDMA3_InstanceInitConfig array pointed to by the
103 * ti_sdo_fc_edmamgr_edma3RegionConfig variable.
104 *
105 * @param[in] edma3_config Optional edma3_config which will override the
106 * configuration which is pointed to by
107 * ti_sdo_fc_edmamgr_edma3RegionConfig.
108 *
109 * @retval EdmaMgr_SUCCESS @copydoc EdmaMgr_SUCCESS
110 * @retval EdmaMgr_ERROR_INVARG @copydoc EdmaMgr_ERROR_INVARG
111 * @retval EdmaMgr_ERROR_INVCFG @copydoc EdmaMgr_ERROR_INVCFG
112 * @retval EdmaMgr_ERROR_RMANINIT @copydoc EdmaMgr_ERROR_RMANINIT
113 *
114 * @remarks @c edma3_config may be NULL to accept default values.
115 *
116 * @remarks The FC product includes an example (ex23_edmamgr) which
117 * demonstrates how to set up a @c ti_sdo_fc_edma3RegionConfig
118 * variable.
119 */
120 int32_t EdmaMgr_init
121 (
122 int32_t proc_id,
123 void *edma3_config
124 );
127 /**
128 * @brief Allocate an EdmaMgr channel
129 *
130 * @param[in] max_linked_transfers Maximum linked transfers
131 *
132 * @retval NULL Failure to allocate the channel
133 * @retval non-NULL Success
134 *
135 * @pre EdmaMgr_init() must have first been called.
136 *
137 */
138 EdmaMgr_Handle EdmaMgr_alloc
139 (
140 int32_t max_linked_transfers
141 );
144 #define EdmaMgr_MAX_NUM_MEMRECS_LARGE 1 /**< Maximum number of buffers
145 * required to allocate a large
146 * channel.
147 */
148 /**
149 * @brief Configuration for a large channel.
150 */
151 typedef struct _EdmaMgr_ConfigLarge {
153 /**< Maximum number of lines which may be transfered by the channel. */
154 int32_t max_num_lines;
156 } EdmaMgr_ConfigLarge;
159 /**
160 * @brief Get buffer requirements for a large channel.
161 *
162 * @param[in] cfg Configuration for a large channel.
163 *
164 * @param[out] memTab Buffer requirements for a large channel.
165 *
166 * @retval EdmaMgr_SUCCESS @copydoc EdmaMgr_SUCCESS
167 * @retval EdmaMgr_ERROR_INVCFG @copydoc EdmaMgr_ERROR_INVCFG
168 *
169 * @remark These buffers must be provided to EdmaMgr_allocLarge() along with
170 * the corresponding EdmaMgr_ConfigLarge structure.
171 */
172 int32_t EdmaMgr_getSizesLarge
173 (
174 EdmaMgr_ConfigLarge *cfg,
175 IALG_MemRec memTab[]
176 );
179 /**
180 * @brief Allocate an EdmaMgr channel for "Large" 1D2D or 2D1D transfers
181 * which have a pitch outside the range [-32768,32768].
182 *
183 * @param[in] cfg Configuration for a large channel.
184 *
185 * @param[in] memTab Buffer requirements along with allocated buffers for
186 * a large channel.
187 *
188 * @retval NULL Failure to allocate the channel
189 * @retval non-NULL Success
190 *
191 * @pre EdmaMgr_init() must have first been called.
192 * @pre EdmaMgr_getSizesLarge() must have been called and buffers
193 * allocated satisfying the requirements in memTab.
194 *
195 */
196 EdmaMgr_Handle EdmaMgr_allocLarge
197 (
198 EdmaMgr_ConfigLarge *cfg,
199 IALG_MemRec memTab[]
200 );
203 /**
204 * @brief Frees an EdmaMgr channel.
205 *
206 * @param[in] h Handle returned from EdmaMgr_alloc().
207 *
208 * @retval EdmaMgr_SUCCESS @copydoc EdmaMgr_SUCCESS
209 * @retval EdmaMgr_ERROR_INVHANDLE @copydoc EdmaMgr_ERROR_INVHANDLE
210 * @retval EdmaMgr_ERROR_FREE @copydoc EdmaMgr_ERROR_FREE
211 *
212 * @pre @c h must be a handle successfully returned from EdmaMgr_alloc().
213 */
214 int32_t EdmaMgr_free
215 (
216 EdmaMgr_Handle h
217 );
220 /*
221 * The below declarations are placed here as only a reference
222 * (hence the comment block).
223 *
224 * These functions are defined further below.
225 */
226 #if defined(EDMAMGR_INLINE_ALL)
227 #include <ti/sdo/fc/edmamgr/edmamgr_xfer.h>
228 #else
229 /**
230 * @brief Wait for transfers to complete
231 *
232 * @param[in] h Handle returned from EdmaMgr_alloc().
233 *
234 * @pre @c h must be a handle successfully returned from EdmaMgr_alloc().
235 *
236 * @remarks This function waits for all transfers on a specific channel
237 * to complete. It is a blocking call.
238 */
239 void EdmaMgr_wait
240 (
241 EdmaMgr_Handle h
242 );
245 /**
246 * @brief Perform a single 1D->1D transfer
247 *
248 * @param[in] h Handle returned from EdmaMgr_alloc().
249 * @param[in] src Source address
250 * @param[in] dst Destination address
251 * @param[in] num_bytes Number of bytes to transfer
252 *
253 * @pre @c h must be a handle successfully returned from EdmaMgr_alloc().
254 *
255 * @remarks Perform a single 1D->1D transfer of @c num_bytes bytes from
256 * @c src address to @c dst address.
257 *
258 * @sa EdmaMgr_copy1D1DLinked
259 */
260 int32_t EdmaMgr_copy1D1D
261 (
262 EdmaMgr_Handle h,
263 void *restrict src,
264 void *restrict dst,
265 int32_t num_bytes
266 );
268 /**
269 * @brief Perform a 1D->2D transfer
270 *
271 * @param[in] h Handle returned from EdmaMgr_alloc().
272 * @param[in] src Source address
273 * @param[in] dst Destination address
274 * @param[in] num_bytes Number of bytes to transfer
275 * @param[in] num_lines Number of lines
276 * @param[in] pitch Pitch
277 *
278 * @pre @c h must be a handle successfully returned from EdmaMgr_alloc().
279 *
280 * @remarks Perform a 1D->2D transfer of @c num_bytes bytes. The source
281 * is one dimensional, and the destination is two dimensional.
282 *
283 * @remarks After every line of @c num_bytes is transferred, the @c src
284 * address is incremented by @c num_bytes and the @c dst address
285 * is incremented by @c pitch bytes.
286 */
287 int32_t EdmaMgr_copy1D2D
288 (
289 EdmaMgr_Handle h,
290 void *restrict src,
291 void *restrict dst,
292 int32_t num_bytes,
293 int32_t num_lines,
294 int32_t pitch
295 );
297 /**
298 * @brief Perform a 2D->1D transfer
299 *
300 * @param[in] h Handle returned from EdmaMgr_alloc().
301 * @param[in] src Source address
302 * @param[in] dst Destination address
303 * @param[in] num_bytes Number of bytes to transfer
304 * @param[in] num_lines Number of lines
305 * @param[in] pitch Pitch
306 *
307 * @pre @c h must be a handle successfully returned from EdmaMgr_alloc().
308 *
309 * @remarks Perform a 2D->1D transfer of @c num_bytes bytes. The source
310 * is two dimensional, and the destination is one dimensional.
311 *
312 * @remarks After every line of @c num_bytes is transferred, the @c src
313 * address is incremented by @c pitch and the @c dst address
314 * is incremented by @c num_bytes bytes.
315 */
316 int32_t EdmaMgr_copy2D1D
317 (
318 EdmaMgr_Handle h,
319 void *restrict src,
320 void *restrict dst,
321 int32_t num_bytes,
322 int32_t num_lines,
323 int32_t pitch
324 );
326 /**
327 * @brief Perform a 2D->2D transfer of buffers with the same pitch
328 *
329 * @param[in] h Handle returned from EdmaMgr_alloc().
330 * @param[in] src Source address
331 * @param[in] dst Destination address
332 * @param[in] num_bytes Number of bytes to transfer
333 * @param[in] num_lines Number of lines
334 * @param[in] pitch Pitch
335 *
336 * @pre @c h must be a handle successfully returned from EdmaMgr_alloc().
337 *
338 * @remarks Perform a 2D->2D transfer of @c num_bytes bytes. The source
339 * and destination are two dimensional.
340 *
341 * @remarks After every line of @c num_bytes is transferred, the @c src
342 * address and @c dst address is incremented by @c pitch bytes.
343 */
344 int32_t EdmaMgr_copy2D2D
345 (
346 EdmaMgr_Handle h,
347 void *restrict src,
348 void *restrict dst,
349 int32_t num_bytes,
350 int32_t num_lines,
351 int32_t pitch
352 );
354 /**
355 * @brief Perform a 2D->2D transfer of buffers with different pitches
356 *
357 * @param[in] h Handle returned from EdmaMgr_alloc().
358 * @param[in] src Source address
359 * @param[in] dst Destination address
360 * @param[in] num_bytes Number of bytes to transfer
361 * @param[in] num_lines Number of lines
362 * @param[in] src_pitch Source buffer pitch
363 * @param[in] dst_pitch Destination buffer pitch
364 *
365 * @pre @c h must be a handle successfully returned from EdmaMgr_alloc().
366 *
367 * @remarks Perform a 2D->2D transfer of @c num_bytes bytes. The source
368 * and destination are two dimensional.
369 *
370 * @remarks After every line of @c num_bytes is transferred, the @c src
371 * address is incremented by @c src_pitch bytes and the @c dst
372 * address is incremented by @c dst_pitch bytes.
373 */
374 int32_t EdmaMgr_copy2D2DSep
375 (
376 EdmaMgr_Handle h,
377 void *restrict src,
378 void *restrict dst,
379 int32_t num_bytes,
380 int32_t num_lines,
381 int32_t src_pitch,
382 int32_t dst_pitch
383 );
385 /**
386 * @brief Perform a group of linked 1D->1D transfers
387 *
388 * @param[in] h Handle returned from EdmaMgr_alloc().
389 * @param[in] src[] Array of source addresses
390 * @param[in] dst[] Array of destination addresses
391 * @param[in] num_bytes[] Array of number of bytes to transfer
392 * @param[in] num_transfers Number of transfers
393 *
394 * @pre @c h must be a handle successfully returned from EdmaMgr_alloc().
395 *
396 * @sa EdmaMgr_copy1D1D
397 */
398 int32_t EdmaMgr_copy1D1DLinked
399 (
400 EdmaMgr_Handle h,
401 void *restrict src[],
402 void *restrict dst[],
403 int32_t num_bytes[],
404 int32_t num_transfers
405 );
407 /**
408 * @brief Perform a group of linked 1D->2D transfers
409 *
410 * @param[in] h Handle returned from EdmaMgr_alloc().
411 * @param[in] src[] Array of source addresses
412 * @param[in] dst[] Array of destination addresses
413 * @param[in] num_bytes[] Array of number of bytes to transfer
414 * @param[in] num_lines[] Array of lines to transfer
415 * @param[in] pitch[] Array of pitches
416 * @param[in] num_transfers Number of transfers
417 *
418 * @pre @c h must be a handle successfully returned from EdmaMgr_alloc().
419 *
420 * @sa EdmaMgr_copy1D2D
421 */
422 int32_t EdmaMgr_copy1D2DLinked
423 (
424 EdmaMgr_Handle h,
425 void *restrict src[],
426 void *restrict dst[],
427 int32_t num_bytes[],
428 int32_t num_lines[],
429 int32_t pitch[],
430 int32_t num_transfers
431 );
433 /**
434 * @brief Perform a group of linked 2D->1D transfers
435 *
436 * @param[in] h Handle returned from EdmaMgr_alloc().
437 * @param[in] src[] Array of source addresses
438 * @param[in] dst[] Array of destination addresses
439 * @param[in] num_bytes[] Array of number of bytes to transfer
440 * @param[in] num_lines[] Array of lines to transfer
441 * @param[in] pitch[] Array of pitches
442 * @param[in] num_transfers Number of transfers
443 *
444 * @pre @c h must be a handle successfully returned from EdmaMgr_alloc().
445 *
446 * @sa EdmaMgr_copy2D1D
447 */
448 int32_t EdmaMgr_copy2D1DLinked
449 (
450 EdmaMgr_Handle h,
451 void *restrict src[],
452 void *restrict dst[],
453 int32_t num_bytes[],
454 int32_t num_lines[],
455 int32_t pitch[],
456 int32_t num_transfers
457 );
459 /**
460 * @brief Perform a group of linked 2D->2D transfers
461 *
462 * @param[in] h Handle returned from EdmaMgr_alloc().
463 * @param[in] src[] Array of source addresses
464 * @param[in] dst[] Array of destination addresses
465 * @param[in] num_bytes[] Array of number of bytes to transfer
466 * @param[in] num_lines[] Array of lines to transfer
467 * @param[in] pitch[] Array of pitches
468 * @param[in] num_transfers Number of transfers
469 *
470 * @pre @c h must be a handle successfully returned from EdmaMgr_alloc().
471 *
472 * @sa EdmaMgr_copy2D2D
473 */
474 int32_t EdmaMgr_copy2D2DLinked
475 (
476 EdmaMgr_Handle h,
477 void *restrict src[],
478 void *restrict dst[],
479 int32_t num_bytes[],
480 int32_t num_lines[],
481 int32_t pitch[],
482 int32_t num_transfers
483 );
485 /**
486 * @brief Perform a group of linked 2D->2D transfers with different
487 * pitches
488 *
489 * @param[in] h Handle returned from EdmaMgr_alloc().
490 * @param[in] src[] Array of source addresses
491 * @param[in] dst[] Array of destination addresses
492 * @param[in] num_bytes[] Array of number of bytes to transfer
493 * @param[in] num_lines[] Array of lines to transfer
494 * @param[in] src_pitch[] Array of source pitches
495 * @param[in] dst_pitch[] Array of destination pitches
496 * @param[in] num_transfers Number of transfers
497 *
498 * @pre @c h must be a handle successfully returned from EdmaMgr_alloc().
499 *
500 * @sa EdmaMgr_copy2D2DSep
501 */
502 int32_t EdmaMgr_copy2D2DSepLinked
503 (
504 EdmaMgr_Handle h,
505 void *restrict src[],
506 void *restrict dst[],
507 int32_t num_bytes[],
508 int32_t num_lines[],
509 int32_t src_pitch[],
510 int32_t dst_pitch[],
511 int32_t num_transfers
512 );
514 /**
515 * @brief Perform a 1D->2D large transfer
516 *
517 * @param[in] h Handle returned from EdmaMgr_alloc().
518 * @param[in] src Source address
519 * @param[in] dst Destination address
520 * @param[in] num_bytes Number of bytes to transfer
521 * @param[in] num_lines Number of lines
522 * @param[in] pitch Pitch
523 *
524 * @pre @c h must be a handle successfully returned from
525 * EdmaMgr_allocLarge().
526 *
527 * @remarks Perform a 1D->2D transfer of @c num_bytes bytes. The source
528 * is one dimensional, and the destination is two dimensional.
529 *
530 * @remarks After every line of @c num_bytes is transferred, the @c src
531 * address is incremented by @c num_bytes and the @c dst address
532 * is incremented by @c pitch bytes.
533 *
534 * @remarks This should be used when the pitch is outside the range of
535 * [-32768,32767].
536 */
537 int32_t EdmaMgr_copy1D2DLarge
538 (
539 EdmaMgr_Handle h,
540 void *restrict src,
541 void *restrict dst,
542 int32_t num_bytes,
543 int32_t num_lines,
544 int32_t pitch
545 );
547 /**
548 * @brief Perform a 2D->1D large transfer
549 *
550 * @param[in] h Handle returned from EdmaMgr_alloc().
551 * @param[in] src Source address
552 * @param[in] dst Destination address
553 * @param[in] num_bytes Number of bytes to transfer
554 * @param[in] num_lines Number of lines
555 * @param[in] pitch Pitch
556 *
557 * @pre @c h must be a handle successfully returned from
558 * EdmaMgr_allocLarge().
559 *
560 * @remarks Perform a 2D->1D transfer of @c num_bytes bytes. The source
561 * is two dimensional, and the destination is one dimensional.
562 *
563 * @remarks After every line of @c num_bytes is transferred, the @c src
564 * address is incremented by @c pitch and the @c dst address
565 * is incremented by @c num_bytes bytes.
566 *
567 * @remarks This should be used when the pitch is outside the range of
568 * [-32768,32767].
569 */
570 int32_t EdmaMgr_copy2D1DLarge
571 (
572 EdmaMgr_Handle h,
573 void *restrict src,
574 void *restrict dst,
575 int32_t num_bytes,
576 int32_t num_lines,
577 int32_t pitch
578 );
581 /**
582 * @brief Perform a fast copy. This API inherits the transfer configuration
583 * of a previous transfer and only modifies the @c src and @c dst
584 * addresses.
585 *
586 * @param[in] h Handle returned from EdmaMgr_alloc().
587 * @param[in] src Source address
588 * @param[in] dst Destination address
589 *
590 * @pre @c h must be a handle successfully returned from EdmaMgr_alloc().
591 *
592 * @pre A non-linked transfer must have been completed on handle @c h
593 * before calling this function.
594 *
595 * @sa EdmaMgr_copyLinkedFast
596 */
597 int32_t EdmaMgr_copyFast
598 (
599 EdmaMgr_Handle h,
600 void *restrict src,
601 void *restrict dst
602 );
604 /**
605 * @brief Perform a linked fast copy. This API inherits the transfer
606 * configuration of a previous transfer and only modifies the
607 * @c src and @c dst addresses.
608 *
609 * @param[in] h Handle returned from EdmaMgr_alloc().
610 * @param[in] src[] Array of source addresses
611 * @param[in] dst[] Array of destination addresses
612 * @param[in] num_transfers Number of transfers
613 *
614 * @pre @c h must be a handle successfully returned from EdmaMgr_alloc().
615 *
616 * @pre A linked transfer must have been completed on handle @c h
617 * before calling this function.
618 *
619 * @sa EdmaMgr_copyLinkedFast
620 */
621 int32_t EdmaMgr_copyLinkedFast
622 (
623 EdmaMgr_Handle h,
624 void *restrict src[],
625 void *restrict dst[],
626 int32_t num_transfers
627 );
628 #endif
630 /*@}*/
632 #endif /* ti_sdo_fc_edmamgr_EdmaMgr_ */