board/xilinx/common/xbuf_descriptor.h

   1 /******************************************************************************
   2 *
   3 *     Author: Xilinx, Inc.
   4 *
   5 *
   6 *     This program is free software; you can redistribute it and/or modify it
   7 *     under the terms of the GNU General Public License as published by the
   8 *     Free Software Foundation; either version 2 of the License, or (at your
   9 *     option) any later version.
  10 *
  11 *
  12 *     XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS" AS A
  13 *     COURTESY TO YOU. BY PROVIDING THIS DESIGN, CODE, OR INFORMATION AS
  14 *     ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE, APPLICATION OR STANDARD,
  15 *     XILINX IS MAKING NO REPRESENTATION THAT THIS IMPLEMENTATION IS FREE
  16 *     FROM ANY CLAIMS OF INFRINGEMENT, AND YOU ARE RESPONSIBLE FOR OBTAINING
  17 *     ANY THIRD PARTY RIGHTS YOU MAY REQUIRE FOR YOUR IMPLEMENTATION.
  18 *     XILINX EXPRESSLY DISCLAIMS ANY WARRANTY WHATSOEVER WITH RESPECT TO
  19 *     THE ADEQUACY OF THE IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY
  20 *     WARRANTIES OR REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM
  21 *     CLAIMS OF INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND
  22 *     FITNESS FOR A PARTICULAR PURPOSE.
  23 *
  24 *
  25 *     Xilinx hardware products are not intended for use in life support
  26 *     appliances, devices, or systems. Use in such applications is
  27 *     expressly prohibited.
  28 *
  29 *
  30 *     (c) Copyright 2002-2004 Xilinx Inc.
  31 *     All rights reserved.
  32 *
  33 *
  34 *     You should have received a copy of the GNU General Public License along
  35 *     with this program; if not, write to the Free Software Foundation, Inc.,
  36 *     675 Mass Ave, Cambridge, MA 02139, USA.
  37 *
  38 * FILENAME:
  39 *
  40 * xbuf_descriptor.h
  41 *
  42 * DESCRIPTION:
  43 *
  44 * This file contains the interface for the XBufDescriptor component.
  45 * The XBufDescriptor component is a passive component that only maps over
  46 * a buffer descriptor data structure shared by the scatter gather DMA hardware
  47 * and software. The component's primary purpose is to provide encapsulation of
  48 * the buffer descriptor processing.  See the source file xbuf_descriptor.c for
  49 * details.
  50 *
  51 * NOTES:
  52 *
  53 * Most of the functions of this component are implemented as macros in order
  54 * to optimize the processing.  The names are not all uppercase such that they
  55 * can be switched between macros and functions easily.
  56 *
  57 ******************************************************************************/
  58
  59 #ifndef XBUF_DESCRIPTOR_H       /* prevent circular inclusions */
  60 #define XBUF_DESCRIPTOR_H       /* by using protection macros */
  61
  62 /***************************** Include Files *********************************/
  63
  64 #include "xbasic_types.h"
  65 #include "xdma_channel_i.h"
  66
  67 /************************** Constant Definitions *****************************/
  68
  69 /* The following constants allow access to all fields of a buffer descriptor
  70  * and are necessary at this level of visibility to allow macros to access
  71  * and modify the fields of a buffer descriptor.  It is not expected that the
  72  * user of a buffer descriptor would need to use these constants.
  73  */
  74
  75 #define XBD_DEVICE_STATUS_OFFSET    0
  76 #define XBD_CONTROL_OFFSET          1
  77 #define XBD_SOURCE_OFFSET           2
  78 #define XBD_DESTINATION_OFFSET      3
  79 #define XBD_LENGTH_OFFSET           4
  80 #define XBD_STATUS_OFFSET           5
  81 #define XBD_NEXT_PTR_OFFSET         6
  82 #define XBD_ID_OFFSET               7
  83 #define XBD_FLAGS_OFFSET            8
  84 #define XBD_RQSTED_LENGTH_OFFSET    9
  85
  86 #define XBD_SIZE_IN_WORDS           10
  87
  88 /*
  89  * The following constants define the bits of the flags field of a buffer
  90  * descriptor
  91  */
  92
  93 #define XBD_FLAGS_LOCKED_MASK       1UL
  94
  95 /**************************** Type Definitions *******************************/
  96
  97 typedef u32 XBufDescriptor[XBD_SIZE_IN_WORDS];
  98
  99 /***************** Macros (Inline Functions) Definitions *********************/
 100
 101 /* each of the following macros are named the same as functions rather than all
 102  * upper case in order to allow either the macros or the functions to be
 103  * used, see the source file xbuf_descriptor.c for documentation
 104  */
 105
 106 #define XBufDescriptor_Initialize(InstancePtr)                  \
 107 {                                                               \
 108     (*((u32 *)InstancePtr + XBD_CONTROL_OFFSET) = 0);       \
 109     (*((u32 *)InstancePtr + XBD_SOURCE_OFFSET) = 0);        \
 110     (*((u32 *)InstancePtr + XBD_DESTINATION_OFFSET) = 0);   \
 111     (*((u32 *)InstancePtr + XBD_LENGTH_OFFSET) = 0);        \
 112     (*((u32 *)InstancePtr + XBD_STATUS_OFFSET) = 0);        \
 113     (*((u32 *)InstancePtr + XBD_DEVICE_STATUS_OFFSET) = 0); \
 114     (*((u32 *)InstancePtr + XBD_NEXT_PTR_OFFSET) = 0);      \
 115     (*((u32 *)InstancePtr + XBD_ID_OFFSET) = 0);            \
 116     (*((u32 *)InstancePtr + XBD_FLAGS_OFFSET) = 0);         \
 117     (*((u32 *)InstancePtr + XBD_RQSTED_LENGTH_OFFSET) = 0); \
 118 }
 119
 120 #define XBufDescriptor_GetControl(InstancePtr)   \
 121     (u32)(*((u32 *)InstancePtr + XBD_CONTROL_OFFSET))
 122
 123 #define XBufDescriptor_SetControl(InstancePtr, Control)  \
 124     (*((u32 *)InstancePtr + XBD_CONTROL_OFFSET) = (u32)Control)
 125
 126 #define XBufDescriptor_IsLastControl(InstancePtr) \
 127     (u32)(*((u32 *)InstancePtr + XBD_CONTROL_OFFSET) & \
 128                XDC_CONTROL_LAST_BD_MASK)
 129
 130 #define XBufDescriptor_SetLast(InstancePtr) \
 131     (*((u32 *)InstancePtr + XBD_CONTROL_OFFSET) |= XDC_CONTROL_LAST_BD_MASK)
 132
 133 #define XBufDescriptor_GetSrcAddress(InstancePtr) \
 134     ((u32 *)(*((u32 *)InstancePtr + XBD_SOURCE_OFFSET)))
 135
 136 #define XBufDescriptor_SetSrcAddress(InstancePtr, Source) \
 137     (*((u32 *)InstancePtr + XBD_SOURCE_OFFSET) = (u32)Source)
 138
 139 #define XBufDescriptor_GetDestAddress(InstancePtr) \
 140     ((u32 *)(*((u32 *)InstancePtr + XBD_DESTINATION_OFFSET)))
 141
 142 #define XBufDescriptor_SetDestAddress(InstancePtr, Destination) \
 143     (*((u32 *)InstancePtr + XBD_DESTINATION_OFFSET) = (u32)Destination)
 144
 145 #define XBufDescriptor_GetLength(InstancePtr)                           \
 146     (u32)(*((u32 *)InstancePtr + XBD_RQSTED_LENGTH_OFFSET) -    \
 147               *((u32 *)InstancePtr + XBD_LENGTH_OFFSET))
 148
 149 #define XBufDescriptor_SetLength(InstancePtr, Length)                       \
 150 {                                                                           \
 151     (*((u32 *)InstancePtr + XBD_LENGTH_OFFSET) = (u32)(Length));    \
 152     (*((u32 *)InstancePtr + XBD_RQSTED_LENGTH_OFFSET) = (u32)(Length));\
 153 }
 154
 155 #define XBufDescriptor_GetStatus(InstancePtr)    \
 156     (u32)(*((u32 *)InstancePtr + XBD_STATUS_OFFSET))
 157
 158 #define XBufDescriptor_SetStatus(InstancePtr, Status)    \
 159     (*((u32 *)InstancePtr + XBD_STATUS_OFFSET) = (u32)Status)
 160
 161 #define XBufDescriptor_IsLastStatus(InstancePtr) \
 162     (u32)(*((u32 *)InstancePtr + XBD_STATUS_OFFSET) & \
 163                XDC_STATUS_LAST_BD_MASK)
 164
 165 #define XBufDescriptor_GetDeviceStatus(InstancePtr) \
 166     ((u32)(*((u32 *)InstancePtr + XBD_DEVICE_STATUS_OFFSET)))
 167
 168 #define XBufDescriptor_SetDeviceStatus(InstancePtr, Status) \
 169     (*((u32 *)InstancePtr + XBD_DEVICE_STATUS_OFFSET) = (u32)Status)
 170
 171 #define XBufDescriptor_GetNextPtr(InstancePtr) \
 172     (XBufDescriptor *)(*((u32 *)InstancePtr + XBD_NEXT_PTR_OFFSET))
 173
 174 #define XBufDescriptor_SetNextPtr(InstancePtr, NextPtr) \
 175     (*((u32 *)InstancePtr + XBD_NEXT_PTR_OFFSET) = (u32)NextPtr)
 176
 177 #define XBufDescriptor_GetId(InstancePtr) \
 178     (u32)(*((u32 *)InstancePtr + XBD_ID_OFFSET))
 179
 180 #define XBufDescriptor_SetId(InstancePtr, Id) \
 181     (*((u32 *)InstancePtr + XBD_ID_OFFSET) = (u32)Id)
 182
 183 #define XBufDescriptor_GetFlags(InstancePtr) \
 184     (u32)(*((u32 *)InstancePtr + XBD_FLAGS_OFFSET))
 185
 186 #define XBufDescriptor_SetFlags(InstancePtr, Flags) \
 187     (*((u32 *)InstancePtr + XBD_FLAGS_OFFSET) = (u32)Flags)
 188
 189 #define XBufDescriptor_Lock(InstancePtr) \
 190     (*((u32 *)InstancePtr + XBD_FLAGS_OFFSET) |= XBD_FLAGS_LOCKED_MASK)
 191
 192 #define XBufDescriptor_Unlock(InstancePtr) \
 193     (*((u32 *)InstancePtr + XBD_FLAGS_OFFSET) &= ~XBD_FLAGS_LOCKED_MASK)
 194
 195 #define XBufDescriptor_IsLocked(InstancePtr) \
 196     (*((u32 *)InstancePtr + XBD_FLAGS_OFFSET) & XBD_FLAGS_LOCKED_MASK)
 197
 198 /************************** Function Prototypes ******************************/
 199
 200 /* The following prototypes are provided to allow each of the functions to
 201  * be implemented as a function rather than a macro, and to provide the
 202  * syntax to allow users to understand how to call the macros, they are
 203  * commented out to prevent linker errors
 204  *
 205
 206 u32 XBufDescriptor_Initialize(XBufDescriptor* InstancePtr);
 207
 208 u32 XBufDescriptor_GetControl(XBufDescriptor* InstancePtr);
 209 void XBufDescriptor_SetControl(XBufDescriptor* InstancePtr, u32 Control);
 210
 211 u32 XBufDescriptor_IsLastControl(XBufDescriptor* InstancePtr);
 212 void XBufDescriptor_SetLast(XBufDescriptor* InstancePtr);
 213
 214 u32 XBufDescriptor_GetLength(XBufDescriptor* InstancePtr);
 215 void XBufDescriptor_SetLength(XBufDescriptor* InstancePtr, u32 Length);
 216
 217 u32 XBufDescriptor_GetStatus(XBufDescriptor* InstancePtr);
 218 void XBufDescriptor_SetStatus(XBufDescriptor* InstancePtr, u32 Status);
 219 u32 XBufDescriptor_IsLastStatus(XBufDescriptor* InstancePtr);
 220
 221 u32 XBufDescriptor_GetDeviceStatus(XBufDescriptor* InstancePtr);
 222 void XBufDescriptor_SetDeviceStatus(XBufDescriptor* InstancePtr,
 223                                     u32 Status);
 224
 225 u32 XBufDescriptor_GetSrcAddress(XBufDescriptor* InstancePtr);
 226 void XBufDescriptor_SetSrcAddress(XBufDescriptor* InstancePtr,
 227                                   u32 SourceAddress);
 228
 229 u32 XBufDescriptor_GetDestAddress(XBufDescriptor* InstancePtr);
 230 void XBufDescriptor_SetDestAddress(XBufDescriptor* InstancePtr,
 231                                    u32 DestinationAddress);
 232
 233 XBufDescriptor* XBufDescriptor_GetNextPtr(XBufDescriptor* InstancePtr);
 234 void XBufDescriptor_SetNextPtr(XBufDescriptor* InstancePtr,
 235                                XBufDescriptor* NextPtr);
 236
 237 u32 XBufDescriptor_GetId(XBufDescriptor* InstancePtr);
 238 void XBufDescriptor_SetId(XBufDescriptor* InstancePtr, u32 Id);
 239
 240 u32 XBufDescriptor_GetFlags(XBufDescriptor* InstancePtr);
 241 void XBufDescriptor_SetFlags(XBufDescriptor* InstancePtr, u32 Flags);
 242
 243 void XBufDescriptor_Lock(XBufDescriptor* InstancePtr);
 244 void XBufDescriptor_Unlock(XBufDescriptor* InstancePtr);
 245 u32 XBufDescriptor_IsLocked(XBufDescriptor* InstancePtr);
 246
 247 void XBufDescriptor_Copy(XBufDescriptor* InstancePtr,
 248                          XBufDescriptor* DestinationPtr);
 249
 250 */
 251
 252 #endif                          /* end of protection macro */