git.sur5r.net Git - freertos/blob

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