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