1 /******************************************************************************\r
2 **+-------------------------------------------------------------------------+**\r
3 **| **** |**\r
4 **| **** |**\r
5 **| ******o*** |**\r
6 **| ********_///_**** |**\r
7 **| ***** /_//_/ **** |**\r
8 **| ** ** (__/ **** |**\r
9 **| ********* |**\r
10 **| **** |**\r
11 **| *** |**\r
12 **| |**\r
13 **| Copyright (c) 1998-2006 Texas Instruments Incorporated |**\r
14 **| ALL RIGHTS RESERVED |**\r
15 **| |**\r
16 **| Permission is hereby granted to licensees of Texas Instruments |**\r
17 **| Incorporated (TI) products to use this computer program for the sole |**\r
18 **| purpose of implementing a licensee product based on TI products. |**\r
19 **| No other rights to reproduce, use, or disseminate this computer |**\r
20 **| program, whether in part or in whole, are granted. |**\r
21 **| |**\r
22 **| TI makes no representation or warranties with respect to the |**\r
23 **| performance of this computer program, and specifically disclaims |**\r
24 **| any responsibility for any damages, special or consequential, |**\r
25 **| connected with the use of this program. |**\r
26 **| |**\r
27 **+-------------------------------------------------------------------------+**\r
28 ******************************************************************************/\r
29 \r
30 /** \file edma3_common.h\r
31 \brief EDMA3 Common header provides generic defines/typedefs and\r
32 debugging info.\r
33 \r
34 This file contains the generic defines and typedefs and the debugging\r
35 info that are common across interfaces of EDMA Res Mgr and EDMA Driver\r
36 and visible to the application.\r
37 \r
38 (C) Copyright 2006, Texas Instruments, Inc\r
39 \r
40 */\r
41 \r
42 #ifndef _EDMA3_COMMON_H_\r
43 #define _EDMA3_COMMON_H_\r
44 \r
45 #ifdef __cplusplus\r
46 extern "C" {\r
47 #endif\r
48 \r
49 \r
50 /** define to enable/disable Resource Manager debug messages*/\r
51 #define EDMA3_RM_DEBUG\r
52 #undef EDMA3_RM_DEBUG\r
53 \r
54 /** define to enable/disable EDMA3 Driver debug messages*/\r
55 #define EDMA3_DRV_DEBUG\r
56 #undef EDMA3_DRV_DEBUG\r
57 \r
58 \r
59 /** Debug mechanism used for Resource Manager */\r
60 #ifdef EDMA3_RM_DEBUG\r
61 #include <stdio.h>\r
62 #define EDMA3_RM_PRINTF printf\r
63 #endif\r
64 \r
65 /** Debug mechanism used for EDMA Driver */\r
66 #ifdef EDMA3_DRV_DEBUG\r
67 #include <stdio.h>\r
68 #define EDMA3_DRV_PRINTF printf\r
69 #endif\r
70 \r
71 \r
72 /** Defines for boolean variables */\r
73 #ifndef TRUE\r
74 /** TRUE */\r
75 #define TRUE (1u)\r
76 /** FALSE */\r
77 #define FALSE (0u)\r
78 #endif\r
79 \r
80 \r
81 /** Define for NULL values*/\r
82 #ifndef NULL\r
83 #define NULL 0u\r
84 #endif\r
85 \r
86 \r
87 /** EDMA3_RM Result - return value of a function */\r
88 typedef int EDMA3_RM_Result;\r
89 /** EDMA3_DRV Result - return value of a function */\r
90 typedef int EDMA3_DRV_Result;\r
91 \r
92 \r
93 /** EDMA3 Resource Manager Result OK */\r
94 #define EDMA3_RM_SOK (0u)\r
95 /** EDMA3 Driver Result OK */\r
96 #define EDMA3_DRV_SOK (0u)\r
97 \r
98 \r
99 /**\r
100 * EDMA3 Resource Manager Handle.\r
101 * It will be returned from EDMA3_RM_open() and will be used to call\r
102 * other Resource Manager APIs.\r
103 */\r
104 typedef void *EDMA3_RM_Handle;\r
105 /**\r
106 * EDMA3 Driver Handle.\r
107 * It will be returned from EDMA3_DRV_open() and will be used to call\r
108 * other EDMA3 Driver APIs.\r
109 */\r
110 typedef void *EDMA3_DRV_Handle;\r
111 \r
112 \r
113 /**\r
114 * OS specific Semaphore Handle.\r
115 * Used to acquire/free the semaphore, used for sharing of resources\r
116 * among multiple users.\r
117 */\r
118 typedef void *EDMA3_OS_Sem_Handle;\r
119 \r
120 /** Blocking call without timeout */\r
121 #define EDMA3_OSSEM_NO_TIMEOUT (-1)\r
122 \r
123 \r
124 /**\r
125 * Defines used to support the maximum resources supported\r
126 * by the EDMA3 controller. These are used to allocate the maximum\r
127 * memory for different data structures of the EDMA3 Driver and Resource\r
128 * Manager.\r
129 */\r
130 /** Maximum EDMA3 Controllers on the SoC */\r
131 #define EDMA3_MAX_EDMA3_INSTANCES (1u)\r
132 /** Maximum DMA channels supported by the EDMA3 Controller */\r
133 #define EDMA3_MAX_DMA_CH (64u)\r
134 /** Maximum QDMA channels supported by the EDMA3 Controller */\r
135 #define EDMA3_MAX_QDMA_CH (8u)\r
136 /** Maximum PaRAM Sets supported by the EDMA3 Controller */\r
137 #define EDMA3_MAX_PARAM_SETS (512u)\r
138 /** Maximum Logical channels supported by the EDMA3 Package */\r
139 #define EDMA3_MAX_LOGICAL_CH (EDMA3_MAX_DMA_CH + \\r
140 EDMA3_MAX_PARAM_SETS + \\r
141 EDMA3_MAX_QDMA_CH)\r
142 /** Maximum TCCs (Interrupt Channels) supported by the EDMA3 Controller */\r
143 #define EDMA3_MAX_TCC (64u)\r
144 /** Maximum Event Queues supported by the EDMA3 Controller */\r
145 #define EDMA3_MAX_EVT_QUE (8u)\r
146 /** Maximum Transfer Controllers supported by the EDMA3 Controller */\r
147 #define EDMA3_MAX_TC (8u)\r
148 /** Maximum Shadow Regions supported by the EDMA3 Controller */\r
149 #define EDMA3_MAX_REGIONS (8u)\r
150 \r
151 /**\r
152 * Maximum Words (4-bytes region) required for the book-keeping information\r
153 * specific to the maximum possible DMA channels.\r
154 */\r
155 #define EDMA3_MAX_DMA_CHAN_DWRDS (EDMA3_MAX_DMA_CH / 32u)\r
156 \r
157 /**\r
158 * Maximum Words (4-bytes region) required for the book-keeping information\r
159 * specific to the maximum possible QDMA channels.\r
160 */\r
161 #define EDMA3_MAX_QDMA_CHAN_DWRDS (1u)\r
162 \r
163 /**\r
164 * Maximum Words (4-bytes region) required for the book-keeping information\r
165 * specific to the maximum possible PaRAM Sets.\r
166 */\r
167 #define EDMA3_MAX_PARAM_DWRDS (EDMA3_MAX_PARAM_SETS / 32u)\r
168 \r
169 /**\r
170 * Maximum Words (4-bytes region) required for the book-keeping information\r
171 * specific to the maximum possible TCCs.\r
172 */\r
173 #define EDMA3_MAX_TCC_DWRDS (EDMA3_MAX_TCC / 32u)\r
174 \r
175 \r
176 \r
177 /**\r
178 * EDMA3 ISRs which need to be registered with the underlying OS by the user\r
179 * (Not all TC error ISRs need to be registered, register only for the\r
180 * available Transfer Controllers).\r
181 */\r
182 \r
183 /** EDMA3 Completion Handler ISR Routine */\r
184 extern void lisrEdma3ComplHandler0 (unsigned int arg);\r
185 \r
186 /** EDMA3 CC Error Interrupt Handler ISR Routine */\r
187 extern void lisrEdma3CCErrHandler0 (unsigned int arg);\r
188 \r
189 /** EDMA3 TC0 Error Interrupt Handler ISR Routine */\r
190 extern void lisrEdma3TC0ErrHandler0(unsigned int arg);\r
191 /** EDMA3 TC1 Error Interrupt Handler ISR Routine */\r
192 extern void lisrEdma3TC1ErrHandler0(unsigned int arg);\r
193 /** EDMA3 TC2 Error Interrupt Handler ISR Routine */\r
194 extern void lisrEdma3TC2ErrHandler0(unsigned int arg);\r
195 /** EDMA3 TC3 Error Interrupt Handler ISR Routine */\r
196 extern void lisrEdma3TC3ErrHandler0(unsigned int arg);\r
197 /** EDMA3 TC4 Error Interrupt Handler ISR Routine */\r
198 extern void lisrEdma3TC4ErrHandler0(unsigned int arg);\r
199 /** EDMA3 TC5 Error Interrupt Handler ISR Routine */\r
200 extern void lisrEdma3TC5ErrHandler0(unsigned int arg);\r
201 /** EDMA3 TC6 Error Interrupt Handler ISR Routine */\r
202 extern void lisrEdma3TC6ErrHandler0(unsigned int arg);\r
203 /** EDMA3 TC7 Error Interrupt Handler ISR Routine */\r
204 extern void lisrEdma3TC7ErrHandler0(unsigned int arg);\r
205 \r
206 \r
207 \r
208 /**\r
209 * Defines for the level of OS protection needed when calling\r
210 * edma3OsProtectEntry()\r
211 */\r
212 \r
213 /** Protection from All Interrupts required */\r
214 #define EDMA3_OS_PROTECT_INTERRUPT 1\r
215 /** Protection from scheduling required */\r
216 #define EDMA3_OS_PROTECT_SCHEDULER 2\r
217 /** Protection from EDMA3 Transfer Completion Interrupt required */\r
218 #define EDMA3_OS_PROTECT_INTERRUPT_XFER_COMPLETION 3\r
219 /** Protection from EDMA3 CC Error Interrupt required */\r
220 #define EDMA3_OS_PROTECT_INTERRUPT_CC_ERROR 4\r
221 /** Protection from EDMA3 TC Error Interrupt required */\r
222 #define EDMA3_OS_PROTECT_INTERRUPT_TC_ERROR 5\r
223 \r
224 \r
225 \r
226 /**\r
227 * Critical section entry and exit functions (OS dependent) should be\r
228 * implemented by the application for proper linking with the EDMA3 Driver\r
229 * and/or EDMA3 Resource Manager. Without the definitions being provided,\r
231 *\r
232 * It is possible that for some regions of code, user needs ultimate\r
233 * degree of protection where some or all external interrupts are blocked,\r
234 * essentially locking out the CPU exclusively for the critical\r
235 * section of code. On the other hand, user may wish to merely avoid\r
236 * thread or task switch from occuring inside said region of code,\r
237 * but he may wish to entertain ISRs to run if so required.\r
238 *\r
239 * Depending on the underlying OS, the number of levels of protection\r
240 * offered may vary. At the least, these basic levels of protection are\r
241 * supported --\r
242 * - EDMA3_OS_PROTECT_INTERRUPT - Mask interrupts globally. This has\r
243 * real-time implications and must be used with descretion.\r
244 \r
245 * - EDMA3_OS_PROTECT_SCHEDULER - Only turns off Kernel scheduler\r
246 * completely, but still allows h/w interrupts from being serviced.\r
247 \r
248 * - EDMA3_OS_PROTECT_INTERRUPT_XFER_COMPLETION - Mask EDMA3 Transfer\r
249 Completion Interrupt.\r
250 \r
251 * - EDMA3_OS_PROTECT_INTERRUPT_CC_ERROR - Mask EDMA3 CC Error Interrupt.\r
252 \r
253 * - EDMA3_OS_PROTECT_INTERRUPT_TC_ERROR - Mask EDMA3 TC Error Interrupt.\r
254 \r
255 * These APIs should be mandatorily implemented ONCE by the global\r
256 * initialization routine or by the user itself.\r
257 */\r
258 \r
259 /** \fn extern void edma3OsProtectEntry (int level, unsigned int *intState);\r
260 * \brief EDMA3 OS Protect Entry\r
261 *\r
262 * This function saves the current state of protection in 'intState'\r
263 * variable passed by caller, if the protection level is\r
264 * EDMA3_OS_PROTECT_INTERRUPT. It then applies the requested level of\r
265 * protection.\r
266 * For EDMA3_OS_PROTECT_INTERRUPT_XFER_COMPLETION and\r
267 * EDMA3_OS_PROTECT_INTERRUPT_CC_ERROR, variable 'intState' is ignored,\r
268 * and the requested interrupt is disabled.\r
269 * For EDMA3_OS_PROTECT_INTERRUPT_TC_ERROR, '*intState' specifies the\r
270 * Transfer Controller number whose interrupt needs to be disabled.\r
271 *\r
272 * \param level is numeric identifier of the desired degree of protection.\r
273 * \param intState is memory location where current state of protection is\r
274 * saved for future use while restoring it via edma3OsProtectExit() (Only\r
275 * for EDMA3_OS_PROTECT_INTERRUPT protection level).\r
276 *\r
277 * \return None\r
278 */\r
279 extern void edma3OsProtectEntry (int level, unsigned int *intState);\r
280 \r
281 \r
282 /** \fn extern void edma3OsProtectExit (int level, unsigned int intState);\r
283 * \brief EDMA3 OS Protect Exit\r
284 *\r
285 * This function undoes the protection enforced to original state\r
286 * as is specified by the variable 'intState' passed, if the protection\r
287 * level is EDMA3_OS_PROTECT_INTERRUPT.\r
288 * For EDMA3_OS_PROTECT_INTERRUPT_XFER_COMPLETION and\r
289 * EDMA3_OS_PROTECT_INTERRUPT_CC_ERROR, variable 'intState' is ignored,\r
290 * and the requested interrupt is enabled.\r
291 * For EDMA3_OS_PROTECT_INTERRUPT_TC_ERROR, 'intState' specifies the\r
292 * Transfer Controller number whose interrupt needs to be enabled.\r
293 *\r
294 * \param level is numeric identifier of the desired degree of protection.\r
295 * \param intState is original state of protection at time when the\r
296 * corresponding edma3OsProtectEntry() was called (Only\r
297 * for EDMA3_OS_PROTECT_INTERRUPT protection level).\r
298 *\r
299 * \return None\r
300 */\r
301 extern void edma3OsProtectExit (int level, unsigned int intState);\r
302 \r
303 \r
304 /**\r
305 * Counting Semaphore related functions (OS dependent) should be\r
306 * implemented by the application for proper linking with the EDMA3\r
307 * Driver and Resource Manager. The EDMA3 Resource Manager\r
308 * uses these functions for proper sharing of resources (among various users)\r
309 * and assume the implementation of these functions\r
310 * to be provided by the application. Without the definitions being provided,\r
312 */\r
313 /** \fn extern EDMA3_DRV_Result edma3OsSemTake (EDMA3_OS_Sem_Handle hSem,\r
314 * int mSecTimeout);\r
315 * \brief EDMA3 OS Semaphore Take\r
316 *\r
317 * This function takes a semaphore token if available.\r
318 * If a semaphore is unavailable, it blocks currently\r
319 * running thread in wait (for specified duration) for\r
320 * a free semaphore.\r
321 *\r
322 * \param hSem [IN] is the handle of the specified semaphore\r
323 * \param mSecTimeout [IN] is wait time in milliseconds\r
324 *\r
325 * \return EDMA3_DRV_Result if successful else a suitable error code\r
326 */\r
327 extern EDMA3_DRV_Result edma3OsSemTake (EDMA3_OS_Sem_Handle hSem,\r
328 int mSecTimeout);\r
329 \r
330 /** \fn extern EDMA3_DRV_Result edma3OsSemGive(EDMA3_OS_Sem_Handle hSem);\r
331 * \brief EDMA3 OS Semaphore Give\r
332 *\r
333 * This function gives or relinquishes an already\r
334 * acquired semaphore token\r
335 *\r
336 * \param hSem [IN] is the handle of the specified semaphore\r
337 *\r
338 * \return EDMA3_DRV_Result if successful else a suitable error code\r
339 */\r
340 extern EDMA3_DRV_Result edma3OsSemGive(EDMA3_OS_Sem_Handle hSem);\r
341 \r
342 #ifdef __cplusplus\r
343 }\r
344 #endif /* extern "C" */\r
345 \r
346 #endif /* _EDMA3_COMMON_H_ */\r
347 \r