packages/ti/sdo/edma3/rm/src/edma3resmgr.h

   1 /*
   2  * edma3resmgr.h
   3  *
   4  * EDMA3 Resource Manager Internal header file.
   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_RES_MGR_H_
  40 #define _EDMA3_RES_MGR_H_
  41
  42
  43 /** Include Resource Manager header file */
  44 #include <ti/sdo/edma3/rm/edma3_rm.h>
  45
  46 /* For the EDMA3 Register Layer functionality. */
  47 #include <ti/sdo/edma3/rm/src/edma3_rl_cc.h>
  48 #include <ti/sdo/edma3/rm/src/edma3_rl_tc.h>
  49
  50 #ifdef __cplusplus
  51 extern "C" {
  52 #endif
  53
  54 /**
  55  * Number of PaRAM Sets actually present on the SoC. This will be updated
  56  * while creating the Resource Manager Object.
  57  */
  58 extern unsigned int edma3NumPaRAMSets;
  59
  60
  61 /** Define for setting all bits of the EDMA3 Controller Registers */
  62 #define EDMA3_RM_SET_ALL_BITS              (0xFFFFFFFFu)
  63
  64 /* Other Mask defines */
  65 /** DCHMAP-PaRAMEntry bitfield Clear */
  66 #define EDMA3_RM_DCH_PARAM_CLR_MASK                (~EDMA3_CCRL_DCHMAP_PAENTRY_MASK)
  67 /** DCHMAP-PaRAMEntry bitfield Set */
  68 #define EDMA3_RM_DCH_PARAM_SET_MASK(paRAMId)       (((EDMA3_CCRL_DCHMAP_PAENTRY_MASK >> EDMA3_CCRL_DCHMAP_PAENTRY_SHIFT) & (paRAMId)) << EDMA3_CCRL_DCHMAP_PAENTRY_SHIFT)
  69 /** QCHMAP-PaRAMEntry bitfield Clear */
  70 #define EDMA3_RM_QCH_PARAM_CLR_MASK                (~EDMA3_CCRL_QCHMAP_PAENTRY_MASK)
  71 /** QCHMAP-PaRAMEntry bitfield Set */
  72 #define EDMA3_RM_QCH_PARAM_SET_MASK(trWord)       (((EDMA3_CCRL_QCHMAP_PAENTRY_MASK >> EDMA3_CCRL_QCHMAP_PAENTRY_SHIFT) & (trWord)) << EDMA3_CCRL_QCHMAP_PAENTRY_SHIFT)
  73 /** QCHMAP-TrigWord bitfield Clear */
  74 #define EDMA3_RM_QCH_TRWORD_CLR_MASK               (~EDMA3_CCRL_QCHMAP_TRWORD_MASK)
  75 /** QCHMAP-TrigWord bitfield Set */
  76 #define EDMA3_RM_QCH_TRWORD_SET_MASK(paRAMId)      (((EDMA3_CCRL_QCHMAP_TRWORD_MASK >> EDMA3_CCRL_QCHMAP_TRWORD_SHIFT) & (paRAMId)) << EDMA3_CCRL_QCHMAP_TRWORD_SHIFT)
  77 /** QUEPRI bits Clear */
  78 #define EDMA3_RM_QUEPRI_CLR_MASK(queNum)           (~(EDMA3_CCRL_QUEPRI_PRIQ0_MASK << ((queNum) * EDMA3_CCRL_QUEPRI_PRIQ1_SHIFT)))
  79 /** QUEPRI bits Set */
  80 #define EDMA3_RM_QUEPRI_SET_MASK(queNum,quePri)    ((EDMA3_CCRL_QUEPRI_PRIQ0_MASK & (quePri)) << ((queNum) * EDMA3_CCRL_QUEPRI_PRIQ1_SHIFT))
  81 /** QUEWMTHR bits Clear */
  82 #define EDMA3_RM_QUEWMTHR_CLR_MASK(queNum)         (~(EDMA3_CCRL_QWMTHRA_Q0_MASK << ((queNum) * EDMA3_CCRL_QWMTHRA_Q1_SHIFT)))
  83 /** QUEWMTHR bits Set */
  84 #define EDMA3_RM_QUEWMTHR_SET_MASK(queNum,queThr)  ((EDMA3_CCRL_QWMTHRA_Q0_MASK & (queThr)) << ((queNum) * EDMA3_CCRL_QWMTHRA_Q1_SHIFT))
  85
  86 /** OPT-TCC bitfield Clear */
  87 #define EDMA3_RM_OPT_TCC_CLR_MASK                  (~EDMA3_CCRL_OPT_TCC_MASK)
  88 /** OPT-TCC bitfield Set */
  89 #define EDMA3_RM_OPT_TCC_SET_MASK(tcc)             (((EDMA3_CCRL_OPT_TCC_MASK >> EDMA3_CCRL_OPT_TCC_SHIFT) & (tcc)) << EDMA3_CCRL_OPT_TCC_SHIFT)
  90
  91 /** PaRAM Set Entry for Link and B count Reload field */
  92 #define EDMA3_RM_PARAM_ENTRY_LINK_BCNTRLD   (5u)
  93
  94
  95 /**
  96  * \defgroup Edma3ResMgrInt Internal Interface Definition for Resource Manager
  97  *
  98  * Documentation of the Internal Interface of Resource Manager
  99  *
 100  * @{
 101  */
 102
 103
 104 /**
 105  * \defgroup Edma3ResMgrIntObjMaint Object Maintenance
 106  *
 107  * Maintenance of the EDMA3 Resource Manager Object
 108  *
 109  * @{
 110  */
 111
 112
 113 /** To maintain the state of the EDMA3 Resource Manager Object */
 114 typedef enum {
 115     /** Object deleted */
 116     EDMA3_RM_DELETED   = 0,
 117     /** Obect Created */
 118     EDMA3_RM_CREATED   = 1,
 119     /** Object Opened */
 120     EDMA3_RM_OPENED    = 2,
 121     /** Object Closed */
 122     EDMA3_RM_CLOSED    = 3
 123 } EDMA3_RM_ObjState;
 124
 125
 126
 127 /**
 128  * \brief EDMA3 Hardware Instance Configuration Structure.
 129  *
 130  * Used to maintain information of the EDMA3 HW configuration.
 131  * One such storage exists for each instance of the EDMA 3 HW.
 132  */
 133 typedef struct
 134     {
 135     /** HW Instance Id of the EDMA3 Controller */
 136     unsigned int        phyCtrllerInstId;
 137
 138     /** State information of the Resource Manager object */
 139     EDMA3_RM_ObjState   state;
 140
 141     /** Number of active opens of RM Instances */
 142     unsigned int        numOpens;
 143
 144     /**
 145      * \brief Init-time Configuration structure for EDMA3
 146      * controller, to provide Global SoC specific Information.
 147      *
 148      * This configuration will can be provided by the user at run-time,
 149      * while calling EDMA3_RM_create().
 150      */
 151     EDMA3_RM_GblConfigParams gblCfgParams;
 152     } EDMA3_RM_Obj;
 153
 154
 155 /**
 156  * \brief EDMA3 RM Instance Specific Configuration Structure.
 157  *
 158  * Used to maintain information of the EDMA3 Res Mgr instances.
 159  * One such storage exists for each instance of the EDMA3 Res Mgr.
 160  *
 161  * Maximum EDMA3_MAX_RM_INSTANCES instances are allowed for
 162  * each EDMA3 hardware instance, for same or different shadow regions.
 163  */
 164 typedef struct
 165     {
 166     /**
 167      * Configuration such as region id, IsMaster, Callback function
 168      * This configuration is passed to the "Open" API.
 169      * For a single EDMA3 HW controller, there can be EDMA3_MAX_REGIONS
 170      * different instances tied to different regions.
 171      */
 172     EDMA3_RM_Param                  initParam;
 173
 174     /** Pointer to appropriate Shadow Register region of CC Registers */
 175     EDMA3_CCRL_ShadowRegs           *shadowRegs;
 176
 177     /**
 178      * Pointer to the EDMA3 RM Object (HW specific)
 179      * opened by RM instance.
 180      */
 181     EDMA3_RM_Obj                    *pResMgrObjHandle;
 182
 183     /** Available DMA Channels to the RM Instance */
 184     unsigned int        avlblDmaChannels[EDMA3_MAX_DMA_CHAN_DWRDS];
 185
 186     /** Available QDMA Channels to the RM Instance */
 187     unsigned int        avlblQdmaChannels[EDMA3_MAX_QDMA_CHAN_DWRDS];
 188
 189     /** Available PaRAM Sets to the RM Instance */
 190     unsigned int        avlblPaRAMSets[EDMA3_MAX_PARAM_DWRDS];
 191
 192     /** Available TCCs to the RM Instance */
 193     unsigned int        avlblTccs[EDMA3_MAX_TCC_DWRDS];
 194
 195     /**
 196      * Sometimes, PaRAM clearing is not required for some particular RM
 197      * Instances. In that case, PaRAM Sets allocated will NOT be cleared before
 198      * allocating to any particular user. It is the responsibility of user
 199      * to program it accordingly, without assuming anything for a specific
 200      * field because the PaRAM Set might contain junk values. Not programming
 201      * it fully might result in erroneous behavior.
 202      * On the other hand, RM instances can also use this variable to get the
 203      * PaRAM Sets cleared before allocating them to the specific user.
 204      * User can program only the selected fields in this case.
 205      *
 206      * Value '0' : PaRAM Sets will NOT be cleared during their allocation.
 207      * Value '1' : PaRAM Sets will be cleared during their allocation.
 208      *
 209      * This value can be modified using the IOCTL commands.
 210      */
 211     unsigned int          paramInitRequired;
 212
 213     /**
 214      * Sometimes, global EDMA3 registers (DCHMAP/QCHMAP) and PaRAM Sets should
 215      * not be modified during EDMA3_RM_allocLogicalChannel (), for some particular RM
 216      * Instances. In that case, it is the responsibility of user
 217      * to program them accordingly, when needed, without assuming anything because
 218      * they might contain junk values. Not programming
 219      * the registers/PaRAMs fully might result in erroneous behavior.
 220      * On the other hand, RM instances can also use this variable to get the
 221      * global registers and PaRAM Sets minimally programmed before allocating them to
 222      * the specific user.
 223      * User can program only the remaining fields in this case.
 224      *
 225      * Value '0' : EDMA3 registers (DCHMAP/QCHMAP) and PaRAM Sets will NOT be
 226      *                  programmed during their allocation.
 227      * Value '1' : EDMA3 registers (DCHMAP/QCHMAP) and PaRAM Sets will be
 228      *                  programmed during their allocation.
 229      *
 230      * This value can be modified using the IOCTL commands.
 231      */
 232     unsigned int          regModificationRequired;
 233     }EDMA3_RM_Instance;
 234
 235 /* @} Edma3ResMgrIntObjMaint */
 236
 237
 238 /**
 239  * \brief EDMA3 Channel-Bound resources.
 240  *
 241  * Used to maintain information of the EDMA3 resources
 242  * (specifically Parameter RAM set and TCC), bound to the
 243  * particular channel within EDMA3_RM_allocLogicalChannel ().
 244  */
 245 typedef struct {
 246     /** PaRAM Set number associated with the particular channel */
 247     int paRAMId;
 248
 249     /** TCC associated with the particular channel */
 250     unsigned int tcc;
 251 } EDMA3_RM_ChBoundResources;
 252
 253
 254 /**
 255  * \brief TCC Callback - Caters to channel specific status reporting.
 256  */
 257 typedef struct {
 258     /** Callback function */
 259     EDMA3_RM_TccCallback tccCb;
 260
 261     /** Callback data, passed to the Callback function */
 262     void *cbData;
 263 } EDMA3_RM_TccCallbackParams;
 264
 265
 266 /* @} Edma3ResMgrInt */
 267
 268 #ifdef __cplusplus
 269 }
 270 #endif /* extern "C" */
 271
 272 #endif    /* _EDMA3_RES_MGR_H_ */