PRSDK-3513 Updated example config file to load McBSP library
[keystone-rtos/mcbsp-lld.git] / example / c6657 / MCBSPDigLpbk / bios6_edma3_drv_sample.h
1 /*
2  * bios6_edma3_drv_sample.h
3  *
4  * Header file for the sample application for the EDMA3 Driver.
5  *
6  * Copyright (C) 2009-2012 Texas Instruments Incorporated - http://www.ti.com/
7  *
8  *
9  *  Redistribution and use in source and binary forms, with or without
10  *  modification, are permitted provided that the following conditions
11  *  are met:
12  *
13  *    Redistributions of source code must retain the above copyright
14  *    notice, this list of conditions and the following disclaimer.
15  *
16  *    Redistributions in binary form must reproduce the above copyright
17  *    notice, this list of conditions and the following disclaimer in the
18  *    documentation and/or other materials provided with the
19  *    distribution.
20  *
21  *    Neither the name of Texas Instruments Incorporated nor the names of
22  *    its contributors may be used to endorse or promote products derived
23  *    from this software without specific prior written permission.
24  *
25  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
26  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
27  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
28  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
29  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
30  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
31  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
35  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36  *
37 */
39 #ifndef _BIOS6_EDMA3_DRV_SAMPLE_H_
40 #define _BIOS6_EDMA3_DRV_SAMPLE_H_
42 #include <stdio.h>
43 #include <ti/sysbios/knl/Semaphore.h>
45 /* Include EDMA3 Driver */
46 #include <ti/sdo/edma3/drv/edma3_drv.h>
48 #ifdef __cplusplus
49 extern "C" {
50 #endif
52 /**
53  * Cache line size on the underlying SoC. It needs to be modified
54  * for different cache line sizes, if the Cache is Enabled.
55  */
56 #define EDMA3_CACHE_LINE_SIZE_IN_BYTES      (128u)
58 /* Error returned in case of buffers are not aligned on the cache boundary */
59 #define EDMA3_NON_ALIGNED_BUFFERS_ERROR     (-1)
61 /* Error returned in case of data mismatch */
62 #define EDMA3_DATA_MISMATCH_ERROR           (-2)
64 /**
65  * \brief   EDMA3 Initialization
66  *
67  * This function initializes the EDMA3 Driver for the given EDMA3 controller
68  * and opens a EDMA3 driver instance. It internally calls EDMA3_DRV_create() and
69  * EDMA3_DRV_open(), in that order.
70  *
71  * It also registers interrupt handlers for various EDMA3 interrupts like 
72  * transfer completion or error interrupts.
73  *
74  *  \param  edma3Id     [IN]            EDMA3 Controller Instance Id (Hardware
75  *                                                                      instance id, starting from 0)
76  *  \param  errorCode   [IN/OUT]        Error code while opening DRV instance
77  *  \return EDMA3_DRV_Handle: If successfully opened, the API will return the
78  *                            associated driver's instance handle.
79  */
80 EDMA3_DRV_Handle edma3init (unsigned int edma3Id, EDMA3_DRV_Result *errorCode);
82 /**
83  * \brief   EDMA3 De-initialization
84  *
85  * This function de-initializes the EDMA3 Driver for the given EDMA3 controller
86  * and closes the previously opened EDMA3 driver instance. It internally calls 
87  * EDMA3_DRV_close and EDMA3_DRV_delete(), in that order.
88  *
89  * It also un-registers the previously registered interrupt handlers for various 
90  * EDMA3 interrupts.
91  *
92  *  \param  edma3Id     [IN]            EDMA3 Controller Instance Id (Hardware
93  *                                                                      instance id, starting from 0)
94  *  \param  hEdma               [IN]            EDMA3 Driver handle, returned while using
95  *                                                                      edma3init().
96  *  \return  EDMA3_DRV_SOK if success, else error code
97  */
98 EDMA3_DRV_Result edma3deinit (unsigned int edma3Id, EDMA3_DRV_Handle hEdma);
101 /**
102  *  \brief   EDMA3 Cache Invalidate
103  *
104  *  This function invalidates the D cache.
105  *
106  *  \param  mem_start_ptr [IN]      Starting address of memory.
107  *                                  Please note that this should be
108  *                                  aligned according to the cache line size.
109  *  \param  num_bytes [IN]          length of buffer
110  *  \return  EDMA3_DRV_SOK if success, else error code in case of error
111  *          or non-alignment of buffers.
112  *
113  * Note: This function is required if the buffer is in DDR.
114  * For other cases, where buffer is NOT in DDR, user
115  * may or may not require the below implementation and
116  * should modify it according to her need.
117  */
118 EDMA3_DRV_Result Edma3_CacheInvalidate(unsigned int mem_start_ptr,
119                            unsigned int num_bytes);
123 /**
124  * \brief   EDMA3 Cache Flush
125  *
126  *  This function flushes (cleans) the Cache
127  *
128  *  \param  mem_start_ptr [IN]      Starting address of memory.
129  *                                  Please note that this should be
130  *                                  aligned according to the cache line size.
131  *  \param  num_bytes [IN]          length of buffer
132  *  \return  EDMA3_DRV_SOK if success, else error code in case of error
133  *          or non-alignment of buffers.
134  *
135  * Note: This function is required if the buffer is in DDR.
136  * For other cases, where buffer is NOT in DDR, user
137  * may or may not require the below implementation and
138  * should modify it according to her need.
139  */
140 EDMA3_DRV_Result Edma3_CacheFlush(unsigned int mem_start_ptr,
141                       unsigned int num_bytes);
145 /**
146   * Counting Semaphore related functions (OS dependent) should be
147   * called/implemented by the application. A handle to the semaphore
148   * is required while opening the driver/resource manager instance.
149   */
151 /**
152  * \brief   EDMA3 OS Semaphore Create
153  *
154  *      This function creates a counting semaphore with specified
155  *      attributes and initial value. It should be used to create a semaphore
156  *      with initial value as '1'. The semaphore is then passed by the user
157  *      to the EDMA3 driver/RM for proper sharing of resources.
158  * \param   initVal [IN] is initial value for semaphore
159  * \param   semParams [IN] is the semaphore attributes.
160  * \param   hSem [OUT] is location to receive the handle to just created
161  *      semaphore.
162  * \return  EDMA3_DRV_SOK if successful, else a suitable error code.
163  */
164 EDMA3_DRV_Result edma3OsSemCreate(int initVal,
165                                                         const Semaphore_Params *semParams,
166                                                         EDMA3_OS_Sem_Handle *hSem);
170 /**
171  * \brief   EDMA3 OS Semaphore Delete
172  *
173  *      This function deletes or removes the specified semaphore
174  *      from the system. Associated dynamically allocated memory
175  *      if any is also freed up.
176  * \param   hSem [IN] handle to the semaphore to be deleted
177  * \return  EDMA3_DRV_SOK if successful else a suitable error code
178  */
179 EDMA3_DRV_Result edma3OsSemDelete(EDMA3_OS_Sem_Handle hSem);
181 #ifdef __cplusplus
183 #endif /* extern "C" */
185 #endif  /* _BIOS6_EDMA3_DRV_SAMPLE_H_ */