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