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 55extern "C" { 56#endif 57 58typedef 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 66typedef 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 73typedef 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 84typedef 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 100typedef void (*cvmx_usbd_callback_func_t)(cvmx_usbd_callback_t reason, int endpoint_num, int bytes_transferred, void *user_data); 101 102typedef 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 */ 130int 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 */ 141int 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 */ 152int 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 */ 163int 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 */ 176int 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 */ 189int 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 */ 199int 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 */ 208void 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 */ 218cvmx_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 */ 227void 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 */ 246int 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 */ 260int 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 */ 279int 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 */ 293int 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 301