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 * (c) Copyright 2010 Xilinx, Inc. All rights reserved.
   5 *
   6 * This file contains confidential and proprietary information of Xilinx, Inc.
   7 * and is protected under U.S. and international copyright and other
   8 * intellectual property laws.
   9 *
  10 * DISCLAIMER
  11 * This disclaimer is not a license and does not grant any rights to the
  12 * materials distributed herewith. Except as otherwise provided in a valid
  13 * license issued to you by Xilinx, and to the maximum extent permitted by
  14 * applicable law: (1) THESE MATERIALS ARE MADE AVAILABLE "AS IS" AND WITH ALL
  15 * FAULTS, AND XILINX HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS,
  16 * IMPLIED, OR STATUTORY, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
  17 * MERCHANTABILITY, NON-INFRINGEMENT, OR FITNESS FOR ANY PARTICULAR PURPOSE;
  18 * and (2) Xilinx shall not be liable (whether in contract or tort, including
  19 * negligence, or under any other theory of liability) for any loss or damage
  20 * of any kind or nature related to, arising under or in connection with these
  21 * materials, including for any direct, or any indirect, special, incidental,
  22 * or consequential loss or damage (including loss of data, profits, goodwill,
  23 * or any type of loss or damage suffered as a result of any action brought by
  24 * a third party) even if such damage or loss was reasonably foreseeable or
  25 * Xilinx had been advised of the possibility of the same.
  26 *
  27 * CRITICAL APPLICATIONS
  28 * Xilinx products are not designed or intended to be fail-safe, or for use in
  29 * any application requiring fail-safe performance, such as life-support or
  30 * safety devices or systems, Class III medical devices, nuclear facilities,
  31 * applications related to the deployment of airbags, or any other applications
  32 * that could lead to death, personal injury, or severe property or
  33 * environmental damage (individually and collectively, "Critical
  34 * Applications"). Customer assumes the sole risk and liability of any use of
  35 * Xilinx products in Critical Applications, subject only to applicable laws
  36 * and regulations governing limitations on product liability.
  37 *
  38 * THIS COPYRIGHT NOTICE AND DISCLAIMER MUST BE RETAINED AS PART OF THIS FILE
  39 * AT ALL TIMES.
  40 *
  41 ******************************************************************************/
  42 /*****************************************************************************/
  43 /**
  44 *
  45 * @file xemacps_bdring.h
  46 *
  47 * The Xiline EmacPs Buffer Descriptor ring driver. This is part of EmacPs
  48 * DMA functionalities.
  49 *
  50 * <pre>
  51 * MODIFICATION HISTORY:
  52 *
  53 * Ver   Who  Date     Changes
  54 * ----- ---- -------- -------------------------------------------------------
  55 * 1.00a wsy  01/10/10 First release
  56 * </pre>
  57 *
  58 ******************************************************************************/
  59
  60 #ifndef XEMACPS_BDRING_H        /* prevent curcular inclusions */
  61 #define XEMACPS_BDRING_H        /* by using protection macros */
  62
  63 #ifdef __cplusplus
  64 extern "C" {
  65 #endif
  66
  67
  68 /**************************** Type Definitions *******************************/
  69
  70 /** This is an internal structure used to maintain the DMA list */
  71 typedef struct {
  72         u32 PhysBaseAddr;/**< Physical address of 1st BD in list */
  73         u32 BaseBdAddr;  /**< Virtual address of 1st BD in list */
  74         u32 HighBdAddr;  /**< Virtual address of last BD in the list */
  75         u32 Length;      /**< Total size of ring in bytes */
  76         u32 RunState;    /**< Flag to indicate DMA is started */
  77         u32 Separation;  /**< Number of bytes between the starting address
  78                                   of adjacent BDs */
  79         XEmacPs_Bd *FreeHead;
  80                              /**< First BD in the free group */
  81         XEmacPs_Bd *PreHead;/**< First BD in the pre-work group */
  82         XEmacPs_Bd *HwHead; /**< First BD in the work group */
  83         XEmacPs_Bd *HwTail; /**< Last BD in the work group */
  84         XEmacPs_Bd *PostHead;
  85                              /**< First BD in the post-work group */
  86         XEmacPs_Bd *BdaRestart;
  87                              /**< BDA to load when channel is started */
  88         unsigned HwCnt;      /**< Number of BDs in work group */
  89         unsigned PreCnt;     /**< Number of BDs in pre-work group */
  90         unsigned FreeCnt;    /**< Number of allocatable BDs in the free group */
  91         unsigned PostCnt;    /**< Number of BDs in post-work group */
  92         unsigned AllCnt;     /**< Total Number of BDs for channel */
  93 } XEmacPs_BdRing;
  94
  95
  96 /***************** Macros (Inline Functions) Definitions *********************/
  97
  98 /*****************************************************************************/
  99 /**
 100 * Use this macro at initialization time to determine how many BDs will fit
 101 * in a BD list within the given memory constraints.
 102 *
 103 * The results of this macro can be provided to XEmacPs_BdRingCreate().
 104 *
 105 * @param Alignment specifies what byte alignment the BDs must fall on and
 106 *        must be a power of 2 to get an accurate calculation (32, 64, 128,...)
 107 * @param Bytes is the number of bytes to be used to store BDs.
 108 *
 109 * @return Number of BDs that can fit in the given memory area
 110 *
 111 * @note
 112 * C-style signature:
 113 *    u32 XEmacPs_BdRingCntCalc(u32 Alignment, u32 Bytes)
 114 *
 115 ******************************************************************************/
 116 #define XEmacPs_BdRingCntCalc(Alignment, Bytes)                    \
 117     (u32)((Bytes) / ((sizeof(XEmacPs_Bd) + ((Alignment)-1)) &   \
 118     ~((Alignment)-1)))
 119
 120 /*****************************************************************************/
 121 /**
 122 * Use this macro at initialization time to determine how many bytes of memory
 123 * is required to contain a given number of BDs at a given alignment.
 124 *
 125 * @param Alignment specifies what byte alignment the BDs must fall on. This
 126 *        parameter must be a power of 2 to get an accurate calculation (32, 64,
 127 *        128,...)
 128 * @param NumBd is the number of BDs to calculate memory size requirements for
 129 *
 130 * @return The number of bytes of memory required to create a BD list with the
 131 *         given memory constraints.
 132 *
 133 * @note
 134 * C-style signature:
 135 *    u32 XEmacPs_BdRingMemCalc(u32 Alignment, u32 NumBd)
 136 *
 137 ******************************************************************************/
 138 #define XEmacPs_BdRingMemCalc(Alignment, NumBd)                    \
 139     (u32)((sizeof(XEmacPs_Bd) + ((Alignment)-1)) &              \
 140     ~((Alignment)-1)) * (NumBd)
 141
 142 /****************************************************************************/
 143 /**
 144 * Return the total number of BDs allocated by this channel with
 145 * XEmacPs_BdRingCreate().
 146 *
 147 * @param  RingPtr is the DMA channel to operate on.
 148 *
 149 * @return The total number of BDs allocated for this channel.
 150 *
 151 * @note
 152 * C-style signature:
 153 *    u32 XEmacPs_BdRingGetCnt(XEmacPs_BdRing* RingPtr)
 154 *
 155 *****************************************************************************/
 156 #define XEmacPs_BdRingGetCnt(RingPtr) ((RingPtr)->AllCnt)
 157
 158 /****************************************************************************/
 159 /**
 160 * Return the number of BDs allocatable with XEmacPs_BdRingAlloc() for pre-
 161 * processing.
 162 *
 163 * @param  RingPtr is the DMA channel to operate on.
 164 *
 165 * @return The number of BDs currently allocatable.
 166 *
 167 * @note
 168 * C-style signature:
 169 *    u32 XEmacPs_BdRingGetFreeCnt(XEmacPs_BdRing* RingPtr)
 170 *
 171 *****************************************************************************/
 172 #define XEmacPs_BdRingGetFreeCnt(RingPtr)   ((RingPtr)->FreeCnt)
 173
 174 /****************************************************************************/
 175 /**
 176 * Return the next BD from BdPtr in a list.
 177 *
 178 * @param  RingPtr is the DMA channel to operate on.
 179 * @param  BdPtr is the BD to operate on.
 180 *
 181 * @return The next BD in the list relative to the BdPtr parameter.
 182 *
 183 * @note
 184 * C-style signature:
 185 *    XEmacPs_Bd *XEmacPs_BdRingNext(XEmacPs_BdRing* RingPtr,
 186 *                                      XEmacPs_Bd *BdPtr)
 187 *
 188 *****************************************************************************/
 189 #define XEmacPs_BdRingNext(RingPtr, BdPtr)                           \
 190     (((u32)(BdPtr) >= (RingPtr)->HighBdAddr) ?                     \
 191     (XEmacPs_Bd*)(RingPtr)->BaseBdAddr :                              \
 192     (XEmacPs_Bd*)((u32)(BdPtr) + (RingPtr)->Separation))
 193
 194 /****************************************************************************/
 195 /**
 196 * Return the previous BD from BdPtr in the list.
 197 *
 198 * @param  RingPtr is the DMA channel to operate on.
 199 * @param  BdPtr is the BD to operate on
 200 *
 201 * @return The previous BD in the list relative to the BdPtr parameter.
 202 *
 203 * @note
 204 * C-style signature:
 205 *    XEmacPs_Bd *XEmacPs_BdRingPrev(XEmacPs_BdRing* RingPtr,
 206 *                                      XEmacPs_Bd *BdPtr)
 207 *
 208 *****************************************************************************/
 209 #define XEmacPs_BdRingPrev(RingPtr, BdPtr)                           \
 210     (((u32)(BdPtr) <= (RingPtr)->BaseBdAddr) ?                     \
 211     (XEmacPs_Bd*)(RingPtr)->HighBdAddr :                              \
 212     (XEmacPs_Bd*)((u32)(BdPtr) - (RingPtr)->Separation))
 213
 214 /************************** Function Prototypes ******************************/
 215
 216 /*
 217  * Scatter gather DMA related functions in xemacps_bdring.c
 218  */
 219 int XEmacPs_BdRingCreate(XEmacPs_BdRing * RingPtr, u32 PhysAddr,
 220                           u32 VirtAddr, u32 Alignment, unsigned BdCount);
 221 int XEmacPs_BdRingClone(XEmacPs_BdRing * RingPtr, XEmacPs_Bd * SrcBdPtr,
 222                          u8 Direction);
 223 int XEmacPs_BdRingAlloc(XEmacPs_BdRing * RingPtr, unsigned NumBd,
 224                          XEmacPs_Bd ** BdSetPtr);
 225 int XEmacPs_BdRingUnAlloc(XEmacPs_BdRing * RingPtr, unsigned NumBd,
 226                            XEmacPs_Bd * BdSetPtr);
 227 int XEmacPs_BdRingToHw(XEmacPs_BdRing * RingPtr, unsigned NumBd,
 228                         XEmacPs_Bd * BdSetPtr);
 229 int XEmacPs_BdRingFree(XEmacPs_BdRing * RingPtr, unsigned NumBd,
 230                         XEmacPs_Bd * BdSetPtr);
 231 unsigned XEmacPs_BdRingFromHwTx(XEmacPs_BdRing * RingPtr, unsigned BdLimit,
 232                                  XEmacPs_Bd ** BdSetPtr);
 233 unsigned XEmacPs_BdRingFromHwRx(XEmacPs_BdRing * RingPtr, unsigned BdLimit,
 234                                  XEmacPs_Bd ** BdSetPtr);
 235 int XEmacPs_BdRingCheck(XEmacPs_BdRing * RingPtr, u8 Direction);
 236
 237 #ifdef __cplusplus
 238 }
 239 #endif
 240
 241
 242 #endif /* end of protection macros */