git.sur5r.net Git - freertos/blob

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