git.sur5r.net Git - freertos/blob

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2010 - 2014 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 xusbps_endpoint.h
  36  *
  37  * This is an internal file containung the definitions for endpoints. It is
  38  * included by the xusbps_endpoint.c which is implementing the endpoint
  39  * functions and by xusbps_intr.c.
  40  *
  41  * <pre>
  42  * MODIFICATION HISTORY:
  43  *
  44  * Ver   Who  Date     Changes
  45  * ----- ---- -------- --------------------------------------------------------
  46  * 1.00a wgr  10/10/10 First release
  47  * </pre>
  48  *
  49  ******************************************************************************/
  50 #ifndef XUSBPS_ENDPOINT_H
  51 #define XUSBPS_ENDPOINT_H
  52
  53 #ifdef __cplusplus
  54 extern "C" {
  55 #endif
  56
  57 /***************************** Include Files *********************************/
  58
  59 #include "xil_cache.h"
  60 #include "xusbps.h"
  61 #include "xil_types.h"
  62
  63 /**************************** Type Definitions *******************************/
  64
  65 /************************** Constant Definitions *****************************/
  66
  67
  68 /**
  69  * Endpoint Device Transfer Descriptor
  70  *
  71  * The dTD describes to the device controller the location and quantity of data
  72  * to be sent/received for given transfer. The driver does not attempt to
  73  * modify any field in an active dTD except the Next Link Pointer.
  74  */
  75 #define XUSBPS_dTDNLP           0x00 /**< Pointer to the next descriptor */
  76 #define XUSBPS_dTDTOKEN 0x04 /**< Descriptor Token */
  77 #define XUSBPS_dTDBPTR0 0x08 /**< Buffer Pointer 0 */
  78 #define XUSBPS_dTDBPTR1 0x0C /**< Buffer Pointer 1 */
  79 #define XUSBPS_dTDBPTR2 0x10 /**< Buffer Pointer 2 */
  80 #define XUSBPS_dTDBPTR3 0x14 /**< Buffer Pointer 3 */
  81 #define XUSBPS_dTDBPTR4 0x18 /**< Buffer Pointer 4 */
  82 #define XUSBPS_dTDBPTR(n)       (XUSBPS_dTDBPTR0 + (n) * 0x04)
  83 #define XUSBPS_dTDRSRVD 0x1C /**< Reserved field */
  84
  85 /* We use the reserved field in the dTD to store user data. */
  86 #define XUSBPS_dTDUSERDATA      XUSBPS_dTDRSRVD /**< Reserved field */
  87
  88
  89 /** @name dTD Next Link Pointer (dTDNLP) bit positions.
  90  *  @{
  91  */
  92 #define XUSBPS_dTDNLP_T_MASK            0x00000001
  93                                 /**< USB dTD Next Link Pointer Terminate Bit */
  94 #define XUSBPS_dTDNLP_ADDR_MASK 0xFFFFFFE0
  95                                 /**< USB dTD Next Link Pointer Address [31:5] */
  96 /* @} */
  97
  98
  99 /** @name dTD Token (dTDTOKEN) bit positions.
 100  *  @{
 101  */
 102 #define XUSBPS_dTDTOKEN_XERR_MASK       0x00000008 /**< dTD Transaction Error */
 103 #define XUSBPS_dTDTOKEN_BUFERR_MASK     0x00000020 /**< dTD Data Buffer Error */
 104 #define XUSBPS_dTDTOKEN_HALT_MASK       0x00000040 /**< dTD Halted Flag */
 105 #define XUSBPS_dTDTOKEN_ACTIVE_MASK     0x00000080 /**< dTD Active Bit */
 106 #define XUSBPS_dTDTOKEN_MULTO_MASK      0x00000C00 /**< Multiplier Override Field [1:0] */
 107 #define XUSBPS_dTDTOKEN_IOC_MASK        0x00008000 /**< Interrupt on Complete Bit */
 108 #define XUSBPS_dTDTOKEN_LEN_MASK        0x7FFF0000 /**< Transfer Length Field */
 109 /* @} */
 110
 111
 112 /***************** Macros (Inline Functions) Definitions *********************/
 113
 114 /*****************************************************************************/
 115 /**
 116  *
 117  * IMPORTANT NOTE:
 118  * ===============
 119  *
 120  * Many of the following macros modify Device Queue Head (dQH) data structures
 121  * and Device Transfer Descriptor (dTD) data structures. Those structures can
 122  * potentially reside in CACHED memory. Therefore, it's the callers
 123  * responsibility to ensure cache coherency by using provided
 124  *
 125  *      XUsbPs_dQHInvalidateCache()
 126  *      XUsbPs_dQHFlushCache()
 127  *      XUsbPs_dTDInvalidateCache()
 128  *      XUsbPs_dTDFlushCache()
 129  *
 130  * function calls.
 131  *
 132  ******************************************************************************/
 133 #define XUsbPs_dTDInvalidateCache(dTDPtr) \
 134                 Xil_DCacheInvalidateRange((unsigned int)dTDPtr, sizeof(XUsbPs_dTD))
 135
 136 #define XUsbPs_dTDFlushCache(dTDPtr) \
 137                 Xil_DCacheFlushRange((unsigned int)dTDPtr, sizeof(XUsbPs_dTD))
 138
 139 #define XUsbPs_dQHInvalidateCache(dQHPtr) \
 140                 Xil_DCacheInvalidateRange((unsigned int)dQHPtr, sizeof(XUsbPs_dQH))
 141
 142 #define XUsbPs_dQHFlushCache(dQHPtr) \
 143                 Xil_DCacheFlushRange((unsigned int)dQHPtr, sizeof(XUsbPs_dQH))
 144
 145 /*****************************************************************************/
 146 /**
 147  *
 148  * This macro sets the Transfer Length for the given Transfer Descriptor.
 149  *
 150  * @param       dTDPtr is pointer to the dTD element.
 151  * @param       Len is the length to be set. Range: 0..16384
 152  *
 153  * @note        C-style signature:
 154  *              void XUsbPs_dTDSetTransferLen(u32 dTDPtr, u32 Len)
 155  *
 156  ******************************************************************************/
 157 #define XUsbPs_dTDSetTransferLen(dTDPtr, Len)                           \
 158                 XUsbPs_WritedTD(dTDPtr, XUSBPS_dTDTOKEN,                \
 159                         (XUsbPs_ReaddTD(dTDPtr, XUSBPS_dTDTOKEN) &      \
 160                                 ~XUSBPS_dTDTOKEN_LEN_MASK) | ((Len) << 16))
 161
 162
 163 /*****************************************************************************/
 164 /**
 165  *
 166  * This macro gets the Next Link pointer of the given Transfer Descriptor.
 167  *
 168  * @param       dTDPtr is pointer to the dTD element.
 169  *
 170  * @return      TransferLength field of the descriptor.
 171  *
 172  * @note        C-style signature:
 173  *              u32 XUsbPs_dTDGetTransferLen(u32 dTDPtr)
 174  *
 175  ******************************************************************************/
 176 #define XUsbPs_dTDGetNLP(dTDPtr)                                        \
 177                 (XUsbPs_dTD *) ((XUsbPs_ReaddTD(dTDPtr, XUSBPS_dTDNLP)\
 178                                         & XUSBPS_dTDNLP_ADDR_MASK))
 179
 180
 181 /*****************************************************************************/
 182 /**
 183  *
 184  * This macro sets the Next Link pointer of the given Transfer Descriptor.
 185  *
 186  * @param       dTDPtr is a pointer to the dTD element.
 187  * @param       NLP is the Next Link Pointer
 188  *
 189  * @note        C-style signature:
 190  *              void XUsbPs_dTDSetTransferLen(u32 dTDPtr, u32 Len)
 191  *
 192  ******************************************************************************/
 193 #define XUsbPs_dTDSetNLP(dTDPtr, NLP)                                   \
 194                 XUsbPs_WritedTD(dTDPtr, XUSBPS_dTDNLP,          \
 195                         (XUsbPs_ReaddTD(dTDPtr, XUSBPS_dTDNLP) &        \
 196                                 ~XUSBPS_dTDNLP_ADDR_MASK) |             \
 197                                         ((NLP) & XUSBPS_dTDNLP_ADDR_MASK))
 198
 199
 200 /*****************************************************************************/
 201 /**
 202  *
 203  * This macro gets the Transfer Length for the given Transfer Descriptor.
 204  *
 205  * @param       dTDPtr is a pointer to the dTD element.
 206  *
 207  * @return      TransferLength field of the descriptor.
 208  *
 209  * @note        C-style signature:
 210  *              u32 XUsbPs_dTDGetTransferLen(u32 dTDPtr)
 211  *
 212  ******************************************************************************/
 213 #define XUsbPs_dTDGetTransferLen(dTDPtr)                                \
 214                 (u32) ((XUsbPs_ReaddTD(dTDPtr, XUSBPS_dTDTOKEN)         \
 215                                 & XUSBPS_dTDTOKEN_LEN_MASK) >> 16)
 216
 217
 218 /*****************************************************************************/
 219 /**
 220  *
 221  * This macro sets the Interrupt On Complete (IOC) bit for the given Transfer
 222  * Descriptor.
 223  *
 224  * @param       dTDPtr is a pointer to the dTD element.
 225  *
 226  * @note        C-style signature:
 227  *              void XUsbPs_dTDSetIOC(u32 dTDPtr)
 228  *
 229  ******************************************************************************/
 230 #define XUsbPs_dTDSetIOC(dTDPtr)                                        \
 231                 XUsbPs_WritedTD(dTDPtr, XUSBPS_dTDTOKEN,                \
 232                         XUsbPs_ReaddTD(dTDPtr, XUSBPS_dTDTOKEN) |       \
 233                                                 XUSBPS_dTDTOKEN_IOC_MASK)
 234
 235
 236 /*****************************************************************************/
 237 /**
 238  *
 239  * This macro sets the Terminate bit for the given Transfer Descriptor.
 240  *
 241  * @param       dTDPtr is a pointer to the dTD element.
 242  *
 243  * @note        C-style signature:
 244  *              void XUsbPs_dTDSetTerminate(u32 dTDPtr)
 245  *
 246  ******************************************************************************/
 247 #define XUsbPs_dTDSetTerminate(dTDPtr)                          \
 248                 XUsbPs_WritedTD(dTDPtr, XUSBPS_dTDNLP,          \
 249                         XUsbPs_ReaddTD(dTDPtr, XUSBPS_dTDNLP) | \
 250                                                 XUSBPS_dTDNLP_T_MASK)
 251
 252
 253 /*****************************************************************************/
 254 /**
 255  *
 256  * This macro clears the Terminate bit for the given Transfer Descriptor.
 257  *
 258  * @param       dTDPtr is a pointer to the dTD element.
 259  *
 260  * @note        C-style signature:
 261  *              void XUsbPs_dTDClrTerminate(u32 dTDPtr)
 262  *
 263  ******************************************************************************/
 264 #define XUsbPs_dTDClrTerminate(dTDPtr)                          \
 265                 XUsbPs_WritedTD(dTDPtr, XUSBPS_dTDNLP,          \
 266                         XUsbPs_ReaddTD(dTDPtr, XUSBPS_dTDNLP) & \
 267                                                 ~XUSBPS_dTDNLP_T_MASK)
 268
 269
 270 /*****************************************************************************/
 271 /**
 272  *
 273  * This macro checks if the given descriptor is active.
 274  *
 275  * @param       dTDPtr is a pointer to the dTD element.
 276  *
 277  * @return
 278  *              - TRUE: The buffer is active.
 279  *              - FALSE: The buffer is not active.
 280  *
 281  * @note        C-style signature:
 282  *              int XUsbPs_dTDIsActive(u32 dTDPtr)
 283  *
 284  ******************************************************************************/
 285 #define XUsbPs_dTDIsActive(dTDPtr)                                      \
 286                 ((XUsbPs_ReaddTD(dTDPtr, XUSBPS_dTDTOKEN) &             \
 287                                 XUSBPS_dTDTOKEN_ACTIVE_MASK) ? TRUE : FALSE)
 288
 289
 290 /*****************************************************************************/
 291 /**
 292  *
 293  * This macro sets the Active bit for the given Transfer Descriptor.
 294  *
 295  * @param       dTDPtr is a pointer to the dTD element.
 296  *
 297  * @note        C-style signature:
 298  *              void XUsbPs_dTDSetActive(u32 dTDPtr)
 299  *
 300  ******************************************************************************/
 301 #define XUsbPs_dTDSetActive(dTDPtr)                                     \
 302                 XUsbPs_WritedTD(dTDPtr, XUSBPS_dTDTOKEN,                \
 303                         XUsbPs_ReaddTD(dTDPtr, XUSBPS_dTDTOKEN) |       \
 304                                                 XUSBPS_dTDTOKEN_ACTIVE_MASK)
 305
 306
 307 /*****************************************************************************/
 308 /**
 309  *
 310  * This macro reads the content of a field in a Transfer Descriptor.
 311  *
 312  * @param       dTDPtr is a pointer to the dTD element.
 313  * @param       Id is the field ID inside the dTD element to read.
 314  *
 315  * @note        C-style signature:
 316  *              u32 XUsbPs_ReaddTD(u32 dTDPtr, u32 Id)
 317  *
 318  ******************************************************************************/
 319 #define XUsbPs_ReaddTD(dTDPtr, Id)      (*(u32 *)((u32)(dTDPtr) + (u32)(Id)))
 320
 321 /*****************************************************************************/
 322 /**
 323  *
 324  * This macro writes a value to a field in a Transfer Descriptor.
 325  *
 326  * @param       dTDPtr is pointer to the dTD element.
 327  * @param       Id is the field ID inside the dTD element to read.
 328  * @param       Val is the value to write to the field.
 329  *
 330  * @note        C-style signature:
 331  *              u32 XUsbPs_WritedTD(u32 dTDPtr, u32 Id, u32 Val)
 332  *
 333  ******************************************************************************/
 334 #define XUsbPs_WritedTD(dTDPtr, Id, Val)        \
 335                         (*(u32 *) ((u32)(dTDPtr) + (u32)(Id)) = (u32)(Val))
 336
 337
 338 /******************************************************************************/
 339 /**
 340  * Endpoint Device Queue Head
 341  *
 342  * Device queue heads are arranged in an array in a continuous area of memory
 343  * pointed to by the ENDPOINTLISTADDR pointer. The device controller will index
 344  * into this array based upon the endpoint number received from the USB bus.
 345  * All information necessary to respond to transactions for all primed
 346  * transfers is contained in this list so the Device Controller can readily
 347  * respond to incoming requests without having to traverse a linked list.
 348  *
 349  * The device Endpoint Queue Head (dQH) is where all transfers are managed. The
 350  * dQH is a 48-byte data structure, but must be aligned on a 64-byte boundary.
 351  * During priming of an endpoint, the dTD (device transfer descriptor) is
 352  * copied into the overlay area of the dQH, which starts at the nextTD pointer
 353  * DWord and continues through the end of the buffer pointers DWords. After a
 354  * transfer is complete, the dTD status DWord is updated in the dTD pointed to
 355  * by the currentTD pointer. While a packet is in progress, the overlay area of
 356  * the dQH is used as a staging area for the dTD so that the Device Controller
 357  * can access needed information with little minimal latency.
 358  *
 359  * @note
 360  *    Software must ensure that no interface data structure reachable by the
 361  *    Device Controller spans a 4K-page boundary.  The first element of the
 362  *    Endpoint Queue Head List must be aligned on a 4K boundary.
 363  */
 364 #define XUSBPS_dQHCFG                   0x00 /**< dQH Configuration */
 365 #define XUSBPS_dQHCPTR                  0x04 /**< dQH Current dTD Pointer */
 366 #define XUSBPS_dQHdTDNLP                0x08 /**< dTD Next Link Ptr in dQH
 367                                                overlay */
 368 #define XUSBPS_dQHdTDTOKEN              0x0C /**< dTD Token in dQH overlay */
 369 #define XUSBPS_dQHSUB0                  0x28 /**< USB dQH Setup Buffer 0 */
 370 #define XUSBPS_dQHSUB1                  0x2C /**< USB dQH Setup Buffer 1 */
 371
 372
 373 /** @name dQH Configuration (dQHCFG) bit positions.
 374  *  @{
 375  */
 376 #define XUSBPS_dQHCFG_IOS_MASK          0x00008000
 377                                         /**< USB dQH Interrupt on Setup Bit */
 378 #define XUSBPS_dQHCFG_MPL_MASK          0x07FF0000
 379                                         /**< USB dQH Maximum Packet Length
 380                                          * Field [10:0] */
 381 #define XUSBPS_dQHCFG_MPL_SHIFT    16
 382 #define XUSBPS_dQHCFG_ZLT_MASK          0x20000000
 383                                         /**< USB dQH Zero Length Termination
 384                                          * Select Bit */
 385 #define XUSBPS_dQHCFG_MULT_MASK         0xC0000000
 386                                         /* USB dQH Number of Transactions Field
 387                                          * [1:0] */
 388 #define XUSBPS_dQHCFG_MULT_SHIFT       30
 389 /* @} */
 390
 391
 392 /*****************************************************************************/
 393 /**
 394  *
 395  * This macro sets the Maximum Packet Length field of the give Queue Head.
 396  *
 397  * @param       dQHPtr is a pointer to the dQH element.
 398  * @param       Len is the length to be set.
 399  *
 400  * @note        C-style signature:
 401  *              void XUsbPs_dQHSetMaxPacketLen(u32 dQHPtr, u32 Len)
 402  *
 403  ******************************************************************************/
 404 #define XUsbPs_dQHSetMaxPacketLen(dQHPtr, Len)                  \
 405                 XUsbPs_WritedQH(dQHPtr, XUSBPS_dQHCFG,          \
 406                         (XUsbPs_ReaddQH(dQHPtr, XUSBPS_dQHCFG) &        \
 407                                 ~XUSBPS_dQHCFG_MPL_MASK) | ((Len) << 16))
 408
 409 /*****************************************************************************/
 410 /**
 411  *
 412  * This macro sets the Interrupt On Setup (IOS) bit for an endpoint.
 413  *
 414  * @param       dQHPtr is a pointer to the dQH element.
 415  *
 416  * @note        C-style signature:
 417  *              void XUsbPs_dQHSetIOS(u32 dQHPtr)
 418  *
 419  ******************************************************************************/
 420 #define XUsbPs_dQHSetIOS(dQHPtr)                                        \
 421                 XUsbPs_WritedQH(dQHPtr, XUSBPS_dQHCFG,          \
 422                         XUsbPs_ReaddQH(dQHPtr, XUSBPS_dQHCFG) | \
 423                                                 XUSBPS_dQHCFG_IOS_MASK)
 424
 425 /*****************************************************************************/
 426 /**
 427  *
 428  * This macro clears the Interrupt On Setup (IOS) bit for an endpoint.
 429  *
 430  * @param       dQHPtr is a pointer to the dQH element.
 431  *
 432  * @note        C-style signature:
 433  *              void XUsbPs_dQHClrIOS(u32 dQHPtr)
 434  *
 435  ******************************************************************************/
 436 #define XUsbPs_dQHClrIOS(dQHPtr)                                        \
 437                 XUsbPs_WritedQH(dQHPtr, XUSBPS_dQHCFG,          \
 438                         XUsbPs_ReaddQH(dQHPtr, XUSBPS_dQHCFG) & \
 439                                                 ~XUSBPS_dQHCFG_IOS_MASK)
 440
 441 /*****************************************************************************/
 442 /**
 443  *
 444  * This macro enables Zero Length Termination for the endpoint.
 445  *
 446  * @param       dQHPtr is a pointer to the dQH element.
 447  *
 448  * @note        C-style signature:
 449  *              void XUsbPs_dQHEnableZLT(u32 dQHPtr)
 450  *
 451  *
 452  ******************************************************************************/
 453 #define XUsbPs_dQHEnableZLT(dQHPtr)                                     \
 454                 XUsbPs_WritedQH(dQHPtr, XUSBPS_dQHCFG,          \
 455                         XUsbPs_ReaddQH(dQHPtr, XUSBPS_dQHCFG) & \
 456                                                 ~XUSBPS_dQHCFG_ZLT_MASK)
 457
 458
 459 /*****************************************************************************/
 460 /**
 461  *
 462  * This macro disables Zero Length Termination for the endpoint.
 463  *
 464  * @param       dQHPtr is a pointer to the dQH element.
 465  *
 466  * @note        C-style signature:
 467  *              void XUsbPs_dQHDisableZLT(u32 dQHPtr)
 468  *
 469  *
 470  ******************************************************************************/
 471 #define XUsbPs_dQHDisableZLT(dQHPtr)                                    \
 472                 XUsbPs_WritedQH(dQHPtr, XUSBPS_dQHCFG,          \
 473                         XUsbPs_ReaddQH(dQHPtr, XUSBPS_dQHCFG) | \
 474                                                 XUSBPS_dQHCFG_ZLT_MASK)
 475
 476 /*****************************************************************************/
 477 /**
 478  *
 479  * This macro reads the content of a field in a Queue Head.
 480  *
 481  * @param       dQHPtr is a pointer to the dQH element.
 482  * @param       Id is the Field ID inside the dQH element to read.
 483  *
 484  * @note        C-style signature:
 485  *              u32 XUsbPs_ReaddQH(u32 dQHPtr, u32 Id)
 486  *
 487  ******************************************************************************/
 488 #define XUsbPs_ReaddQH(dQHPtr, Id)      (*(u32 *)((u32)(dQHPtr) + (u32) (Id)))
 489
 490 /*****************************************************************************/
 491 /**
 492  *
 493  * This macro writes a value to a field in a Queue Head.
 494  *
 495  * @param       dQHPtr is a pointer to the dQH element.
 496  * @param       Id is the Field ID inside the dQH element to read.
 497  * @param       Val is the Value to write to the field.
 498  *
 499  * @note        C-style signature:
 500  *              u32 XUsbPs_WritedQH(u32 dQHPtr, u32 Id, u32 Val)
 501  *
 502  ******************************************************************************/
 503 #define XUsbPs_WritedQH(dQHPtr, Id, Val)        \
 504                         (*(u32 *) ((u32)(dQHPtr) + (u32)(Id)) = (u32)(Val))
 505
 506
 507
 508 #ifdef __cplusplus
 509 }
 510 #endif
 511
 512 #endif /* XUSBPS_ENDPOINT_H */