sys/contrib/octeon-sdk/cvmx-usb.h

   1 /***********************license start***************
   2  *  Copyright (c) 2003-2008 Cavium Networks (support@cavium.com). All rights
   3  *  reserved.
   4  *
   5  *
   6  *  Redistribution and use in source and binary forms, with or without
   7  *  modification, are permitted provided that the following conditions are
   8  *  met:
   9  *
  10  *      * Redistributions of source code must retain the above copyright
  11  *        notice, this list of conditions and the following disclaimer.
  12  *
  13  *      * Redistributions in binary form must reproduce the above
  14  *        copyright notice, this list of conditions and the following
  15  *        disclaimer in the documentation and/or other materials provided
  16  *        with the distribution.
  17  *
  18  *      * Neither the name of Cavium Networks nor the names of
  19  *        its contributors may be used to endorse or promote products
  20  *        derived from this software without specific prior written
  21  *        permission.
  22  *
  23  *  TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS"
  24  *  AND WITH ALL FAULTS AND CAVIUM NETWORKS MAKES NO PROMISES, REPRESENTATIONS
  25  *  OR WARRANTIES, EITHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, WITH
  26  *  RESPECT TO THE SOFTWARE, INCLUDING ITS CONDITION, ITS CONFORMITY TO ANY
  27  *  REPRESENTATION OR DESCRIPTION, OR THE EXISTENCE OF ANY LATENT OR PATENT
  28  *  DEFECTS, AND CAVIUM SPECIFICALLY DISCLAIMS ALL IMPLIED (IF ANY) WARRANTIES
  29  *  OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR A PARTICULAR
  30  *  PURPOSE, LACK OF VIRUSES, ACCURACY OR COMPLETENESS, QUIET ENJOYMENT, QUIET
  31  *  POSSESSION OR CORRESPONDENCE TO DESCRIPTION.  THE ENTIRE RISK ARISING OUT
  32  *  OF USE OR PERFORMANCE OF THE SOFTWARE LIES WITH YOU.
  33  *
  34  *
  35  *  For any questions regarding licensing please contact marketing@caviumnetworks.com
  36  *
  37  ***********************license end**************************************/
  38
  39 /**
  40  * @file
  41  *
  42  * "cvmx-usb.h" defines a set of low level USB functions to help
  43  * developers create Octeon USB drivers for various operating
  44  * systems. These functions provide a generic API to the Octeon
  45  * USB blocks, hiding the internal hardware specific
  46  * operations.
  47  *
  48  * At a high level the device driver needs to:
  49  *
  50  * -# Call cvmx_usb_get_num_ports() to get the number of
  51  *  supported ports.
  52  * -# Call cvmx_usb_initialize() for each Octeon USB port.
  53  * -# Enable the port using cvmx_usb_enable().
  54  * -# Either periodically, or in an interrupt handler, call
  55  *  cvmx_usb_poll() to service USB events.
  56  * -# Manage pipes using cvmx_usb_open_pipe() and
  57  *  cvmx_usb_close_pipe().
  58  * -# Manage transfers using cvmx_usb_submit_*() and
  59  *  cvmx_usb_cancel*().
  60  * -# Shutdown USB on unload using cvmx_usb_shutdown().
  61  *
  62  * To monitor USB status changes, the device driver must use
  63  * cvmx_usb_register_callback() to register for events that it
  64  * is interested in. Below are a few hints on successfully
  65  * implementing a driver on top of this API.
  66  *
  67  * <h2>Initialization</h2>
  68  *
  69  * When a driver is first loaded, it is normally not necessary
  70  * to bring up the USB port completely. Most operating systems
  71  * expect to initialize and enable the port in two independent
  72  * steps. Normally an operating system will probe hardware,
  73  * initialize anything found, and then enable the hardware.
  74  *
  75  * In the probe phase you should:
  76  * -# Use cvmx_usb_get_num_ports() to determine the number of
  77  *  USB port to be supported.
  78  * -# Allocate space for a cvmx_usb_state_t structure for each
  79  *  port.
  80  * -# Tell the operating system about each port
  81  *
  82  * In the initialization phase you should:
  83  * -# Use cvmx_usb_initialize() on each port.
  84  * -# Do not call cvmx_usb_enable(). This leaves the USB port in
  85  *  the disabled state until the operating system is ready.
  86  *
  87  * Finally, in the enable phase you should:
  88  * -# Call cvmx_usb_enable() on the appropriate port.
  89  * -# Note that some operating system use a RESET instead of an
  90  *  enable call. To implement RESET, you should call
  91  *  cvmx_usb_disable() followed by cvmx_usb_enable().
  92  *
  93  * <h2>Locking</h2>
  94  *
  95  * All of the functions in the cvmx-usb API assume exclusive
  96  * access to the USB hardware and internal data structures. This
  97  * means that the driver must provide locking as necessary.
  98  *
  99  * In the single CPU state it is normally enough to disable
 100  * interrupts before every call to cvmx_usb*() and enable them
 101  * again after the call is complete. Keep in mind that it is
 102  * very common for the callback handlers to make additional
 103  * calls into cvmx-usb, so the disable/enable must be protected
 104  * against recursion. As an example, the Linux kernel
 105  * local_irq_save() and local_irq_restore() are perfect for this
 106  * in the non SMP case.
 107  *
 108  * In the SMP case, locking is more complicated. For SMP you not
 109  * only need to disable interrupts on the local core, but also
 110  * take a lock to make sure that another core cannot call
 111  * cvmx-usb.
 112  *
 113  * <h2>Port callback</h2>
 114  *
 115  * The port callback prototype needs to look as follows:
 116  *
 117  * void port_callback(cvmx_usb_state_t *usb,
 118  *                    cvmx_usb_callback_t reason,
 119  *                    cvmx_usb_complete_t status,
 120  *                    int pipe_handle,
 121  *                    int submit_handle,
 122  *                    int bytes_transferred,
 123  *                    void *user_data);
 124  * - @b usb is the cvmx_usb_state_t for the port.
 125  * - @b reason will always be
 126  *   CVMX_USB_CALLBACK_PORT_CHANGED.
 127  * - @b status will always be CVMX_USB_COMPLETE_SUCCESS.
 128  * - @b pipe_handle will always be -1.
 129  * - @b submit_handle will always be -1.
 130  * - @b bytes_transferred will always be 0.
 131  * - @b user_data is the void pointer originally passed along
 132  *   with the callback. Use this for any state information you
 133  *   need.
 134  *
 135  * The port callback will be called whenever the user plugs /
 136  * unplugs a device from the port. It will not be called when a
 137  * device is plugged / unplugged from a hub connected to the
 138  * root port. Normally all the callback needs to do is tell the
 139  * operating system to poll the root hub for status. Under
 140  * Linux, this is performed by calling usb_hcd_poll_rh_status().
 141  * In the Linux driver we use @b user_data. to pass around the
 142  * Linux "hcd" structure. Once the port callback completes,
 143  * Linux automatically calls octeon_usb_hub_status_data() which
 144  * uses cvmx_usb_get_status() to determine the root port status.
 145  *
 146  * <h2>Complete callback</h2>
 147  *
 148  * The completion callback prototype needs to look as follows:
 149  *
 150  * void complete_callback(cvmx_usb_state_t *usb,
 151  *                        cvmx_usb_callback_t reason,
 152  *                        cvmx_usb_complete_t status,
 153  *                        int pipe_handle,
 154  *                        int submit_handle,
 155  *                        int bytes_transferred,
 156  *                        void *user_data);
 157  * - @b usb is the cvmx_usb_state_t for the port.
 158  * - @b reason will always be
 159  *   CVMX_USB_CALLBACK_TRANSFER_COMPLETE.
 160  * - @b status will be one of the cvmx_usb_complete_t
 161  *   enumerations.
 162  * - @b pipe_handle is the handle to the pipe the transaction
 163  *   was originally submitted on.
 164  * - @b submit_handle is the handle returned by the original
 165  *   cvmx_usb_submit_* call.
 166  * - @b bytes_transferred is the number of bytes successfully
 167  *   transferred in the transaction. This will be zero on most
 168  *   error conditions.
 169  * - @b user_data is the void pointer originally passed along
 170  *   with the callback. Use this for any state information you
 171  *   need. For example, the Linux "urb" is stored in here in the
 172  *   Linux driver.
 173  *
 174  * In general your callback handler should use @b status and @b
 175  * bytes_transferred to tell the operating system the how the
 176  * transaction completed. Normally the pipe is not changed in
 177  * this callback.
 178  *
 179  * <h2>Canceling transactions</h2>
 180  *
 181  * When a transaction is cancelled using cvmx_usb_cancel*(), the
 182  * actual length of time until the complete callback is called
 183  * can vary greatly. It may be called before cvmx_usb_cancel*()
 184  * returns, or it may be called a number of usb frames in the
 185  * future once the hardware frees the transaction. In either of
 186  * these cases, the complete handler will receive
 187  * CVMX_USB_COMPLETE_CANCEL.
 188  *
 189  * <h2>Handling pipes</h2>
 190  *
 191  * USB "pipes" is a software construct created by this API to
 192  * enable the ordering of usb transactions to a device endpoint.
 193  * Octeon's underlying hardware doesn't have any concept
 194  * equivalent to "pipes". The hardware instead has eight
 195  * channels that can be used simultaneously to have up to eight
 196  * transaction in process at the same time. In order to maintain
 197  * ordering in a pipe, the transactions for a pipe will only be
 198  * active in one hardware channel at a time. From an API user's
 199  * perspective, this doesn't matter but it can be helpful to
 200  * keep this in mind when you are probing hardware while
 201  * debugging.
 202  *
 203  * Also keep in mind that usb transactions contain state
 204  * information about the previous transaction to the same
 205  * endpoint. Each transaction has a PID toggle that changes 0/1
 206  * between each sub packet. This is maintained in the pipe data
 207  * structures. For this reason, you generally cannot create and
 208  * destroy a pipe for every transaction. A sequence of
 209  * transaction to the same endpoint must use the same pipe.
 210  *
 211  * <h2>Root Hub</h2>
 212  *
 213  * Some operating systems view the usb root port as a normal usb
 214  * hub. These systems attempt to control the root hub with
 215  * messages similar to the usb 2.0 spec for hub control and
 216  * status. For these systems it may be necessary to write
 217  * function to decode standard usb control messages into
 218  * equivalent cvmx-usb API calls. As an example, the following
 219  * code is used under Linux for some of the basic hub control
 220  * messages.
 221  *
 222  * @code
 223  * static int octeon_usb_hub_control(struct usb_hcd *hcd, u16 typeReq, u16 wValue, u16 wIndex, char *buf, u16 wLength)
 224  * {
 225  *     cvmx_usb_state_t *usb = (cvmx_usb_state_t *)hcd->hcd_priv;
 226  *     cvmx_usb_port_status_t usb_port_status;
 227  *     int port_status;
 228  *     struct usb_hub_descriptor *desc;
 229  *     unsigned long flags;
 230  *
 231  *     switch (typeReq)
 232  *     {
 233  *         case ClearHubFeature:
 234  *             DEBUG_ROOT_HUB("OcteonUSB: ClearHubFeature\n");
 235  *             switch (wValue)
 236  *             {
 237  *                 case C_HUB_LOCAL_POWER:
 238  *                 case C_HUB_OVER_CURRENT:
 239  *                     // Nothing required here
 240  *                     break;
 241  *                 default:
 242  *                     return -EINVAL;
 243  *             }
 244  *             break;
 245  *         case ClearPortFeature:
 246  *             DEBUG_ROOT_HUB("OcteonUSB: ClearPortFeature");
 247  *             if (wIndex != 1)
 248  *             {
 249  *                 DEBUG_ROOT_HUB(" INVALID\n");
 250  *                 return -EINVAL;
 251  *             }
 252  *
 253  *             switch (wValue)
 254  *             {
 255  *                 case USB_PORT_FEAT_ENABLE:
 256  *                     DEBUG_ROOT_HUB(" ENABLE");
 257  *                     local_irq_save(flags);
 258  *                     cvmx_usb_disable(usb);
 259  *                     local_irq_restore(flags);
 260  *                     break;
 261  *                 case USB_PORT_FEAT_SUSPEND:
 262  *                     DEBUG_ROOT_HUB(" SUSPEND");
 263  *                     // Not supported on Octeon
 264  *                     break;
 265  *                 case USB_PORT_FEAT_POWER:
 266  *                     DEBUG_ROOT_HUB(" POWER");
 267  *                     // Not supported on Octeon
 268  *                     break;
 269  *                 case USB_PORT_FEAT_INDICATOR:
 270  *                     DEBUG_ROOT_HUB(" INDICATOR");
 271  *                     // Port inidicator not supported
 272  *                     break;
 273  *                 case USB_PORT_FEAT_C_CONNECTION:
 274  *                     DEBUG_ROOT_HUB(" C_CONNECTION");
 275  *                     // Clears drivers internal connect status change flag
 276  *                     cvmx_usb_set_status(usb, cvmx_usb_get_status(usb));
 277  *                     break;
 278  *                 case USB_PORT_FEAT_C_RESET:
 279  *                     DEBUG_ROOT_HUB(" C_RESET");
 280  *                     // Clears the driver's internal Port Reset Change flag
 281  *                     cvmx_usb_set_status(usb, cvmx_usb_get_status(usb));
 282  *                     break;
 283  *                 case USB_PORT_FEAT_C_ENABLE:
 284  *                     DEBUG_ROOT_HUB(" C_ENABLE");
 285  *                     // Clears the driver's internal Port Enable/Disable Change flag
 286  *                     cvmx_usb_set_status(usb, cvmx_usb_get_status(usb));
 287  *                     break;
 288  *                 case USB_PORT_FEAT_C_SUSPEND:
 289  *                     DEBUG_ROOT_HUB(" C_SUSPEND");
 290  *                     // Clears the driver's internal Port Suspend Change flag,
 291  *                         which is set when resume signaling on the host port is
 292  *                         complete
 293  *                     break;
 294  *                 case USB_PORT_FEAT_C_OVER_CURRENT:
 295  *                     DEBUG_ROOT_HUB(" C_OVER_CURRENT");
 296  *                     // Clears the driver's overcurrent Change flag
 297  *                     cvmx_usb_set_status(usb, cvmx_usb_get_status(usb));
 298  *                     break;
 299  *                 default:
 300  *                     DEBUG_ROOT_HUB(" UNKNOWN\n");
 301  *                     return -EINVAL;
 302  *             }
 303  *             DEBUG_ROOT_HUB("\n");
 304  *             break;
 305  *         case GetHubDescriptor:
 306  *             DEBUG_ROOT_HUB("OcteonUSB: GetHubDescriptor\n");
 307  *             desc = (struct usb_hub_descriptor *)buf;
 308  *             desc->bDescLength = 9;
 309  *             desc->bDescriptorType = 0x29;
 310  *             desc->bNbrPorts = 1;
 311  *             desc->wHubCharacteristics = 0x08;
 312  *             desc->bPwrOn2PwrGood = 1;
 313  *             desc->bHubContrCurrent = 0;
 314  *             desc->bitmap[0] = 0;
 315  *             desc->bitmap[1] = 0xff;
 316  *             break;
 317  *         case GetHubStatus:
 318  *             DEBUG_ROOT_HUB("OcteonUSB: GetHubStatus\n");
 319  *             *(__le32 *)buf = 0;
 320  *             break;
 321  *         case GetPortStatus:
 322  *             DEBUG_ROOT_HUB("OcteonUSB: GetPortStatus");
 323  *             if (wIndex != 1)
 324  *             {
 325  *                 DEBUG_ROOT_HUB(" INVALID\n");
 326  *                 return -EINVAL;
 327  *             }
 328  *
 329  *             usb_port_status = cvmx_usb_get_status(usb);
 330  *             port_status = 0;
 331  *
 332  *             if (usb_port_status.connect_change)
 333  *             {
 334  *                 port_status |= (1 << USB_PORT_FEAT_C_CONNECTION);
 335  *                 DEBUG_ROOT_HUB(" C_CONNECTION");
 336  *             }
 337  *
 338  *             if (usb_port_status.port_enabled)
 339  *             {
 340  *                 port_status |= (1 << USB_PORT_FEAT_C_ENABLE);
 341  *                 DEBUG_ROOT_HUB(" C_ENABLE");
 342  *             }
 343  *
 344  *             if (usb_port_status.connected)
 345  *             {
 346  *                 port_status |= (1 << USB_PORT_FEAT_CONNECTION);
 347  *                 DEBUG_ROOT_HUB(" CONNECTION");
 348  *             }
 349  *
 350  *             if (usb_port_status.port_enabled)
 351  *             {
 352  *                 port_status |= (1 << USB_PORT_FEAT_ENABLE);
 353  *                 DEBUG_ROOT_HUB(" ENABLE");
 354  *             }
 355  *
 356  *             if (usb_port_status.port_over_current)
 357  *             {
 358  *                 port_status |= (1 << USB_PORT_FEAT_OVER_CURRENT);
 359  *                 DEBUG_ROOT_HUB(" OVER_CURRENT");
 360  *             }
 361  *
 362  *             if (usb_port_status.port_powered)
 363  *             {
 364  *                 port_status |= (1 << USB_PORT_FEAT_POWER);
 365  *                 DEBUG_ROOT_HUB(" POWER");
 366  *             }
 367  *
 368  *             if (usb_port_status.port_speed == CVMX_USB_SPEED_HIGH)
 369  *             {
 370  *                 port_status |= (1 << USB_PORT_FEAT_HIGHSPEED);
 371  *                 DEBUG_ROOT_HUB(" HIGHSPEED");
 372  *             }
 373  *             else if (usb_port_status.port_speed == CVMX_USB_SPEED_LOW)
 374  *             {
 375  *                 port_status |= (1 << USB_PORT_FEAT_LOWSPEED);
 376  *                 DEBUG_ROOT_HUB(" LOWSPEED");
 377  *             }
 378  *
 379  *             *((__le32 *)buf) = cpu_to_le32(port_status);
 380  *             DEBUG_ROOT_HUB("\n");
 381  *             break;
 382  *         case SetHubFeature:
 383  *             DEBUG_ROOT_HUB("OcteonUSB: SetHubFeature\n");
 384  *             // No HUB features supported
 385  *             break;
 386  *         case SetPortFeature:
 387  *             DEBUG_ROOT_HUB("OcteonUSB: SetPortFeature");
 388  *             if (wIndex != 1)
 389  *             {
 390  *                 DEBUG_ROOT_HUB(" INVALID\n");
 391  *                 return -EINVAL;
 392  *             }
 393  *
 394  *             switch (wValue)
 395  *             {
 396  *                 case USB_PORT_FEAT_SUSPEND:
 397  *                     DEBUG_ROOT_HUB(" SUSPEND\n");
 398  *                     return -EINVAL;
 399  *                 case USB_PORT_FEAT_POWER:
 400  *                     DEBUG_ROOT_HUB(" POWER\n");
 401  *                     return -EINVAL;
 402  *                 case USB_PORT_FEAT_RESET:
 403  *                     DEBUG_ROOT_HUB(" RESET\n");
 404  *                     local_irq_save(flags);
 405  *                     cvmx_usb_disable(usb);
 406  *                     if (cvmx_usb_enable(usb))
 407  *                         DEBUG_ERROR("Failed to enable the port\n");
 408  *                     local_irq_restore(flags);
 409  *                     return 0;
 410  *                 case USB_PORT_FEAT_INDICATOR:
 411  *                     DEBUG_ROOT_HUB(" INDICATOR\n");
 412  *                     // Not supported
 413  *                     break;
 414  *                 default:
 415  *                     DEBUG_ROOT_HUB(" UNKNOWN\n");
 416  *                     return -EINVAL;
 417  *             }
 418  *             break;
 419  *         default:
 420  *             DEBUG_ROOT_HUB("OcteonUSB: Unknown root hub request\n");
 421  *             return -EINVAL;
 422  *     }
 423  *     return 0;
 424  * }
 425  * @endcode
 426  *
 427  * <h2>Interrupts</h2>
 428  *
 429  * If you plan on using usb interrupts, cvmx_usb_poll() must be
 430  * called on every usb interrupt. It will read the usb state,
 431  * call any needed callbacks, and schedule transactions as
 432  * needed. Your device driver needs only to hookup an interrupt
 433  * handler and call cvmx_usb_poll(). Octeon's usb port 0 causes
 434  * CIU bit CIU_INT*_SUM0[USB] to be set (bit 56). For port 1,
 435  * CIU bit CIU_INT_SUM1[USB1] is set (bit 17). How these bits
 436  * are turned into interrupt numbers is operating system
 437  * specific. For Linux, there are the convenient defines
 438  * OCTEON_IRQ_USB0 and OCTEON_IRQ_USB1 for the IRQ numbers.
 439  *
 440  * If you aren't using interrupts, simple call cvmx_usb_poll()
 441  * in your main processing loop.
 442  *
 443  * <hr>$Revision: 32636 $<hr>
 444  */
 445
 446 #ifndef __CVMX_USB_H__
 447 #define __CVMX_USB_H__
 448
 449 #ifdef  __cplusplus
 450 extern "C" {
 451 #endif
 452
 453 /**
 454  * Enumerations representing the status of function calls.
 455  */
 456 typedef enum
 457 {
 458     CVMX_USB_SUCCESS = 0,           /**< There were no errors */
 459     CVMX_USB_INVALID_PARAM = -1,    /**< A parameter to the function was invalid */
 460     CVMX_USB_NO_MEMORY = -2,        /**< Insufficient resources were available for the request */
 461     CVMX_USB_BUSY = -3,             /**< The resource is busy and cannot service the request */
 462     CVMX_USB_TIMEOUT = -4,          /**< Waiting for an action timed out */
 463     CVMX_USB_INCORRECT_MODE = -5,   /**< The function call doesn't work in the current USB
 464                                          mode. This happens when host only functions are
 465                                          called in device mode or vice versa */
 466 } cvmx_usb_status_t;
 467
 468 /**
 469  * Enumerations representing the possible USB device speeds
 470  */
 471 typedef enum
 472 {
 473     CVMX_USB_SPEED_HIGH = 0,        /**< Device is operation at 480Mbps */
 474     CVMX_USB_SPEED_FULL = 1,        /**< Device is operation at 12Mbps */
 475     CVMX_USB_SPEED_LOW = 2,         /**< Device is operation at 1.5Mbps */
 476 } cvmx_usb_speed_t;
 477
 478 /**
 479  * Enumeration representing the possible USB transfer types.
 480  */
 481 typedef enum
 482 {
 483     CVMX_USB_TRANSFER_CONTROL = 0,      /**< USB transfer type control for hub and status transfers */
 484     CVMX_USB_TRANSFER_ISOCHRONOUS = 1,  /**< USB transfer type isochronous for low priority periodic transfers */
 485     CVMX_USB_TRANSFER_BULK = 2,         /**< USB transfer type bulk for large low priority transfers */
 486     CVMX_USB_TRANSFER_INTERRUPT = 3,    /**< USB transfer type interrupt for high priority periodic transfers */
 487 } cvmx_usb_transfer_t;
 488
 489 /**
 490  * Enumeration of the transfer directions
 491  */
 492 typedef enum
 493 {
 494     CVMX_USB_DIRECTION_OUT,         /**< Data is transferring from Octeon to the device/host */
 495     CVMX_USB_DIRECTION_IN,          /**< Data is transferring from the device/host to Octeon */
 496 } cvmx_usb_direction_t;
 497
 498 /**
 499  * Enumeration of all possible status codes passed to callback
 500  * functions.
 501  */
 502 typedef enum
 503 {
 504     CVMX_USB_COMPLETE_SUCCESS,      /**< The transaction / operation finished without any errors */
 505     CVMX_USB_COMPLETE_SHORT,        /**< FIXME: This is currently not implemented */
 506     CVMX_USB_COMPLETE_CANCEL,       /**< The transaction was canceled while in flight by a user call to cvmx_usb_cancel* */
 507     CVMX_USB_COMPLETE_ERROR,        /**< The transaction aborted with an unexpected error status */
 508     CVMX_USB_COMPLETE_STALL,        /**< The transaction received a USB STALL response from the device */
 509     CVMX_USB_COMPLETE_XACTERR,      /**< The transaction failed with an error from the device even after a number of retries */
 510     CVMX_USB_COMPLETE_DATATGLERR,   /**< The transaction failed with a data toggle error even after a number of retries */
 511     CVMX_USB_COMPLETE_BABBLEERR,    /**< The transaction failed with a babble error */
 512     CVMX_USB_COMPLETE_FRAMEERR,     /**< The transaction failed with a frame error even after a number of retries */
 513 } cvmx_usb_complete_t;
 514
 515 /**
 516  * Structure returned containing the USB port status information.
 517  */
 518 typedef struct
 519 {
 520     uint32_t reserved           : 25;
 521     uint32_t port_enabled       : 1; /**< 1 = Usb port is enabled, 0 = disabled */
 522     uint32_t port_over_current  : 1; /**< 1 = Over current detected, 0 = Over current not detected. Octeon doesn't support over current detection */
 523     uint32_t port_powered       : 1; /**< 1 = Port power is being supplied to the device, 0 = power is off. Octeon doesn't support turning port power off */
 524     cvmx_usb_speed_t port_speed : 2; /**< Current port speed */
 525     uint32_t connected          : 1; /**< 1 = A device is connected to the port, 0 = No device is connected */
 526     uint32_t connect_change     : 1; /**< 1 = Device connected state changed since the last set status call */
 527 } cvmx_usb_port_status_t;
 528
 529 /**
 530  * This is the structure of a Control packet header
 531  */
 532 typedef union
 533 {
 534     uint64_t u64;
 535     struct
 536     {
 537         uint64_t request_type   : 8;  /**< Bit 7 tells the direction: 1=IN, 0=OUT */
 538         uint64_t request        : 8;  /**< The standard usb request to make */
 539         uint64_t value          : 16; /**< Value parameter for the request in little endian format */
 540         uint64_t index          : 16; /**< Index for the request in little endian format */
 541         uint64_t length         : 16; /**< Length of the data associated with this request in little endian format */
 542     } s;
 543 } cvmx_usb_control_header_t;
 544
 545 /**
 546  * Descriptor for Isochronous packets
 547  */
 548 typedef struct
 549 {
 550     int offset;                     /**< This is the offset in bytes into the main buffer where this data is stored */
 551     int length;                     /**< This is the length in bytes of the data */
 552     cvmx_usb_complete_t status;     /**< This is the status of this individual packet transfer */
 553 } cvmx_usb_iso_packet_t;
 554
 555 /**
 556  * Possible callback reasons for the USB API.
 557  */
 558 typedef enum
 559 {
 560     CVMX_USB_CALLBACK_TRANSFER_COMPLETE,
 561                                     /**< A callback of this type is called when a submitted transfer
 562                                         completes. The completion callback will be called even if the
 563                                         transfer fails or is canceled. The status parameter will
 564                                         contain details of why he callback was called. */
 565     CVMX_USB_CALLBACK_PORT_CHANGED, /**< The status of the port changed. For example, someone may have
 566                                         plugged a device in. The status parameter contains
 567                                         CVMX_USB_COMPLETE_SUCCESS. Use cvmx_usb_get_status() to get
 568                                         the new port status. */
 569     CVMX_USB_CALLBACK_DEVICE_SETUP, /**< This is called in device mode when a control channels receives
 570                                         a setup header */
 571     __CVMX_USB_CALLBACK_END         /**< Do not use. Used internally for array bounds */
 572 } cvmx_usb_callback_t;
 573
 574 /**
 575  * USB state internal data. The contents of this structure
 576  * may change in future SDKs. No data in it should be referenced
 577  * by user's of this API.
 578  */
 579 typedef struct
 580 {
 581     char data[65536];
 582 } cvmx_usb_state_t;
 583
 584 /**
 585  * USB callback functions are always of the following type.
 586  * The parameters are as follows:
 587  *      - state = USB device state populated by
 588  *        cvmx_usb_initialize().
 589  *      - reason = The cvmx_usb_callback_t used to register
 590  *        the callback.
 591  *      - status = The cvmx_usb_complete_t representing the
 592  *        status code of a transaction.
 593  *      - pipe_handle = The Pipe that caused this callback, or
 594  *        -1 if this callback wasn't associated with a pipe.
 595  *      - submit_handle = Transfer submit handle causing this
 596  *        callback, or -1 if this callback wasn't associated
 597  *        with a transfer.
 598  *      - Actual number of bytes transfer.
 599  *      - user_data = The user pointer supplied to the
 600  *        function cvmx_usb_submit() or
 601  *        cvmx_usb_register_callback() */
 602 typedef void (*cvmx_usb_callback_func_t)(cvmx_usb_state_t *state,
 603                                          cvmx_usb_callback_t reason,
 604                                          cvmx_usb_complete_t status,
 605                                          int pipe_handle, int submit_handle,
 606                                          int bytes_transferred, void *user_data);
 607
 608 /**
 609  * Flags to pass the initialization function.
 610  */
 611 typedef enum
 612 {
 613     CVMX_USB_INITIALIZE_FLAGS_CLOCK_XO_XI = 1<<0,       /**< The USB port uses a 12MHz crystal as clock source
 614                                                             at USB_XO and USB_XI. */
 615     CVMX_USB_INITIALIZE_FLAGS_CLOCK_XO_GND = 1<<1,      /**< The USB port uses 12/24/48MHz 2.5V board clock
 616                                                             source at USB_XO. USB_XI should be tied to GND.*/
 617     CVMX_USB_INITIALIZE_FLAGS_CLOCK_AUTO = 0,           /**< Automatically determine clock type based on function
 618                                                              in cvmx-helper-board.c. */
 619     CVMX_USB_INITIALIZE_FLAGS_DEVICE_MODE = 1<<2,       /**< Program the USB port for device mode instead of host mode */
 620     CVMX_USB_INITIALIZE_FLAGS_CLOCK_MHZ_MASK  = 3<<3,       /**< Mask for clock speed field */
 621     CVMX_USB_INITIALIZE_FLAGS_CLOCK_12MHZ = 1<<3,       /**< Speed of reference clock or crystal */
 622     CVMX_USB_INITIALIZE_FLAGS_CLOCK_24MHZ = 2<<3,       /**< Speed of reference clock */
 623     CVMX_USB_INITIALIZE_FLAGS_CLOCK_48MHZ = 3<<3,       /**< Speed of reference clock */
 624     /* Bits 3-4 used to encode the clock frequency */
 625     CVMX_USB_INITIALIZE_FLAGS_DEBUG_TRANSFERS = 1<<16,  /**< Enable extra console output for debugging USB transfers */
 626     CVMX_USB_INITIALIZE_FLAGS_DEBUG_CALLBACKS = 1<<17,  /**< Enable extra console output for debugging USB callbacks */
 627     CVMX_USB_INITIALIZE_FLAGS_DEBUG_INFO = 1<<18,       /**< Enable extra console output for USB informational data */
 628     CVMX_USB_INITIALIZE_FLAGS_DEBUG_CALLS = 1<<19,      /**< Enable extra console output for every function call */
 629     CVMX_USB_INITIALIZE_FLAGS_DEBUG_CSRS = 1<<20,       /**< Enable extra console output for every CSR access */
 630     CVMX_USB_INITIALIZE_FLAGS_DEBUG_ALL = ((CVMX_USB_INITIALIZE_FLAGS_DEBUG_CSRS<<1)-1) - (CVMX_USB_INITIALIZE_FLAGS_DEBUG_TRANSFERS-1),
 631 } cvmx_usb_initialize_flags_t;
 632
 633 /**
 634  * Flags for passing when a pipe is created. Currently no flags
 635  * need to be passed.
 636  */
 637 typedef enum
 638 {
 639     CVMX_USB_PIPE_FLAGS_DEBUG_TRANSFERS = 1<<15,/**< Used to display CVMX_USB_INITIALIZE_FLAGS_DEBUG_TRANSFERS for a specific pipe only */
 640     __CVMX_USB_PIPE_FLAGS_OPEN = 1<<16,         /**< Used internally to determine if a pipe is open. Do not use */
 641     __CVMX_USB_PIPE_FLAGS_SCHEDULED = 1<<17,    /**< Used internally to determine if a pipe is actively using hardware. Do not use */
 642     __CVMX_USB_PIPE_FLAGS_NEED_PING = 1<<18,    /**< Used internally to determine if a high speed pipe is in the ping state. Do not use */
 643 } cvmx_usb_pipe_flags_t;
 644
 645 /**
 646  * Return the number of USB ports supported by this Octeon
 647  * chip. If the chip doesn't support USB, or is not supported
 648  * by this API, a zero will be returned. Most Octeon chips
 649  * support one usb port, but some support two ports.
 650  * cvmx_usb_initialize() must be called on independent
 651  * cvmx_usb_state_t structures.
 652  *
 653  * @return Number of port, zero if usb isn't supported
 654  */
 655 extern int cvmx_usb_get_num_ports(void);
 656
 657 /**
 658  * Initialize a USB port for use. This must be called before any
 659  * other access to the Octeon USB port is made. The port starts
 660  * off in the disabled state.
 661  *
 662  * @param state  Pointer to an empty cvmx_usb_state_t structure
 663  *               that will be populated by the initialize call.
 664  *               This structure is then passed to all other USB
 665  *               functions.
 666  * @param usb_port_number
 667  *               Which Octeon USB port to initialize.
 668  * @param flags  Flags to control hardware initialization. See
 669  *               cvmx_usb_initialize_flags_t for the flag
 670  *               definitions. Some flags are mandatory.
 671  *
 672  * @return CVMX_USB_SUCCESS or a negative error code defined in
 673  *         cvmx_usb_status_t.
 674  */
 675 extern cvmx_usb_status_t cvmx_usb_initialize(cvmx_usb_state_t *state,
 676                                              int usb_port_number,
 677                                              cvmx_usb_initialize_flags_t flags);
 678
 679 /**
 680  * Shutdown a USB port after a call to cvmx_usb_initialize().
 681  * The port should be disabled with all pipes closed when this
 682  * function is called.
 683  *
 684  * @param state  USB device state populated by
 685  *               cvmx_usb_initialize().
 686  *
 687  * @return CVMX_USB_SUCCESS or a negative error code defined in
 688  *         cvmx_usb_status_t.
 689  */
 690 extern cvmx_usb_status_t cvmx_usb_shutdown(cvmx_usb_state_t *state);
 691
 692 /**
 693  * Enable a USB port. After this call succeeds, the USB port is
 694  * online and servicing requests.
 695  *
 696  * @param state  USB device state populated by
 697  *               cvmx_usb_initialize().
 698  *
 699  * @return CVMX_USB_SUCCESS or a negative error code defined in
 700  *         cvmx_usb_status_t.
 701  */
 702 extern cvmx_usb_status_t cvmx_usb_enable(cvmx_usb_state_t *state);
 703
 704 /**
 705  * Disable a USB port. After this call the USB port will not
 706  * generate data transfers and will not generate events.
 707  * Transactions in process will fail and call their
 708  * associated callbacks.
 709  *
 710  * @param state  USB device state populated by
 711  *               cvmx_usb_initialize().
 712  *
 713  * @return CVMX_USB_SUCCESS or a negative error code defined in
 714  *         cvmx_usb_status_t.
 715  */
 716 extern cvmx_usb_status_t cvmx_usb_disable(cvmx_usb_state_t *state);
 717
 718 /**
 719  * Get the current state of the USB port. Use this call to
 720  * determine if the usb port has anything connected, is enabled,
 721  * or has some sort of error condition. The return value of this
 722  * call has "changed" bits to signal of the value of some fields
 723  * have changed between calls. These "changed" fields are based
 724  * on the last call to cvmx_usb_set_status(). In order to clear
 725  * them, you must update the status through cvmx_usb_set_status().
 726  *
 727  * @param state  USB device state populated by
 728  *               cvmx_usb_initialize().
 729  *
 730  * @return Port status information
 731  */
 732 extern cvmx_usb_port_status_t cvmx_usb_get_status(cvmx_usb_state_t *state);
 733
 734 /**
 735  * Set the current state of the USB port. The status is used as
 736  * a reference for the "changed" bits returned by
 737  * cvmx_usb_get_status(). Other than serving as a reference, the
 738  * status passed to this function is not used. No fields can be
 739  * changed through this call.
 740  *
 741  * @param state  USB device state populated by
 742  *               cvmx_usb_initialize().
 743  * @param port_status
 744  *               Port status to set, most like returned by cvmx_usb_get_status()
 745  */
 746 extern void cvmx_usb_set_status(cvmx_usb_state_t *state, cvmx_usb_port_status_t port_status);
 747
 748 /**
 749  * Open a virtual pipe between the host and a USB device. A pipe
 750  * must be opened before data can be transferred between a device
 751  * and Octeon.
 752  *
 753  * @param state      USB device state populated by
 754  *                   cvmx_usb_initialize().
 755  * @param flags      Optional pipe flags defined in
 756  *                   cvmx_usb_pipe_flags_t.
 757  * @param device_addr
 758  *                   USB device address to open the pipe to
 759  *                   (0-127).
 760  * @param endpoint_num
 761  *                   USB endpoint number to open the pipe to
 762  *                   (0-15).
 763  * @param device_speed
 764  *                   The speed of the device the pipe is going
 765  *                   to. This must match the device's speed,
 766  *                   which may be different than the port speed.
 767  * @param max_packet The maximum packet length the device can
 768  *                   transmit/receive (low speed=0-8, full
 769  *                   speed=0-1023, high speed=0-1024). This value
 770  *                   comes from the stadnard endpoint descriptor
 771  *                   field wMaxPacketSize bits <10:0>.
 772  * @param transfer_type
 773  *                   The type of transfer this pipe is for.
 774  * @param transfer_dir
 775  *                   The direction the pipe is in. This is not
 776  *                   used for control pipes.
 777  * @param interval   For ISOCHRONOUS and INTERRUPT transfers,
 778  *                   this is how often the transfer is scheduled
 779  *                   for. All other transfers should specify
 780  *                   zero. The units are in frames (8000/sec at
 781  *                   high speed, 1000/sec for full speed).
 782  * @param multi_count
 783  *                   For high speed devices, this is the maximum
 784  *                   allowed number of packet per microframe.
 785  *                   Specify zero for non high speed devices. This
 786  *                   value comes from the stadnard endpoint descriptor
 787  *                   field wMaxPacketSize bits <12:11>.
 788  * @param hub_device_addr
 789  *                   Hub device address this device is connected
 790  *                   to. Devices connected directly to Octeon
 791  *                   use zero. This is only used when the device
 792  *                   is full/low speed behind a high speed hub.
 793  *                   The address will be of the high speed hub,
 794  *                   not and full speed hubs after it.
 795  * @param hub_port   Which port on the hub the device is
 796  *                   connected. Use zero for devices connected
 797  *                   directly to Octeon. Like hub_device_addr,
 798  *                   this is only used for full/low speed
 799  *                   devices behind a high speed hub.
 800  *
 801  * @return A non negative value is a pipe handle. Negative
 802  *         values are failure codes from cvmx_usb_status_t.
 803  */
 804 extern int cvmx_usb_open_pipe(cvmx_usb_state_t *state,
 805                               cvmx_usb_pipe_flags_t flags,
 806                               int device_addr, int endpoint_num,
 807                               cvmx_usb_speed_t device_speed, int max_packet,
 808                               cvmx_usb_transfer_t transfer_type,
 809                               cvmx_usb_direction_t transfer_dir, int interval,
 810                               int multi_count, int hub_device_addr,
 811                               int hub_port);
 812
 813 /**
 814  * Call to submit a USB Bulk transfer to a pipe.
 815  *
 816  * @param state     USB device state populated by
 817  *                  cvmx_usb_initialize().
 818  * @param pipe_handle
 819  *                  Handle to the pipe for the transfer.
 820  * @param buffer    Physical address of the data buffer in
 821  *                  memory. Note that this is NOT A POINTER, but
 822  *                  the full 64bit physical address of the
 823  *                  buffer. This may be zero if buffer_length is
 824  *                  zero.
 825  * @param buffer_length
 826  *                  Length of buffer in bytes.
 827  * @param callback  Function to call when this transaction
 828  *                  completes. If the return value of this
 829  *                  function isn't an error, then this function
 830  *                  is guaranteed to be called when the
 831  *                  transaction completes. If this parameter is
 832  *                  NULL, then the generic callback registered
 833  *                  through cvmx_usb_register_callback is
 834  *                  called. If both are NULL, then there is no
 835  *                  way to know when a transaction completes.
 836  * @param user_data User supplied data returned when the
 837  *                  callback is called. This is only used if
 838  *                  callback in not NULL.
 839  *
 840  * @return A submitted transaction handle or negative on
 841  *         failure. Negative values are failure codes from
 842  *         cvmx_usb_status_t.
 843  */
 844 extern int cvmx_usb_submit_bulk(cvmx_usb_state_t *state, int pipe_handle,
 845                                 uint64_t buffer, int buffer_length,
 846                                 cvmx_usb_callback_func_t callback,
 847                                 void *user_data);
 848
 849 /**
 850  * Call to submit a USB Interrupt transfer to a pipe.
 851  *
 852  * @param state     USB device state populated by
 853  *                  cvmx_usb_initialize().
 854  * @param pipe_handle
 855  *                  Handle to the pipe for the transfer.
 856  * @param buffer    Physical address of the data buffer in
 857  *                  memory. Note that this is NOT A POINTER, but
 858  *                  the full 64bit physical address of the
 859  *                  buffer. This may be zero if buffer_length is
 860  *                  zero.
 861  * @param buffer_length
 862  *                  Length of buffer in bytes.
 863  * @param callback  Function to call when this transaction
 864  *                  completes. If the return value of this
 865  *                  function isn't an error, then this function
 866  *                  is guaranteed to be called when the
 867  *                  transaction completes. If this parameter is
 868  *                  NULL, then the generic callback registered
 869  *                  through cvmx_usb_register_callback is
 870  *                  called. If both are NULL, then there is no
 871  *                  way to know when a transaction completes.
 872  * @param user_data User supplied data returned when the
 873  *                  callback is called. This is only used if
 874  *                  callback in not NULL.
 875  *
 876  * @return A submitted transaction handle or negative on
 877  *         failure. Negative values are failure codes from
 878  *         cvmx_usb_status_t.
 879  */
 880 extern int cvmx_usb_submit_interrupt(cvmx_usb_state_t *state, int pipe_handle,
 881                                      uint64_t buffer, int buffer_length,
 882                                      cvmx_usb_callback_func_t callback,
 883                                      void *user_data);
 884
 885 /**
 886  * Call to submit a USB Control transfer to a pipe.
 887  *
 888  * @param state     USB device state populated by
 889  *                  cvmx_usb_initialize().
 890  * @param pipe_handle
 891  *                  Handle to the pipe for the transfer.
 892  * @param control_header
 893  *                  USB 8 byte control header physical address.
 894  *                  Note that this is NOT A POINTER, but the
 895  *                  full 64bit physical address of the buffer.
 896  * @param buffer    Physical address of the data buffer in
 897  *                  memory. Note that this is NOT A POINTER, but
 898  *                  the full 64bit physical address of the
 899  *                  buffer. This may be zero if buffer_length is
 900  *                  zero.
 901  * @param buffer_length
 902  *                  Length of buffer in bytes.
 903  * @param callback  Function to call when this transaction
 904  *                  completes. If the return value of this
 905  *                  function isn't an error, then this function
 906  *                  is guaranteed to be called when the
 907  *                  transaction completes. If this parameter is
 908  *                  NULL, then the generic callback registered
 909  *                  through cvmx_usb_register_callback is
 910  *                  called. If both are NULL, then there is no
 911  *                  way to know when a transaction completes.
 912  * @param user_data User supplied data returned when the
 913  *                  callback is called. This is only used if
 914  *                  callback in not NULL.
 915  *
 916  * @return A submitted transaction handle or negative on
 917  *         failure. Negative values are failure codes from
 918  *         cvmx_usb_status_t.
 919  */
 920 extern int cvmx_usb_submit_control(cvmx_usb_state_t *state, int pipe_handle,
 921                                    uint64_t control_header,
 922                                    uint64_t buffer, int buffer_length,
 923                                    cvmx_usb_callback_func_t callback,
 924                                    void *user_data);
 925
 926 /**
 927  * Flags to pass the cvmx_usb_submit_isochronous() function.
 928  */
 929 typedef enum
 930 {
 931     CVMX_USB_ISOCHRONOUS_FLAGS_ALLOW_SHORT = 1<<0,  /**< Do not return an error if a transfer is less than the maximum packet size of the device */
 932     CVMX_USB_ISOCHRONOUS_FLAGS_ASAP = 1<<1,         /**< Schedule the transaction as soon as possible */
 933 } cvmx_usb_isochronous_flags_t;
 934
 935 /**
 936  * Call to submit a USB Isochronous transfer to a pipe.
 937  *
 938  * @param state     USB device state populated by
 939  *                  cvmx_usb_initialize().
 940  * @param pipe_handle
 941  *                  Handle to the pipe for the transfer.
 942  * @param start_frame
 943  *                  Number of frames into the future to schedule
 944  *                  this transaction.
 945  * @param flags     Flags to control the transfer. See
 946  *                  cvmx_usb_isochronous_flags_t for the flag
 947  *                  definitions.
 948  * @param number_packets
 949  *                  Number of sequential packets to transfer.
 950  *                  "packets" is a pointer to an array of this
 951  *                  many packet structures.
 952  * @param packets   Description of each transfer packet as
 953  *                  defined by cvmx_usb_iso_packet_t. The array
 954  *                  pointed to here must stay valid until the
 955  *                  complete callback is called.
 956  * @param buffer    Physical address of the data buffer in
 957  *                  memory. Note that this is NOT A POINTER, but
 958  *                  the full 64bit physical address of the
 959  *                  buffer. This may be zero if buffer_length is
 960  *                  zero.
 961  * @param buffer_length
 962  *                  Length of buffer in bytes.
 963  * @param callback  Function to call when this transaction
 964  *                  completes. If the return value of this
 965  *                  function isn't an error, then this function
 966  *                  is guaranteed to be called when the
 967  *                  transaction completes. If this parameter is
 968  *                  NULL, then the generic callback registered
 969  *                  through cvmx_usb_register_callback is
 970  *                  called. If both are NULL, then there is no
 971  *                  way to know when a transaction completes.
 972  * @param user_data User supplied data returned when the
 973  *                  callback is called. This is only used if
 974  *                  callback in not NULL.
 975  *
 976  * @return A submitted transaction handle or negative on
 977  *         failure. Negative values are failure codes from
 978  *         cvmx_usb_status_t.
 979  */
 980 extern int cvmx_usb_submit_isochronous(cvmx_usb_state_t *state, int pipe_handle,
 981                                        int start_frame, int flags,
 982                                        int number_packets,
 983                                        cvmx_usb_iso_packet_t packets[],
 984                                        uint64_t buffer, int buffer_length,
 985                                        cvmx_usb_callback_func_t callback,
 986                                        void *user_data);
 987
 988 /**
 989  * Cancel one outstanding request in a pipe. Canceling a request
 990  * can fail if the transaction has already completed before cancel
 991  * is called. Even after a successful cancel call, it may take
 992  * a frame or two for the cvmx_usb_poll() function to call the
 993  * associated callback.
 994  *
 995  * @param state  USB device state populated by
 996  *               cvmx_usb_initialize().
 997  * @param pipe_handle
 998  *               Pipe handle to cancel requests in.
 999  * @param submit_handle
1000  *               Handle to transaction to cancel, returned by the submit function.
1001  *
1002  * @return CVMX_USB_SUCCESS or a negative error code defined in
1003  *         cvmx_usb_status_t.
1004  */
1005 extern cvmx_usb_status_t cvmx_usb_cancel(cvmx_usb_state_t *state,
1006                                          int pipe_handle, int submit_handle);
1007
1008
1009 /**
1010  * Cancel all outstanding requests in a pipe. Logically all this
1011  * does is call cvmx_usb_cancel() in a loop.
1012  *
1013  * @param state  USB device state populated by
1014  *               cvmx_usb_initialize().
1015  * @param pipe_handle
1016  *               Pipe handle to cancel requests in.
1017  *
1018  * @return CVMX_USB_SUCCESS or a negative error code defined in
1019  *         cvmx_usb_status_t.
1020  */
1021 extern cvmx_usb_status_t cvmx_usb_cancel_all(cvmx_usb_state_t *state,
1022                                              int pipe_handle);
1023
1024 /**
1025  * Close a pipe created with cvmx_usb_open_pipe().
1026  *
1027  * @param state  USB device state populated by
1028  *               cvmx_usb_initialize().
1029  * @param pipe_handle
1030  *               Pipe handle to close.
1031  *
1032  * @return CVMX_USB_SUCCESS or a negative error code defined in
1033  *         cvmx_usb_status_t. CVMX_USB_BUSY is returned if the
1034  *         pipe has outstanding transfers.
1035  */
1036 extern cvmx_usb_status_t cvmx_usb_close_pipe(cvmx_usb_state_t *state,
1037                                              int pipe_handle);
1038
1039 /**
1040  * Register a function to be called when various USB events occur.
1041  *
1042  * @param state     USB device state populated by
1043  *                  cvmx_usb_initialize().
1044  * @param reason    Which event to register for.
1045  * @param callback  Function to call when the event occurs.
1046  * @param user_data User data parameter to the function.
1047  *
1048  * @return CVMX_USB_SUCCESS or a negative error code defined in
1049  *         cvmx_usb_status_t.
1050  */
1051 extern cvmx_usb_status_t cvmx_usb_register_callback(cvmx_usb_state_t *state,
1052                                                     cvmx_usb_callback_t reason,
1053                                                     cvmx_usb_callback_func_t callback,
1054                                                     void *user_data);
1055
1056 /**
1057  * Get the current USB protocol level frame number. The frame
1058  * number is always in the range of 0-0x7ff.
1059  *
1060  * @param state  USB device state populated by
1061  *               cvmx_usb_initialize().
1062  *
1063  * @return USB frame number
1064  */
1065 extern int cvmx_usb_get_frame_number(cvmx_usb_state_t *state);
1066
1067 /**
1068  * Poll the USB block for status and call all needed callback
1069  * handlers. This function is meant to be called in the interrupt
1070  * handler for the USB controller. It can also be called
1071  * periodically in a loop for non-interrupt based operation.
1072  *
1073  * @param state  USB device state populated by
1074  *               cvmx_usb_initialize().
1075  *
1076  * @return CVMX_USB_SUCCESS or a negative error code defined in
1077  *         cvmx_usb_status_t.
1078  */
1079 extern cvmx_usb_status_t cvmx_usb_poll(cvmx_usb_state_t *state);
1080
1081 /**
1082  * Enable an endpoint for use in device mode. After this call
1083  * transactions will be allowed over the endpoint. This must be
1084  * called after every usb reset.
1085  *
1086  * @param state  USB device state populated by
1087  *               cvmx_usb_initialize().
1088  * @param endpoint_num
1089  *               The endpoint number to enable (0-4)
1090  * @param transfer_type
1091  *               USB transfer type of this endpoint
1092  * @param transfer_dir
1093  *               Direction of transfer relative to Octeon
1094  * @param max_packet_size
1095  *               Maximum packet size support by this endpoint
1096  * @param buffer Buffer to send/receive
1097  * @param buffer_length
1098  *               Length of the buffer in bytes
1099  *
1100  * @return CVMX_USB_SUCCESS or a negative error code defined in
1101  *         cvmx_usb_status_t.
1102  */
1103 extern cvmx_usb_status_t cvmx_usb_device_enable_endpoint(cvmx_usb_state_t *state,
1104                                                   int endpoint_num,
1105                                                   cvmx_usb_transfer_t transfer_type,
1106                                                   cvmx_usb_direction_t transfer_dir,
1107                                                   int max_packet_size,
1108                                                   uint64_t buffer,
1109                                                   int buffer_length);
1110
1111 /**
1112  * Disable an endpoint in device mode.
1113  *
1114  * @param state  USB device state populated by
1115  *               cvmx_usb_initialize().
1116  * @param endpoint_num
1117  *               The endpoint number to disable (0-4)
1118  *
1119  * @return CVMX_USB_SUCCESS or a negative error code defined in
1120  *         cvmx_usb_status_t.
1121  */
1122 extern cvmx_usb_status_t cvmx_usb_device_disable_endpoint(cvmx_usb_state_t *state,
1123                                                           int endpoint_num);
1124
1125 /*
1126  * The FreeBSD host driver uses these functions to manipulate the toggle to deal
1127  * more easily with endpoint management.
1128  */
1129 extern void cvmx_usb_set_toggle(cvmx_usb_state_t *state, int endpoint_num, int toggle);
1130 extern int cvmx_usb_get_toggle(cvmx_usb_state_t *state, int endpoint_num);
1131
1132 #ifdef  __cplusplus
1133 }
1134 #endif
1135
1136 #endif  /* __CVMX_USB_H__ */