git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_A9_Zynq_ZC702/RTOSDemo_bsp/ps7_cortexa9_0/include/xusbps.h

   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.h
  36 * @addtogroup usbps_v2_1
  37 * @{
  38 * @details
  39  *
  40  * This file contains the implementation of the XUsbPs driver. It is the
  41  * driver for an USB controller in DEVICE or HOST mode.
  42  *
  43  * <h2>Introduction</h2>
  44  *
  45  * The Spartan-3AF Embedded Peripheral Block contains a USB controller for
  46  * communication with serial peripherals or hosts. The USB controller supports
  47  * Host, Device and On the Go (OTG) applications.
  48  *
  49  * <h2>USB Controller Features</h2>
  50  *
  51  * - Supports Low Speed USB 1.1 (1.5Mbps), Full Speed USB 1.1 (12Mbps), and
  52  *   High Speed USB 2.0 (480Mbps) data speeds
  53  * - Supports Device, Host and OTG operational modes
  54  * - ULPI transceiver interface for USB 2.0 operation
  55  * - Integrated USB Full and Low speed serial transceiver interfaces for lowest
  56  *   cost connections
  57  *
  58  * <h2>Initialization & Configuration</h2>
  59  *
  60  * The configuration of the USB driver happens in multiple stages:
  61  *
  62  * - (a) Configuration of the basic parameters:
  63  *   In this stage the basic parameters for the driver are configured,
  64  *   including the base address and the controller ID.
  65  *
  66  * - (b) Configuration of the DEVICE endpoints (if applicable):
  67  *   If DEVICE mode is desired, the endpoints of the controller need to be
  68  *   configured using the XUsbPs_DeviceConfig data structure. Once the
  69  *   endpoint configuration is set up in the data structure, The user then
  70  *   needs to allocate the required amount of DMAable memory and
  71  *   finalize the configuration of the XUsbPs_DeviceConfig data structure,
  72  *   e.g. setting the DMAMemVirt and DMAMemPhys members.
  73  *
  74  * - (c) Configuration of the DEVICE modes:
  75  *   In the second stage the parameters for DEVICE are configured.
  76  *   The caller only needs to configure the modes that are
  77  *   actually used. Configuration is done with the:
  78  *      XUsbPs_ConfigureDevice()
  79  * Configuration parameters are defined and passed
  80  *   into these functions using the:
  81  *      XUsbPs_DeviceConfig data structures.
  82  *
  83  *
  84  * <h2>USB Device Endpoints</h2>
  85  *
  86  * The USB core supports up to 4 endpoints. Each endpoint has two directions,
  87  * an OUT (RX) and an IN (TX) direction. Note that the direction is viewed from
  88  * the host's perspective. Endpoint 0 defaults to be the control endpoint and
  89  * does not need to be set up. Other endpoints need to be configured and set up
  90  * depending on the application. Only endpoints that are actuelly used by the
  91  * application need to be initialized.
  92  * See the example code (xusbps_intr_example.c) for more information.
  93  *
  94  *
  95  * <h2>Interrupt Handling</h2>
  96  *
  97  * The USB core uses one interrupt line to report interrupts to the CPU.
  98  * Interrupts are handled by the driver's interrupt handler function
  99  * XUsbPs_IntrHandler().
 100  * It has to be registered with the OS's interrupt subsystem. The driver's
 101  * interrupt handler divides incoming interrupts into two categories:
 102  *
 103  *  - General device interrupts
 104  *  - Endopint related interrupts
 105  *
 106  * The user (typically the adapter layer) can register general interrupt
 107  * handler fucntions and endpoint specific interrupt handler functions with the
 108  * driver to receive those interrupts by calling the
 109  *    XUsbPs_IntrSetHandler()
 110  * and
 111  *    XUsbPs_EpSetHandler()
 112  * functions respectively. Calling these functions with a NULL pointer as the
 113  * argument for the function pointer will "clear" the handler function.
 114  *
 115  * The user can register one handler function for the generic interrupts and
 116  * two handler functions for each endpoint, one for the RX (OUT) and one for
 117  * the TX (IN) direction. For some applications it may be useful to register a
 118  * single endpoint handler function for muliple endpoints/directions.
 119  *
 120  * When a callback function is called by the driver, parameters identifying the
 121  * type of the interrupt will be passed into the handler functions. For general
 122  * interrupts the interrupt mask will be passed into the handler function. For
 123  * endpoint interrupts the parameters include the number of the endpoint, the
 124  * direction (OUT/IN) and the type of the interrupt.
 125  *
 126  *
 127  * <h2>Data buffer handling</h2>
 128  *
 129  * Data buffers are sent to and received from endpoint using the
 130  *    XUsbPs_EpBufferSend(), XUsbPs_EpBufferSendWithZLT()
 131  * and
 132  *    XUsbPs_EpBufferReceive()
 133  * functions.
 134  *
 135  * User data buffer size is limited to 16 Kbytes. If the user wants to send a
 136  * data buffer that is bigger than this limit it needs to break down the data
 137  * buffer into multiple fragments and send the fragments individually.
 138  *
 139  * From the controller perspective Data buffers can be aligned at any boundary.
 140  * if the buffers are from cache region then the buffer and buffer size should
 141  * be aligned to cache line aligned
 142  *
 143  *
 144  * <h3>Zero copy</h3>
 145  *
 146  * The driver uses a zero copy mechanism which imposes certain restrictions to
 147  * the way the user can handle the data buffers.
 148  *
 149  * One restriction is that the user needs to release a buffer after it is done
 150  * processing the data in the buffer.
 151  *
 152  * Similarly, when the user sends a data buffer it MUST not re-use the buffer
 153  * until it is notified by the driver that the buffer has been transmitted. The
 154  * driver will notify the user via the registered endpoint interrupt handling
 155  * function by sending a XUSBPS_EP_EVENT_DATA_TX event.
 156  *
 157  *
 158  * <h2>DMA</h2>
 159  *
 160  * The driver uses DMA internally to move data from/to memory. This behaviour
 161  * is transparent to the user. Keeping the DMA handling hidden from the user
 162  * has the advantage that the same API can be used with USB cores that do not
 163  * support DMA.
 164  *
 165  *
 166  * <pre>
 167  * MODIFICATION HISTORY:
 168  *
 169  * Ver   Who  Date     Changes
 170  * ----- ---- -------- ----------------------------------------------------------
 171  * 1.00a wgr  10/10/10 First release
 172  * 1.02a wgr  05/16/12 Removed comments as they are showing up in SDK
 173  *                     Tabs for CR 657898
 174  * 1.03a nm   09/21/12 Fixed CR#678977. Added proper sequence for setup packet
 175  *                    handling.
 176  * 1.04a nm   10/23/12 Fixed CR# 679106.
 177  *            11/02/12 Fixed CR# 683931. Mult bits are set properly in dQH.
 178  * 2.00a kpc 04/03/14 Fixed CR#777763. Corrected the setup tripwire macro val.
 179  * 2.1   kpc 04/28/14 Removed unused function prototypes
 180  * </pre>
 181  *
 182  ******************************************************************************/
 183
 184 #ifndef XUSBPS_H
 185 #define XUSBPS_H
 186
 187 #ifdef __cplusplus
 188 extern "C" {
 189 #endif
 190
 191 /***************************** Include Files *********************************/
 192
 193 #include "xusbps_hw.h"
 194 #include "xil_types.h"
 195 #include "xstatus.h"
 196
 197 /************************** Constant Definitions *****************************/
 198
 199 /**
 200  * @name System hang prevention Timeout counter value.
 201  *
 202  * This value is used throughout the code to initialize a Timeout counter that
 203  * is used when hard polling a register. The ides is to initialize the Timeout
 204  * counter to a value that is longer than any expected Timeout but short enough
 205  * so the system will continue to work and report an error while the user is
 206  * still paying attention. A reasonable Timeout time would be about 10 seconds.
 207  * The XUSBPS_TIMEOUT_COUNTER value should be chosen so a polling loop would
 208  * run about 10 seconds before a Timeout is detected. For example:
 209  *
 210  *      int Timeout = XUSBPS_TIMEOUT_COUNTER;
 211  *      while ((XUsbPs_ReadReg(InstancePtr->Config.BaseAddress,
 212  *                              XUSBPS_CMD_OFFSET) &
 213  *                              XUSBPS_CMD_RST_MASK) && --Timeout) {
 214  *              ;
 215  *      }
 216  *      if (0 == Timeout) {
 217  *              return XST_FAILURE;
 218  *      }
 219  *
 220  */
 221 #define XUSBPS_TIMEOUT_COUNTER          1000000
 222
 223
 224 /**
 225  * @name Endpoint Direction (bitmask)
 226  * Definitions to be used with Endpoint related function that require a
 227  * 'Direction' parameter.
 228  *
 229  * NOTE:
 230  *   The direction is always defined from the perspective of the HOST! This
 231  *   means that an IN endpoint on the controller is used for sending data while
 232  *   the OUT endpoint on the controller is used for receiving data.
 233  * @{
 234  */
 235 #define XUSBPS_EP_DIRECTION_IN          0x01 /**< Endpoint direction IN. */
 236 #define XUSBPS_EP_DIRECTION_OUT         0x02 /**< Endpoint direction OUT. */
 237 /* @} */
 238
 239
 240 /**
 241  * @name Endpoint Type
 242  * Definitions to be used with Endpoint related functions that require a 'Type'
 243  * parameter.
 244  * @{
 245  */
 246 #define XUSBPS_EP_TYPE_NONE             0 /**< Endpoint is not used. */
 247 #define XUSBPS_EP_TYPE_CONTROL          1 /**< Endpoint for Control Transfers */
 248 #define XUSBPS_EP_TYPE_ISOCHRONOUS      2 /**< Endpoint for isochronous data */
 249 #define XUSBPS_EP_TYPE_BULK             3 /**< Endpoint for BULK Transfers. */
 250 #define XUSBPS_EP_TYPE_INTERRUPT        4 /**< Endpoint for interrupt Transfers */
 251 /* @} */
 252
 253 /**
 254  * Endpoint Max Packet Length in DeviceConfig is a coded value, ch9.6.6.
 255  *
 256  * @{
 257  */
 258 #define ENDPOINT_MAXP_LENGTH            0x400
 259 #define ENDPOINT_MAXP_MULT_MASK         0xC00
 260 #define ENDPOINT_MAXP_MULT_SHIFT        10
 261 /* @} */
 262
 263 /**
 264  * @name Field names for status retrieval
 265  * Definitions for the XUsbPs_GetStatus() function call 'StatusType'
 266  * parameter.
 267  * @{
 268  */
 269 #define XUSBPS_EP_STS_ADDRESS           1 /**< Address of controller. */
 270 #define XUSBPS_EP_STS_CONTROLLER_STATE  2 /**< Current controller state. */
 271 /* @} */
 272
 273
 274
 275 /**
 276  * @name USB Default alternate setting
 277  *
 278  * @{
 279  */
 280 #define XUSBPS_DEFAULT_ALT_SETTING      0 /**< The default alternate setting is 0 */
 281 /* @} */
 282
 283 /**
 284  * @name Endpoint event types
 285  * Definitions that are used to identify events that occur on endpoints. Passed
 286  * to the endpoint event handler functions registered with
 287  * XUsbPs_EpSetHandler().
 288  * @{
 289  */
 290 #define XUSBPS_EP_EVENT_SETUP_DATA_RECEIVED     0x01
 291                         /**< Setup data has been received on the enpoint. */
 292 #define XUSBPS_EP_EVENT_DATA_RX         0x02
 293                         /**< Data frame has been received on the endpoint. */
 294 #define XUSBPS_EP_EVENT_DATA_TX         0x03
 295                         /**< Data frame has been sent on the endpoint. */
 296 /* @} */
 297
 298
 299 /*
 300  * Maximum packet size for endpoint, 1024
 301  * @{
 302  */
 303 #define XUSBPS_MAX_PACKET_SIZE          1024
 304                                 /**< Maximum value can be put into the queue head */
 305 /* @} */
 306 /**************************** Type Definitions *******************************/
 307
 308 /******************************************************************************
 309  * This data type defines the callback function to be used for Endpoint
 310  * handlers.
 311  *
 312  * @param       CallBackRef is the Callback reference passed in by the upper
 313  *              layer when setting the handler, and is passed back to the upper
 314  *              layer when the handler is called.
 315  * @param       EpNum is the Number of the endpoint that caused the event.
 316  * @param       EventType is the type of the event that occured on the endpoint.
 317  * @param       Data is a pointer to user data pointer specified when callback
 318  *              was registered.
 319  */
 320 typedef void (*XUsbPs_EpHandlerFunc)(void *CallBackRef,
 321                                       u8 EpNum, u8 EventType, void *Data);
 322
 323
 324 /******************************************************************************
 325  * This data type defines the callback function to be used for the general
 326  * interrupt handler.
 327  *
 328  * @param       CallBackRef is the Callback reference passed in by the upper
 329  *              layer when setting the handler, and is passed back to the upper
 330  *              layer when the handler is called.
 331  * @param       IrqMask is the Content of the interrupt status register. This
 332  *              value can be used by the callback function to distinguish the
 333  *              individual interrupt types.
 334  */
 335 typedef void (*XUsbPs_IntrHandlerFunc)(void *CallBackRef, u32 IrqMask);
 336
 337
 338 /******************************************************************************/
 339
 340 /* The following type definitions are used for referencing Queue Heads and
 341  * Transfer Descriptors. The structures themselves are not used, however, the
 342  * types are used in the API to avoid using (void *) pointers.
 343  */
 344 typedef u8      XUsbPs_dQH[XUSBPS_dQH_ALIGN];
 345 typedef u8      XUsbPs_dTD[XUSBPS_dTD_ALIGN];
 346
 347
 348 /**
 349  * The following data structures are used internally by the L0/L1 driver.
 350  * Their contents MUST NOT be changed by the upper layers.
 351  */
 352
 353 /**
 354  * The following data structure represents OUT endpoint.
 355  */
 356 typedef struct {
 357         XUsbPs_dQH      *dQH;
 358                 /**< Pointer to the Queue Head structure of the endpoint. */
 359
 360         XUsbPs_dTD      *dTDs;
 361                 /**< Pointer to the first dTD of the dTD list for this
 362                  * endpoint. */
 363
 364         XUsbPs_dTD      *dTDCurr;
 365                 /**< Buffer to the currently processed descriptor. */
 366
 367         u8      *dTDBufs;
 368                 /**< Pointer to the first buffer of the buffer list for this
 369                  * endpoint. */
 370
 371         XUsbPs_EpHandlerFunc    HandlerFunc;
 372                 /**< Handler function for this endpoint. */
 373         void                    *HandlerRef;
 374                 /**< User data reference for the handler. */
 375 } XUsbPs_EpOut;
 376
 377
 378 /**
 379  * The following data structure represents IN endpoint.
 380  */
 381 typedef struct {
 382         XUsbPs_dQH      *dQH;
 383                 /**< Pointer to the Queue Head structure of the endpoint. */
 384
 385         XUsbPs_dTD      *dTDs;
 386                 /**< List of pointers to the Transfer Descriptors of the
 387                  * endpoint. */
 388
 389         XUsbPs_dTD      *dTDHead;
 390                 /**< Buffer to the next available descriptor in the list. */
 391
 392         XUsbPs_dTD      *dTDTail;
 393                 /**< Buffer to the last unsent descriptor in the list*/
 394
 395         XUsbPs_EpHandlerFunc    HandlerFunc;
 396                 /**< Handler function for this endpoint. */
 397         void                    *HandlerRef;
 398                 /**< User data reference for the handler. */
 399 } XUsbPs_EpIn;
 400
 401
 402 /**
 403  * The following data structure represents an endpoint used internally
 404  * by the L0/L1 driver.
 405  */
 406 typedef struct {
 407         /* Each endpoint has an OUT and an IN component.
 408          */
 409         XUsbPs_EpOut    Out;    /**< OUT endpoint structure */
 410         XUsbPs_EpIn     In;     /**< IN endpoint structure */
 411 } XUsbPs_Endpoint;
 412
 413
 414
 415 /**
 416  * The following structure is used by the user to receive Setup Data from an
 417  * endpoint. Using this structure simplifies the process of interpreting the
 418  * setup data in the core's data fields.
 419  *
 420  * The naming scheme for the members of this structure is different from the
 421  * naming scheme found elsewhere in the code. The members of this structure are
 422  * defined in the Chapter 9 USB reference guide. Using this naming scheme makes
 423  * it easier for people familiar with the standard to read the code.
 424  */
 425 typedef struct {
 426         u8  bmRequestType;      /**< bmRequestType in setup data */
 427         u8  bRequest;           /**< bRequest in setup data */
 428         u16 wValue;             /**< wValue in setup data */
 429         u16 wIndex;             /**< wIndex in setup data */
 430         u16 wLength;            /**< wLength in setup data */
 431 }
 432 XUsbPs_SetupData;
 433
 434
 435 /**
 436  * Data structures used to configure endpoints.
 437  */
 438 typedef struct {
 439         u32     Type;
 440                 /**< Endpoint type:
 441                         - XUSBPS_EP_TYPE_CONTROL
 442                         - XUSBPS_EP_TYPE_ISOCHRONOUS
 443                         - XUSBPS_EP_TYPE_BULK
 444                         - XUSBPS_EP_TYPE_INTERRUPT */
 445
 446         u32     NumBufs;
 447                 /**< Number of buffers to be handled by this endpoint. */
 448         u32     BufSize;
 449                 /**< Buffer size. Only relevant for OUT (receive) Endpoints. */
 450
 451         u16     MaxPacketSize;
 452                 /**< Maximum packet size for this endpoint. This number will
 453                  * define the maximum number of bytes sent on the wire per
 454                  * transaction. Range: 0..1024 */
 455 } XUsbPs_EpSetup;
 456
 457
 458 /**
 459  * Endpoint configuration structure.
 460  */
 461 typedef struct {
 462         XUsbPs_EpSetup          Out; /**< OUT component of endpoint. */
 463         XUsbPs_EpSetup          In;  /**< IN component of endpoint. */
 464 } XUsbPs_EpConfig;
 465
 466
 467 /**
 468  * The XUsbPs_DeviceConfig structure contains the configuration information to
 469  * configure the USB controller for DEVICE mode. This data structure is used
 470  * with the XUsbPs_ConfigureDevice() function call.
 471  */
 472 typedef struct {
 473         u8  NumEndpoints;       /**< Number of Endpoints for the controller.
 474                                   This number depends on the runtime
 475                                   configuration of driver. The driver may
 476                                   configure fewer endpoints than are available
 477                                   in the core. */
 478
 479         XUsbPs_EpConfig EpCfg[XUSBPS_MAX_ENDPOINTS];
 480                                 /**< List of endpoint configurations. */
 481
 482
 483         u32 DMAMemPhys;         /**< Physical base address of DMAable memory
 484                                   allocated for the driver. */
 485
 486         /* The following members are used internally by the L0/L1 driver.  They
 487          * MUST NOT be accesses and/or modified in any way by the upper layers.
 488          *
 489          * The reason for having these members is that we generally try to
 490          * avoid allocating memory in the L0/L1 driver as we want to be OS
 491          * independent. In order to avoid allocating memory for this data
 492          * structure wihin L0/L1 we put it into the XUsbPs_DeviceConfig
 493          * structure which is allocated by the caller.
 494          */
 495         XUsbPs_Endpoint Ep[XUSBPS_MAX_ENDPOINTS];
 496                                 /**< List of endpoint metadata structures. */
 497
 498         u32 PhysAligned;        /**< 64 byte aligned base address of the DMA
 499                                    memory block. Will be computed and set by
 500                                    the L0/L1 driver. */
 501 } XUsbPs_DeviceConfig;
 502
 503
 504 /**
 505  * The XUsbPs_Config structure contains configuration information for the USB
 506  * controller.
 507  *
 508  * This structure only contains the basic configuration for the controller. The
 509  * caller also needs to initialize the controller for the DEVICE mode
 510  * using the XUsbPs_DeviceConfig data structures with the
 511  * XUsbPs_ConfigureDevice() function call
 512  */
 513 typedef struct {
 514         u16 DeviceID;           /**< Unique ID of controller. */
 515         u32 BaseAddress;        /**< Core register base address. */
 516 } XUsbPs_Config;
 517
 518
 519 /**
 520  * The XUsbPs driver instance data. The user is required to allocate a
 521  * variable of this type for every USB controller in the system. A pointer to a
 522  * variable of this type is then passed to the driver API functions.
 523  */
 524 typedef struct {
 525         XUsbPs_Config Config;   /**< Configuration structure */
 526
 527         int CurrentAltSetting;  /**< Current alternative setting of interface */
 528
 529         void *UserDataPtr;      /**< Data pointer to be used by upper layers to
 530                                   store application dependent data structures.
 531                                   The upper layers are responsible to allocated
 532                                   and free the memory. The driver will not
 533                                   mofidy this data pointer. */
 534
 535         /**
 536          * The following structures hold the configuration for DEVICE mode
 537          * of the controller. They are initialized using the
 538          * XUsbPs_ConfigureDevice() function call.
 539          */
 540         XUsbPs_DeviceConfig     DeviceConfig;
 541                                 /**< Configuration for the DEVICE mode. */
 542
 543         XUsbPs_IntrHandlerFunc  HandlerFunc;
 544                 /**< Handler function for the controller. */
 545         void                    *HandlerRef;
 546                 /**< User data reference for the handler. */
 547         u32                     HandlerMask;
 548                 /**< User interrupt mask. Defines which interrupts will cause
 549                  * the callback to be called. */
 550 } XUsbPs;
 551
 552
 553 /***************** Macros (Inline Functions) Definitions *********************/
 554
 555 /******************************************************************************
 556  *
 557  * USB CONTROLLER RELATED MACROS
 558  *
 559  ******************************************************************************/
 560 /*****************************************************************************/
 561 /**
 562  * This macro returns the current frame number.
 563  *
 564  * @param       InstancePtr is a pointer to the XUsbPs instance of the
 565  *              controller.
 566  *
 567  * @return      The current frame number.
 568  *
 569  * @note        C-style signature:
 570  *              u32 XUsbPs_GetFrameNum(const XUsbPs *InstancePtr)
 571  *
 572  ******************************************************************************/
 573 #define XUsbPs_GetFrameNum(InstancePtr) \
 574         XUsbPs_ReadReg((InstancePtr)->Config.BaseAddress, XUSBPS_FRAME_OFFSET)
 575
 576
 577 /*****************************************************************************/
 578 /**
 579  * This macro starts the USB engine.
 580  *
 581  * @param       InstancePtr is a pointer to the XUsbPs instance of the
 582  *              controller.
 583  *
 584  * @note        C-style signature:
 585  *              void XUsbPs_Start(XUsbPs *InstancePtr)
 586  *
 587  ******************************************************************************/
 588 #define XUsbPs_Start(InstancePtr) \
 589         XUsbPs_SetBits(InstancePtr, XUSBPS_CMD_OFFSET, XUSBPS_CMD_RS_MASK)
 590
 591
 592 /*****************************************************************************/
 593 /**
 594  * This macro stops the USB engine.
 595  *
 596  * @param       InstancePtr is a pointer to the XUsbPs instance of the
 597  *              controller.
 598  *
 599  * @note        C-style signature:
 600  *              void XUsbPs_Stop(XUsbPs *InstancePtr)
 601  *
 602  ******************************************************************************/
 603 #define XUsbPs_Stop(InstancePtr) \
 604         XUsbPs_ClrBits(InstancePtr, XUSBPS_CMD_OFFSET, XUSBPS_CMD_RS_MASK)
 605
 606
 607 /*****************************************************************************/
 608 /**
 609  * This macro forces the USB engine to be in Full Speed (FS) mode.
 610  *
 611  * @param       InstancePtr is a pointer to the XUsbPs instance of the
 612  *              controller.
 613  *
 614  * @note        C-style signature:
 615  *              void XUsbPs_ForceFS(XUsbPs *InstancePtr)
 616  *
 617  ******************************************************************************/
 618 #define XUsbPs_ForceFS(InstancePtr)                                     \
 619         XUsbPs_SetBits(InstancePtr, XUSBPS_PORTSCR1_OFFSET,             \
 620                 XUSBPS_PORTSCR_PFSC_MASK)
 621
 622
 623 /*****************************************************************************/
 624 /**
 625  * This macro starts the USB Timer 0, with repeat option for period of
 626  * one second.
 627  *
 628  * @param       InstancePtr is a pointer to XUsbPs instance of the controller.
 629  * @param       Interval is the interval for Timer0 to generate an interrupt
 630  *
 631  * @note        C-style signature:
 632  *              void XUsbPs_StartTimer0(XUsbPs *InstancePtr, u32 Interval)
 633  *
 634  ******************************************************************************/
 635 #define XUsbPs_StartTimer0(InstancePtr, Interval)                       \
 636 {                                                                       \
 637         XUsbPs_WriteReg((InstancePtr)->Config.BaseAddress,              \
 638                         XUSBPS_TIMER0_LD_OFFSET, (Interval));           \
 639         XUsbPs_SetBits(InstancePtr, XUSBPS_TIMER0_CTL_OFFSET,           \
 640                         XUSBPS_TIMER_RUN_MASK |                 \
 641                         XUSBPS_TIMER_RESET_MASK |                       \
 642                         XUSBPS_TIMER_REPEAT_MASK);                      \
 643 }                                                                       \
 644
 645
 646 /*****************************************************************************/
 647 /**
 648 * This macro stops Timer 0.
 649 *
 650 * @param        InstancePtr is a pointer to XUsbPs instance of the controller.
 651 *
 652 * @note         C-style signature:
 653 *               void XUsbPs_StopTimer0(XUsbPs *InstancePtr)
 654 *
 655 ******************************************************************************/
 656 #define XUsbPs_StopTimer0(InstancePtr) \
 657         XUsbPs_ClrBits(InstancePtr, XUSBPS_TIMER0_CTL_OFFSET,           \
 658                 XUSBPS_TIMER_RUN_MASK)
 659
 660
 661 /*****************************************************************************/
 662 /**
 663 * This macro reads Timer 0.
 664 *
 665 * @param        InstancePtr is a pointer to XUsbPs instance of the controller.
 666 *
 667 * @note         C-style signature:
 668 *               void XUsbPs_ReadTimer0(XUsbPs *InstancePtr)
 669 *
 670 ******************************************************************************/
 671 #define XUsbPs_ReadTimer0(InstancePtr)                          \
 672         XUsbPs_ReadReg((InstancePtr)->Config.BaseAddress,               \
 673                         XUSBPS_TIMER0_CTL_OFFSET) &                     \
 674                                         XUSBPS_TIMER_COUNTER_MASK
 675
 676
 677 /*****************************************************************************/
 678 /**
 679 * This macro force remote wakeup on host
 680 *
 681 * @param        InstancePtr is a pointer to XUsbPs instance of the controller.
 682 *
 683 * @note         C-style signature:
 684 *               void XUsbPs_RemoteWakeup(XUsbPs *InstancePtr)
 685 *
 686 ******************************************************************************/
 687 #define XUsbPs_RemoteWakeup(InstancePtr) \
 688         XUsbPs_SetBits(InstancePtr, XUSBPS_PORTSCR1_OFFSET,              \
 689                         XUSBPS_PORTSCR_FPR_MASK)
 690
 691
 692 /******************************************************************************
 693  *
 694  * ENDPOINT RELATED MACROS
 695  *
 696  ******************************************************************************/
 697 /*****************************************************************************/
 698 /**
 699 * This macro enables the given endpoint for the given direction.
 700 *
 701 * @param        InstancePtr is a pointer to the XUsbPs instance of the
 702 *               controller.
 703 * @param        EpNum is number of the endpoint to enable.
 704 * @param        Dir is direction of the endpoint (bitfield):
 705 *                       - XUSBPS_EP_DIRECTION_OUT
 706 *                       - XUSBPS_EP_DIRECTION_IN
 707 *
 708 * @note         C-style signature:
 709 *               void XUsbPs_EpEnable(XUsbPs *InstancePtr, u8 EpNum, u8 Dir)
 710 *
 711 ******************************************************************************/
 712 #define XUsbPs_EpEnable(InstancePtr, EpNum, Dir) \
 713         XUsbPs_SetBits(InstancePtr, XUSBPS_EPCRn_OFFSET(EpNum),  \
 714         ((Dir) & XUSBPS_EP_DIRECTION_OUT ? XUSBPS_EPCR_RXE_MASK : 0) | \
 715         ((Dir) & XUSBPS_EP_DIRECTION_IN  ? XUSBPS_EPCR_TXE_MASK : 0))
 716
 717
 718 /*****************************************************************************/
 719 /**
 720 * This macro disables the given endpoint for the given direction.
 721 *
 722 * @param        InstancePtr is a pointer to the XUsbPs instance of the
 723 *               controller.
 724 * @param        EpNum is the number of the endpoint to disable.
 725 * @param        Dir is the direction of the endpoint (bitfield):
 726 *               - XUSBPS_EP_DIRECTION_OUT
 727 *               - XUSBPS_EP_DIRECTION_IN
 728 *
 729 * @note         C-style signature:
 730 *               void XUsbPs_EpDisable(XUsbPs *InstancePtr, u8 EpNum, u8 Dir)
 731 *
 732 ******************************************************************************/
 733 #define XUsbPs_EpDisable(InstancePtr, EpNum, Dir) \
 734         XUsbPs_ClrBits(InstancePtr, XUSBPS_EPCRn_OFFSET(EpNum),          \
 735                 ((Dir) & XUSBPS_EP_DIRECTION_OUT ? XUSBPS_EPCR_RXE_MASK : 0) | \
 736                 ((Dir) & XUSBPS_EP_DIRECTION_IN  ? XUSBPS_EPCR_TXE_MASK : 0))
 737
 738
 739 /*****************************************************************************/
 740 /**
 741 * This macro stalls the given endpoint for the given direction, and flush
 742 * the buffers.
 743 *
 744 * @param        InstancePtr is a pointer to the XUsbPs instance of the
 745 *               controller.
 746 * @param        EpNum is number of the endpoint to stall.
 747 * @param        Dir is the direction of the endpoint (bitfield):
 748 *                       - XUSBPS_EP_DIRECTION_OUT
 749 *                       - XUSBPS_EP_DIRECTION_IN
 750 *
 751 * @note         C-style signature:
 752 *               void XUsbPs_EpStall(XUsbPs *InstancePtr, u8 EpNum, u8 Dir)
 753 *
 754 ******************************************************************************/
 755 #define XUsbPs_EpStall(InstancePtr, EpNum, Dir) \
 756         XUsbPs_SetBits(InstancePtr, XUSBPS_EPCRn_OFFSET(EpNum),  \
 757         ((Dir) & XUSBPS_EP_DIRECTION_OUT ? XUSBPS_EPCR_RXS_MASK : 0) | \
 758         ((Dir) & XUSBPS_EP_DIRECTION_IN  ? XUSBPS_EPCR_TXS_MASK : 0))
 759
 760
 761 /*****************************************************************************/
 762 /**
 763 * This macro unstalls the given endpoint for the given direction.
 764 *
 765 * @param        InstancePtr is a pointer to the XUsbPs instance of the
 766 *               controller.
 767 * @param        EpNum is the Number of the endpoint to unstall.
 768 * @param        Dir is the Direction of the endpoint (bitfield):
 769 *               - XUSBPS_EP_DIRECTION_OUT
 770 *               - XUSBPS_EP_DIRECTION_IN
 771 *
 772 * @note         C-style signature:
 773 *               void XUsbPs_EpUnStall(XUsbPs *InstancePtr, u8 EpNum, u8 Dir)
 774 *
 775 ******************************************************************************/
 776 #define XUsbPs_EpUnStall(InstancePtr, EpNum, Dir) \
 777         XUsbPs_ClrBits(InstancePtr, XUSBPS_EPCRn_OFFSET(EpNum),  \
 778         ((Dir) & XUSBPS_EP_DIRECTION_OUT ? XUSBPS_EPCR_RXS_MASK : 0) | \
 779         ((Dir) & XUSBPS_EP_DIRECTION_IN  ? XUSBPS_EPCR_TXS_MASK : 0))
 780
 781
 782 /*****************************************************************************/
 783 /**
 784 * This macro flush an endpoint upon interface disable
 785 *
 786 * @param        InstancePtr is a pointer to the XUsbPs instance of the
 787 *               controller.
 788 * @param        EpNum is the number of the endpoint to flush.
 789 * @param        Dir is the direction of the endpoint (bitfield):
 790 *                       - XUSBPS_EP_DIRECTION_OUT
 791 *                       - XUSBPS_EP_DIRECTION_IN
 792 *
 793 * @note         C-style signature:
 794 *               void XUsbPs_EpFlush(XUsbPs *InstancePtr, u8 EpNum, u8 Dir)
 795 *
 796 ******************************************************************************/
 797 #define XUsbPs_EpFlush(InstancePtr, EpNum, Dir) \
 798         XUsbPs_SetBits(InstancePtr, XUSBPS_EPFLUSH_OFFSET,      \
 799                 EpNum << ((Dir) & XUSBPS_EP_DIRECTION_OUT ?             \
 800                         XUSBPS_EPFLUSH_RX_SHIFT:XUSBPS_EPFLUSH_TX_SHIFT)) \
 801
 802 /*****************************************************************************/
 803 /**
 804 * This macro enables the interrupts defined by the bit mask.
 805 *
 806 * @param        InstancePtr is a pointer to XUsbPs instance of the controller.
 807 * @param        IntrMask is the Bit mask of interrupts to be enabled.
 808 *
 809 * @note         C-style signature:
 810 *               void XUsbPs_IntrEnable(XUsbPs *InstancePtr, u32 IntrMask)
 811 *
 812 ******************************************************************************/
 813 #define XUsbPs_IntrEnable(InstancePtr, IntrMask)        \
 814                 XUsbPs_SetBits(InstancePtr, XUSBPS_IER_OFFSET, IntrMask)
 815
 816
 817 /*****************************************************************************/
 818 /**
 819 * This function disables the interrupts defined by the bit mask.
 820 *
 821 *
 822 * @param        InstancePtr is a pointer to XUsbPs instance of the controller.
 823 * @param        IntrMask is a Bit mask of interrupts to be disabled.
 824 *
 825 * @note         C-style signature:
 826 *               void XUsbPs_IntrDisable(XUsbPs *InstancePtr, u32 IntrMask)
 827 *
 828 ******************************************************************************/
 829 #define XUsbPs_IntrDisable(InstancePtr, IntrMask)       \
 830                 XUsbPs_ClrBits(InstancePtr, XUSBPS_IER_OFFSET, IntrMask)
 831
 832
 833 /*****************************************************************************/
 834 /**
 835 * This macro enables the endpoint NAK interrupts defined by the bit mask.
 836 *
 837 * @param        InstancePtr is a pointer to XUsbPs instance of the controller.
 838 * @param        NakIntrMask is the Bit mask of endpoint NAK interrupts to be
 839 *               enabled.
 840 * @note         C-style signature:
 841 *               void XUsbPs_NakIntrEnable(XUsbPs *InstancePtr, u32 NakIntrMask)
 842 *
 843 ******************************************************************************/
 844 #define XUsbPs_NakIntrEnable(InstancePtr, NakIntrMask)  \
 845         XUsbPs_SetBits(InstancePtr, XUSBPS_EPNAKIER_OFFSET, NakIntrMask)
 846
 847
 848 /*****************************************************************************/
 849 /**
 850 * This macro disables the endpoint NAK interrupts defined by the bit mask.
 851 *
 852 * @param        InstancePtr is a pointer to XUsbPs instance of the controller.
 853 * @param        NakIntrMask is a Bit mask of endpoint NAK interrupts to be
 854 *               disabled.
 855 *
 856 * @note
 857 *       C-style signature:
 858 *       void XUsbPs_NakIntrDisable(XUsbPs *InstancePtr, u32 NakIntrMask)
 859 *
 860 ******************************************************************************/
 861 #define XUsbPs_NakIntrDisable(InstancePtr, NakIntrMask) \
 862         XUsbPs_ClrBits(InstancePtr, XUSBPS_EPNAKIER_OFFSET, NakIntrMask)
 863
 864
 865 /*****************************************************************************/
 866 /**
 867 * This function clears the endpoint NAK interrupts status defined by the
 868 * bit mask.
 869 *
 870 * @param        InstancePtr is a pointer to XUsbPs instance of the controller.
 871 * @param        NakIntrMask is the Bit mask of endpoint NAK interrupts to be cleared.
 872 *
 873 * @note         C-style signature:
 874 *               void XUsbPs_NakIntrClear(XUsbPs *InstancePtr, u32 NakIntrMask)
 875 *
 876 ******************************************************************************/
 877 #define XUsbPs_NakIntrClear(InstancePtr, NakIntrMask)                   \
 878         XUsbPs_WriteReg((InstancePtr)->Config.BaseAddress,              \
 879                                 XUSBPS_EPNAKISR_OFFSET, NakIntrMask)
 880
 881
 882
 883 /*****************************************************************************/
 884 /**
 885 * This macro sets the Interrupt Threshold value in the control register
 886 *
 887 * @param        InstancePtr is a pointer to XUsbPs instance of the controller.
 888 * @param        Threshold is the Interrupt threshold to be set.
 889 *               Allowed values:
 890 *                       - XUSBPS_CMD_ITHRESHOLD_0 - Immediate interrupt
 891 *                       - XUSBPS_CMD_ITHRESHOLD_1 - 1 Frame
 892 *                       - XUSBPS_CMD_ITHRESHOLD_2 - 2 Frames
 893 *                       - XUSBPS_CMD_ITHRESHOLD_4 - 4 Frames
 894 *                       - XUSBPS_CMD_ITHRESHOLD_8 - 8 Frames
 895 *                       - XUSBPS_CMD_ITHRESHOLD_16 - 16 Frames
 896 *                       - XUSBPS_CMD_ITHRESHOLD_32 - 32 Frames
 897 *                       - XUSBPS_CMD_ITHRESHOLD_64 - 64 Frames
 898 *
 899 * @note
 900 *       C-style signature:
 901 *       void XUsbPs_SetIntrThreshold(XUsbPs *InstancePtr, u8 Threshold)
 902 *
 903 ******************************************************************************/
 904 #define XUsbPs_SetIntrThreshold(InstancePtr, Threshold)         \
 905                 XUsbPs_WriteReg((InstancePtr)->Config.BaseAddress,      \
 906                                         XUSBPS_CMD_OFFSET, (Threshold))\
 907
 908
 909 /*****************************************************************************/
 910 /**
 911 * This macro sets the Tripwire bit in the USB command register.
 912 *
 913 * @param        InstancePtr is a pointer to XUsbPs instance of the controller.
 914 *
 915 * @note         C-style signature:
 916 *               void XUsbPs_SetTripwire(XUsbPs *InstancePtr)
 917 *
 918 ******************************************************************************/
 919 #define XUsbPs_SetSetupTripwire(InstancePtr)                            \
 920                 XUsbPs_SetBits(InstancePtr, XUSBPS_CMD_OFFSET,  \
 921                                 XUSBPS_CMD_SUTW_MASK)
 922
 923
 924 /*****************************************************************************/
 925 /**
 926 * This macro clears the Tripwire bit in the USB command register.
 927 *
 928 * @param        InstancePtr is a pointer to XUsbPs instance of the controller.
 929 *
 930 * @note         C-style signature:
 931 *               void XUsbPs_ClrTripwire(XUsbPs *InstancePtr)
 932 *
 933 ******************************************************************************/
 934 #define XUsbPs_ClrSetupTripwire(InstancePtr)                            \
 935                 XUsbPs_ClrBits(InstancePtr, XUSBPS_CMD_OFFSET,  \
 936                                 XUSBPS_CMD_SUTW_MASK)
 937
 938
 939 /*****************************************************************************/
 940 /**
 941 * This macro checks if the Tripwire bit in the USB command register is set.
 942 *
 943 * @param        InstancePtr is a pointer to XUsbPs instance of the controller.
 944 *
 945 * @return
 946 *               - TRUE: The tripwire bit is still set.
 947 *               - FALSE: The tripwire bit has been cleared.
 948 *
 949 * @note         C-style signature:
 950 *               int XUsbPs_TripwireIsSet(XUsbPs *InstancePtr)
 951 *
 952 ******************************************************************************/
 953 #define XUsbPs_SetupTripwireIsSet(InstancePtr)                          \
 954                 (XUsbPs_ReadReg((InstancePtr)->Config.BaseAddress,      \
 955                                 XUSBPS_CMD_OFFSET) &                    \
 956                                 XUSBPS_CMD_SUTW_MASK ? TRUE : FALSE)
 957
 958
 959 /******************************************************************************
 960 *
 961 * GENERAL REGISTER / BIT MANIPULATION MACROS
 962 *
 963 ******************************************************************************/
 964 /****************************************************************************/
 965 /**
 966 * This macro sets the given bit mask in the register.
 967 *
 968 * @param        InstancePtr is a pointer to XUsbPs instance of the controller.
 969 * @param        RegOffset is the register offset to be written.
 970 * @param        Bits is the Bits to be set in the register
 971 *
 972 * @return       None.
 973 *
 974 * @note         C-style signature:
 975 *               void XUsbPs_SetBits(u32 BaseAddress, u32 RegOffset, u32 Bits)
 976 *
 977 *****************************************************************************/
 978 #define XUsbPs_SetBits(InstancePtr, RegOffset, Bits) \
 979         XUsbPs_WriteReg((InstancePtr)->Config.BaseAddress, RegOffset,   \
 980                 XUsbPs_ReadReg((InstancePtr)->Config.BaseAddress,       \
 981                                         RegOffset) | (Bits));
 982
 983
 984 /****************************************************************************/
 985 /**
 986 *
 987 * This macro clears the given bits in the register.
 988 *
 989 * @param        InstancePtr is a pointer to XUsbPs instance of the controller.
 990 * @param        RegOffset is the register offset to be written.
 991 * @param        Bits are the bits to be cleared in the register
 992 *
 993 * @return       None.
 994 *
 995 * @note
 996 *       C-style signature:
 997 *       void XUsbPs_ClrBits(u32 BaseAddress, u32 RegOffset, u32 Bits)
 998 *
 999 *****************************************************************************/
1000 #define XUsbPs_ClrBits(InstancePtr, RegOffset, Bits) \
1001         XUsbPs_WriteReg((InstancePtr)->Config.BaseAddress, RegOffset,   \
1002                 XUsbPs_ReadReg((InstancePtr)->Config.BaseAddress,       \
1003                                 RegOffset) & ~(Bits));
1004
1005
1006 /************************** Function Prototypes ******************************/
1007
1008 /**
1009  * Setup / Initialize functions.
1010  *
1011  * Implemented in file xusbps.c
1012  */
1013 int XUsbPs_CfgInitialize(XUsbPs *InstancePtr,
1014                           const XUsbPs_Config *ConfigPtr, u32 BaseAddress);
1015
1016 int XUsbPs_ConfigureDevice(XUsbPs *InstancePtr,
1017                                 const XUsbPs_DeviceConfig *CfgPtr);
1018
1019 /**
1020  * Common functions used for DEVICE/HOST mode.
1021  */
1022 int XUsbPs_Reset(XUsbPs *InstancePtr);
1023
1024 /**
1025  * DEVICE mode specific functions.
1026  */
1027 int XUsbPs_BusReset(XUsbPs *InstancePtr);
1028 int XUsbPs_SetDeviceAddress(XUsbPs *InstancePtr, u8 Address);
1029
1030
1031 /**
1032  * Handling Suspend and Resume.
1033  *
1034  * Implemented in xusbps.c
1035  */
1036 int XUsbPs_Suspend(const XUsbPs *InstancePtr);
1037 int XUsbPs_Resume(const XUsbPs *InstancePtr);
1038 int XUsbPs_RequestHostResume(const XUsbPs *InstancePtr);
1039
1040
1041 /*
1042  * Functions for managing Endpoints / Transfers
1043  *
1044  * Implemented in file xusbps_endpoint.c
1045  */
1046 int XUsbPs_EpBufferSend(XUsbPs *InstancePtr, u8 EpNum,
1047                         const u8 *BufferPtr, u32 BufferLen);
1048 int XUsbPs_EpBufferSendWithZLT(XUsbPs *InstancePtr, u8 EpNum,
1049                         const u8 *BufferPtr, u32 BufferLen);
1050 int XUsbPs_EpBufferReceive(XUsbPs *InstancePtr, u8 EpNum,
1051                         u8 **BufferPtr, u32 *BufferLenPtr, u32 *Handle);
1052 void XUsbPs_EpBufferRelease(u32 Handle);
1053
1054 int XUsbPs_EpSetHandler(XUsbPs *InstancePtr, u8 EpNum, u8 Direction,
1055                         XUsbPs_EpHandlerFunc CallBackFunc,
1056                         void *CallBackRef);
1057 int XUsbPs_EpGetSetupData(XUsbPs *InstancePtr, int EpNum,
1058                         XUsbPs_SetupData *SetupDataPtr);
1059
1060 int XUsbPs_EpPrime(XUsbPs *InstancePtr, u8 EpNum, u8 Direction);
1061
1062 int XUsbPs_ReconfigureEp(XUsbPs *InstancePtr, XUsbPs_DeviceConfig *CfgPtr,
1063                         int EpNum, unsigned short NewDirection, int DirectionChanged);
1064
1065 /*
1066  * Interrupt handling functions
1067  *
1068  * Implemented in file xusbps_intr.c
1069  */
1070 void XUsbPs_IntrHandler(void *InstancePtr);
1071
1072 int XUsbPs_IntrSetHandler(XUsbPs *InstancePtr,
1073                            XUsbPs_IntrHandlerFunc CallBackFunc,
1074                            void *CallBackRef, u32 Mask);
1075 /*
1076  * Helper functions for static configuration.
1077  * Implemented in xusbps_sinit.c
1078  */
1079 XUsbPs_Config *XUsbPs_LookupConfig(u16 DeviceId);
1080
1081 #ifdef __cplusplus
1082 }
1083 #endif
1084
1085 #endif /* XUSBPS_H */
1086 /** @} */