git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_A53_64-bit_UltraScale_MPSoC/RTOSDemo_A53_bsp/psu_cortexa53_0/libsrc/emacps_v3_7/src/xemacps_bdring.h

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2010 - 2015 Xilinx, Inc.  All rights reserved.
   4 *
   5 * Permission is hereby granted, free of charge, to any person obtaining a copy
   6 * of this software and associated documentation files (the "Software"), to deal
   7 * in the Software without restriction, including without limitation the rights
   8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   9 * copies of the Software, and to permit persons to whom the Software is
  10 * furnished to do so, subject to the following conditions:
  11 *
  12 * The above copyright notice and this permission notice shall be included in
  13 * all copies or substantial portions of the Software.
  14 *
  15 * Use of the Software is limited solely to applications:
  16 * (a) running on a Xilinx device, or
  17 * (b) that interact with a Xilinx device through a bus or interconnect.
  18 *
  19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  22 * XILINX  BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  23 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
  24 * OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  25 * SOFTWARE.
  26 *
  27 * Except as contained in this notice, the name of the Xilinx shall not be used
  28 * in advertising or otherwise to promote the sale, use or other dealings in
  29 * this Software without prior written authorization from Xilinx.
  30 *
  31 ******************************************************************************/
  32 /*****************************************************************************/
  33 /**
  34 *
  35 * @file xemacps_bdring.h
  36 * @addtogroup emacps_v3_7
  37 * @{
  38 *
  39 * The Xiline EmacPs Buffer Descriptor ring driver. This is part of EmacPs
  40 * DMA functionalities.
  41 *
  42 * <pre>
  43 * MODIFICATION HISTORY:
  44 *
  45 * Ver   Who  Date     Changes
  46 * ----- ---- -------- -------------------------------------------------------
  47 * 1.00a wsy  01/10/10 First release
  48 * 2.1   srt  07/15/14 Add support for Zynq Ultrascale Mp architecture.
  49 * 3.0   kvn  02/13/15 Modified code for MISRA-C:2012 compliance.
  50 * 3.6   rb   09/08/17 HwCnt variable (in XEmacPs_BdRing structure) is
  51 *                     changed to volatile.
  52 *
  53 * </pre>
  54 *
  55 ******************************************************************************/
  56
  57 #ifndef XEMACPS_BDRING_H        /* prevent curcular inclusions */
  58 #define XEMACPS_BDRING_H        /* by using protection macros */
  59
  60 #ifdef __cplusplus
  61 extern "C" {
  62 #endif
  63
  64
  65 /**************************** Type Definitions *******************************/
  66
  67 /** This is an internal structure used to maintain the DMA list */
  68 typedef struct {
  69         UINTPTR PhysBaseAddr;/**< Physical address of 1st BD in list */
  70         UINTPTR BaseBdAddr;      /**< Virtual address of 1st BD in list */
  71         UINTPTR HighBdAddr;      /**< Virtual address of last BD in the list */
  72         u32 Length;      /**< Total size of ring in bytes */
  73         u32 RunState;    /**< Flag to indicate DMA is started */
  74         u32 Separation;  /**< Number of bytes between the starting address
  75                                   of adjacent BDs */
  76         XEmacPs_Bd *FreeHead;
  77                              /**< First BD in the free group */
  78         XEmacPs_Bd *PreHead;/**< First BD in the pre-work group */
  79         XEmacPs_Bd *HwHead; /**< First BD in the work group */
  80         XEmacPs_Bd *HwTail; /**< Last BD in the work group */
  81         XEmacPs_Bd *PostHead;
  82                              /**< First BD in the post-work group */
  83         XEmacPs_Bd *BdaRestart;
  84                              /**< BDA to load when channel is started */
  85
  86         volatile u32 HwCnt;    /**< Number of BDs in work group */
  87         u32 PreCnt;     /**< Number of BDs in pre-work group */
  88         u32 FreeCnt;    /**< Number of allocatable BDs in the free group */
  89         u32 PostCnt;    /**< Number of BDs in post-work group */
  90         u32 AllCnt;     /**< Total Number of BDs for channel */
  91 } XEmacPs_BdRing;
  92
  93
  94 /***************** Macros (Inline Functions) Definitions *********************/
  95
  96 /*****************************************************************************/
  97 /**
  98 * Use this macro at initialization time to determine how many BDs will fit
  99 * in a BD list within the given memory constraints.
 100 *
 101 * The results of this macro can be provided to XEmacPs_BdRingCreate().
 102 *
 103 * @param Alignment specifies what byte alignment the BDs must fall on and
 104 *        must be a power of 2 to get an accurate calculation (32, 64, 128,...)
 105 * @param Bytes is the number of bytes to be used to store BDs.
 106 *
 107 * @return Number of BDs that can fit in the given memory area
 108 *
 109 * @note
 110 * C-style signature:
 111 *    u32 XEmacPs_BdRingCntCalc(u32 Alignment, u32 Bytes)
 112 *
 113 ******************************************************************************/
 114 #define XEmacPs_BdRingCntCalc(Alignment, Bytes)                    \
 115     (u32)((Bytes) / (sizeof(XEmacPs_Bd)))
 116
 117 /*****************************************************************************/
 118 /**
 119 * Use this macro at initialization time to determine how many bytes of memory
 120 * is required to contain a given number of BDs at a given alignment.
 121 *
 122 * @param Alignment specifies what byte alignment the BDs must fall on. This
 123 *        parameter must be a power of 2 to get an accurate calculation (32, 64,
 124 *        128,...)
 125 * @param NumBd is the number of BDs to calculate memory size requirements for
 126 *
 127 * @return The number of bytes of memory required to create a BD list with the
 128 *         given memory constraints.
 129 *
 130 * @note
 131 * C-style signature:
 132 *    u32 XEmacPs_BdRingMemCalc(u32 Alignment, u32 NumBd)
 133 *
 134 ******************************************************************************/
 135 #define XEmacPs_BdRingMemCalc(Alignment, NumBd)                    \
 136     (u32)(sizeof(XEmacPs_Bd) * (NumBd))
 137
 138 /****************************************************************************/
 139 /**
 140 * Return the total number of BDs allocated by this channel with
 141 * XEmacPs_BdRingCreate().
 142 *
 143 * @param  RingPtr is the DMA channel to operate on.
 144 *
 145 * @return The total number of BDs allocated for this channel.
 146 *
 147 * @note
 148 * C-style signature:
 149 *    u32 XEmacPs_BdRingGetCnt(XEmacPs_BdRing* RingPtr)
 150 *
 151 *****************************************************************************/
 152 #define XEmacPs_BdRingGetCnt(RingPtr) ((RingPtr)->AllCnt)
 153
 154 /****************************************************************************/
 155 /**
 156 * Return the number of BDs allocatable with XEmacPs_BdRingAlloc() for pre-
 157 * processing.
 158 *
 159 * @param  RingPtr is the DMA channel to operate on.
 160 *
 161 * @return The number of BDs currently allocatable.
 162 *
 163 * @note
 164 * C-style signature:
 165 *    u32 XEmacPs_BdRingGetFreeCnt(XEmacPs_BdRing* RingPtr)
 166 *
 167 *****************************************************************************/
 168 #define XEmacPs_BdRingGetFreeCnt(RingPtr)   ((RingPtr)->FreeCnt)
 169
 170 /****************************************************************************/
 171 /**
 172 * Return the next BD from BdPtr in a list.
 173 *
 174 * @param  RingPtr is the DMA channel to operate on.
 175 * @param  BdPtr is the BD to operate on.
 176 *
 177 * @return The next BD in the list relative to the BdPtr parameter.
 178 *
 179 * @note
 180 * C-style signature:
 181 *    XEmacPs_Bd *XEmacPs_BdRingNext(XEmacPs_BdRing* RingPtr,
 182 *                                      XEmacPs_Bd *BdPtr)
 183 *
 184 *****************************************************************************/
 185 #define XEmacPs_BdRingNext(RingPtr, BdPtr)                           \
 186     (((UINTPTR)((void *)(BdPtr)) >= (RingPtr)->HighBdAddr) ?                     \
 187     (XEmacPs_Bd*)((void*)(RingPtr)->BaseBdAddr) :                              \
 188     (XEmacPs_Bd*)((UINTPTR)((void *)(BdPtr)) + (RingPtr)->Separation))
 189
 190 /****************************************************************************/
 191 /**
 192 * Return the previous BD from BdPtr in the list.
 193 *
 194 * @param  RingPtr is the DMA channel to operate on.
 195 * @param  BdPtr is the BD to operate on
 196 *
 197 * @return The previous BD in the list relative to the BdPtr parameter.
 198 *
 199 * @note
 200 * C-style signature:
 201 *    XEmacPs_Bd *XEmacPs_BdRingPrev(XEmacPs_BdRing* RingPtr,
 202 *                                      XEmacPs_Bd *BdPtr)
 203 *
 204 *****************************************************************************/
 205 #define XEmacPs_BdRingPrev(RingPtr, BdPtr)                           \
 206     (((UINTPTR)(BdPtr) <= (RingPtr)->BaseBdAddr) ?                     \
 207     (XEmacPs_Bd*)(RingPtr)->HighBdAddr :                              \
 208     (XEmacPs_Bd*)((UINTPTR)(BdPtr) - (RingPtr)->Separation))
 209
 210 /************************** Function Prototypes ******************************/
 211
 212 /*
 213  * Scatter gather DMA related functions in xemacps_bdring.c
 214  */
 215 LONG XEmacPs_BdRingCreate(XEmacPs_BdRing * RingPtr, UINTPTR PhysAddr,
 216                           UINTPTR VirtAddr, u32 Alignment, u32 BdCount);
 217 LONG XEmacPs_BdRingClone(XEmacPs_BdRing * RingPtr, XEmacPs_Bd * SrcBdPtr,
 218                          u8 Direction);
 219 LONG XEmacPs_BdRingAlloc(XEmacPs_BdRing * RingPtr, u32 NumBd,
 220                          XEmacPs_Bd ** BdSetPtr);
 221 LONG XEmacPs_BdRingUnAlloc(XEmacPs_BdRing * RingPtr, u32 NumBd,
 222                            XEmacPs_Bd * BdSetPtr);
 223 LONG XEmacPs_BdRingToHw(XEmacPs_BdRing * RingPtr, u32 NumBd,
 224                         XEmacPs_Bd * BdSetPtr);
 225 LONG XEmacPs_BdRingFree(XEmacPs_BdRing * RingPtr, u32 NumBd,
 226                         XEmacPs_Bd * BdSetPtr);
 227 u32 XEmacPs_BdRingFromHwTx(XEmacPs_BdRing * RingPtr, u32 BdLimit,
 228                                  XEmacPs_Bd ** BdSetPtr);
 229 u32 XEmacPs_BdRingFromHwRx(XEmacPs_BdRing * RingPtr, u32 BdLimit,
 230                                  XEmacPs_Bd ** BdSetPtr);
 231 LONG XEmacPs_BdRingCheck(XEmacPs_BdRing * RingPtr, u8 Direction);
 232
 233 void XEmacPs_BdRingPtrReset(XEmacPs_BdRing * RingPtr, void *virtaddrloc);
 234
 235 #ifdef __cplusplus
 236 }
 237 #endif
 238
 239
 240 #endif /* end of protection macros */
 241 /** @} */