example/k2g/MCBSPDigLpbk/bios6_edma3_drv_sample.h

   1 /*
   2  * bios6_edma3_drv_sample.h
   3  *
   4  * Header file for the sample application for the EDMA3 Driver.
   5  *
   6  * Copyright (C) 2009-2012 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 _BIOS6_EDMA3_DRV_SAMPLE_H_
  40 #define _BIOS6_EDMA3_DRV_SAMPLE_H_
  41
  42 #include <stdio.h>
  43 #include <ti/sysbios/knl/Semaphore.h>
  44
  45 /* Include EDMA3 Driver */
  46 #include <ti/sdo/edma3/drv/edma3_drv.h>
  47
  48 #ifdef __cplusplus
  49 extern "C" {
  50 #endif
  51
  52 /**
  53  * Cache line size on the underlying SoC. It needs to be modified
  54  * for different cache line sizes, if the Cache is Enabled.
  55  */
  56 #define EDMA3_CACHE_LINE_SIZE_IN_BYTES      (128u)
  57
  58 /* Error returned in case of buffers are not aligned on the cache boundary */
  59 #define EDMA3_NON_ALIGNED_BUFFERS_ERROR     (-1)
  60
  61 /* Error returned in case of data mismatch */
  62 #define EDMA3_DATA_MISMATCH_ERROR           (-2)
  63
  64 /**
  65  * \brief   EDMA3 Initialization
  66  *
  67  * This function initializes the EDMA3 Driver for the given EDMA3 controller
  68  * and opens a EDMA3 driver instance. It internally calls EDMA3_DRV_create() and
  69  * EDMA3_DRV_open(), in that order.
  70  *
  71  * It also registers interrupt handlers for various EDMA3 interrupts like
  72  * transfer completion or error interrupts.
  73  *
  74  *  \param  edma3Id     [IN]            EDMA3 Controller Instance Id (Hardware
  75  *                                                                      instance id, starting from 0)
  76  *  \param  errorCode   [IN/OUT]        Error code while opening DRV instance
  77  *  \return EDMA3_DRV_Handle: If successfully opened, the API will return the
  78  *                            associated driver's instance handle.
  79  */
  80 EDMA3_DRV_Handle edma3init (unsigned int edma3Id, EDMA3_DRV_Result *errorCode);
  81
  82 /**
  83  * \brief   EDMA3 De-initialization
  84  *
  85  * This function de-initializes the EDMA3 Driver for the given EDMA3 controller
  86  * and closes the previously opened EDMA3 driver instance. It internally calls
  87  * EDMA3_DRV_close and EDMA3_DRV_delete(), in that order.
  88  *
  89  * It also un-registers the previously registered interrupt handlers for various
  90  * EDMA3 interrupts.
  91  *
  92  *  \param  edma3Id     [IN]            EDMA3 Controller Instance Id (Hardware
  93  *                                                                      instance id, starting from 0)
  94  *  \param  hEdma               [IN]            EDMA3 Driver handle, returned while using
  95  *                                                                      edma3init().
  96  *  \return  EDMA3_DRV_SOK if success, else error code
  97  */
  98 EDMA3_DRV_Result edma3deinit (unsigned int edma3Id, EDMA3_DRV_Handle hEdma);
  99
 100
 101 /**
 102  *  \brief   EDMA3 Cache Invalidate
 103  *
 104  *  This function invalidates the D cache.
 105  *
 106  *  \param  mem_start_ptr [IN]      Starting address of memory.
 107  *                                  Please note that this should be
 108  *                                  aligned according to the cache line size.
 109  *  \param  num_bytes [IN]          length of buffer
 110  *  \return  EDMA3_DRV_SOK if success, else error code in case of error
 111  *          or non-alignment of buffers.
 112  *
 113  * Note: This function is required if the buffer is in DDR.
 114  * For other cases, where buffer is NOT in DDR, user
 115  * may or may not require the below implementation and
 116  * should modify it according to her need.
 117  */
 118 EDMA3_DRV_Result Edma3_CacheInvalidate(unsigned int mem_start_ptr,
 119                            unsigned int num_bytes);
 120
 121
 122
 123 /**
 124  * \brief   EDMA3 Cache Flush
 125  *
 126  *  This function flushes (cleans) the Cache
 127  *
 128  *  \param  mem_start_ptr [IN]      Starting address of memory.
 129  *                                  Please note that this should be
 130  *                                  aligned according to the cache line size.
 131  *  \param  num_bytes [IN]          length of buffer
 132  *  \return  EDMA3_DRV_SOK if success, else error code in case of error
 133  *          or non-alignment of buffers.
 134  *
 135  * Note: This function is required if the buffer is in DDR.
 136  * For other cases, where buffer is NOT in DDR, user
 137  * may or may not require the below implementation and
 138  * should modify it according to her need.
 139  */
 140 EDMA3_DRV_Result Edma3_CacheFlush(unsigned int mem_start_ptr,
 141                       unsigned int num_bytes);
 142
 143
 144
 145 /**
 146   * Counting Semaphore related functions (OS dependent) should be
 147   * called/implemented by the application. A handle to the semaphore
 148   * is required while opening the driver/resource manager instance.
 149   */
 150
 151 /**
 152  * \brief   EDMA3 OS Semaphore Create
 153  *
 154  *      This function creates a counting semaphore with specified
 155  *      attributes and initial value. It should be used to create a semaphore
 156  *      with initial value as '1'. The semaphore is then passed by the user
 157  *      to the EDMA3 driver/RM for proper sharing of resources.
 158  * \param   initVal [IN] is initial value for semaphore
 159  * \param   semParams [IN] is the semaphore attributes.
 160  * \param   hSem [OUT] is location to receive the handle to just created
 161  *      semaphore.
 162  * \return  EDMA3_DRV_SOK if successful, else a suitable error code.
 163  */
 164 EDMA3_DRV_Result edma3OsSemCreate(int initVal,
 165                                                         const Semaphore_Params *semParams,
 166                                                         EDMA3_OS_Sem_Handle *hSem);
 167
 168
 169
 170 /**
 171  * \brief   EDMA3 OS Semaphore Delete
 172  *
 173  *      This function deletes or removes the specified semaphore
 174  *      from the system. Associated dynamically allocated memory
 175  *      if any is also freed up.
 176  * \param   hSem [IN] handle to the semaphore to be deleted
 177  * \return  EDMA3_DRV_SOK if successful else a suitable error code
 178  */
 179 EDMA3_DRV_Result edma3OsSemDelete(EDMA3_OS_Sem_Handle hSem);
 180
 181 #ifdef __cplusplus
 182 }
 183 #endif /* extern "C" */
 184
 185 #endif  /* _BIOS6_EDMA3_DRV_SAMPLE_H_ */
 186