debian/edma3/usr/include/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 */
  38
  39 #ifndef _EDMA3_COMMON_H_
  40 #define _EDMA3_COMMON_H_
  41
  42 #ifdef __cplusplus
  43 extern "C" {
  44 #endif
  45
  46 /** define to enable/disable Resource Manager debug messages*/
  47 #define EDMA3_RM_DEBUG
  48 #undef EDMA3_RM_DEBUG
  49
  50 /** define to enable/disable EDMA3 Driver debug messages*/
  51 #define EDMA3_DRV_DEBUG
  52 #undef EDMA3_DRV_DEBUG
  53
  54 /** Debug mechanism used for Resource Manager */
  55 #ifdef EDMA3_RM_DEBUG
  56 #include <stdio.h>
  57 #define EDMA3_RM_PRINTF printf
  58 #endif
  59
  60 /** Debug mechanism used for EDMA Driver */
  61 #ifdef EDMA3_DRV_DEBUG
  62 #include <stdio.h>
  63 #define EDMA3_DRV_PRINTF printf
  64 #endif
  65
  66 /** Defines for boolean variables */
  67 #ifndef TRUE
  68   /** TRUE */
  69   #define TRUE  (1u)
  70   /** FALSE */
  71   #define FALSE (0u)
  72 #endif
  73
  74 /** Define for NULL values*/
  75 #ifndef NULL
  76 #define NULL 0u
  77 #endif
  78
  79 /** EDMA3_RM Result - return value of a function  */
  80 typedef int32_t             EDMA3_RM_Result;
  81 /** EDMA3_DRV Result - return value of a function  */
  82 typedef int32_t             EDMA3_DRV_Result;
  83
  84 /** EDMA3 Resource Manager Result OK */
  85 #define EDMA3_RM_SOK             (0u)
  86 /** EDMA3 Driver Result OK */
  87 #define EDMA3_DRV_SOK            (0u)
  88
  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;
 101
 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;
 108
 109 /** Blocking call without timeout */
 110 #define EDMA3_OSSEM_NO_TIMEOUT    (-1)
 111
 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)
 138
 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)
 144
 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)
 150
 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)
 156
 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)
 162
 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 arg);
 170
 171 /**  EDMA3 CC Error Interrupt Handler ISR Routine */
 172 extern void lisrEdma3CCErrHandler0 (uint32_t arg);
 173
 174 /**  EDMA3 TC0 Error Interrupt Handler ISR Routine */
 175 extern void lisrEdma3TC0ErrHandler0(uint32_t arg);
 176 /**  EDMA3 TC1 Error Interrupt Handler ISR Routine */
 177 extern void lisrEdma3TC1ErrHandler0(uint32_t arg);
 178 /**  EDMA3 TC2 Error Interrupt Handler ISR Routine */
 179 extern void lisrEdma3TC2ErrHandler0(uint32_t arg);
 180 /**  EDMA3 TC3 Error Interrupt Handler ISR Routine */
 181 extern void lisrEdma3TC3ErrHandler0(uint32_t arg);
 182 /**  EDMA3 TC4 Error Interrupt Handler ISR Routine */
 183 extern void lisrEdma3TC4ErrHandler0(uint32_t arg);
 184 /**  EDMA3 TC5 Error Interrupt Handler ISR Routine */
 185 extern void lisrEdma3TC5ErrHandler0(uint32_t arg);
 186 /**  EDMA3 TC6 Error Interrupt Handler ISR Routine */
 187 extern void lisrEdma3TC6ErrHandler0(uint32_t arg);
 188 /**  EDMA3 TC7 Error Interrupt Handler ISR Routine */
 189 extern void lisrEdma3TC7ErrHandler0(uint32_t arg);
 190
 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
 205
 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.
 224
 225  * - EDMA3_OS_PROTECT_SCHEDULER - Only turns off Kernel scheduler
 226  *   completely, but still allows h/w interrupts from being serviced.
 227
 228  * - EDMA3_OS_PROTECT_INTERRUPT_XFER_COMPLETION - Mask EDMA3 Transfer
 229       Completion Interrupt.
 230
 231  * - EDMA3_OS_PROTECT_INTERRUPT_CC_ERROR - Mask EDMA3 CC Error Interrupt.
 232
 233  * - EDMA3_OS_PROTECT_INTERRUPT_TC_ERROR - Mask EDMA3 TC Error Interrupt.
 234
 235  * These APIs should be mandatorily implemented ONCE by the global
 236  * initialization routine or by the user itself.
 237  */
 238
 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);
 263
 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);
 287
 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  */
 297
 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_DRV_Result edma3OsSemTake (EDMA3_OS_Sem_Handle hSem,
 312                                         int32_t mSecTimeout);
 313
 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_DRV_Result edma3OsSemGive(EDMA3_OS_Sem_Handle hSem);
 325
 326 #ifdef __cplusplus
 327 }
 328 #endif /* extern "C" */
 329
 330 #endif  /* _EDMA3_COMMON_H_ */