1 /*
2 * edma3_common.h
3 *
4 * EDMA3 common header providing generic defines/typedefs and debugging info.
5 *
6 * Copyright (C) 2009 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 EDMA3_COMMON_H_
40 #define EDMA3_COMMON_H_
42 /***************************************************************\
43 * Standard Definition Header File For Null Definition *
44 \***************************************************************/
45 #include <stddef.h>
47 #ifdef __cplusplus
48 extern "C" {
49 #endif
51 /** define to enable/disable Resource Manager debug messages*/
52 /* #define EDMA3_RM_DEBUG */
54 /** define to enable/disable EDMA3 Driver debug messages*/
55 /* #define EDMA3_DRV_DEBUG */
57 /** Debug mechanism used for Resource Manager */
58 #ifdef EDMA3_RM_DEBUG
59 #include <stdio.h>
60 #define EDMA3_RM_PRINTF printf
61 #endif
63 /** Debug mechanism used for EDMA Driver */
64 #ifdef EDMA3_DRV_DEBUG
65 #include <stdio.h>
66 #define EDMA3_DRV_PRINTF printf
67 #endif
69 /** Defines for boolean variables */
70 #ifndef TRUE
71 /** TRUE */
72 #define TRUE (1U)
73 /** FALSE */
74 #define FALSE (0U)
75 #endif
77 /** EDMA3_RM Result - return value of a function */
78 typedef int32_t EDMA3_RM_Result;
79 /** EDMA3_DRV Result - return value of a function */
80 typedef int32_t EDMA3_DRV_Result;
82 /** EDMA3 Resource Manager Result OK */
83 #define EDMA3_RM_SOK (0)
84 /** EDMA3 Driver Result OK */
85 #define EDMA3_DRV_SOK (0)
87 /**
88 * EDMA3 Resource Manager Handle.
89 * It will be returned from EDMA3_RM_open() and will be used to call
90 * other Resource Manager APIs.
91 */
92 typedef void *EDMA3_RM_Handle;
93 /**
94 * EDMA3 Driver Handle.
95 * It will be returned from EDMA3_DRV_open() and will be used to call
96 * other EDMA3 Driver APIs.
97 */
98 typedef void *EDMA3_DRV_Handle;
100 /**
101 * OS specific Semaphore Handle.
102 * Used to acquire/free the semaphore, used for sharing of resources
103 * among multiple users.
104 */
105 typedef void *EDMA3_OS_Sem_Handle;
107 /** Blocking call without timeout */
108 #define EDMA3_OSSEM_NO_TIMEOUT (-1)
110 /**
111 * Defines used to support the maximum resources supported
112 * by the EDMA3 controller. These are used to allocate the maximum
113 * memory for different data structures of the EDMA3 Driver and Resource
114 * Manager.
115 */
116 /** Maximum EDMA3 Controllers on the SoC */
117 #define EDMA3_MAX_EDMA3_INSTANCES (5U)
118 /** Maximum DMA channels supported by the EDMA3 Controller */
119 #define EDMA3_MAX_DMA_CH (64U)
120 /** Maximum QDMA channels supported by the EDMA3 Controller */
121 #define EDMA3_MAX_QDMA_CH (8U)
122 /** Maximum PaRAM Sets supported by the EDMA3 Controller */
123 #define EDMA3_MAX_PARAM_SETS (512U)
124 /** Maximum Logical channels supported by the EDMA3 Package */
125 #define EDMA3_MAX_LOGICAL_CH (EDMA3_MAX_DMA_CH + \
126 EDMA3_MAX_PARAM_SETS + \
127 EDMA3_MAX_QDMA_CH)
128 /** Maximum TCCs (Interrupt Channels) supported by the EDMA3 Controller */
129 #define EDMA3_MAX_TCC (64U)
130 /** Maximum Event Queues supported by the EDMA3 Controller */
131 #define EDMA3_MAX_EVT_QUE (8U)
132 /** Maximum Transfer Controllers supported by the EDMA3 Controller */
133 #define EDMA3_MAX_TC (8U)
134 /** Maximum Shadow Regions supported by the EDMA3 Controller */
135 #define EDMA3_MAX_REGIONS (8U)
137 /**
138 * Maximum Words (4-bytes region) required for the book-keeping information
139 * specific to the maximum possible DMA channels.
140 */
141 #define EDMA3_MAX_DMA_CHAN_DWRDS (EDMA3_MAX_DMA_CH / 32U)
143 /**
144 * Maximum Words (4-bytes region) required for the book-keeping information
145 * specific to the maximum possible QDMA channels.
146 */
147 #define EDMA3_MAX_QDMA_CHAN_DWRDS (1U)
149 /**
150 * Maximum Words (4-bytes region) required for the book-keeping information
151 * specific to the maximum possible PaRAM Sets.
152 */
153 #define EDMA3_MAX_PARAM_DWRDS (EDMA3_MAX_PARAM_SETS / 32U)
155 /**
156 * Maximum Words (4-bytes region) required for the book-keeping information
157 * specific to the maximum possible TCCs.
158 */
159 #define EDMA3_MAX_TCC_DWRDS (EDMA3_MAX_TCC / 32U)
161 /**
162 * EDMA3 ISRs which need to be registered with the underlying OS by the user
163 * (Not all TC error ISRs need to be registered, register only for the
164 * available Transfer Controllers).
165 */
166 /** EDMA3 Completion Handler ISR Routine */
167 extern void lisrEdma3ComplHandler0 (uint32_t arg);
169 /** EDMA3 CC Error Interrupt Handler ISR Routine */
170 extern void lisrEdma3CCErrHandler0 (uint32_t arg);
172 /** EDMA3 TC0 Error Interrupt Handler ISR Routine */
173 extern void lisrEdma3TC0ErrHandler0(uint32_t arg);
174 /** EDMA3 TC1 Error Interrupt Handler ISR Routine */
175 extern void lisrEdma3TC1ErrHandler0(uint32_t arg);
176 /** EDMA3 TC2 Error Interrupt Handler ISR Routine */
177 extern void lisrEdma3TC2ErrHandler0(uint32_t arg);
178 /** EDMA3 TC3 Error Interrupt Handler ISR Routine */
179 extern void lisrEdma3TC3ErrHandler0(uint32_t arg);
180 /** EDMA3 TC4 Error Interrupt Handler ISR Routine */
181 extern void lisrEdma3TC4ErrHandler0(uint32_t arg);
182 /** EDMA3 TC5 Error Interrupt Handler ISR Routine */
183 extern void lisrEdma3TC5ErrHandler0(uint32_t arg);
184 /** EDMA3 TC6 Error Interrupt Handler ISR Routine */
185 extern void lisrEdma3TC6ErrHandler0(uint32_t arg);
186 /** EDMA3 TC7 Error Interrupt Handler ISR Routine */
187 extern void lisrEdma3TC7ErrHandler0(uint32_t arg);
189 /**
190 * Defines for the level of OS protection needed when calling
191 * edma3OsProtectEntry()
192 */
193 /** Protection from All Interrupts required */
194 #define EDMA3_OS_PROTECT_INTERRUPT 1
195 /** Protection from scheduling required */
196 #define EDMA3_OS_PROTECT_SCHEDULER 2
197 /** Protection from EDMA3 Transfer Completion Interrupt required */
198 #define EDMA3_OS_PROTECT_INTERRUPT_XFER_COMPLETION 3
199 /** Protection from EDMA3 CC Error Interrupt required */
200 #define EDMA3_OS_PROTECT_INTERRUPT_CC_ERROR 4
201 /** Protection from EDMA3 TC Error Interrupt required */
202 #define EDMA3_OS_PROTECT_INTERRUPT_TC_ERROR 5
204 /**
205 * Critical section entry and exit functions (OS dependent) should be
206 * implemented by the application for proper linking with the EDMA3 Driver
207 * and/or EDMA3 Resource Manager. Without the definitions being provided,
208 * the image won\92t get linked properly.
209 *
210 * It is possible that for some regions of code, user needs ultimate
211 * degree of protection where some or all external interrupts are blocked,
212 * essentially locking out the CPU exclusively for the critical
213 * section of code. On the other hand, user may wish to merely avoid
214 * thread or task switch from occuring inside said region of code,
215 * but he may wish to entertain ISRs to run if so required.
216 *
217 * Depending on the underlying OS, the number of levels of protection
218 * offered may vary. At the least, these basic levels of protection are
219 * supported --
220 * - EDMA3_OS_PROTECT_INTERRUPT - Mask interrupts globally. This has
221 * real-time implications and must be used with descretion.
223 * - EDMA3_OS_PROTECT_SCHEDULER - Only turns off Kernel scheduler
224 * completely, but still allows h/w interrupts from being serviced.
226 * - EDMA3_OS_PROTECT_INTERRUPT_XFER_COMPLETION - Mask EDMA3 Transfer
227 Completion Interrupt.
229 * - EDMA3_OS_PROTECT_INTERRUPT_CC_ERROR - Mask EDMA3 CC Error Interrupt.
231 * - EDMA3_OS_PROTECT_INTERRUPT_TC_ERROR - Mask EDMA3 TC Error Interrupt.
233 * These APIs should be mandatorily implemented ONCE by the global
234 * initialization routine or by the user itself.
235 */
237 /**
238 * \brief EDMA3 OS Protect Entry
239 *
240 * This function saves the current state of protection in 'intState'
241 * variable passed by caller, if the protection level is
242 * EDMA3_OS_PROTECT_INTERRUPT. It then applies the requested level of
243 * protection.
244 * For EDMA3_OS_PROTECT_INTERRUPT_XFER_COMPLETION and
245 * EDMA3_OS_PROTECT_INTERRUPT_CC_ERROR, variable 'intState' is ignored,
246 * and the requested interrupt is disabled.
247 * For EDMA3_OS_PROTECT_INTERRUPT_TC_ERROR, '*intState' specifies the
248 * Transfer Controller number whose interrupt needs to be disabled.
249 *
250 * \param edma3InstanceId is EDMA3 hardware instance id.
251 * \param level is numeric identifier of the desired degree of protection.
252 * \param intState is memory location where current state of protection is
253 * saved for future use while restoring it via edma3OsProtectExit() (Only
254 * for EDMA3_OS_PROTECT_INTERRUPT protection level).
255 *
256 * \return None
257 */
258 extern void edma3OsProtectEntry (uint32_t edma3InstanceId,
259 int32_t level,
260 uint32_t *intState);
262 /**
263 * \brief EDMA3 OS Protect Exit
264 *
265 * This function undoes the protection enforced to original state
266 * as is specified by the variable 'intState' passed, if the protection
267 * level is EDMA3_OS_PROTECT_INTERRUPT.
268 * For EDMA3_OS_PROTECT_INTERRUPT_XFER_COMPLETION and
269 * EDMA3_OS_PROTECT_INTERRUPT_CC_ERROR, variable 'intState' is ignored,
270 * and the requested interrupt is enabled.
271 * For EDMA3_OS_PROTECT_INTERRUPT_TC_ERROR, 'intState' specifies the
272 * Transfer Controller number whose interrupt needs to be enabled.
273 *
274 * \param edma3InstanceId is EDMA3 hardware instance id.
275 * \param level is numeric identifier of the desired degree of protection.
276 * \param intState is original state of protection at time when the
277 * corresponding edma3OsProtectEntry() was called (Only
278 * for EDMA3_OS_PROTECT_INTERRUPT protection level).
279 *
280 * \return None
281 */
282 extern void edma3OsProtectExit (uint32_t edma3InstanceId,
283 int32_t level,
284 uint32_t intState);
286 /**
287 * Counting Semaphore related functions (OS dependent) should be
288 * implemented by the application for proper linking with the EDMA3
289 * Driver and Resource Manager. The EDMA3 Resource Manager
290 * uses these functions for proper sharing of resources (among various users)
291 * and assume the implementation of these functions
292 * to be provided by the application. Without the definitions being provided,
293 * the image won\92t get linked properly.
294 */
296 /**
297 * \brief EDMA3 OS Semaphore Take
298 *
299 * This function takes a semaphore token if available.
300 * If a semaphore is unavailable, it blocks currently
301 * running thread in wait (for specified duration) for
302 * a free semaphore.
303 *
304 * \param hSem [IN] is the handle of the specified semaphore
305 * \param mSecTimeout [IN] is wait time in milliseconds
306 *
307 * \return EDMA3_DRV_Result if successful else a suitable error code
308 */
309 extern EDMA3_DRV_Result edma3OsSemTake (EDMA3_OS_Sem_Handle hSem,
310 int32_t mSecTimeout);
312 /**
313 * \brief EDMA3 OS Semaphore Give
314 *
315 * This function gives or relinquishes an already
316 * acquired semaphore token
317 *
318 * \param hSem [IN] is the handle of the specified semaphore
319 *
320 * \return EDMA3_DRV_Result if successful else a suitable error code
321 */
322 extern EDMA3_DRV_Result edma3OsSemGive(EDMA3_OS_Sem_Handle hSem);
324 #ifdef __cplusplus
325 }
326 #endif /* extern "C" */
328 #endif /* _EDMA3_COMMON_H_ */