cvmx-usb.h revision 256281
1/***********************license start*************** 2 * Copyright (c) 2003-2010 Cavium Inc. (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 Inc. 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 INC. 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. As an example, the following 221 * code is used under Linux for some of the basic hub control 222 * messages. 223 * 224 * @code 225 * static int octeon_usb_hub_control(struct usb_hcd *hcd, u16 typeReq, u16 wValue, u16 wIndex, char *buf, u16 wLength) 226 * { 227 * cvmx_usb_state_t *usb = (cvmx_usb_state_t *)hcd->hcd_priv; 228 * cvmx_usb_port_status_t usb_port_status; 229 * int port_status; 230 * struct usb_hub_descriptor *desc; 231 * unsigned long flags; 232 * 233 * switch (typeReq) 234 * { 235 * case ClearHubFeature: 236 * DEBUG_ROOT_HUB("OcteonUSB: ClearHubFeature\n"); 237 * switch (wValue) 238 * { 239 * case C_HUB_LOCAL_POWER: 240 * case C_HUB_OVER_CURRENT: 241 * // Nothing required here 242 * break; 243 * default: 244 * return -EINVAL; 245 * } 246 * break; 247 * case ClearPortFeature: 248 * DEBUG_ROOT_HUB("OcteonUSB: ClearPortFeature"); 249 * if (wIndex != 1) 250 * { 251 * DEBUG_ROOT_HUB(" INVALID\n"); 252 * return -EINVAL; 253 * } 254 * 255 * switch (wValue) 256 * { 257 * case USB_PORT_FEAT_ENABLE: 258 * DEBUG_ROOT_HUB(" ENABLE"); 259 * local_irq_save(flags); 260 * cvmx_usb_disable(usb); 261 * local_irq_restore(flags); 262 * break; 263 * case USB_PORT_FEAT_SUSPEND: 264 * DEBUG_ROOT_HUB(" SUSPEND"); 265 * // Not supported on Octeon 266 * break; 267 * case USB_PORT_FEAT_POWER: 268 * DEBUG_ROOT_HUB(" POWER"); 269 * // Not supported on Octeon 270 * break; 271 * case USB_PORT_FEAT_INDICATOR: 272 * DEBUG_ROOT_HUB(" INDICATOR"); 273 * // Port inidicator not supported 274 * break; 275 * case USB_PORT_FEAT_C_CONNECTION: 276 * DEBUG_ROOT_HUB(" C_CONNECTION"); 277 * // Clears drivers internal connect status change flag 278 * cvmx_usb_set_status(usb, cvmx_usb_get_status(usb)); 279 * break; 280 * case USB_PORT_FEAT_C_RESET: 281 * DEBUG_ROOT_HUB(" C_RESET"); 282 * // Clears the driver's internal Port Reset Change flag 283 * cvmx_usb_set_status(usb, cvmx_usb_get_status(usb)); 284 * break; 285 * case USB_PORT_FEAT_C_ENABLE: 286 * DEBUG_ROOT_HUB(" C_ENABLE"); 287 * // Clears the driver's internal Port Enable/Disable Change flag 288 * cvmx_usb_set_status(usb, cvmx_usb_get_status(usb)); 289 * break; 290 * case USB_PORT_FEAT_C_SUSPEND: 291 * DEBUG_ROOT_HUB(" C_SUSPEND"); 292 * // Clears the driver's internal Port Suspend Change flag, 293 * which is set when resume signaling on the host port is 294 * complete 295 * break; 296 * case USB_PORT_FEAT_C_OVER_CURRENT: 297 * DEBUG_ROOT_HUB(" C_OVER_CURRENT"); 298 * // Clears the driver's overcurrent Change flag 299 * cvmx_usb_set_status(usb, cvmx_usb_get_status(usb)); 300 * break; 301 * default: 302 * DEBUG_ROOT_HUB(" UNKNOWN\n"); 303 * return -EINVAL; 304 * } 305 * DEBUG_ROOT_HUB("\n"); 306 * break; 307 * case GetHubDescriptor: 308 * DEBUG_ROOT_HUB("OcteonUSB: GetHubDescriptor\n"); 309 * desc = (struct usb_hub_descriptor *)buf; 310 * desc->bDescLength = 9; 311 * desc->bDescriptorType = 0x29; 312 * desc->bNbrPorts = 1; 313 * desc->wHubCharacteristics = 0x08; 314 * desc->bPwrOn2PwrGood = 1; 315 * desc->bHubContrCurrent = 0; 316 * desc->bitmap[0] = 0; 317 * desc->bitmap[1] = 0xff; 318 * break; 319 * case GetHubStatus: 320 * DEBUG_ROOT_HUB("OcteonUSB: GetHubStatus\n"); 321 * *(__le32 *)buf = 0; 322 * break; 323 * case GetPortStatus: 324 * DEBUG_ROOT_HUB("OcteonUSB: GetPortStatus"); 325 * if (wIndex != 1) 326 * { 327 * DEBUG_ROOT_HUB(" INVALID\n"); 328 * return -EINVAL; 329 * } 330 * 331 * usb_port_status = cvmx_usb_get_status(usb); 332 * port_status = 0; 333 * 334 * if (usb_port_status.connect_change) 335 * { 336 * port_status |= (1 << USB_PORT_FEAT_C_CONNECTION); 337 * DEBUG_ROOT_HUB(" C_CONNECTION"); 338 * } 339 * 340 * if (usb_port_status.port_enabled) 341 * { 342 * port_status |= (1 << USB_PORT_FEAT_C_ENABLE); 343 * DEBUG_ROOT_HUB(" C_ENABLE"); 344 * } 345 * 346 * if (usb_port_status.connected) 347 * { 348 * port_status |= (1 << USB_PORT_FEAT_CONNECTION); 349 * DEBUG_ROOT_HUB(" CONNECTION"); 350 * } 351 * 352 * if (usb_port_status.port_enabled) 353 * { 354 * port_status |= (1 << USB_PORT_FEAT_ENABLE); 355 * DEBUG_ROOT_HUB(" ENABLE"); 356 * } 357 * 358 * if (usb_port_status.port_over_current) 359 * { 360 * port_status |= (1 << USB_PORT_FEAT_OVER_CURRENT); 361 * DEBUG_ROOT_HUB(" OVER_CURRENT"); 362 * } 363 * 364 * if (usb_port_status.port_powered) 365 * { 366 * port_status |= (1 << USB_PORT_FEAT_POWER); 367 * DEBUG_ROOT_HUB(" POWER"); 368 * } 369 * 370 * if (usb_port_status.port_speed == CVMX_USB_SPEED_HIGH) 371 * { 372 * port_status |= (1 << USB_PORT_FEAT_HIGHSPEED); 373 * DEBUG_ROOT_HUB(" HIGHSPEED"); 374 * } 375 * else if (usb_port_status.port_speed == CVMX_USB_SPEED_LOW) 376 * { 377 * port_status |= (1 << USB_PORT_FEAT_LOWSPEED); 378 * DEBUG_ROOT_HUB(" LOWSPEED"); 379 * } 380 * 381 * *((__le32 *)buf) = cpu_to_le32(port_status); 382 * DEBUG_ROOT_HUB("\n"); 383 * break; 384 * case SetHubFeature: 385 * DEBUG_ROOT_HUB("OcteonUSB: SetHubFeature\n"); 386 * // No HUB features supported 387 * break; 388 * case SetPortFeature: 389 * DEBUG_ROOT_HUB("OcteonUSB: SetPortFeature"); 390 * if (wIndex != 1) 391 * { 392 * DEBUG_ROOT_HUB(" INVALID\n"); 393 * return -EINVAL; 394 * } 395 * 396 * switch (wValue) 397 * { 398 * case USB_PORT_FEAT_SUSPEND: 399 * DEBUG_ROOT_HUB(" SUSPEND\n"); 400 * return -EINVAL; 401 * case USB_PORT_FEAT_POWER: 402 * DEBUG_ROOT_HUB(" POWER\n"); 403 * return -EINVAL; 404 * case USB_PORT_FEAT_RESET: 405 * DEBUG_ROOT_HUB(" RESET\n"); 406 * local_irq_save(flags); 407 * cvmx_usb_disable(usb); 408 * if (cvmx_usb_enable(usb)) 409 * DEBUG_ERROR("Failed to enable the port\n"); 410 * local_irq_restore(flags); 411 * return 0; 412 * case USB_PORT_FEAT_INDICATOR: 413 * DEBUG_ROOT_HUB(" INDICATOR\n"); 414 * // Not supported 415 * break; 416 * default: 417 * DEBUG_ROOT_HUB(" UNKNOWN\n"); 418 * return -EINVAL; 419 * } 420 * break; 421 * default: 422 * DEBUG_ROOT_HUB("OcteonUSB: Unknown root hub request\n"); 423 * return -EINVAL; 424 * } 425 * return 0; 426 * } 427 * @endcode 428 * 429 * <h2>Interrupts</h2> 430 * 431 * If you plan on using usb interrupts, cvmx_usb_poll() must be 432 * called on every usb interrupt. It will read the usb state, 433 * call any needed callbacks, and schedule transactions as 434 * needed. Your device driver needs only to hookup an interrupt 435 * handler and call cvmx_usb_poll(). Octeon's usb port 0 causes 436 * CIU bit CIU_INT*_SUM0[USB] to be set (bit 56). For port 1, 437 * CIU bit CIU_INT_SUM1[USB1] is set (bit 17). How these bits 438 * are turned into interrupt numbers is operating system 439 * specific. For Linux, there are the convenient defines 440 * OCTEON_IRQ_USB0 and OCTEON_IRQ_USB1 for the IRQ numbers. 441 * 442 * If you aren't using interrupts, simple call cvmx_usb_poll() 443 * in your main processing loop. 444 * 445 * <hr>$Revision: 32636 $<hr> 446 */ 447 448#ifndef __CVMX_USB_H__ 449#define __CVMX_USB_H__ 450 451#ifdef __cplusplus 452extern "C" { 453#endif 454 455/** 456 * Enumerations representing the status of function calls. 457 */ 458typedef enum 459{ 460 CVMX_USB_SUCCESS = 0, /**< There were no errors */ 461 CVMX_USB_INVALID_PARAM = -1, /**< A parameter to the function was invalid */ 462 CVMX_USB_NO_MEMORY = -2, /**< Insufficient resources were available for the request */ 463 CVMX_USB_BUSY = -3, /**< The resource is busy and cannot service the request */ 464 CVMX_USB_TIMEOUT = -4, /**< Waiting for an action timed out */ 465 CVMX_USB_INCORRECT_MODE = -5, /**< The function call doesn't work in the current USB 466 mode. This happens when host only functions are 467 called in device mode or vice versa */ 468} cvmx_usb_status_t; 469 470/** 471 * Enumerations representing the possible USB device speeds 472 */ 473typedef enum 474{ 475 CVMX_USB_SPEED_HIGH = 0, /**< Device is operation at 480Mbps */ 476 CVMX_USB_SPEED_FULL = 1, /**< Device is operation at 12Mbps */ 477 CVMX_USB_SPEED_LOW = 2, /**< Device is operation at 1.5Mbps */ 478} cvmx_usb_speed_t; 479 480/** 481 * Enumeration representing the possible USB transfer types. 482 */ 483typedef enum 484{ 485 CVMX_USB_TRANSFER_CONTROL = 0, /**< USB transfer type control for hub and status transfers */ 486 CVMX_USB_TRANSFER_ISOCHRONOUS = 1, /**< USB transfer type isochronous for low priority periodic transfers */ 487 CVMX_USB_TRANSFER_BULK = 2, /**< USB transfer type bulk for large low priority transfers */ 488 CVMX_USB_TRANSFER_INTERRUPT = 3, /**< USB transfer type interrupt for high priority periodic transfers */ 489} cvmx_usb_transfer_t; 490 491/** 492 * Enumeration of the transfer directions 493 */ 494typedef enum 495{ 496 CVMX_USB_DIRECTION_OUT, /**< Data is transferring from Octeon to the device/host */ 497 CVMX_USB_DIRECTION_IN, /**< Data is transferring from the device/host to Octeon */ 498} cvmx_usb_direction_t; 499 500/** 501 * Enumeration of all possible status codes passed to callback 502 * functions. 503 */ 504typedef enum 505{ 506 CVMX_USB_COMPLETE_SUCCESS, /**< The transaction / operation finished without any errors */ 507 CVMX_USB_COMPLETE_SHORT, /**< FIXME: This is currently not implemented */ 508 CVMX_USB_COMPLETE_CANCEL, /**< The transaction was canceled while in flight by a user call to cvmx_usb_cancel* */ 509 CVMX_USB_COMPLETE_ERROR, /**< The transaction aborted with an unexpected error status */ 510 CVMX_USB_COMPLETE_STALL, /**< The transaction received a USB STALL response from the device */ 511 CVMX_USB_COMPLETE_XACTERR, /**< The transaction failed with an error from the device even after a number of retries */ 512 CVMX_USB_COMPLETE_DATATGLERR, /**< The transaction failed with a data toggle error even after a number of retries */ 513 CVMX_USB_COMPLETE_BABBLEERR, /**< The transaction failed with a babble error */ 514 CVMX_USB_COMPLETE_FRAMEERR, /**< The transaction failed with a frame error even after a number of retries */ 515} cvmx_usb_complete_t; 516 517/** 518 * Structure returned containing the USB port status information. 519 */ 520typedef struct 521{ 522 uint32_t reserved : 25; 523 uint32_t port_enabled : 1; /**< 1 = Usb port is enabled, 0 = disabled */ 524 uint32_t port_over_current : 1; /**< 1 = Over current detected, 0 = Over current not detected. Octeon doesn't support over current detection */ 525 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 */ 526 cvmx_usb_speed_t port_speed : 2; /**< Current port speed */ 527 uint32_t connected : 1; /**< 1 = A device is connected to the port, 0 = No device is connected */ 528 uint32_t connect_change : 1; /**< 1 = Device connected state changed since the last set status call */ 529} cvmx_usb_port_status_t; 530 531/** 532 * This is the structure of a Control packet header 533 */ 534typedef union 535{ 536 uint64_t u64; 537 struct 538 { 539 uint64_t request_type : 8; /**< Bit 7 tells the direction: 1=IN, 0=OUT */ 540 uint64_t request : 8; /**< The standard usb request to make */ 541 uint64_t value : 16; /**< Value parameter for the request in little endian format */ 542 uint64_t index : 16; /**< Index for the request in little endian format */ 543 uint64_t length : 16; /**< Length of the data associated with this request in little endian format */ 544 } s; 545} cvmx_usb_control_header_t; 546 547/** 548 * Descriptor for Isochronous packets 549 */ 550typedef struct 551{ 552 int offset; /**< This is the offset in bytes into the main buffer where this data is stored */ 553 int length; /**< This is the length in bytes of the data */ 554 cvmx_usb_complete_t status; /**< This is the status of this individual packet transfer */ 555} cvmx_usb_iso_packet_t; 556 557/** 558 * Possible callback reasons for the USB API. 559 */ 560typedef enum 561{ 562 CVMX_USB_CALLBACK_TRANSFER_COMPLETE, 563 /**< A callback of this type is called when a submitted transfer 564 completes. The completion callback will be called even if the 565 transfer fails or is canceled. The status parameter will 566 contain details of why he callback was called. */ 567 CVMX_USB_CALLBACK_PORT_CHANGED, /**< The status of the port changed. For example, someone may have 568 plugged a device in. The status parameter contains 569 CVMX_USB_COMPLETE_SUCCESS. Use cvmx_usb_get_status() to get 570 the new port status. */ 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 */ 579typedef 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() */ 602typedef 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 */ 611typedef 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_CLOCK_MHZ_MASK = 3<<3, /**< Mask for clock speed field */ 620 CVMX_USB_INITIALIZE_FLAGS_CLOCK_12MHZ = 1<<3, /**< Speed of reference clock or crystal */ 621 CVMX_USB_INITIALIZE_FLAGS_CLOCK_24MHZ = 2<<3, /**< Speed of reference clock */ 622 CVMX_USB_INITIALIZE_FLAGS_CLOCK_48MHZ = 3<<3, /**< Speed of reference clock */ 623 /* Bits 3-4 used to encode the clock frequency */ 624 CVMX_USB_INITIALIZE_FLAGS_NO_DMA = 1<<5, /**< Disable DMA and used polled IO for data transfer use for the USB */ 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 */ 637typedef 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 */ 655extern 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 */ 675extern 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 */ 690extern 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 */ 702extern 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 */ 716extern 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 */ 732extern 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 */ 746extern 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 standard 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 standard 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 */ 804extern 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 */ 844extern 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 */ 880extern 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 */ 920extern 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 */ 929typedef 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 */ 980extern 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 */ 1005extern 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 */ 1021extern 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 */ 1036extern 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 */ 1051extern 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 */ 1065extern 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 */ 1079extern cvmx_usb_status_t cvmx_usb_poll(cvmx_usb_state_t *state); 1080 1081/* 1082 * The FreeBSD host driver uses these functions to manipulate the toggle to deal 1083 * more easily with endpoint management. 1084 */ 1085extern void cvmx_usb_set_toggle(cvmx_usb_state_t *state, int endpoint_num, int toggle); 1086extern int cvmx_usb_get_toggle(cvmx_usb_state_t *state, int endpoint_num); 1087 1088#ifdef __cplusplus 1089} 1090#endif 1091 1092#endif /* __CVMX_USB_H__ */ 1093