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

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