drivers/staging/octeon-usb/cvmx-usb.h

   1 /***********************license start***************
   2  * Copyright (c) 2003-2010  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  * This Software, including technical data, may be subject to U.S. export  control
  24  * laws, including the U.S. Export Administration Act and its  associated
  25  * regulations, and may be subject to export or import  regulations in other
  26  * countries.
  27
  28  * TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS"
  29  * AND WITH ALL FAULTS AND CAVIUM  NETWORKS MAKES NO PROMISES, REPRESENTATIONS OR
  30  * WARRANTIES, EITHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, WITH RESPECT TO
  31  * THE SOFTWARE, INCLUDING ITS CONDITION, ITS CONFORMITY TO ANY REPRESENTATION OR
  32  * DESCRIPTION, OR THE EXISTENCE OF ANY LATENT OR PATENT DEFECTS, AND CAVIUM
  33  * SPECIFICALLY DISCLAIMS ALL IMPLIED (IF ANY) WARRANTIES OF TITLE,
  34  * MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR A PARTICULAR PURPOSE, LACK OF
  35  * VIRUSES, ACCURACY OR COMPLETENESS, QUIET ENJOYMENT, QUIET POSSESSION OR
  36  * CORRESPONDENCE TO DESCRIPTION. THE ENTIRE  RISK ARISING OUT OF USE OR
  37  * PERFORMANCE OF THE SOFTWARE LIES WITH YOU.
  38  ***********************license end**************************************/
  39
  40
  41 /**
  42  * @file
  43  *
  44  * "cvmx-usb.h" defines a set of low level USB functions to help
  45  * developers create Octeon USB drivers for various operating
  46  * systems. These functions provide a generic API to the Octeon
  47  * USB blocks, hiding the internal hardware specific
  48  * operations.
  49  *
  50  * At a high level the device driver needs to:
  51  *
  52  * -# Call cvmx_usb_get_num_ports() to get the number of
  53  *  supported ports.
  54  * -# Call cvmx_usb_initialize() for each Octeon USB port.
  55  * -# Enable the port using cvmx_usb_enable().
  56  * -# Either periodically, or in an interrupt handler, call
  57  *  cvmx_usb_poll() to service USB events.
  58  * -# Manage pipes using cvmx_usb_open_pipe() and
  59  *  cvmx_usb_close_pipe().
  60  * -# Manage transfers using cvmx_usb_submit_*() and
  61  *  cvmx_usb_cancel*().
  62  * -# Shutdown USB on unload using cvmx_usb_shutdown().
  63  *
  64  * To monitor USB status changes, the device driver must use
  65  * cvmx_usb_register_callback() to register for events that it
  66  * is interested in. Below are a few hints on successfully
  67  * implementing a driver on top of this API.
  68  *
  69  * <h2>Initialization</h2>
  70  *
  71  * When a driver is first loaded, it is normally not necessary
  72  * to bring up the USB port completely. Most operating systems
  73  * expect to initialize and enable the port in two independent
  74  * steps. Normally an operating system will probe hardware,
  75  * initialize anything found, and then enable the hardware.
  76  *
  77  * In the probe phase you should:
  78  * -# Use cvmx_usb_get_num_ports() to determine the number of
  79  *  USB port to be supported.
  80  * -# Allocate space for a cvmx_usb_state_t structure for each
  81  *  port.
  82  * -# Tell the operating system about each port
  83  *
  84  * In the initialization phase you should:
  85  * -# Use cvmx_usb_initialize() on each port.
  86  * -# Do not call cvmx_usb_enable(). This leaves the USB port in
  87  *  the disabled state until the operating system is ready.
  88  *
  89  * Finally, in the enable phase you should:
  90  * -# Call cvmx_usb_enable() on the appropriate port.
  91  * -# Note that some operating system use a RESET instead of an
  92  *  enable call. To implement RESET, you should call
  93  *  cvmx_usb_disable() followed by cvmx_usb_enable().
  94  *
  95  * <h2>Locking</h2>
  96  *
  97  * All of the functions in the cvmx-usb API assume exclusive
  98  * access to the USB hardware and internal data structures. This
  99  * means that the driver must provide locking as necessary.
 100  *
 101  * In the single CPU state it is normally enough to disable
 102  * interrupts before every call to cvmx_usb*() and enable them
 103  * again after the call is complete. Keep in mind that it is
 104  * very common for the callback handlers to make additional
 105  * calls into cvmx-usb, so the disable/enable must be protected
 106  * against recursion. As an example, the Linux kernel
 107  * local_irq_save() and local_irq_restore() are perfect for this
 108  * in the non SMP case.
 109  *
 110  * In the SMP case, locking is more complicated. For SMP you not
 111  * only need to disable interrupts on the local core, but also
 112  * take a lock to make sure that another core cannot call
 113  * cvmx-usb.
 114  *
 115  * <h2>Port callback</h2>
 116  *
 117  * The port callback prototype needs to look as follows:
 118  *
 119  * void port_callback(cvmx_usb_state_t *usb,
 120  *                    cvmx_usb_callback_t reason,
 121  *                    cvmx_usb_complete_t status,
 122  *                    int pipe_handle,
 123  *                    int submit_handle,
 124  *                    int bytes_transferred,
 125  *                    void *user_data);
 126  * - @b usb is the cvmx_usb_state_t for the port.
 127  * - @b reason will always be
 128  *   CVMX_USB_CALLBACK_PORT_CHANGED.
 129  * - @b status will always be CVMX_USB_COMPLETE_SUCCESS.
 130  * - @b pipe_handle will always be -1.
 131  * - @b submit_handle will always be -1.
 132  * - @b bytes_transferred will always be 0.
 133  * - @b user_data is the void pointer originally passed along
 134  *   with the callback. Use this for any state information you
 135  *   need.
 136  *
 137  * The port callback will be called whenever the user plugs /
 138  * unplugs a device from the port. It will not be called when a
 139  * device is plugged / unplugged from a hub connected to the
 140  * root port. Normally all the callback needs to do is tell the
 141  * operating system to poll the root hub for status. Under
 142  * Linux, this is performed by calling usb_hcd_poll_rh_status().
 143  * In the Linux driver we use @b user_data. to pass around the
 144  * Linux "hcd" structure. Once the port callback completes,
 145  * Linux automatically calls octeon_usb_hub_status_data() which
 146  * uses cvmx_usb_get_status() to determine the root port status.
 147  *
 148  * <h2>Complete callback</h2>
 149  *
 150  * The completion callback prototype needs to look as follows:
 151  *
 152  * void complete_callback(cvmx_usb_state_t *usb,
 153  *                        cvmx_usb_callback_t reason,
 154  *                        cvmx_usb_complete_t status,
 155  *                        int pipe_handle,
 156  *                        int submit_handle,
 157  *                        int bytes_transferred,
 158  *                        void *user_data);
 159  * - @b usb is the cvmx_usb_state_t for the port.
 160  * - @b reason will always be
 161  *   CVMX_USB_CALLBACK_TRANSFER_COMPLETE.
 162  * - @b status will be one of the cvmx_usb_complete_t
 163  *   enumerations.
 164  * - @b pipe_handle is the handle to the pipe the transaction
 165  *   was originally submitted on.
 166  * - @b submit_handle is the handle returned by the original
 167  *   cvmx_usb_submit_* call.
 168  * - @b bytes_transferred is the number of bytes successfully
 169  *   transferred in the transaction. This will be zero on most
 170  *   error conditions.
 171  * - @b user_data is the void pointer originally passed along
 172  *   with the callback. Use this for any state information you
 173  *   need. For example, the Linux "urb" is stored in here in the
 174  *   Linux driver.
 175  *
 176  * In general your callback handler should use @b status and @b
 177  * bytes_transferred to tell the operating system the how the
 178  * transaction completed. Normally the pipe is not changed in
 179  * this callback.
 180  *
 181  * <h2>Canceling transactions</h2>
 182  *
 183  * When a transaction is cancelled using cvmx_usb_cancel*(), the
 184  * actual length of time until the complete callback is called
 185  * can vary greatly. It may be called before cvmx_usb_cancel*()
 186  * returns, or it may be called a number of usb frames in the
 187  * future once the hardware frees the transaction. In either of
 188  * these cases, the complete handler will receive
 189  * CVMX_USB_COMPLETE_CANCEL.
 190  *
 191  * <h2>Handling pipes</h2>
 192  *
 193  * USB "pipes" is a software construct created by this API to
 194  * enable the ordering of usb transactions to a device endpoint.
 195  * Octeon's underlying hardware doesn't have any concept
 196  * equivalent to "pipes". The hardware instead has eight
 197  * channels that can be used simultaneously to have up to eight
 198  * transaction in process at the same time. In order to maintain
 199  * ordering in a pipe, the transactions for a pipe will only be
 200  * active in one hardware channel at a time. From an API user's
 201  * perspective, this doesn't matter but it can be helpful to
 202  * keep this in mind when you are probing hardware while
 203  * debugging.
 204  *
 205  * Also keep in mind that usb transactions contain state
 206  * information about the previous transaction to the same
 207  * endpoint. Each transaction has a PID toggle that changes 0/1
 208  * between each sub packet. This is maintained in the pipe data
 209  * structures. For this reason, you generally cannot create and
 210  * destroy a pipe for every transaction. A sequence of
 211  * transaction to the same endpoint must use the same pipe.
 212  *
 213  * <h2>Root Hub</h2>
 214  *
 215  * Some operating systems view the usb root port as a normal usb
 216  * hub. These systems attempt to control the root hub with
 217  * messages similar to the usb 2.0 spec for hub control and
 218  * status. For these systems it may be necessary to write
 219  * function to decode standard usb control messages into
 220  * equivalent cvmx-usb API calls.
 221  *
 222  * <h2>Interrupts</h2>
 223  *
 224  * If you plan on using usb interrupts, cvmx_usb_poll() must be
 225  * called on every usb interrupt. It will read the usb state,
 226  * call any needed callbacks, and schedule transactions as
 227  * needed. Your device driver needs only to hookup an interrupt
 228  * handler and call cvmx_usb_poll(). Octeon's usb port 0 causes
 229  * CIU bit CIU_INT*_SUM0[USB] to be set (bit 56). For port 1,
 230  * CIU bit CIU_INT_SUM1[USB1] is set (bit 17). How these bits
 231  * are turned into interrupt numbers is operating system
 232  * specific. For Linux, there are the convenient defines
 233  * OCTEON_IRQ_USB0 and OCTEON_IRQ_USB1 for the IRQ numbers.
 234  *
 235  * If you aren't using interrupts, simple call cvmx_usb_poll()
 236  * in your main processing loop.
 237  */
 238
 239 #ifndef __CVMX_USB_H__
 240 #define __CVMX_USB_H__
 241
 242 /**
 243  * Enumerations representing the possible USB device speeds
 244  */
 245 typedef enum
 246 {
 247     CVMX_USB_SPEED_HIGH = 0,        /**< Device is operation at 480Mbps */
 248     CVMX_USB_SPEED_FULL = 1,        /**< Device is operation at 12Mbps */
 249     CVMX_USB_SPEED_LOW = 2,         /**< Device is operation at 1.5Mbps */
 250 } cvmx_usb_speed_t;
 251
 252 /**
 253  * Enumeration representing the possible USB transfer types.
 254  */
 255 typedef enum
 256 {
 257     CVMX_USB_TRANSFER_CONTROL = 0,      /**< USB transfer type control for hub and status transfers */
 258     CVMX_USB_TRANSFER_ISOCHRONOUS = 1,  /**< USB transfer type isochronous for low priority periodic transfers */
 259     CVMX_USB_TRANSFER_BULK = 2,         /**< USB transfer type bulk for large low priority transfers */
 260     CVMX_USB_TRANSFER_INTERRUPT = 3,    /**< USB transfer type interrupt for high priority periodic transfers */
 261 } cvmx_usb_transfer_t;
 262
 263 /**
 264  * Enumeration of the transfer directions
 265  */
 266 typedef enum
 267 {
 268     CVMX_USB_DIRECTION_OUT,         /**< Data is transferring from Octeon to the device/host */
 269     CVMX_USB_DIRECTION_IN,          /**< Data is transferring from the device/host to Octeon */
 270 } cvmx_usb_direction_t;
 271
 272 /**
 273  * Enumeration of all possible status codes passed to callback
 274  * functions.
 275  */
 276 typedef enum
 277 {
 278     CVMX_USB_COMPLETE_SUCCESS,      /**< The transaction / operation finished without any errors */
 279     CVMX_USB_COMPLETE_SHORT,        /**< FIXME: This is currently not implemented */
 280     CVMX_USB_COMPLETE_CANCEL,       /**< The transaction was canceled while in flight by a user call to cvmx_usb_cancel* */
 281     CVMX_USB_COMPLETE_ERROR,        /**< The transaction aborted with an unexpected error status */
 282     CVMX_USB_COMPLETE_STALL,        /**< The transaction received a USB STALL response from the device */
 283     CVMX_USB_COMPLETE_XACTERR,      /**< The transaction failed with an error from the device even after a number of retries */
 284     CVMX_USB_COMPLETE_DATATGLERR,   /**< The transaction failed with a data toggle error even after a number of retries */
 285     CVMX_USB_COMPLETE_BABBLEERR,    /**< The transaction failed with a babble error */
 286     CVMX_USB_COMPLETE_FRAMEERR,     /**< The transaction failed with a frame error even after a number of retries */
 287 } cvmx_usb_complete_t;
 288
 289 /**
 290  * Structure returned containing the USB port status information.
 291  */
 292 typedef struct
 293 {
 294     uint32_t reserved           : 25;
 295     uint32_t port_enabled       : 1; /**< 1 = Usb port is enabled, 0 = disabled */
 296     uint32_t port_over_current  : 1; /**< 1 = Over current detected, 0 = Over current not detected. Octeon doesn't support over current detection */
 297     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 */
 298     cvmx_usb_speed_t port_speed : 2; /**< Current port speed */
 299     uint32_t connected          : 1; /**< 1 = A device is connected to the port, 0 = No device is connected */
 300     uint32_t connect_change     : 1; /**< 1 = Device connected state changed since the last set status call */
 301 } cvmx_usb_port_status_t;
 302
 303 /**
 304  * This is the structure of a Control packet header
 305  */
 306 typedef union
 307 {
 308     uint64_t u64;
 309     struct
 310     {
 311         uint64_t request_type   : 8;  /**< Bit 7 tells the direction: 1=IN, 0=OUT */
 312         uint64_t request        : 8;  /**< The standard usb request to make */
 313         uint64_t value          : 16; /**< Value parameter for the request in little endian format */
 314         uint64_t index          : 16; /**< Index for the request in little endian format */
 315         uint64_t length         : 16; /**< Length of the data associated with this request in little endian format */
 316     } s;
 317 } cvmx_usb_control_header_t;
 318
 319 /**
 320  * Descriptor for Isochronous packets
 321  */
 322 typedef struct
 323 {
 324     int offset;                     /**< This is the offset in bytes into the main buffer where this data is stored */
 325     int length;                     /**< This is the length in bytes of the data */
 326     cvmx_usb_complete_t status;     /**< This is the status of this individual packet transfer */
 327 } cvmx_usb_iso_packet_t;
 328
 329 /**
 330  * Possible callback reasons for the USB API.
 331  */
 332 typedef enum
 333 {
 334     CVMX_USB_CALLBACK_TRANSFER_COMPLETE,
 335                                     /**< A callback of this type is called when a submitted transfer
 336                                         completes. The completion callback will be called even if the
 337                                         transfer fails or is canceled. The status parameter will
 338                                         contain details of why he callback was called. */
 339     CVMX_USB_CALLBACK_PORT_CHANGED, /**< The status of the port changed. For example, someone may have
 340                                         plugged a device in. The status parameter contains
 341                                         CVMX_USB_COMPLETE_SUCCESS. Use cvmx_usb_get_status() to get
 342                                         the new port status. */
 343     __CVMX_USB_CALLBACK_END         /**< Do not use. Used internally for array bounds */
 344 } cvmx_usb_callback_t;
 345
 346 /**
 347  * USB state internal data. The contents of this structure
 348  * may change in future SDKs. No data in it should be referenced
 349  * by user's of this API.
 350  */
 351 typedef struct
 352 {
 353     char data[65536];
 354 } cvmx_usb_state_t;
 355
 356 /**
 357  * USB callback functions are always of the following type.
 358  * The parameters are as follows:
 359  *      - state = USB device state populated by
 360  *        cvmx_usb_initialize().
 361  *      - reason = The cvmx_usb_callback_t used to register
 362  *        the callback.
 363  *      - status = The cvmx_usb_complete_t representing the
 364  *        status code of a transaction.
 365  *      - pipe_handle = The Pipe that caused this callback, or
 366  *        -1 if this callback wasn't associated with a pipe.
 367  *      - submit_handle = Transfer submit handle causing this
 368  *        callback, or -1 if this callback wasn't associated
 369  *        with a transfer.
 370  *      - Actual number of bytes transfer.
 371  *      - user_data = The user pointer supplied to the
 372  *        function cvmx_usb_submit() or
 373  *        cvmx_usb_register_callback() */
 374 typedef void (*cvmx_usb_callback_func_t)(cvmx_usb_state_t *state,
 375                                          cvmx_usb_callback_t reason,
 376                                          cvmx_usb_complete_t status,
 377                                          int pipe_handle, int submit_handle,
 378                                          int bytes_transferred, void *user_data);
 379
 380 /**
 381  * Flags to pass the initialization function.
 382  */
 383 typedef enum
 384 {
 385     CVMX_USB_INITIALIZE_FLAGS_CLOCK_XO_XI = 1<<0,       /**< The USB port uses a 12MHz crystal as clock source
 386                                                             at USB_XO and USB_XI. */
 387     CVMX_USB_INITIALIZE_FLAGS_CLOCK_XO_GND = 1<<1,      /**< The USB port uses 12/24/48MHz 2.5V board clock
 388                                                             source at USB_XO. USB_XI should be tied to GND.*/
 389     CVMX_USB_INITIALIZE_FLAGS_CLOCK_AUTO = 0,           /**< Automatically determine clock type based on function
 390                                                              in cvmx-helper-board.c. */
 391     CVMX_USB_INITIALIZE_FLAGS_CLOCK_MHZ_MASK  = 3<<3,       /**< Mask for clock speed field */
 392     CVMX_USB_INITIALIZE_FLAGS_CLOCK_12MHZ = 1<<3,       /**< Speed of reference clock or crystal */
 393     CVMX_USB_INITIALIZE_FLAGS_CLOCK_24MHZ = 2<<3,       /**< Speed of reference clock */
 394     CVMX_USB_INITIALIZE_FLAGS_CLOCK_48MHZ = 3<<3,       /**< Speed of reference clock */
 395     /* Bits 3-4 used to encode the clock frequency */
 396     CVMX_USB_INITIALIZE_FLAGS_NO_DMA = 1<<5,            /**< Disable DMA and used polled IO for data transfer use for the USB  */
 397 } cvmx_usb_initialize_flags_t;
 398
 399 /**
 400  * Flags for passing when a pipe is created. Currently no flags
 401  * need to be passed.
 402  */
 403 typedef enum
 404 {
 405     __CVMX_USB_PIPE_FLAGS_OPEN = 1<<16,         /**< Used internally to determine if a pipe is open. Do not use */
 406     __CVMX_USB_PIPE_FLAGS_SCHEDULED = 1<<17,    /**< Used internally to determine if a pipe is actively using hardware. Do not use */
 407     __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 */
 408 } cvmx_usb_pipe_flags_t;
 409
 410 extern int cvmx_usb_get_num_ports(void);
 411 extern int cvmx_usb_initialize(cvmx_usb_state_t *state, int usb_port_number,
 412                                cvmx_usb_initialize_flags_t flags);
 413 extern int cvmx_usb_shutdown(cvmx_usb_state_t *state);
 414 extern int cvmx_usb_enable(cvmx_usb_state_t *state);
 415 extern int cvmx_usb_disable(cvmx_usb_state_t *state);
 416 extern cvmx_usb_port_status_t cvmx_usb_get_status(cvmx_usb_state_t *state);
 417 extern void cvmx_usb_set_status(cvmx_usb_state_t *state, cvmx_usb_port_status_t port_status);
 418 extern int cvmx_usb_open_pipe(cvmx_usb_state_t *state,
 419                               cvmx_usb_pipe_flags_t flags,
 420                               int device_addr, int endpoint_num,
 421                               cvmx_usb_speed_t device_speed, int max_packet,
 422                               cvmx_usb_transfer_t transfer_type,
 423                               cvmx_usb_direction_t transfer_dir, int interval,
 424                               int multi_count, int hub_device_addr,
 425                               int hub_port);
 426 extern int cvmx_usb_submit_bulk(cvmx_usb_state_t *state, int pipe_handle,
 427                                 uint64_t buffer, int buffer_length,
 428                                 cvmx_usb_callback_func_t callback,
 429                                 void *user_data);
 430 extern int cvmx_usb_submit_interrupt(cvmx_usb_state_t *state, int pipe_handle,
 431                                      uint64_t buffer, int buffer_length,
 432                                      cvmx_usb_callback_func_t callback,
 433                                      void *user_data);
 434 extern int cvmx_usb_submit_control(cvmx_usb_state_t *state, int pipe_handle,
 435                                    uint64_t control_header,
 436                                    uint64_t buffer, int buffer_length,
 437                                    cvmx_usb_callback_func_t callback,
 438                                    void *user_data);
 439
 440 /**
 441  * Flags to pass the cvmx_usb_submit_isochronous() function.
 442  */
 443 typedef enum
 444 {
 445     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 */
 446     CVMX_USB_ISOCHRONOUS_FLAGS_ASAP = 1<<1,         /**< Schedule the transaction as soon as possible */
 447 } cvmx_usb_isochronous_flags_t;
 448
 449 extern int cvmx_usb_submit_isochronous(cvmx_usb_state_t *state, int pipe_handle,
 450                                        int start_frame, int flags,
 451                                        int number_packets,
 452                                        cvmx_usb_iso_packet_t packets[],
 453                                        uint64_t buffer, int buffer_length,
 454                                        cvmx_usb_callback_func_t callback,
 455                                        void *user_data);
 456 extern int cvmx_usb_cancel(cvmx_usb_state_t *state, int pipe_handle,
 457                            int submit_handle);
 458 extern int cvmx_usb_cancel_all(cvmx_usb_state_t *state, int pipe_handle);
 459 extern int cvmx_usb_close_pipe(cvmx_usb_state_t *state, int pipe_handle);
 460 extern int cvmx_usb_register_callback(cvmx_usb_state_t *state,
 461                                       cvmx_usb_callback_t reason,
 462                                       cvmx_usb_callback_func_t callback,
 463                                       void *user_data);
 464 extern int cvmx_usb_get_frame_number(cvmx_usb_state_t *state);
 465 extern int cvmx_usb_poll(cvmx_usb_state_t *state);
 466
 467 #endif  /* __CVMX_USB_H__ */