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