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

   1 #ifndef __CVMX_USBD_H__
   2 #define __CVMX_USBD_H__
   3 /***********************license start***************
   4  * Copyright (c) 2003-2010  Cavium Inc. (support@cavium.com). All rights
   5  * reserved.
   6  *
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions are
  10  * met:
  11  *
  12  *   * Redistributions of source code must retain the above copyright
  13  *     notice, this list of conditions and the following disclaimer.
  14  *
  15  *   * Redistributions in binary form must reproduce the above
  16  *     copyright notice, this list of conditions and the following
  17  *     disclaimer in the documentation and/or other materials provided
  18  *     with the distribution.
  19
  20  *   * Neither the name of Cavium Inc. nor the names of
  21  *     its contributors may be used to endorse or promote products
  22  *     derived from this software without specific prior written
  23  *     permission.
  24
  25  * This Software, including technical data, may be subject to U.S. export  control
  26  * laws, including the U.S. Export Administration Act and its  associated
  27  * regulations, and may be subject to export or import  regulations in other
  28  * countries.
  29
  30  * TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS"
  31  * AND WITH ALL FAULTS AND CAVIUM INC. MAKES NO PROMISES, REPRESENTATIONS OR
  32  * WARRANTIES, EITHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, WITH RESPECT TO
  33  * THE SOFTWARE, INCLUDING ITS CONDITION, ITS CONFORMITY TO ANY REPRESENTATION OR
  34  * DESCRIPTION, OR THE EXISTENCE OF ANY LATENT OR PATENT DEFECTS, AND CAVIUM
  35  * SPECIFICALLY DISCLAIMS ALL IMPLIED (IF ANY) WARRANTIES OF TITLE,
  36  * MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR A PARTICULAR PURPOSE, LACK OF
  37  * VIRUSES, ACCURACY OR COMPLETENESS, QUIET ENJOYMENT, QUIET POSSESSION OR
  38  * CORRESPONDENCE TO DESCRIPTION. THE ENTIRE  RISK ARISING OUT OF USE OR
  39  * PERFORMANCE OF THE SOFTWARE LIES WITH YOU.
  40  ***********************license end**************************************/
  41
  42
  43 /**
  44  * @file
  45  *
  46  * "cvmx-usbd.h" defines a set of low level USB functions to help developers
  47  * create Octeon USB devices for various operating systems. These functions
  48  * provide a generic API to the Octeon USB blocks, hiding the internal hardware
  49  * specific operations.
  50  *
  51  * <hr>$Revision: 32636 $<hr>
  52  */
  53
  54 #ifdef  __cplusplus
  55 extern "C" {
  56 #endif
  57
  58 typedef enum
  59 {
  60     CVMX_USBD_TRANSFER_CONTROL = 0,
  61     CVMX_USBD_TRANSFER_ISOCHRONOUS = 1,
  62     CVMX_USBD_TRANSFER_BULK = 2,
  63     CVMX_USBD_TRANSFER_INTERRUPT = 3,
  64 } cvmx_usbd_transfer_t;
  65
  66 typedef enum
  67 {
  68     CVMX_USBD_SPEED_HIGH = 0,
  69     CVMX_USBD_SPEED_FULL = 1,
  70     CVMX_USBD_SPEED_LOW = 2,
  71 } cvmx_usbd_speed_t;
  72
  73 typedef enum
  74 {
  75     CVMX_USBD_CALLBACK_SUSPEND,
  76     CVMX_USBD_CALLBACK_RESET,
  77     CVMX_USBD_CALLBACK_ENUM_COMPLETE,
  78     CVMX_USBD_CALLBACK_DEVICE_SETUP,
  79     CVMX_USBD_CALLBACK_IN_COMPLETE,
  80     CVMX_USBD_CALLBACK_OUT_COMPLETE,
  81     __CVMX_USBD_CALLBACK_END
  82 } cvmx_usbd_callback_t;
  83
  84 typedef enum
  85 {
  86     CVMX_USBD_INITIALIZE_FLAGS_CLOCK_XO_XI = 1<<0,       /**< The USB port uses a 12MHz crystal as clock source
  87                                                             at USB_XO and USB_XI. */
  88     CVMX_USBD_INITIALIZE_FLAGS_CLOCK_XO_GND = 1<<1,      /**< The USB port uses 12/24/48MHz 2.5V board clock
  89                                                             source at USB_XO. USB_XI should be tied to GND.*/
  90     CVMX_USBD_INITIALIZE_FLAGS_CLOCK_AUTO = 0,           /**< Automatically determine clock type based on function
  91                                                              in cvmx-helper-board.c. */
  92     CVMX_USBD_INITIALIZE_FLAGS_CLOCK_MHZ_MASK  = 3<<3,       /**< Mask for clock speed field */
  93     CVMX_USBD_INITIALIZE_FLAGS_CLOCK_12MHZ = 1<<3,       /**< Speed of reference clock or crystal */
  94     CVMX_USBD_INITIALIZE_FLAGS_CLOCK_24MHZ = 2<<3,       /**< Speed of reference clock */
  95     CVMX_USBD_INITIALIZE_FLAGS_CLOCK_48MHZ = 3<<3,       /**< Speed of reference clock */
  96     /* Bits 3-4 used to encode the clock frequency */
  97     CVMX_USBD_INITIALIZE_FLAGS_DEBUG = 1<<16
  98 } cvmx_usbd_initialize_flags_t;
  99
 100 typedef void (*cvmx_usbd_callback_func_t)(cvmx_usbd_callback_t reason, int endpoint_num, int bytes_transferred, void *user_data);
 101
 102 typedef struct
 103 {
 104     int init_flags;
 105     int index;
 106     cvmx_usbd_callback_func_t callback[__CVMX_USBD_CALLBACK_END];
 107     void *callback_data[__CVMX_USBD_CALLBACK_END];
 108     struct {
 109         int buffer_length;
 110     } endpoint[16];
 111 } cvmx_usbd_state_t;
 112
 113 /**
 114  * Initialize a USB port for use. This must be called before any
 115  * other access to the Octeon USB port is made. The port starts
 116  * off in the disabled state.
 117  *
 118  * @param usb    Pointer to an empty cvmx_usbd_state_t structure
 119  *               that will be populated by the initialize call.
 120  *               This structure is then passed to all other USB
 121  *               functions.
 122  * @param usb_port_number
 123  *               Which Octeon USB port to initialize.
 124  * @param flags  Flags to control hardware initialization. See
 125  *               cvmx_usbd_initialize_flags_t for the flag
 126  *               definitions. Some flags are mandatory.
 127  *
 128  * @return Zero or a negative on error.
 129  */
 130 int cvmx_usbd_initialize(cvmx_usbd_state_t *usb, int usb_port_number,
 131     cvmx_usbd_initialize_flags_t flags);
 132
 133 /**
 134  * Shutdown a USB port after a call to cvmx_usbd_initialize().
 135  *
 136  * @param usb    USB device state populated by
 137  *               cvmx_usbd_initialize().
 138  *
 139  * @return Zero or a negative on error.
 140  */
 141 int cvmx_usbd_shutdown(cvmx_usbd_state_t *usb);
 142
 143 /**
 144  * Enable a USB port. After this call succeeds, the USB port is
 145  * online and servicing requests.
 146  *
 147  * @param usb  USB device state populated by
 148  *               cvmx_usb_initialize().
 149  *
 150  * @return Zero or negative on error.
 151  */
 152 int cvmx_usbd_enable(cvmx_usbd_state_t *usb);
 153
 154 /**
 155  * Disable a USB port. After this call the USB port will not
 156  * generate data transfers and will not generate events.
 157  *
 158  * @param usb    USB device state populated by
 159  *               cvmx_usb_initialize().
 160  *
 161  * @return Zero or negative on error.
 162  */
 163 int cvmx_usbd_disable(cvmx_usbd_state_t *usb);
 164
 165 /**
 166  * Register a callback function to process USB events
 167  *
 168  * @param usb       USB device state populated by
 169  *                  cvmx_usbd_initialize().
 170  * @param reason    The reason this callback should be called
 171  * @param func      Function to call
 172  * @param user_data User supplied data for the callback
 173  *
 174  * @return Zero on succes, negative on failure
 175  */
 176 int cvmx_usbd_register(cvmx_usbd_state_t *usb, cvmx_usbd_callback_t reason, cvmx_usbd_callback_func_t func, void *user_data);
 177
 178 /**
 179  * Poll the USB block for status and call all needed callback
 180  * handlers. This function is meant to be called in the interrupt
 181  * handler for the USB controller. It can also be called
 182  * periodically in a loop for non-interrupt based operation.
 183  *
 184  * @param usb    USB device state populated by
 185  *               cvmx_usbd_initialize().
 186  *
 187  * @return Zero or negative on error.
 188  */
 189 int cvmx_usbd_poll(cvmx_usbd_state_t *usb);
 190
 191 /**
 192  * Get the current USB address
 193  *
 194  * @param usb    USB device state populated by
 195  *               cvmx_usbd_initialize().
 196  *
 197  * @return The USB address
 198  */
 199 int cvmx_usbd_get_address(cvmx_usbd_state_t *usb);
 200
 201 /**
 202  * Set the current USB address
 203  *
 204  * @param usb     USB device state populated by
 205  *                cvmx_usbd_initialize().
 206  * @param address Address to set
 207  */
 208 void cvmx_usbd_set_address(cvmx_usbd_state_t *usb, int address);
 209
 210 /**
 211  * Get the current USB speed
 212  *
 213  * @param usb    USB device state populated by
 214  *               cvmx_usbd_initialize().
 215  *
 216  * @return The USB speed
 217  */
 218 cvmx_usbd_speed_t cvmx_usbd_get_speed(cvmx_usbd_state_t *usb);
 219
 220 /**
 221  * Set the current USB speed
 222  *
 223  * @param usb    USB device state populated by
 224  *               cvmx_usbd_initialize().
 225  * @param speed  The requested speed
 226  */
 227 void cvmx_usbd_set_speed(cvmx_usbd_state_t *usb, cvmx_usbd_speed_t speed);
 228
 229 /**
 230  * Enable an endpoint to respond to an OUT transaction
 231  *
 232  * @param usb    USB device state populated by
 233  *               cvmx_usbd_initialize().
 234  * @param endpoint_num
 235  *               Endpoint number to enable
 236  * @param transfer_type
 237  *               Transfer type for the endpoint
 238  * @param max_packet_size
 239  *               Maximum packet size for the endpoint
 240  * @param buffer Buffer to receive the data
 241  * @param buffer_length
 242  *               Length of the buffer in bytes
 243  *
 244  * @return Zero on success, negative on failure
 245  */
 246 int cvmx_usbd_out_endpoint_enable(cvmx_usbd_state_t *usb,
 247     int endpoint_num, cvmx_usbd_transfer_t transfer_type,
 248     int max_packet_size, uint64_t buffer, int buffer_length);
 249
 250 /**
 251  * Disable an OUT endpoint
 252  *
 253  * @param usb    USB device state populated by
 254  *               cvmx_usbd_initialize().
 255  * @param endpoint_num
 256  *               Endpoint number to disable
 257  *
 258  * @return Zero on success, negative on failure
 259  */
 260 int cvmx_usbd_out_endpoint_disable(cvmx_usbd_state_t *usb, int endpoint_num);
 261
 262 /**
 263  * Enable an endpoint to respond to an IN transaction
 264  *
 265  * @param usb    USB device state populated by
 266  *               cvmx_usbd_initialize().
 267  * @param endpoint_num
 268  *               Endpoint number to enable
 269  * @param transfer_type
 270  *               Transfer type for the endpoint
 271  * @param max_packet_size
 272  *               Maximum packet size for the endpoint
 273  * @param buffer Buffer to send
 274  * @param buffer_length
 275  *               Length of the buffer in bytes
 276  *
 277  * @return Zero on success, negative on failure
 278  */
 279 int cvmx_usbd_in_endpoint_enable(cvmx_usbd_state_t *usb,
 280     int endpoint_num, cvmx_usbd_transfer_t transfer_type,
 281     int max_packet_size, uint64_t buffer, int buffer_length);
 282
 283 /**
 284  * Disable an IN endpoint
 285  *
 286  * @param usb    USB device state populated by
 287  *               cvmx_usbd_initialize().
 288  * @param endpoint_num
 289  *               Endpoint number to disable
 290  *
 291  * @return Zero on success, negative on failure
 292  */
 293 int cvmx_usbd_in_endpoint_disable(cvmx_usbd_state_t *usb, int endpoint_num);
 294
 295 #ifdef  __cplusplus
 296 }
 297 #endif
 298
 299 #endif /* __CVMX_USBD_H__ */
 300