packages/ti/sdo/edma3/rm/sample/bios6_edma3_rm_sample.h

   1 /*
   2  * bios6_edma3_rm_sample.h
   3  *
   4  * Header file for the Demo application for the EDMA3 Resource Manager.
   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 _BIOS6_EDMA3_RM_SAMPLE_H_
  40 #define _BIOS6_EDMA3_RM_SAMPLE_H_
  41
  42 #include <ti/sysbios/ipc/Semaphore.h>
  43
  44 #include <ti/sdo/edma3/rm/edma3_rm.h>
  45
  46 #ifdef __cplusplus
  47 extern "C" {
  48 #endif
  49
  50 /* To enable debug traces in the EDMA3 sample app */
  51 #define EDMA3_DEBUG_PRINT
  52
  53 #ifdef EDMA3_DEBUG_PRINT
  54 #include <stdio.h>
  55 #define EDMA3_DEBUG_PRINTF           printf
  56 #endif /* EDMA3_DEBUG_PRINT */
  57
  58 /**
  59  * Cache line size on the underlying SoC. It needs to be modified
  60  * for different cache line sizes, if the Cache is Enabled.
  61  */
  62 #define EDMA3_CACHE_LINE_SIZE_IN_BYTES      (128u)
  63
  64 /* Error returned in case of buffers are not aligned on the cache boundary */
  65 #define EDMA3_NON_ALIGNED_BUFFERS_ERROR     (-1)
  66
  67 /* Error returned in case of data mismatch */
  68 #define EDMA3_DATA_MISMATCH_ERROR           (-2)
  69
  70 /**
  71  * \brief   EDMA3 Initialization
  72  *
  73  * This function initializes the EDMA3 Resource Manager for the given EDMA3 controller
  74  * and opens a EDMA3 RM instance. It internally calls EDMA3_RM_create() and
  75  * EDMA3_RM_open(), in that order.
  76  *
  77  * It also registers interrupt handlers for various EDMA3 interrupts like
  78  * transfer completion or error interrupts.
  79  *
  80  *  \param  edma3Id     [IN]            EDMA3 Controller Instance Id (Hardware
  81  *                                                                      instance id, starting from 0)
  82  *  \param  errorCode   [IN/OUT]        Error code while opening RM instance
  83  *  \return EDMA3_RM_Handle: If successfully opened, the API will return the
  84  *                            associated RM's instance handle.
  85  */
  86 EDMA3_RM_Handle edma3init (unsigned int edma3Id, EDMA3_RM_Result *errorCode);
  87
  88 /**
  89  * \brief   EDMA3 De-initialization
  90  *
  91  * This function de-initializes the EDMA3 RM for the given EDMA3 controller
  92  * and closes the previously opened EDMA3 RM instance. It internally calls
  93  * EDMA3_RM_close and EDMA3_RM_delete(), in that order.
  94  *
  95  * It also un-registers the previously registered interrupt handlers for various
  96  * EDMA3 interrupts.
  97  *
  98  *  \param  edma3Id     [IN]            EDMA3 Controller Instance Id (Hardware
  99  *                                                                      instance id, starting from 0)
 100  *  \param  hEdma               [IN]            EDMA3 RM handle, returned while using
 101  *                                                                      edma3init().
 102  *  \return  EDMA3_RM_SOK if success, else error code
 103  */
 104 EDMA3_RM_Result edma3deinit (unsigned int edma3Id, EDMA3_RM_Handle hEdma);
 105
 106 /**
 107  * Counting Semaphore related functions (OS dependent) should be
 108  * called/implemented by the application. A handle to the semaphore
 109  * is required while opening the driver/resource manager instance.
 110  */
 111
 112 /**
 113  * \brief   EDMA3 OS Semaphore Create
 114  *
 115  *      This function creates a counting semaphore with specified
 116  *      attributes and initial value. It should be used to create a semaphore
 117  *      with initial value as '1'. The semaphore is then passed by the user
 118  *      to the EDMA3 RM for proper sharing of resources.
 119  * \param   initVal [IN] is initial value for semaphore
 120  * \param   attrs [IN] is the semaphore attributes ex: Fifo type
 121  * \param   hSem [OUT] is location to recieve the handle to just created
 122  *      semaphore
 123  * \return  EDMA3_RM_SOK if succesful, else a suitable error code.
 124  */
 125 EDMA3_RM_Result edma3OsSemCreate(int initVal,
 126                                                         const Semaphore_Params *semParams,
 127                                 EDMA3_OS_Sem_Handle *hSem);
 128
 129 /**
 130  * \brief   EDMA3 OS Semaphore Delete
 131  *
 132  *      This function deletes or removes the specified semaphore
 133  *      from the system. Associated dynamically allocated memory
 134  *      if any is also freed up.
 135  * \warning OsSEM services run in client context and not in a thread
 136  *      of their own. If there exist threads pended on a semaphore
 137  *      that is being deleted, results are undefined.
 138  * \param   hSem [IN] handle to the semaphore to be deleted
 139  * \return  EDMA3_RM_SOK if succesful else a suitable error code
 140  */
 141 EDMA3_RM_Result edma3OsSemDelete(EDMA3_OS_Sem_Handle hSem);
 142
 143 #ifdef __cplusplus
 144 }
 145 #endif /* extern "C" */
 146
 147 #endif
 148