drivers/xilinx_common/xstreamer.h

   1 /* $Id: */
   2 /******************************************************************************
   3 *
   4 *       XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS"
   5 *       AS A COURTESY TO YOU, SOLELY FOR USE IN DEVELOPING PROGRAMS AND
   6 *       SOLUTIONS FOR XILINX DEVICES.  BY PROVIDING THIS DESIGN, CODE,
   7 *       OR INFORMATION AS ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE,
   8 *       APPLICATION OR STANDARD, XILINX IS MAKING NO REPRESENTATION
   9 *       THAT THIS IMPLEMENTATION IS FREE FROM ANY CLAIMS OF INFRINGEMENT,
  10 *       AND YOU ARE RESPONSIBLE FOR OBTAINING ANY RIGHTS YOU MAY REQUIRE
  11 *       FOR YOUR IMPLEMENTATION.  XILINX EXPRESSLY DISCLAIMS ANY
  12 *       WARRANTY WHATSOEVER WITH RESPECT TO THE ADEQUACY OF THE
  13 *       IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OR
  14 *       REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM CLAIMS OF
  15 *       INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  16 *       FOR A PARTICULAR PURPOSE.
  17 *
  18 *       (c) Copyright 2005-2008 Xilinx Inc.
  19 *       All rights reserved.
  20 * This program is free software; you can redistribute it and/or modify it
  21 * under the terms of the GNU General Public License as published by the
  22 * Free Software Foundation; either version 2 of the License, or (at your
  23 * option) any later version.
  24 *
  25 * You should have received a copy of the GNU General Public License
  26 * along with this program; if not, write to the Free Software
  27 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  28 *
  29 ******************************************************************************/
  30 /*****************************************************************************/
  31 /*
  32  *
  33  * @file xstreamer.h
  34  *
  35  * The Xilinx byte streamer for packet FIFOs.
  36  *
  37  * <h2>Driver Description</h2>
  38  *
  39  * This driver enables higher layer software to access a hardware FIFO using
  40  * any alignment in the data buffers while preserving alignment for the hardware
  41  * FIFO access.
  42  *
  43  * This driver treats send and receive channels separately, using different
  44  * types of instance objects for each.
  45  *
  46  * This driver makes use of another FIFO driver to access the specific FIFO
  47  * hardware through use of the routines passed into the Tx/RxInitialize
  48  * routines.
  49  *
  50  * <h2>Initialization</h2>
  51  *
  52  * Send and receive channels are intialized separately. The receive channel is
  53  * initiailzed using XStrm_RxInitialize(). The send channel is initialized
  54  * using XStrm_TxInitialize().
  55  *
  56  *
  57  * <h2>Usage</h2>
  58  * It is fairly simple to use the API provided by this byte streamer
  59  * driver. The only somewhat tricky part is that the calling code must
  60  * correctly call a couple routines in the right sequence for receive and
  61  * transmit.
  62  *
  63  *      This sequence is described here. Check the routine functional
  64  * descriptions for information on how to use a specific API routine.
  65  *
  66  * <h3>Receive</h3>
  67  * A frame is received by using the following sequence:<br>
  68  * 1) call XStrm_RxGetLen() to get the length of the next incoming frame.<br>
  69  * 2) call XStrm_Read() one or more times to read the number of bytes
  70  *         reported by XStrm_RxGetLen().<br>
  71  *
  72  * For example:
  73  * <pre>
  74  *      frame_len = XStrm_RxGetLen(&RxInstance);
  75  *      while (frame_len) {
  76  *              unsigned bytes = min(sizeof(buffer), frame_len);
  77  *              XStrm_Read(&RxInstance, buffer, bytes);
  78  *              // do something with buffer here
  79  *              frame_len -= bytes;
  80  *      }
  81  * </pre>
  82  *
  83  * Other restrictions on the sequence of API calls may apply depending on
  84  * the specific FIFO driver used by this byte streamer driver.
  85  *
  86  * <h3>Transmit</h3>
  87  * A frame is transmittted by using the following sequence:<br>
  88  * 1) call XStrm_Write() one or more times to write all the of bytes in
  89  *    the next frame.<br>
  90  * 2) call XStrm_TxSetLen() to begin the transmission of frame just
  91  *    written.<br>
  92  *
  93  * For example:
  94  * <pre>
  95  *      frame_left = frame_len;
  96  *      while (frame_left) {
  97  *              unsigned bytes = min(sizeof(buffer), frame_left);
  98  *              XStrm_Write(&TxInstance, buffer, bytes);
  99  *              // do something here to refill buffer
 100  *      }
 101  *      XStrm_TxSetLen(&RxInstance, frame_len);
 102  * </pre>
 103  *
 104  * Other restrictions on the sequence of API calls may apply depending on
 105  * the specific FIFO driver used by this byte streamer driver.
 106  *
 107  * <pre>
 108  * MODIFICATION HISTORY:
 109  *
 110  * Ver   Who  Date     Changes
 111  * ----- ---- -------- -------------------------------------------------------
 112  * 1.00a jvb  10/12/06 First release
 113  * </pre>
 114  *
 115  *****************************************************************************/
 116 #ifndef XSTREAMER_H             /* prevent circular inclusions */
 117 #define XSTREAMER_H             /* by using preprocessor symbols */
 118
 119 /* force C linkage */
 120 #ifdef __cplusplus
 121 extern "C" {
 122 #endif
 123
 124 #include "xbasic_types.h"
 125 #include "xstatus.h"
 126 #include "xdebug.h"
 127
 128 /*
 129  * key hole size in 32 bit words
 130  */
 131 #define LARGEST_FIFO_KEYHOLE_SIZE_WORDS 4
 132
 133 /*
 134  * This union is used simply to force a 32bit alignment on the
 135  * buffer. Only the 'bytes' member is really used.
 136  */
 137 union XStrm_AlignedBufferType {
 138         u32 _words[LARGEST_FIFO_KEYHOLE_SIZE_WORDS];
 139         char bytes[LARGEST_FIFO_KEYHOLE_SIZE_WORDS * 4];
 140 };
 141
 142 typedef int(*XStrm_XferFnType) (void *FifoInstance, void *BufPtr,
 143                                     unsigned WordCount);
 144 typedef u32 (*XStrm_GetLenFnType) (void *FifoInstance);
 145 typedef void (*XStrm_SetLenFnType) (void *FifoInstance,
 146                                     u32 ByteCount);
 147 typedef u32 (*XStrm_GetOccupancyFnType) (void *FifoInstance);
 148 typedef u32 (*XStrm_GetVacancyFnType) (void *FifoInstance);
 149
 150 /**
 151  * This typedef defines a run-time instance of a receive byte-streamer.
 152  */
 153 typedef struct XStrm_RxFifoStreamer {
 154         union XStrm_AlignedBufferType AlignedBuffer;
 155         unsigned HeadIndex;  /**< HeadIndex is the index to the AlignedBuffer
 156                               *   as bytes.
 157                               */
 158         unsigned FifoWidth;  /**< FifoWidth is the FIFO key hole width in bytes.
 159                               */
 160         unsigned FrmByteCnt; /**< FrmByteCnt is the number of bytes in the next
 161                               *   Frame.
 162                               */
 163         void *FifoInstance;  /**< FifoInstance is the FIFO driver instance to
 164                               *   pass to ReadFn, GetLenFn, and GetOccupancyFn
 165                               *   routines.
 166                               */
 167         XStrm_XferFnType ReadFn;     /**< ReadFn is the routine the streamer
 168                                       *   uses to receive bytes from the Fifo.
 169                                       */
 170         XStrm_GetLenFnType GetLenFn; /**< GetLenFn is the routine the streamer
 171                                       *   uses to initiate receive operations
 172                                       *   on the FIFO.
 173                                       */
 174         XStrm_GetOccupancyFnType GetOccupancyFn; /**< GetOccupancyFn is the
 175                                                   *   routine the streamer uses
 176                                                   *   to get the occupancy from
 177                                                   *   the FIFO.
 178                                                   */
 179 } XStrm_RxFifoStreamer;
 180
 181 /**
 182  * This typedef defines a run-time instance of a transmit byte-streamer.
 183  */
 184 typedef struct XStrm_TxFifoStreamer {
 185         union XStrm_AlignedBufferType AlignedBuffer;
 186         unsigned TailIndex; /**< TailIndex is the index to the AlignedBuffer
 187                              *   as bytes
 188                              */
 189         unsigned FifoWidth; /**< FifoWidth is the FIFO key hole width in bytes.
 190                              */
 191
 192         void *FifoInstance; /**< FifoInstance is the FIFO driver instance to
 193                              *   pass to WriteFn, SetLenFn, and GetVacancyFn
 194                              *   routines.
 195                              */
 196         XStrm_XferFnType WriteFn; /**< WriteFn is the routine the streamer
 197                                    *   uses to transmit bytes to the Fifo.
 198                                    */
 199         XStrm_SetLenFnType SetLenFn; /**< SetLenFn is the routine the streamer
 200                                       *   uses to initiate transmit operations
 201                                       *   on the FIFO.
 202                                       */
 203         XStrm_GetVacancyFnType GetVacancyFn; /**< GetVaccancyFn is the routine
 204                                               *   the streamer uses to get the
 205                                               *   vacancy from the FIFO.
 206                                               */
 207 } XStrm_TxFifoStreamer;
 208
 209 /*****************************************************************************/
 210 /*
 211 *
 212 * XStrm_TxVacancy returns the number of unused 32-bit words available (vacancy)
 213 * between the streamer, specified by <i>InstancePtr</i>, and the FIFO this
 214 * streamer is using.
 215 *
 216 * @param    InstancePtr references the streamer on which to operate.
 217 *
 218 * @return   XStrm_TxVacancy returns the vacancy count in number of 32 bit words.
 219 *
 220 * @note
 221 *
 222 * C Signature: u32 XStrm_TxVacancy(XStrm_TxFifoStreamer *InstancePtr)
 223 *
 224 * The amount of bytes in the holding buffer (rounded up to whole 32-bit words)
 225 * is subtracted from the vacancy value of FIFO this streamer is using. This is
 226 * to ensure the caller can write the number words given in the return value and
 227 * not overflow the FIFO.
 228 *
 229 ******************************************************************************/
 230 #define XStrm_TxVacancy(InstancePtr) \
 231         (((*(InstancePtr)->GetVacancyFn)((InstancePtr)->FifoInstance)) - \
 232                         (((InstancePtr)->TailIndex + 3) / 4))
 233
 234 /*****************************************************************************/
 235 /*
 236 *
 237 * XStrm_RxOccupancy returns the number of 32-bit words available (occupancy) to
 238 * be read from the streamer, specified by <i>InstancePtr</i>, and FIFO this
 239 * steamer is using.
 240 *
 241 * @param    InstancePtr references the streamer on which to operate.
 242 *
 243 * @return   XStrm_RxOccupancy returns the occupancy count in number of 32 bit
 244 *           words.
 245 *
 246 * @note
 247 *
 248 * C Signature: u32 XStrm_RxOccupancy(XStrm_RxFifoStreamer *InstancePtr)
 249 *
 250 * The amount of bytes in the holding buffer (rounded up to whole 32-bit words)
 251 * is added to the occupancy value of FIFO this streamer is using. This is to
 252 * ensure the caller will get a little more accurate occupancy value.
 253 *
 254 ******************************************************************************/
 255 #ifdef DEBUG
 256 extern u32 _xstrm_ro_value;
 257 extern u32 _xstrm_buffered;
 258 #define XStrm_RxOccupancy(InstancePtr) \
 259         (_xstrm_ro_value = ((*(InstancePtr)->GetOccupancyFn)((InstancePtr)->FifoInstance)), \
 260         xdbg_printf(XDBG_DEBUG_FIFO_RX, "reg: %d; frmbytecnt: %d\n", \
 261                 _xstrm_ro_value, (InstancePtr)->FrmByteCnt), \
 262         (((InstancePtr)->FrmByteCnt) ? \
 263                 _xstrm_buffered = ((InstancePtr)->FifoWidth - (InstancePtr)->HeadIndex) : \
 264                 0), \
 265         xdbg_printf(XDBG_DEBUG_FIFO_RX, "buffered_bytes: %d\n", _xstrm_buffered), \
 266         xdbg_printf(XDBG_DEBUG_FIFO_RX, "buffered (rounded): %d\n", _xstrm_buffered), \
 267         (_xstrm_ro_value + _xstrm_buffered))
 268 #else
 269 #define XStrm_RxOccupancy(InstancePtr) \
 270         ( \
 271           ((*(InstancePtr)->GetOccupancyFn)((InstancePtr)->FifoInstance)) + \
 272           ( \
 273             ((InstancePtr)->FrmByteCnt) ? \
 274               ((InstancePtr)->FifoWidth - (InstancePtr)->HeadIndex) : \
 275               0 \
 276           ) \
 277         )
 278 #endif
 279
 280 /****************************************************************************/
 281 /*
 282 *
 283 * XStrm_IsRxInternalEmpty returns true if the streamer, specified by
 284 * <i>InstancePtr</i>, is not holding any bytes in it's  internal buffers. Note
 285 * that this routine does not reflect information about the state of the
 286 * FIFO used by this streamer.
 287 *
 288 * @param    InstancePtr references the streamer on which to operate.
 289 *
 290 * @return   XStrm_IsRxInternalEmpty returns TRUE when the streamer is not
 291 *           holding any bytes in it's internal buffers. Otherwise,
 292 *           XStrm_IsRxInternalEmpty returns FALSE.
 293 *
 294 * @note
 295 * C-style signature:
 296 *    int XStrm_IsRxInternalEmpty(XStrm_RxFifoStreamer *InstancePtr)
 297 *
 298 *****************************************************************************/
 299 #define XStrm_IsRxInternalEmpty(InstancePtr) \
 300         (((InstancePtr)->HeadIndex == (InstancePtr)->FifoWidth) ? TRUE : FALSE)
 301
 302 void XStrm_RxInitialize(XStrm_RxFifoStreamer *InstancePtr,
 303                         unsigned FifoWidth, void *FifoInstance,
 304                         XStrm_XferFnType ReadFn,
 305                         XStrm_GetLenFnType GetLenFn,
 306                         XStrm_GetOccupancyFnType GetOccupancyFn);
 307
 308 void XStrm_TxInitialize(XStrm_TxFifoStreamer *InstancePtr,
 309                         unsigned FifoWidth, void *FifoInstance,
 310                         XStrm_XferFnType WriteFn,
 311                         XStrm_SetLenFnType SetLenFn,
 312                         XStrm_GetVacancyFnType GetVacancyFn);
 313
 314 void XStrm_TxSetLen(XStrm_TxFifoStreamer *InstancePtr, u32 Bytes);
 315 void XStrm_Write(XStrm_TxFifoStreamer *InstancePtr, void *BufPtr,
 316                     unsigned bytes);
 317
 318 u32 XStrm_RxGetLen(XStrm_RxFifoStreamer *InstancePtr);
 319 void XStrm_Read(XStrm_RxFifoStreamer *InstancePtr, void *BufPtr,
 320                    unsigned bytes);
 321
 322 #ifdef __cplusplus
 323 }
 324 #endif
 325 #endif                          /* XSTREAMER_H  end of preprocessor protection symbols */