git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_A9_Zynq_ZC702/RTOSDemo_bsp/ps7_cortexa9_0/libsrc/usbps_v2_4/src/xusbps_endpoint.h

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