1 /* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License (the "License"). 6 * You may not use this file except in compliance with the License. 7 * 8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9 * or http://www.opensolaris.org/os/licensing. 10 * See the License for the specific language governing permissions 11 * and limitations under the License. 12 * 13 * When distributing Covered Code, include this CDDL HEADER in each 14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15 * If applicable, add the following below this CDDL HEADER, with the 16 * fields enclosed by brackets "[]" replaced with your own identifying 17 * information: Portions Copyright [yyyy] [name of copyright owner] 18 * 19 * CDDL HEADER END 20 */ 21 /* 22 * Copyright 2009 Sun Microsystems, Inc. All rights reserved. 23 * Use is subject to license terms. 24 * 25 * Copyright 2014 Garrett D'Amore <garrett@damore.org> 26 * Copyright 2019 Joyent, Inc. 27 */ 28 29 #ifndef _SYS_USB_USBAI_H 30 #define _SYS_USB_USBAI_H 31 32 33 #ifdef __cplusplus 34 extern "C" { 35 #endif 36 37 /* This header file is for USBA2.1 */ 38 #define USBA_MAJOR_VER 2 39 #define USBA_MINOR_VER 1 40 41 /* 42 * USBAI: Interfaces Between USBA and Client Driver 43 * 44 * 45 * Universal USB device state management : 46 * 47 * PWRED_DWN---<3----4>--ONLINE---<2-----1>-DISCONNECTED 48 * | ^ | 49 * | 6 | 50 * | | | 51 * | 5 | 52 * | v | 53 * +----5>----------SUSPENDED----<5----7>---+ 54 * 55 * 1 = Device Unplug 56 * 2 = Original Device reconnected 57 * 3 = Device idles for time T & transitions to low power state 58 * 4 = Remote wakeup by device OR Application kicking off IO to device 59 * 5 = Notification to save state prior to DDI_SUSPEND 60 * 6 = Notification to restore state after DDI_RESUME with correct device 61 * 7 = Notification to restore state after DDI_RESUME with device 62 * disconnected or a wrong device 63 * 64 * NOTE: device states 0x80 to 0xff are device specific and can be 65 * used by client drivers 66 */ 67 #define USB_DEV_ONLINE 1 /* device is online */ 68 #define USB_DEV_DISCONNECTED 2 /* indicates disconnect */ 69 #define USB_DEV_SUSPENDED 3 /* DDI_SUSPEND operation */ 70 #define USB_DEV_PWRED_DOWN 4 /* indicates power off state */ 71 72 73 /* 74 * *************************************************************************** 75 * USBA error and status definitions 76 * *************************************************************************** 77 */ 78 79 80 /* 81 * USBA function return values 82 */ 83 #define USB_SUCCESS 0 /* call success */ 84 #define USB_FAILURE -1 /* unspecified USBA or HCD error */ 85 #define USB_NO_RESOURCES -2 /* no resources available */ 86 #define USB_NO_BANDWIDTH -3 /* no bandwidth available */ 87 #define USB_NOT_SUPPORTED -4 /* function not supported by HCD */ 88 #define USB_PIPE_ERROR -5 /* error occured on the pipe */ 89 #define USB_INVALID_PIPE -6 /* pipe handle passed is invalid */ 90 #define USB_NO_FRAME_NUMBER -7 /* frame No or ASAP not specified */ 91 #define USB_INVALID_START_FRAME -8 /* starting USB frame not valid */ 92 #define USB_HC_HARDWARE_ERROR -9 /* usb host controller error */ 93 #define USB_INVALID_REQUEST -10 /* request had invalid values */ 94 #define USB_INVALID_CONTEXT -11 /* sleep flag in interrupt context */ 95 #define USB_INVALID_VERSION -12 /* invalid version specified */ 96 #define USB_INVALID_ARGS -13 /* invalid func args specified */ 97 #define USB_INVALID_PERM -14 /* privileged operation */ 98 #define USB_BUSY -15 /* busy condition */ 99 100 101 /* 102 * USB request completion flags, more than one may be set. 103 * The following flags are returned after a recovery action by 104 * HCD or USBA (autoclearing) or callbacks from pipe_close, 105 * abort, reset, or stop polling. More than one may be set. 106 * 107 * For sync requests, the client should check the request structure 108 * for this flag to determine what has happened. 109 * 110 * All callbacks are queued to preserve order. Note that if a normal callback 111 * uses a kernel thread, order is not guaranteed since each callback may use 112 * its own thread. The next request will be submitted to the 113 * HCD after the threads exits. 114 * 115 * Exception callbacks using a kernel thread may do auto clearing and no 116 * new request will be started until this thread has completed its work. 117 */ 118 typedef enum { 119 USB_CB_NO_INFO = 0x00, /* no exception */ 120 USB_CB_STALL_CLEARED = 0x01, /* func stall cleared */ 121 USB_CB_FUNCTIONAL_STALL = 0x02, /* func stall occurred */ 122 USB_CB_PROTOCOL_STALL = 0x04, /* protocal stall occurred */ 123 USB_CB_RESET_PIPE = 0x10, /* pipe was reset */ 124 USB_CB_ASYNC_REQ_FAILED = 0x80, /* thread couldn't be started */ 125 USB_CB_NO_RESOURCES = 0x100, /* no resources */ 126 USB_CB_SUBMIT_FAILED = 0x200, /* req was queued then submitted */ 127 /* to HCD which rejected it */ 128 USB_CB_INTR_CONTEXT = 0x400 /* Callback is in interrupt context. */ 129 } usb_cb_flags_t; 130 131 132 /* 133 * completion reason 134 * 135 * Set by HCD; only one can be set. 136 */ 137 typedef enum { 138 USB_CR_OK = 0, /* no errors detected */ 139 USB_CR_CRC = 1, /* crc error detected */ 140 USB_CR_BITSTUFFING = 2, /* bit stuffing violation */ 141 USB_CR_DATA_TOGGLE_MM = 3, /* d/t PID did not match */ 142 USB_CR_STALL = 4, /* e/p returned stall PID */ 143 USB_CR_DEV_NOT_RESP = 5, /* device not responding */ 144 USB_CR_PID_CHECKFAILURE = 6, /* check bits on PID failed */ 145 USB_CR_UNEXP_PID = 7, /* receive PID was not valid */ 146 USB_CR_DATA_OVERRUN = 8, /* data size exceeded */ 147 USB_CR_DATA_UNDERRUN = 9, /* less data received */ 148 USB_CR_BUFFER_OVERRUN = 10, /* memory write can't keep up */ 149 USB_CR_BUFFER_UNDERRUN = 11, /* buffer underrun */ 150 USB_CR_TIMEOUT = 12, /* command timed out */ 151 USB_CR_NOT_ACCESSED = 13, /* Not accessed by hardware */ 152 USB_CR_NO_RESOURCES = 14, /* no resources */ 153 USB_CR_UNSPECIFIED_ERR = 15, /* unspecified usba or hcd err */ 154 USB_CR_STOPPED_POLLING = 16, /* intr/isoc IN polling stopped */ 155 USB_CR_PIPE_CLOSING = 17, /* intr/isoc IN pipe closed */ 156 USB_CR_PIPE_RESET = 18, /* intr/isoc IN pipe reset */ 157 USB_CR_NOT_SUPPORTED = 19, /* command not supported */ 158 USB_CR_FLUSHED = 20, /* this request was flushed */ 159 USB_CR_HC_HARDWARE_ERR = 21 /* usb host controller error */ 160 } usb_cr_t; 161 162 163 /* 164 * *************************************************************************** 165 * General definitions, used all over 166 * *************************************************************************** 167 * 168 * A pipe handle is returned by usb_pipe_open() on success for 169 * all pipes except the default pipe which is accessed from 170 * the registration structure. Placed here as forward referenced by 171 * usb_client_dev_data_t below. 172 * 173 * The pipe_handle is opaque to the client driver. 174 */ 175 typedef struct usb_pipe_handle *usb_pipe_handle_t; 176 177 /* 178 * General opaque pointer. 179 */ 180 typedef struct usb_opaque *usb_opaque_t; 181 182 183 /* 184 * USB flags argument to USBA interfaces 185 */ 186 typedef enum { 187 /* do not block until resources are available */ 188 USB_FLAGS_NOSLEEP = 0x0000, 189 /* block until resources are available */ 190 USB_FLAGS_SLEEP = 0x0100, 191 /* reserved */ 192 USB_FLAGS_RESERVED = 0xFE00 193 } usb_flags_t; 194 195 196 /* 197 * *************************************************************************** 198 * Descriptor definitions (USB version and section noted with structure) 199 * *************************************************************************** 200 */ 201 202 203 /* 204 * USB Descriptor Management 205 * 206 * Standard USB descriptors: 207 * 208 * USB devices present their configuration information in response to 209 * a GET_DESCRIPTOR request in a form which is little-endian and, 210 * for multibyte integers, unaligned. It is also position-dependent, 211 * which makes non-sequential access to particular interface or 212 * endpoint data inconvenient. 213 * A GET_DESCRIPTOR request may yield a chunk of data that contains 214 * multiple descriptor types. For example, a GET_DESCRIPTOR request 215 * for a CONFIGURATION descriptor could return the configuration 216 * descriptor followed by an interface descriptor and the relevant 217 * endpoint descriptors. 218 * 219 * usb_get_dev_data() interface provides an easy way to get all 220 * the descriptors and avoids parsing standard descriptors by each 221 * client driver 222 * 223 * usb_dev_descr: 224 * usb device descriptor, refer to USB 2.0/9.6.1, 225 */ 226 typedef struct usb_dev_descr { 227 uint8_t bLength; /* descriptor size */ 228 uint8_t bDescriptorType; /* set to DEVICE */ 229 uint16_t bcdUSB; /* USB spec rel. number in bcd */ 230 uint8_t bDeviceClass; /* class code */ 231 uint8_t bDeviceSubClass; /* sub class code */ 232 uint8_t bDeviceProtocol; /* protocol code */ 233 uint8_t bMaxPacketSize0; /* max pkt size of e/p 0 */ 234 uint16_t idVendor; /* vendor ID */ 235 uint16_t idProduct; /* product ID */ 236 uint16_t bcdDevice; /* device release number in bcd */ 237 uint8_t iManufacturer; /* manufacturing string */ 238 uint8_t iProduct; /* product string */ 239 uint8_t iSerialNumber; /* serial number string index */ 240 uint8_t bNumConfigurations; /* #configs for device */ 241 } usb_dev_descr_t; 242 243 244 /* 245 * USB Device Qualifier Descriptor 246 * 247 * The device_qualifier descriptor describes information about a High 248 * speed capable device that would change if the device were operating 249 * at other (Full) speed. Example: if the device is currently operating 250 * at Full-speed, the device_qualifier returns information about how if 251 * would operate at high-speed and vice-versa. 252 * 253 * usb_dev_qlf_descr: 254 * 255 * usb device qualifier descriptor, refer to USB 2.0/9.6.2 256 */ 257 typedef struct usb_dev_qlf_descr { 258 uint8_t bLength; /* descriptor size */ 259 uint8_t bDescriptorType; /* set to DEVICE */ 260 uint16_t bcdUSB; /* USB spec rel. number in bcd */ 261 uint8_t bDeviceClass; /* class code */ 262 uint8_t bDeviceSubClass; /* sub class code */ 263 uint8_t bDeviceProtocol; /* protocol code */ 264 uint8_t bMaxPacketSize0; /* max pkt size of e/p 0 */ 265 uint8_t bNumConfigurations; /* #configs for device */ 266 uint8_t bReserved; /* reserved field */ 267 } usb_dev_qlf_descr_t; 268 269 270 /* 271 * usb_cfg_descr: 272 * usb configuration descriptor, refer to USB 2.0/9.6.3 273 */ 274 typedef struct usb_cfg_descr { 275 uint8_t bLength; /* descriptor size */ 276 uint8_t bDescriptorType; /* set to CONFIGURATION */ 277 uint16_t wTotalLength; /* total length of data returned */ 278 uint8_t bNumInterfaces; /* # interfaces in config */ 279 uint8_t bConfigurationValue; /* arg for SetConfiguration */ 280 uint8_t iConfiguration; /* configuration string */ 281 uint8_t bmAttributes; /* config characteristics */ 282 uint8_t bMaxPower; /* max pwr consumption */ 283 } usb_cfg_descr_t; 284 285 /* 286 * Default configuration index setting for devices with multiple 287 * configurations. Note the distinction between config index and config 288 * number 289 */ 290 #define USB_DEV_DEFAULT_CONFIG_INDEX 0 291 292 /* 293 * bmAttribute values for Configuration Descriptor 294 */ 295 #define USB_CFG_ATTR_SELFPWR 0x40 296 #define USB_CFG_ATTR_REMOTE_WAKEUP 0x20 297 #define USB_CFG_ATTR_BAT_PWR 0x10 298 299 /* 300 * USB Other Speed Configuration Descriptor 301 * 302 * The other_speed_configuration descriptor describes a configuration of 303 * a High speed capable device if it were operating at its other possible 304 * (Full) speed and vice-versa. 305 * 306 * usb_other_speed_cfg_descr: 307 * usb other speed configuration descriptor, refer to USB 2.0/9.6.4 308 */ 309 typedef struct usb_other_speed_cfg_descr { 310 uint8_t bLength; /* descriptor size */ 311 uint8_t bDescriptorType; /* set to CONFIGURATION */ 312 uint16_t wTotalLength; /* total length of data returned */ 313 uint8_t bNumInterfaces; /* # interfaces in config */ 314 uint8_t bConfigurationValue; /* arg for SetConfiguration */ 315 uint8_t iConfiguration; /* configuration string */ 316 uint8_t bmAttributes; /* config characteristics */ 317 uint8_t bMaxPower; /* max pwr consumption */ 318 } usb_other_speed_cfg_descr_t; 319 320 321 /* 322 * usb_ia_descr: 323 * usb interface association descriptor, refer to USB 2.0 ECN(IAD) 324 */ 325 typedef struct usb_ia_descr { 326 uint8_t bLength; /* descriptor size */ 327 uint8_t bDescriptorType; /* INTERFACE_ASSOCIATION */ 328 uint8_t bFirstInterface; /* 1st interface number */ 329 uint8_t bInterfaceCount; /* number of interfaces */ 330 uint8_t bFunctionClass; /* class code */ 331 uint8_t bFunctionSubClass; /* sub class code */ 332 uint8_t bFunctionProtocol; /* protocol code */ 333 uint8_t iFunction; /* description string */ 334 } usb_ia_descr_t; 335 336 337 /* 338 * usb_if_descr: 339 * usb interface descriptor, refer to USB 2.0/9.6.5 340 */ 341 typedef struct usb_if_descr { 342 uint8_t bLength; /* descriptor size */ 343 uint8_t bDescriptorType; /* set to INTERFACE */ 344 uint8_t bInterfaceNumber; /* interface number */ 345 uint8_t bAlternateSetting; /* alt. interface number */ 346 uint8_t bNumEndpoints; /* # of endpoints */ 347 uint8_t bInterfaceClass; /* class code */ 348 uint8_t bInterfaceSubClass; /* sub class code */ 349 uint8_t bInterfaceProtocol; /* protocol code */ 350 uint8_t iInterface; /* description string */ 351 } usb_if_descr_t; 352 353 354 /* 355 * usb_ep_descr: 356 * usb endpoint descriptor, refer to USB 2.0/9.6.6 357 */ 358 typedef struct usb_ep_descr { 359 uint8_t bLength; /* descriptor size */ 360 uint8_t bDescriptorType; /* set to ENDPOINT */ 361 uint8_t bEndpointAddress; /* address of this e/p */ 362 uint8_t bmAttributes; /* transfer type */ 363 uint16_t wMaxPacketSize; /* maximum packet size */ 364 uint8_t bInterval; /* e/p polling interval */ 365 } usb_ep_descr_t; 366 367 /* 368 * bEndpointAddress masks 369 */ 370 #define USB_EP_NUM_MASK 0x0F /* endpoint number mask */ 371 #define USB_EP_DIR_MASK 0x80 /* direction mask */ 372 #define USB_EP_DIR_OUT 0x00 /* OUT endpoint */ 373 #define USB_EP_DIR_IN 0x80 /* IN endpoint */ 374 375 /* 376 * bmAttribute transfer types for endpoints 377 */ 378 #define USB_EP_ATTR_MASK 0x03 /* transfer type mask */ 379 #define USB_EP_ATTR_CONTROL 0x00 /* control transfer */ 380 #define USB_EP_ATTR_ISOCH 0x01 /* isochronous transfer */ 381 #define USB_EP_ATTR_BULK 0x02 /* bulk transfer */ 382 #define USB_EP_ATTR_INTR 0x03 /* interrupt transfer */ 383 384 /* 385 * bmAttribute synchronization types for endpoints (isochronous only) 386 */ 387 #define USB_EP_SYNC_MASK 0x0C /* synchronization mask */ 388 #define USB_EP_SYNC_NONE 0x00 /* no synchronization */ 389 #define USB_EP_SYNC_ASYNC 0x04 /* asynchronous */ 390 #define USB_EP_SYNC_ADPT 0x08 /* adaptive */ 391 #define USB_EP_SYNC_SYNC 0x0C /* synchronous */ 392 393 /* 394 * bmAttribute synchronization feedback types for endpoints (isochronous only) 395 */ 396 #define USB_EP_USAGE_MASK 0x30 /* sync feedback mask */ 397 #define USB_EP_USAGE_DATA 0x00 /* data endpoint */ 398 #define USB_EP_USAGE_FEED 0x10 /* feedback endpoint */ 399 #define USB_EP_USAGE_IMPL 0x20 /* implicit feedback endpoint */ 400 401 /* 402 * wMaxPacketSize values for endpoints (isoch and interrupt, high speed only) 403 */ 404 #define USB_EP_MAX_PKTSZ_MASK 0x07FF /* Mask for packetsize bits */ 405 #define USB_EP_MAX_XACTS_MASK 0x1800 /* Max Transactns/microframe */ 406 #define USB_EP_MAX_XACTS_SHIFT 11 /* Above is 10 bits from end */ 407 408 /* 409 * Ranges for endpoint parameter values. 410 */ 411 412 /* Min and Max NAK rates for high sped control endpoints. */ 413 #define USB_EP_MIN_HIGH_CONTROL_INTRVL 0 414 #define USB_EP_MAX_HIGH_CONTROL_INTRVL 255 415 416 /* Min and Max NAK rates for high speed bulk endpoints. */ 417 #define USB_EP_MIN_HIGH_BULK_INTRVL 0 418 #define USB_EP_MAX_HIGH_BULK_INTRVL 255 419 420 /* Min and Max polling intervals for low, full speed interrupt endpoints. */ 421 #define USB_EP_MIN_LOW_INTR_INTRVL 1 422 #define USB_EP_MAX_LOW_INTR_INTRVL 255 423 #define USB_EP_MIN_FULL_INTR_INTRVL 1 424 #define USB_EP_MAX_FULL_INTR_INTRVL 255 425 426 /* 427 * Min and Max polling intervals for high speed interrupt endpoints, and for 428 * isochronous endpoints. 429 * Note that the interval is 2**(value-1). See Section 9.6.6 of USB 2.0 spec. 430 */ 431 #define USB_EP_MIN_HIGH_INTR_INTRVL 1 432 #define USB_EP_MAX_HIGH_INTR_INTRVL 16 433 #define USB_EP_MIN_FULL_ISOCH_INTRVL 1 434 #define USB_EP_MAX_FULL_ISOCH_INTRVL 16 435 #define USB_EP_MIN_HIGH_ISOCH_INTRVL 1 436 #define USB_EP_MAX_HIGH_ISOCH_INTRVL 16 437 438 /* 439 * usb_string_descr: 440 * usb string descriptor, refer to USB 2.0/9.6.7 441 */ 442 typedef struct usb_string_descr { 443 uint8_t bLength; /* descr size */ 444 uint8_t bDescriptorType; /* set to STRING */ 445 uint8_t bString[1]; /* variable length unicode */ 446 /* encoded string */ 447 } usb_string_descr_t; 448 449 #define USB_MAXSTRINGLEN 255 /* max string descr length */ 450 451 /* 452 * usb_ep_ss_comp_descr: 453 * USB SuperSpeed endpoints are required to return this descriptor along 454 * with the general endpoint descriptor. Refer to USB 3.1/9.6.7. 455 */ 456 typedef struct usb_ep_ss_comp_descr { 457 uint8_t bLength; /* descriptor size */ 458 uint8_t bDescriptorType; /* USB_DESCR_TYPE_SS_EP_COMP */ 459 uint8_t bMaxBurst; /* max packets per burst */ 460 uint8_t bmAttributes; /* more endpoint attributes */ 461 uint16_t wBytesPerInterval; /* bytes per service interval */ 462 } usb_ep_ss_comp_descr_t; 463 464 #define USB_EP_SS_COMP_ISOC_MULT_MASK 0x03 465 466 /* 467 * *************************************************************************** 468 * Client driver registration with USBA 469 * *************************************************************************** 470 * 471 * The client registers with USBA during attach in two steps 472 * using usb_client_attach() and usb_get_dev_data(). On completion, the 473 * registration data has been initialized. Most data items are 474 * straightforward. Among the items returned in the data is the tree of 475 * parsed descriptors, in dev_cfg; the number of configurations parsed, 476 * in dev_n_cfg; a pointer to the current configuration in the tree, 477 * in dev_curr_cfg; the index of the first valid interface in the 478 * tree, in dev_curr_if, and a parse level that accurately reflects what 479 * is in the tree, in dev_parse_level. 480 */ 481 482 483 /* 484 * *************************************************************************** 485 * Data structures used in the configuration tree 486 * *************************************************************************** 487 */ 488 489 /* 490 * Tree data structure for each configuration in the tree 491 */ 492 typedef struct usb_cfg_data { 493 struct usb_cfg_descr cfg_descr; /* parsed config descr */ 494 struct usb_if_data *cfg_if; /* interfaces for this cfg */ 495 /* indexed by interface num */ 496 struct usb_cvs_data *cfg_cvs; /* class/vendor specific */ 497 /* descrs mod/extend cfg */ 498 char *cfg_str; /* string descriptor */ 499 uint_t cfg_n_if; /* #elements in cfg_if[] */ 500 uint_t cfg_n_cvs; /* #elements in cfg_cvs[] */ 501 uint_t cfg_strsize; /* size of string descr */ 502 } usb_cfg_data_t; 503 504 505 /* 506 * Tree data structure for each alternate interface set 507 * in each represented configuration 508 */ 509 typedef struct usb_if_data { 510 struct usb_alt_if_data *if_alt; /* sparse array of alts */ 511 /* indexed by alt setting */ 512 uint_t if_n_alt; /* #elements in if_alt[] */ 513 } usb_if_data_t; 514 515 516 /* 517 * Tree data structure for each alternate of each alternate interface set 518 */ 519 typedef struct usb_alt_if_data { 520 usb_if_descr_t altif_descr; /* parsed alternate if descr */ 521 struct usb_ep_data *altif_ep; /* endpts for alt if */ 522 /* (not a sparse array */ 523 struct usb_cvs_data *altif_cvs; /* cvs for this alt if */ 524 char *altif_str; /* string descriptor */ 525 uint_t altif_n_ep; /* #elements in altif_ep[] */ 526 uint_t altif_n_cvs; /* #elements in altif_cvs[] */ 527 uint_t altif_strsize; /* size of string descr */ 528 } usb_alt_if_data_t; 529 530 531 /* 532 * Tree data structure for each endpoint of each alternate 533 */ 534 typedef struct usb_ep_data { 535 usb_ep_descr_t ep_descr; /* endpoint descriptor */ 536 struct usb_cvs_data *ep_cvs; /* cv mod/extending this ep */ 537 uint_t ep_n_cvs; /* #elements in ep_cvs[] */ 538 boolean_t ep_ss_valid; 539 usb_ep_ss_comp_descr_t ep_ss_comp; /* superspeed ep desc */ 540 } usb_ep_data_t; 541 542 543 /* 544 * Tree data structure for each class/vendor specific descriptor 545 */ 546 typedef struct usb_cvs_data { 547 uchar_t *cvs_buf; /* raw data of cvs descr */ 548 uint_t cvs_buf_len; /* cvs_buf size */ 549 } usb_cvs_data_t; 550 551 552 /* 553 * Parse_level determines the extent to which the tree is built, the amount 554 * of parsing usb_client_attach() is to do. It has the following values: 555 * 556 * USB_PARSE_LVL_NONE - Build no tree. dev_n_cfg will return 0, dev_cfg 557 * will return NULL, the dev_curr_xxx fields will be 558 * invalid. 559 * USB_PARSE_LVL_IF - Parse configured interface only, if configuration# 560 * and interface properties are set (as when different 561 * interfaces are viewed by the OS as different device 562 * instances). If an OS device instance is set up to 563 * represent an entire physical device, this works 564 * like USB_PARSE_LVL_ALL. 565 * USB_PARSE_LVL_CFG - Parse entire configuration of configured interface 566 * only. This is like USB_PARSE_LVL_IF except entire 567 * configuration is returned. 568 * USB_PARSE_LVL_ALL - Parse entire device (all configurations), even 569 * when driver is bound to a single interface of a 570 * single configuration. 571 */ 572 typedef enum { 573 USB_PARSE_LVL_NONE = 0, 574 USB_PARSE_LVL_IF = 1, 575 USB_PARSE_LVL_CFG = 2, 576 USB_PARSE_LVL_ALL = 3 577 } usb_reg_parse_lvl_t; 578 579 580 /* 581 * Registration data returned by usb_get_dev_data(). Configuration tree roots 582 * are returned in dev_cfg array. 583 */ 584 typedef struct usb_client_dev_data { 585 usb_pipe_handle_t dev_default_ph; /* default pipe handle */ 586 ddi_iblock_cookie_t dev_iblock_cookie; /* for mutex_init's */ 587 struct usb_dev_descr *dev_descr; /* cooked device descriptor */ 588 char *dev_mfg; /* manufacturing ID */ 589 char *dev_product; /* product ID */ 590 char *dev_serial; /* serial number */ 591 usb_reg_parse_lvl_t dev_parse_level; /* USB_PARSE_LVL_* flag */ 592 struct usb_cfg_data *dev_cfg; /* configs for this device */ 593 /* indexed by config index */ 594 uint_t dev_n_cfg; /* #elements in dev_cfg[] */ 595 struct usb_cfg_data *dev_curr_cfg; /* current cfg */ 596 int dev_curr_if; /* current interface number */ 597 } usb_client_dev_data_t; 598 599 600 /* 601 * *************************************************************************** 602 * Device configuration descriptor tree functions 603 * *************************************************************************** 604 */ 605 606 /* 607 * usb_get_dev_data: 608 * returns initialized registration data. Most data items are clear. 609 * Among the items returned is the tree ofparsed descriptors in dev_cfg; 610 * and the number of configurations parsed in dev_n_cfg. 611 * 612 * Arguments: 613 * dip - pointer to devinfo node of the client 614 * dev_data - return registration data at this address 615 * parse_level - See above 616 * flags - None used 617 * 618 * Return Values: 619 * USB_SUCCESS - usb_register_client succeeded 620 * USB_INVALID_ARGS - received null dip or reg argument 621 * USB_INVALID_CONTEXT - called with sleep from callback context 622 * USB_FAILURE - bad descriptor info or other internal failure 623 * 624 * Notes: 625 * 1) The non-standard USB descriptors are returned in RAW format. 626 * 627 * 2) The registration data is unshared. Each client receives its own copy. 628 * (The default control pipe may be shared, even though its tree 629 * description will be unique per device.) 630 * 631 */ 632 int usb_get_dev_data( 633 dev_info_t *dip, 634 usb_client_dev_data_t **dev_data, 635 usb_reg_parse_lvl_t parse_level, 636 usb_flags_t flags); 637 638 /* 639 * usb_free_dev_data: 640 * undoes what usb_get_dev_data() set up. It releases 641 * memory for all strings, descriptors, and trees set up by usb_get_dev_data(). 642 * 643 * Arguments: 644 * dip - pointer to devinfo node of the client 645 * dev_data - pointer to registration data containing the tree. 646 */ 647 void usb_free_dev_data( 648 dev_info_t *dip, 649 usb_client_dev_data_t *dev_data); 650 651 /* 652 * usb_free_descr_tree: 653 * Take down the configuration tree while leaving the rest of the 654 * registration intact. This can be used, for example, after attach has 655 * copied any descriptors it needs from the tree, but the rest of the 656 * registration data needs to remain intact. 657 * 658 * The following usb_client_dev_data_t fields will be modified: 659 * dev_cfg will be NULL 660 * dev_n_cfg will be 0 661 * dev_curr_cfg_ndx and dev_curr_if will be invalid 662 * dev_parse_level will be USB_REG_DESCR_NONE 663 * 664 * Arguments: 665 * dip - pointer to devinfo node of the client 666 * dev_data - pointer to registration data containing the tree. 667 */ 668 void usb_free_descr_tree( 669 dev_info_t *dip, 670 usb_client_dev_data_t *dev_data); 671 672 673 /* 674 * usb_print_descr_tree: 675 * Dump to the screen a descriptor tree as returned by 676 * usbai_register_client. 677 * 678 * Arguments: 679 * dip - pointer to devinfo of the client 680 * dev_data - pointer to registration area containing the tree 681 * 682 * Returns: 683 * USB_SUCCESS - tree successfully dumped 684 * USB_INVALID_CONTEXT - called from callback context 685 * USB_INVALID_ARGS - bad arguments given 686 */ 687 int usb_print_descr_tree( 688 dev_info_t *dip, 689 usb_client_dev_data_t *dev_data); 690 691 692 /* 693 * *************************************************************************** 694 * Registration and versioning 695 * *************************************************************************** 696 */ 697 698 699 /* 700 * USBA client drivers are required to define USBDRV_MAJOR_VER 701 * USBDRV_MINOR_VER and pass USBDRV_VERSION as the version 702 * number to usb_client_attach 703 */ 704 #if !defined(USBA_MAJOR_VER) || !defined(USBA_MINOR_VER) 705 #error incorrect USBA header 706 #endif 707 708 /* 709 * Driver major version must be the same as USBA major version, and 710 * driver minor version must be <= USBA minor version 711 */ 712 #if !defined(USBA_FRAMEWORK) 713 #if defined(USBDRV_MAJOR_VER) && defined(USBDRV_MINOR_VER) 714 715 #if (USBDRV_MAJOR_VER != USBA_MAJOR_VER) 716 #error USBA and driver major versions do not match 717 #endif 718 #if (USBDRV_MINOR_VER > USBA_MINOR_VER) 719 #error USBA and driver minor versions do not match 720 #endif 721 722 #endif 723 #endif 724 725 #define USBA_MAKE_VER(major, minor) ((major) << 8 | (minor)) 726 #define USBA_GET_MAJOR(ver) ((ver) >> 8) 727 #define USBA_GET_MINOR(ver) ((ver) & 0xff) 728 729 #define USBDRV_VERSION USBA_MAKE_VER(USBDRV_MAJOR_VER, USBDRV_MINOR_VER) 730 731 732 /* 733 * usb_client_attach: 734 * 735 * Arguments: 736 * dip - pointer to devinfo node of the client 737 * version - USBA registration version number 738 * flags - None used 739 * 740 * Return Values: 741 * USB_SUCCESS - attach succeeded 742 * USB_INVALID_ARGS - received null dip or reg argument 743 * USB_INVALID_CONTEXT - called with sleep from callback context 744 * or not at attach time 745 * USB_INVALID_VERSION - version argument is incorrect. 746 * USB_FAILURE - other internal failure 747 */ 748 int usb_client_attach( 749 dev_info_t *dip, 750 uint_t version, 751 usb_flags_t flags); 752 753 /* 754 * usb_client_detach: 755 * 756 * Arguments: 757 * dip - pointer to devinfo node of the client 758 * dev_data - pointer to data to free. may be NULL 759 */ 760 void usb_client_detach( 761 dev_info_t *dip, 762 struct usb_client_dev_data *dev_data); 763 764 /* 765 * *************************************************************************** 766 * Functions for parsing / retrieving data from the descriptor tree 767 * *************************************************************************** 768 */ 769 770 /* 771 * Function for unpacking any kind of little endian data, usually desriptors 772 * 773 * Arguments: 774 * format - string indicating the format in c, s, w, eg. "2c4ws" 775 * which describes 2 bytes, 4 int, one short. 776 * The number prefix parses the number of items of 777 * the following type. 778 * data - pointer to the LE data buffer 779 * datalen - length of the data 780 * structure - pointer to return structure where the unpacked data 781 * will be written 782 * structlen - length of the return structure 783 * 784 * return value: 785 * total number of bytes of the original data that was unpacked 786 * or USB_PARSE_ERROR 787 */ 788 #define USB_PARSE_ERROR 0 789 790 size_t usb_parse_data( 791 char *format, 792 const uchar_t *data, 793 size_t datalen, 794 void *structure, 795 size_t structlen); 796 797 /* 798 * usb_lookup_ep_data: 799 * Function to get specific endpoint data 800 * This function will not access the device. 801 * 802 * Arguments: 803 * dip - pointer to dev info 804 * dev_datap - pointer to registration data 805 * interface - requested interface 806 * alternate - requested alternate 807 * skip - number of endpoints which match the requested type and 808 * direction to skip before finding one to retrieve 809 * type - endpoint type 810 * direction - endpoint direction: USB_EP_DIR_IN/OUT or none 811 * 812 * Return Values: 813 * NULL or an endpoint data pointer 814 */ 815 usb_ep_data_t *usb_lookup_ep_data( 816 dev_info_t *dip, 817 usb_client_dev_data_t *dev_datap, 818 uint_t interface, 819 uint_t alternate, 820 uint_t skip, 821 uint_t type, 822 uint_t direction); 823 824 825 /* Language ID for string descriptors. */ 826 #define USB_LANG_ID 0x0409 /* English, US */ 827 828 /* 829 * usb_get_string_descr: 830 * Reads the string descriptor. This function access the device and 831 * blocks. 832 * 833 * Arguments: 834 * dip - pointer to devinfo of the client. 835 * langid - LANGID to read different LOCALEs. 836 * index - index to the string. 837 * buf - user provided buffer for string descriptor. 838 * buflen - user provided length of the buffer. 839 * 840 * Return Values: 841 * USB_SUCCESS - descriptor is valid. 842 * USB_FAILURE - full descriptor could not be retrieved. 843 */ 844 int usb_get_string_descr( 845 dev_info_t *dip, 846 uint16_t langid, 847 uint8_t index, 848 char *buf, 849 size_t buflen); 850 851 /* 852 * With the advent of USB 3.x, several endpoint compantion descriptors have been 853 * added. These provide additional information required by HCI drivers to 854 * properly open and configure the pipes. 855 */ 856 857 /* 858 * usb_ep_xdescr 859 * 860 * Versioned data structure that's used for usb_pipe_xopen() and should be 861 * filled in by a call to usb_ep_xdescr_fill(). Drivers should always use 862 * USB_EP_XDESCR_CURRENT_VERSION. 863 */ 864 865 #define USB_EP_XDESCR_VERSION_ONE 1 866 #define USB_EP_XDESCR_CURRENT_VERSION USB_EP_XDESCR_VERSION_ONE 867 868 typedef enum usb_ep_xdescr_flags { 869 USB_EP_XFLAGS_SS_COMP = (1 << 0) 870 } usb_ep_xdescr_flags_t; 871 872 typedef struct usb_ep_xdescr { 873 uint_t uex_version; 874 usb_ep_xdescr_flags_t uex_flags; 875 usb_ep_descr_t uex_ep; 876 usb_ep_ss_comp_descr_t uex_ep_ss; 877 } usb_ep_xdescr_t; 878 879 /* 880 * usb_ep_xdescr_fill: 881 * 882 * Fills in the extended endpoint descriptor based on data from the 883 * configuration tree. 884 * 885 * Arguments: 886 * version - Should be USB_EP_XDESCR_CURRENT_VERSION 887 * dip - devinfo pointer 888 * ep_data - endpoint data pointer 889 * ep_xdesc - An extended descriptor structure, filled upon 890 * successful completion. 891 * 892 * Return values: 893 * USB_SUCCESS - filling data succeeded 894 * USB_INVALID_ARGS - invalid arguments 895 */ 896 int usb_ep_xdescr_fill( 897 uint_t version, 898 dev_info_t *dip, 899 usb_ep_data_t *ep_data, 900 usb_ep_xdescr_t *ep_xdesc); 901 902 903 /* 904 * *************************************************************************** 905 * Addressing utility functions 906 * *************************************************************************** 907 */ 908 909 /* 910 * usb_get_addr returns the current usb address, mostly for debugging 911 * purposes. The address may change after hotremove/insert. 912 * This address will not change on a disconnect/reconnect of open device. 913 */ 914 int usb_get_addr(dev_info_t *dip); 915 916 917 /* 918 * usb_get_if_number returns USB_COMBINED_NODE or USB_DEVICE_NODE 919 * if the driver is responsible for the entire device. 920 * Otherwise it returns the interface number. 921 */ 922 #define USB_COMBINED_NODE -1 923 #define USB_DEVICE_NODE -2 924 925 int usb_get_if_number( 926 dev_info_t *dip); 927 928 boolean_t usb_owns_device( 929 dev_info_t *dip); 930 931 932 /* 933 * *************************************************************************** 934 * Pipe Management definitions and functions 935 * *************************************************************************** 936 */ 937 938 939 /* 940 * 941 * usb_pipe_state: 942 * 943 * PIPE_STATE_IDLE: 944 * The pipe's policy is set, but the pipe currently isn't transferring 945 * data. 946 * 947 * PIPE_STATE_ACTIVE: 948 * The pipe's policy has been set, and the pipe is able to transmit data. 949 * When a control or bulk pipe is opened, the pipe's state is 950 * automatically set to PIPE_STATE_ACTIVE. For an interrupt or 951 * isochronous pipe, the pipe state becomes PIPE_STATE_ACTIVE once 952 * the polling on the pipe has been initiated. 953 * 954 * PIPE_STATE_ERROR: 955 * The device has generated a error on the pipe. The client driver 956 * must call usb_pipe_reset() to clear any leftover state that's associated 957 * with the pipe, clear the data toggle, and reset the state of the pipe. 958 * 959 * Calling usb_pipe_reset() on a control or bulk pipe resets the state to 960 * PIPE_STATE_ACTIVE. Calling usb_pipe_reset() on an interrupt or 961 * isochronous pipe, resets the state to PIPE_STATE_IDLE. 962 * 963 * State Diagram for Bulk/Control 964 * 965 * +-<--normal completion------------------<-------^ 966 * | | 967 * V | 968 * usb_pipe_open-->[PIPE_STATE_IDLE]-usb_pipe_*_xfer->[PIPE_STATE_ACTIVE] 969 * ^ | 970 * | v 971 * - usb_pipe_reset<-[PIPE_STATE_ERROR]<-device error 972 * 973 * State Diagram for Interrupt/Isochronous IN 974 * 975 * +-<--usb_pipe_stop_isoc/intr_polling----<-------^ 976 * | | 977 * V | 978 * usb_pipe_open-->[PIPE_STATE_IDLE]-usb_pipe_*_xfer->[PIPE_STATE_ACTIVE] 979 * ^ | 980 * | v 981 * + usb_pipe_reset<-[PIPE_STATE_ERROR]<-device error 982 * 983 * State Diagram for Interrupt/Isochronous OUT 984 * 985 * +-<--normal completion------------------<-------^ 986 * | | 987 * V | 988 * usb_pipe_open-->[PIPE_STATE_IDLE]-usb_pipe_*_xfer->[PIPE_STATE_ACTIVE] 989 * ^ | 990 * | v 991 * + usb_pipe_reset<-[PIPE_STATE_ERROR]<-device error 992 * 993 * 994 * The following table indicates which operations are allowed with each 995 * pipe state: 996 * 997 * -------------------------------------------------------------------------+ 998 * ctrl/bulk | idle | active | error | sync closing | async closing| 999 * -------------------------------------------------------------------------+ 1000 * pipe xfer | OK |queue (USBA)| reject | reject | reject | 1001 * pipe reset | no-op | OK | OK | reject | reject | 1002 * pipe close | OK | wait&close | OK | no-op | no-op | 1003 * -------------------------------------------------------------------------+ 1004 * 1005 * -------------------------------------------------------------------------+ 1006 * intr/isoc IN | idle | active | error | sync closing | async closing| 1007 * -------------------------------------------------------------------------+ 1008 * pipe xfer | OK | reject | reject | reject | reject | 1009 * pipe stoppoll| no-op | OK | no-op | reject | reject | 1010 * pipe reset | no-op | OK | OK | reject | reject | 1011 * pipe close | OK | wait&close | OK | no-op | no-op | 1012 * -------------------------------------------------------------------------+ 1013 * 1014 * -------------------------------------------------------------------------+ 1015 * intr/isoc OUT| idle | active | error | sync closing | async closing| 1016 * -------------------------------------------------------------------------+ 1017 * pipe xfer | OK |queue (HCD) | reject | reject | reject | 1018 * pipe stoppoll| reject| reject | reject | reject | reject | 1019 * pipe reset | no-op | OK | OK | reject | reject | 1020 * pipe close | OK | wait&close | OK | no-op | no-op | 1021 * -------------------------------------------------------------------------+ 1022 */ 1023 typedef enum { 1024 USB_PIPE_STATE_CLOSED = 0, 1025 USB_PIPE_STATE_IDLE = 1, 1026 USB_PIPE_STATE_ACTIVE = 2, 1027 USB_PIPE_STATE_ERROR = 3, 1028 USB_PIPE_STATE_CLOSING = 4 1029 } usb_pipe_state_t; 1030 1031 1032 /* 1033 * pipe state control: 1034 * 1035 * return values: 1036 * USB_SUCCESS - success 1037 * USB_FAILURE - unspecified failure 1038 */ 1039 int usb_pipe_get_state( 1040 usb_pipe_handle_t pipe_handle, 1041 usb_pipe_state_t *pipe_state, 1042 usb_flags_t flags); 1043 1044 /* 1045 * usb_pipe_policy 1046 * 1047 * Pipe policy specifies how a pipe to an endpoint should be used 1048 * by the client driver and the HCD. 1049 */ 1050 typedef struct usb_pipe_policy { 1051 /* 1052 * This is a hint indicating how many asynchronous operations 1053 * requiring a kernel thread will be concurrently active. 1054 * Allow at least one for synch exception callback handling 1055 * and another for asynchronous closing of pipes. 1056 */ 1057 uchar_t pp_max_async_reqs; 1058 } usb_pipe_policy_t; 1059 1060 1061 /* 1062 * usb_pipe_open() and usb_pipe_xopen(): 1063 * 1064 * Before using any pipe including the default pipe, it must be opened. 1065 * On success, a pipe handle is returned for use in other usb_pipe_*() 1066 * functions. 1067 * 1068 * The default pipe can only be opened by the hub driver. 1069 * 1070 * For isochronous and interrupt pipes, bandwidth has been allocated and 1071 * guaranteed. 1072 * 1073 * Only the default pipe can be shared. All other control pipes are 1074 * excusively opened by default. A pipe policy and endpoint descriptor 1075 * must always be provided except for default pipe. 1076 * 1077 * usb_pipe_open() only functions for USB 2.0 and older devices. For USB 3.0 1078 * "SuperSpeed" devices, usb_pipe_xopen() must be used. 1079 * 1080 * Arguments: 1081 * dip - devinfo ptr. 1082 * ep - endpoint descriptor pointer. 1083 * pipe_policy - pointer to pipe policy which provides hints on how 1084 * the pipe will be used. 1085 * flags - USB_FLAGS_SLEEP wait for resources to become 1086 * available. 1087 * pipe_handle - a pipe handle pointer. on a successful open, 1088 * a pipe_handle is returned in this pointer. 1089 * 1090 * Return values: 1091 * USB_SUCCESS - open succeeded. 1092 * USB_FAILURE - unspecified open failure or pipe is already open. 1093 * USB_NO_RESOURCES - no resources were available to complete the open. 1094 * USB_NO_BANDWIDTH - no bandwidth available (isoc/intr pipes). 1095 * USB_NOT_SUPPORTED - USB 3.0 or greater device 1096 * USB_* - refer to list of all possible return values in 1097 * this file 1098 */ 1099 int usb_pipe_open( 1100 dev_info_t *dip, 1101 usb_ep_descr_t *ep, 1102 usb_pipe_policy_t *pipe_policy, 1103 usb_flags_t flags, 1104 usb_pipe_handle_t *pipe_handle); 1105 1106 int usb_pipe_xopen( 1107 dev_info_t *dip, 1108 usb_ep_xdescr_t *ep_xdesc, 1109 usb_pipe_policy_t *pipe_policy, 1110 usb_flags_t flags, 1111 usb_pipe_handle_t *pipe_handle); 1112 1113 1114 /* 1115 * usb_pipe_close(): 1116 * 1117 * Closes the pipe, releases resources and frees the pipe_handle. 1118 * Automatic polling, if active, will be terminated. 1119 * 1120 * Arguments: 1121 * dip - devinfo ptr. 1122 * pipe_handle - pipe handle. 1123 * flags - USB_FLAGS_SLEEP: 1124 * wait for resources, pipe 1125 * to become free, and all callbacks completed. 1126 * cb - If USB_FLAGS_SLEEP has not been specified, a 1127 * callback will be performed. 1128 * cb_arg - the 2nd argument of the callback. Note that the 1129 * pipehandle will be zeroed and therefore not passed. 1130 * 1131 * Notes: 1132 * 1133 * Pipe close always succeeds regardless whether USB_FLAGS_SLEEP has been 1134 * specified or not. An async close will always succeed if the hint in the 1135 * pipe policy has been correct about the max number of async requests 1136 * required. 1137 * In the unlikely event that no async requests can be queued, this 1138 * function will continue retrying before returning 1139 * 1140 * USBA prevents the client from submitting subsequent requests to a pipe 1141 * that is being closed. 1142 * Additional usb_pipe_close() requests on the same pipe causes USBA to 1143 * wait for the previous close(s) to complete. 1144 * 1145 * The pipe will not be destroyed until all activity on the pipe has 1146 * been drained, including outstanding request callbacks, async requests, 1147 * and other usb_pipe_*() calls. 1148 * 1149 * Calling usb_pipe_close() from a deferred callback (in kernel context) 1150 * with USB_FLAGS_SLEEP set, will cause deadlock 1151 */ 1152 void usb_pipe_close( 1153 dev_info_t *dip, 1154 usb_pipe_handle_t pipe_handle, 1155 usb_flags_t flags, 1156 void (*cb)( 1157 usb_pipe_handle_t ph, 1158 usb_opaque_t arg, /* cb arg */ 1159 int rval, 1160 usb_cb_flags_t flags), 1161 usb_opaque_t cb_arg); 1162 1163 1164 /* 1165 * usb_pipe_drain_reqs 1166 * this function blocks until there are no more requests 1167 * owned by this dip on the pipe 1168 * 1169 * Arguments: 1170 * dip - devinfo pointer 1171 * pipe_handle - opaque pipe handle 1172 * timeout - timeout in seconds 1173 * flags - USB_FLAGS_SLEEP: 1174 * wait for completion. 1175 * cb - if USB_FLAGS_SLEEP has not been specified 1176 * this callback function will be called on 1177 * completion. This callback may be NULL 1178 * and no notification of completion will then 1179 * be provided. 1180 * cb_arg - 2nd argument to callback function. 1181 * 1182 * callback and callback_arg should be NULL if USB_FLAGS_SLEEP has 1183 * been specified 1184 * 1185 * Returns: 1186 * USB_SUCCESS - pipe successfully reset or request queued 1187 * USB_FAILURE - timeout 1188 * USB_INVALID_PIPE - pipe is invalid or already closed 1189 * USB_INVALID_CONTEXT - called from interrupt context 1190 * USB_INVALID_ARGS - invalid arguments 1191 * USB_* - refer to return values defines in this file 1192 */ 1193 int usb_pipe_drain_reqs( 1194 dev_info_t *dip, 1195 usb_pipe_handle_t pipe_handle, 1196 uint_t time, 1197 usb_flags_t flags, 1198 void (*cb)( 1199 usb_pipe_handle_t ph, 1200 usb_opaque_t arg, /* cb arg */ 1201 int rval, 1202 usb_cb_flags_t flags), 1203 usb_opaque_t cb_arg); 1204 1205 1206 /* 1207 * Resetting a pipe: Refer to USB 2.0/10.5.2.2 1208 * The pipe's requests are retired and the pipe is cleared. The host state 1209 * is moved to active. If the reflected endpoint state needs to be changed, 1210 * that must be explicitly requested by the client driver. The reset 1211 * completes after all request callbacks have been completed. 1212 * 1213 * Arguments: 1214 * dip - devinfo pointer. 1215 * pipe_handle - pipe handle. 1216 * flags - USB_FLAGS_SLEEP: 1217 * wait for completion. 1218 * cb - if USB_FLAGS_SLEEP has not been specified 1219 * this callback function will be called on 1220 * completion. This callback may be NULL 1221 * and no notification of completion will then 1222 * be provided. 1223 * cb_arg - 2nd argument to callback function. 1224 * 1225 * callback and callback_arg should be NULL if USB_FLAGS_SLEEP has 1226 * been specified 1227 * 1228 * Note: Completion notification may be *before* all async request threads 1229 * have completed but *after* all immediate callbacks have completed. 1230 */ 1231 void usb_pipe_reset( 1232 dev_info_t *dip, 1233 usb_pipe_handle_t pipe_handle, 1234 usb_flags_t usb_flags, 1235 void (*cb)( 1236 usb_pipe_handle_t ph, 1237 usb_opaque_t arg, 1238 int rval, 1239 usb_cb_flags_t flags), 1240 usb_opaque_t cb_arg); 1241 1242 1243 /* 1244 * The client driver can store a private data pointer in the 1245 * pipe_handle. 1246 * 1247 * return values: 1248 * USB_SUCCESS - success 1249 * USB_FAILURE - unspecified failure 1250 */ 1251 int usb_pipe_set_private( 1252 usb_pipe_handle_t pipe_handle, 1253 usb_opaque_t data); 1254 1255 1256 usb_opaque_t usb_pipe_get_private( 1257 usb_pipe_handle_t pipe_handle); 1258 1259 1260 /* 1261 * *************************************************************************** 1262 * Transfer request definitions and functions 1263 * *************************************************************************** 1264 */ 1265 1266 1267 /* 1268 * USB xfer request attributes. 1269 * Set by the client driver, more than one may be set 1270 * 1271 * SHORT_XFER_OK if less data is transferred than specified, no error is 1272 * returned. 1273 * AUTOCLEARING if there is an exception, the pipe will be reset first 1274 * and a functional stall cleared before a callback is done. 1275 * PIPE_RESET if there is an exception, the pipe will be reset only 1276 * ONE_XFER polling will automatically stop on the first callback. 1277 * ISOC_START_FRAME use startframe specified. 1278 * USB_ATTRS_ISOC_XFER_ASAP let the host controller decide on the first 1279 * available frame. 1280 * 1281 * USB_ATTRS_ISOC_START_FRAME and USB_ATTRS_ISOC_XFER_ASAP are mutually 1282 * exclusive 1283 * 1284 * combinations of flag and attributes: 1285 * 1286 * usb_flags usb_req_attrs semantics 1287 * --------------------------------------------------------- 1288 * SLEEP USB_ATTRS_SHORT_XFER_OK legal for IN pipes 1289 * SLEEP USB_ATTRS_AUTOCLEARING legal 1290 * SLEEP USB_ATTRS_PIPE_RESET legal 1291 * SLEEP USB_ATTRS_ONE_XFER legal for interrupt IN pipes 1292 * SLEEP USB_ATTRS_ISOC_START_FRAME illegal 1293 * SLEEP USB_ATTRS_ISOC_XFER_ASAP illegal 1294 * 1295 * noSLEEP USB_ATTRS_SHORT_XFER_OK legal for all IN pipes 1296 * noSLEEP USB_ATTRS_AUTOCLEARING legal 1297 * noSLEEP USB_ATTRS_PIPE_RESET legal 1298 * noSLEEP USB_ATTRS_ONE_XFER legal 1299 * noSLEEP USB_ATTRS_ISOC_START_FRAME legal 1300 * noSLEEP USB_ATTRS_ISOC_XFER_ASAP legal 1301 */ 1302 typedef enum { 1303 USB_ATTRS_NONE = 0, 1304 1305 /* only ctrl/bulk/intr IN pipes */ 1306 USB_ATTRS_SHORT_XFER_OK = 0x01, /* short data xfer is ok */ 1307 USB_ATTRS_PIPE_RESET = 0x02, /* reset pipe only on exc */ 1308 USB_ATTRS_AUTOCLEARING = 0x12, /* autoclear STALLs */ 1309 1310 /* intr pipes only: one poll with data */ 1311 USB_ATTRS_ONE_XFER = 0x100, 1312 1313 /* only for isoch pipe */ 1314 USB_ATTRS_ISOC_START_FRAME = 0x200, /* Starting frame# specified */ 1315 USB_ATTRS_ISOC_XFER_ASAP = 0x400 /* HCD decides START_FRAME# */ 1316 } usb_req_attrs_t; 1317 1318 1319 /* 1320 * Note: client drivers are required to provide data buffers (mblks) for most 1321 * requests 1322 * IN OUT 1323 * ctlr request if wLength > 0 if wLength > 0 1324 * bulk request yes yes 1325 * intr request no yes 1326 * isoc request no yes 1327 */ 1328 1329 /* 1330 * =========================================================================== 1331 * USB control request management 1332 * =========================================================================== 1333 */ 1334 1335 /* 1336 * A client driver allocates and uses the usb_ctrl_req_t for all control 1337 * pipe requests. 1338 * 1339 * Direction of the xfer will be determined based on the bmRequestType. 1340 * 1341 * NULL callbacks are permitted, timeout = 0 indicates infinite timeout. 1342 * All timeouts are in seconds. 1343 * 1344 * All fields are initialized by client except for data on IN request 1345 * in which case the client is responsible for deallocating. 1346 * 1347 * Control requests may be reused. The client driver is responsible 1348 * for reinitializing some fields, eg data read/write pointers. 1349 * 1350 * Control requests can be queued. 1351 */ 1352 typedef struct usb_ctrl_req { 1353 uint8_t ctrl_bmRequestType; /* characteristics of request */ 1354 uint8_t ctrl_bRequest; /* specific request */ 1355 uint16_t ctrl_wValue; /* varies according to request */ 1356 uint16_t ctrl_wIndex; /* index or offset */ 1357 uint16_t ctrl_wLength; /* number of bytes to xfer */ 1358 1359 mblk_t *ctrl_data; /* the data for the data phase */ 1360 /* IN: allocated by HCD */ 1361 /* OUT: allocated by client */ 1362 uint_t ctrl_timeout; /* how long before HCD retires req */ 1363 usb_opaque_t ctrl_client_private; /* for client private info */ 1364 usb_req_attrs_t ctrl_attributes; /* attributes for this req */ 1365 1366 /* 1367 * callback function for control pipe requests 1368 * 1369 * a normal callback will be done upon: 1370 * - successful completion of a control pipe request 1371 * 1372 * callback arguments are: 1373 * - the pipe_handle 1374 * - usb_ctrl_req_t pointer 1375 */ 1376 void (*ctrl_cb)(usb_pipe_handle_t ph, 1377 struct usb_ctrl_req *req); 1378 1379 /* 1380 * exception callback function for control pipe 1381 * 1382 * a exception callback will be done upon: 1383 * - an exception/error (all types) 1384 * - partial xfer of data unless SHORT_XFER_OK has been set 1385 * 1386 * callback arguments are: 1387 * - the pipe_handle 1388 * - usb_ctrl_req_t pointer 1389 * 1390 * if USB_ATTRS_AUTOCLEARING was set, autoclearing will be attempted 1391 * and usb_cb_flags_t in usb_ctrl_req may indicate what was done 1392 */ 1393 void (*ctrl_exc_cb)(usb_pipe_handle_t ph, 1394 struct usb_ctrl_req *req); 1395 1396 /* set by USBA/HCD on completion */ 1397 usb_cr_t ctrl_completion_reason; /* set by HCD */ 1398 usb_cb_flags_t ctrl_cb_flags; /* Callback context / handling flgs */ 1399 } usb_ctrl_req_t; 1400 1401 1402 /* 1403 * In the setup packet, the descriptor type is passed in the high byte of the 1404 * wValue field. 1405 * descriptor types: 1406 */ 1407 #define USB_DESCR_TYPE_SETUP_DEV 0x0100 1408 #define USB_DESCR_TYPE_SETUP_CFG 0x0200 1409 #define USB_DESCR_TYPE_SETUP_STRING 0x0300 1410 #define USB_DESCR_TYPE_SETUP_IF 0x0400 1411 #define USB_DESCR_TYPE_SETUP_EP 0x0500 1412 #define USB_DESCR_TYPE_SETUP_DEV_QLF 0x0600 1413 #define USB_DESCR_TYPE_SETUP_OTHER_SPEED_CFG 0x0700 1414 #define USB_DESCR_TYPE_SETUP_IF_PWR 0x0800 1415 1416 #define USB_DESCR_TYPE_DEV 0x01 1417 #define USB_DESCR_TYPE_CFG 0x02 1418 #define USB_DESCR_TYPE_STRING 0x03 1419 #define USB_DESCR_TYPE_IF 0x04 1420 #define USB_DESCR_TYPE_EP 0x05 1421 #define USB_DESCR_TYPE_DEV_QLF 0x06 1422 #define USB_DESCR_TYPE_OTHER_SPEED_CFG 0x07 1423 #define USB_DESCR_TYPE_IF_PWR 0x08 1424 #define USB_DESCR_TYPE_IA 0x0B 1425 1426 #define USB_DESCR_TYPE_WA 0x21 1427 #define USB_DESCR_TYPE_RPIPE 0x22 1428 #define USB_DESCR_TYPE_HUB 0x29 1429 1430 /* Wireless USB extension, refer to WUSB 1.0/7.4 */ 1431 #define USB_DESCR_TYPE_SECURITY 0x0c 1432 #define USB_DESCR_TYPE_KEY 0x0d 1433 #define USB_DESCR_TYPE_ENCRYPTION 0x0e 1434 #define USB_DESCR_TYPE_BOS 0x0f 1435 #define USB_DESCR_TYPE_DEV_CAPABILITY 0x10 1436 #define USB_DESCR_TYPE_WIRELESS_EP_COMP 0x11 1437 1438 #define USB_WA_DESCR_SIZE 14 1439 #define USB_RPIPE_DESCR_SIZE 28 1440 1441 /* 1442 * USB 3.0 Super Speed specifics. See USB 3.1/9.4. 1443 */ 1444 #define USB_DESCR_TYPE_SS_HUB 0x2A 1445 #define USB_DESCR_TYPE_SS_EP_COMP 0x30 1446 #define USB_DESCR_TYPE_SS_ISO_EP_COMP 0x31 1447 1448 /* 1449 * device request type 1450 */ 1451 #define USB_DEV_REQ_HOST_TO_DEV 0x00 1452 #define USB_DEV_REQ_DEV_TO_HOST 0x80 1453 #define USB_DEV_REQ_DIR_MASK 0x80 1454 1455 #define USB_DEV_REQ_TYPE_STANDARD 0x00 1456 #define USB_DEV_REQ_TYPE_CLASS 0x20 1457 #define USB_DEV_REQ_TYPE_VENDOR 0x40 1458 #define USB_DEV_REQ_TYPE_MASK 0x60 1459 1460 #define USB_DEV_REQ_RCPT_DEV 0x00 1461 #define USB_DEV_REQ_RCPT_IF 0x01 1462 #define USB_DEV_REQ_RCPT_EP 0x02 1463 #define USB_DEV_REQ_RCPT_OTHER 0x03 1464 #define USB_DEV_REQ_RCPT_MASK 0x03 1465 1466 /* Wire adapter class extension for request recipient */ 1467 #define USB_DEV_REQ_RCPT_PORT 0x04 1468 #define USB_DEV_REQ_RCPT_RPIPE 0x05 1469 1470 /* 1471 * device request 1472 */ 1473 #define USB_REQ_GET_STATUS 0x00 1474 #define USB_REQ_CLEAR_FEATURE 0x01 1475 #define USB_REQ_SET_FEATURE 0x03 1476 #define USB_REQ_SET_ADDRESS 0x05 1477 #define USB_REQ_GET_DESCR 0x06 1478 #define USB_REQ_SET_DESCR 0x07 1479 #define USB_REQ_GET_CFG 0x08 1480 #define USB_REQ_SET_CFG 0x09 1481 #define USB_REQ_GET_IF 0x0a 1482 #define USB_REQ_SET_IF 0x0b 1483 #define USB_REQ_SYNC_FRAME 0x0c 1484 /* Wireless USB extension, refer to WUSB 1.0/7.3.1 */ 1485 #define USB_REQ_SET_ENCRYPTION 0x0d 1486 #define USB_REQ_GET_ENCRYPTION 0x0e 1487 #define USB_REQ_RPIPE_ABORT 0x0e 1488 #define USB_REQ_SET_HANDSHAKE 0x0f 1489 #define USB_REQ_RPIPE_RESET 0x0f 1490 #define USB_REQ_GET_HANDSHAKE 0x10 1491 #define USB_REQ_SET_CONNECTION 0x11 1492 #define USB_REQ_SET_SECURITY_DATA 0x12 1493 #define USB_REQ_GET_SECURITY_DATA 0x13 1494 #define USB_REQ_SET_WUSB_DATA 0x14 1495 #define USB_REQ_LOOPBACK_DATA_WRITE 0x15 1496 #define USB_REQ_LOOPBACK_DATA_READ 0x16 1497 #define USB_REQ_SET_INTERFACE_DS 0x17 1498 1499 /* language ID for string descriptors */ 1500 #define USB_LANG_ID 0x0409 1501 1502 /* 1503 * Standard Feature Selectors 1504 */ 1505 #define USB_EP_HALT 0x0000 1506 #define USB_DEV_REMOTE_WAKEUP 0x0001 1507 #define USB_DEV_TEST_MODE 0x0002 1508 /* Wireless USB extension, refer to WUSB 1.0/7.3.1 */ 1509 #define USB_DEV_WUSB 0x0003 1510 1511 1512 /* 1513 * Allocate usb control request 1514 * 1515 * Arguments: 1516 * dip - dev_info pointer of the client driver 1517 * len - length of "data" for this control request. 1518 * if 0, no mblk is alloc'ed 1519 * flags - USB_FLAGS_SLEEP: Sleep if resources are not available 1520 * 1521 * Return Values: 1522 * usb_ctrl_req_t pointer on success, NULL on failure 1523 * 1524 * Implementation NOTE: the dip allows checking on detach for memory leaks 1525 */ 1526 usb_ctrl_req_t *usb_alloc_ctrl_req( 1527 dev_info_t *dip, 1528 size_t len, 1529 usb_flags_t flags); 1530 1531 1532 /* 1533 * free USB control request 1534 */ 1535 void usb_free_ctrl_req( 1536 usb_ctrl_req_t *reqp); 1537 1538 1539 /* 1540 * usb_pipe_ctrl_xfer(); 1541 * Client driver calls this function to issue the control 1542 * request to the USBA which will queue or transport it to the device 1543 * 1544 * Arguments: 1545 * pipe_handle - control pipe pipehandle (obtained via usb_pipe_open() 1546 * reqp - pointer to control request 1547 * flags - USB_FLAGS_SLEEP: 1548 * wait for the request to complete 1549 * 1550 * Return values: 1551 * USB_SUCCESS - successfully queued (no sleep) or successfully 1552 * completed (with sleep specified) 1553 * USB_FAILURE - failure 1554 * USB_NO_RESOURCES - no resources 1555 */ 1556 int usb_pipe_ctrl_xfer(usb_pipe_handle_t pipe_handle, 1557 usb_ctrl_req_t *reqp, 1558 usb_flags_t flags); 1559 1560 1561 /* 1562 * --------------------------------------------------------------------------- 1563 * Wrapper function which allocates and deallocates a request structure, and 1564 * performs a control transfer. 1565 * --------------------------------------------------------------------------- 1566 */ 1567 1568 /* 1569 * Setup arguments for usb_pipe_ctrl_xfer_wait: 1570 * 1571 * bmRequestType - characteristics of request 1572 * bRequest - specific request 1573 * wValue - varies according to request 1574 * wIndex - index or offset 1575 * wLength - number of bytes to xfer 1576 * attrs - required request attributes 1577 * data - pointer to pointer to data 1578 * IN: HCD will allocate data 1579 * OUT: clients driver allocates data 1580 */ 1581 typedef struct usb_ctrl_setup { 1582 uchar_t bmRequestType; 1583 uchar_t bRequest; 1584 uint16_t wValue; 1585 uint16_t wIndex; 1586 uint16_t wLength; 1587 usb_req_attrs_t attrs; 1588 } usb_ctrl_setup_t; 1589 1590 1591 /* 1592 * usb_pipe_ctrl_xfer_wait(): 1593 * for simple synchronous control transactions this wrapper function 1594 * will perform the allocation, xfer, and deallocation. 1595 * USB_ATTRS_AUTOCLEARING will be enabled 1596 * 1597 * Arguments: 1598 * pipe_handle - control pipe pipehandle (obtained via usb_pipe_open()) 1599 * setup - contains pointer to client's devinfo, 1600 * setup descriptor params, attributes and data 1601 * completion_reason - completion status. 1602 * cb_flags - request completions flags. 1603 * flags - none. 1604 * 1605 * Return Values: 1606 * USB_SUCCESS - request successfully executed. 1607 * USB_FAILURE - request failed. 1608 * USB_* - refer to list of all possible return values in 1609 * this file 1610 * 1611 * NOTES: 1612 * - in the case of failure, the client should check completion_reason and 1613 * and cb_flags and determine further recovery action 1614 * - the client should check data and if non-zero, free the data on 1615 * completion 1616 */ 1617 int usb_pipe_ctrl_xfer_wait( 1618 usb_pipe_handle_t pipe_handle, 1619 usb_ctrl_setup_t *setup, 1620 mblk_t **data, 1621 usb_cr_t *completion_reason, 1622 usb_cb_flags_t *cb_flags, 1623 usb_flags_t flags); 1624 1625 1626 /* 1627 * --------------------------------------------------------------------------- 1628 * Some utility defines and wrapper functions for standard control requests. 1629 * --------------------------------------------------------------------------- 1630 */ 1631 1632 /* 1633 * USB STATUS request types and sizes. 1634 */ 1635 #define USB_GET_STATUS_STANDARD 0 1636 #define USB_GET_STATUS_PTM 1 1637 1638 #define USB_GET_STATUS_LEN 2 1639 #define USB_GET_STATUS_PTM_LEN 4 1640 1641 /* 1642 * Status bits returned by a usb_get_status() for a STATUS_STANDARD request. 1643 */ 1644 #define USB_DEV_SLF_PWRD_STATUS 1 /* Supports Self Power */ 1645 #define USB_DEV_RWAKEUP_STATUS 2 /* Remote Wakeup Enabled */ 1646 #define USB_DEV_BAT_PWRD_STATUS 4 /* Battery Powered */ 1647 #define USB_EP_HALT_STATUS 1 /* Endpoint is Halted */ 1648 #define USB_IF_STATUS 0 /* Interface Status is 0 */ 1649 1650 /* 1651 * wrapper function returning status of device, interface, or endpoint 1652 * 1653 * Arguments: 1654 * dip - devinfo pointer. 1655 * ph - pipe handle 1656 * type - bmRequestType to be used 1657 * what - 0 for device, otherwise interface or ep number 1658 * status - pointer to returned status. 1659 * flags - USB_FLAGS_SLEEP (mandatory) 1660 * 1661 * Return Values: 1662 * valid usb_status_t or USB_FAILURE 1663 * 1664 */ 1665 int usb_get_status( 1666 dev_info_t *dip, 1667 usb_pipe_handle_t ph, 1668 uint_t type, /* bmRequestType */ 1669 uint_t what, /* 0, interface, endpoint number */ 1670 uint16_t *status, 1671 usb_flags_t flags); 1672 1673 1674 /* 1675 * function for clearing feature of device, interface, or endpoint 1676 * 1677 * Arguments: 1678 * dip - devinfo pointer. 1679 * type - bmRequestType to be used 1680 * feature - feature to be cleared 1681 * what - 0 for device, otherwise interface or ep number 1682 * flags - USB_FLAGS_SLEEP (mandatory) 1683 * cb - if USB_FLAGS_SLEEP has not been specified 1684 * this callback function will be called on 1685 * completion. This callback may be NULL 1686 * and no notification of completion will then 1687 * be provided. 1688 * cb_arg - 2nd argument to callback function. 1689 * 1690 * Return Values: 1691 * USB_SUCCESS clearing feature succeeded 1692 * USB_FAILURE clearing feature failed 1693 * USB_* refer to list of all possible return values in 1694 * this file 1695 */ 1696 int usb_clr_feature( 1697 dev_info_t *dip, 1698 uint_t type, /* bmRequestType */ 1699 uint_t feature, 1700 uint_t what, /* 0, interface, endpoint number */ 1701 usb_flags_t flags, 1702 void (*cb)( 1703 usb_pipe_handle_t ph, 1704 usb_opaque_t arg, 1705 int rval, 1706 usb_cb_flags_t flags), 1707 usb_opaque_t cb_arg); 1708 1709 1710 /* 1711 * usb_set_cfg(): 1712 * Sets the configuration. Use this function with caution as 1713 * the framework is normally responsible for configuration changes. 1714 * Changing configuration will fail if pipes are still open or 1715 * when invoked from a driver bound to an interface on a composite 1716 * device. This function access the device and blocks. 1717 * 1718 * Arguments: 1719 * dip - devinfo pointer. 1720 * cfg_index - Index of configuration to set. Corresponds to 1721 * index in the usb_client_dev_data_t tree of 1722 * configurations. See usb_client_dev_data_t(9F). 1723 * usb_flags - USB_FLAGS_SLEEP: 1724 * wait for completion. 1725 * cb - if USB_FLAGS_SLEEP has not been specified 1726 * this callback function will be called on 1727 * completion. This callback may be NULL 1728 * and no notification of completion will then 1729 * be provided. 1730 * cb_arg - 2nd argument to callback function. 1731 * 1732 * callback and callback_arg should be NULL if USB_FLAGS_SLEEP has 1733 * been specified 1734 * 1735 * Return Values: 1736 * USB_SUCCESS: new configuration was set or async request 1737 * submitted successfully. 1738 * USB_FAILURE: new configuration could not be set because 1739 * it may been illegal configuration or this 1740 * caller was not allowed to change configs or 1741 * pipes were still open or async request 1742 * could not be submitted. 1743 * USB_* refer to list of all possible return values in 1744 * this file 1745 * 1746 * the pipe handle argument in the callback will be the default pipe handle 1747 */ 1748 int usb_set_cfg( 1749 dev_info_t *dip, 1750 uint_t cfg_index, 1751 usb_flags_t usb_flags, 1752 void (*cb)( 1753 usb_pipe_handle_t ph, 1754 usb_opaque_t arg, 1755 int rval, 1756 usb_cb_flags_t flags), 1757 usb_opaque_t cb_arg); 1758 1759 1760 /* 1761 * usb_get_cfg: 1762 * dip - pointer to devinfo node 1763 * cfgval - pointer to cfgval 1764 * usb_flags - none, will always block 1765 * 1766 * return values: 1767 * USB_SUCCESS - current cfg value is returned to cfgval 1768 * USB_* - refer to list of all possible return values in 1769 * this file 1770 */ 1771 int usb_get_cfg( 1772 dev_info_t *dip, 1773 uint_t *cfgval, 1774 usb_flags_t usb_flags); 1775 1776 1777 /* 1778 * The following functions set or get the alternate interface 1779 * setting. 1780 * 1781 * usb_set_alt_if: 1782 * dip - pointer to devinfo node 1783 * interface - interface 1784 * alt_number - alternate to set to 1785 * usb_flags - USB_FLAGS_SLEEP: 1786 * wait for completion. 1787 * cb - if USB_FLAGS_SLEEP has not been specified 1788 * this callback function will be called on 1789 * completion. This callback may be NULL 1790 * and no notification of completion will then 1791 * be provided. 1792 * cb_arg - 2nd argument to callback function. 1793 * 1794 * callback and callback_arg should be NULL if USB_FLAGS_SLEEP has 1795 * been specified 1796 * 1797 * the pipe handle argument in the callback will be the default pipe handle 1798 * 1799 * return values: 1800 * USB_SUCCESS: alternate was set or async request was 1801 * submitted. 1802 * USB_FAILURE: alternate could not be set because pipes 1803 * were still open or some access error occurred 1804 * or an invalid alt if value was passed or 1805 * async request could not be submitted 1806 * USB_INVALID_PERM the driver does not own the device or the interface 1807 * USB_* refer to list of all possible return values in 1808 * this file 1809 */ 1810 int usb_set_alt_if( 1811 dev_info_t *dip, 1812 uint_t interface, 1813 uint_t alt_number, 1814 usb_flags_t usb_flags, 1815 void (*cb)( 1816 usb_pipe_handle_t ph, 1817 usb_opaque_t arg, 1818 int rval, 1819 usb_cb_flags_t flags), 1820 usb_opaque_t cb_arg); 1821 1822 1823 1824 /* flags must be USB_FLAGS_SLEEP, and this function will block */ 1825 int usb_get_alt_if( 1826 dev_info_t *dip, 1827 uint_t if_number, 1828 uint_t *alt_number, 1829 usb_flags_t flags); 1830 1831 1832 /* 1833 * =========================================================================== 1834 * USB bulk request management 1835 * =========================================================================== 1836 */ 1837 1838 /* 1839 * A client driver allocates/uses the usb_bulk_req_t for bulk pipe xfers. 1840 * 1841 * NOTES: 1842 * - bulk pipe sharing is not supported 1843 * - semantics of combinations of flag and attributes: 1844 * 1845 * flags Type attributes data timeout semantics 1846 * ---------------------------------------------------------------- 1847 * x x x == NULL x illegal 1848 * 1849 * no sleep IN x != NULL 0 fill buffer, no timeout 1850 * callback when xfer-len has 1851 * been xferred 1852 * no sleep IN x != NULL > 0 fill buffer, with timeout 1853 * callback when xfer-len has 1854 * been xferred 1855 * 1856 * sleep IN x != NULL 0 fill buffer, no timeout 1857 * unblock when xfer-len has 1858 * been xferred 1859 * no callback 1860 * sleep IN x != NULL > 0 fill buffer, with timeout 1861 * unblock when xfer-len has 1862 * been xferred or timeout 1863 * no callback 1864 * 1865 * X OUT SHORT_XFER_OK x x illegal 1866 * 1867 * no sleep OUT x != NULL 0 empty buffer, no timeout 1868 * callback when xfer-len has 1869 * been xferred 1870 * no sleep OUT x != NULL > 0 empty buffer, with timeout 1871 * callback when xfer-len has 1872 * been xferred or timeout 1873 * 1874 * sleep OUT x != NULL 0 empty buffer, no timeout 1875 * unblock when xfer-len has 1876 * been xferred 1877 * no callback 1878 * sleep OUT x != NULL > 0 empty buffer, with timeout 1879 * unblock when xfer-len has 1880 * been xferred or timeout 1881 * no callback 1882 * 1883 * - bulk_len and bulk_data must be > 0. SHORT_XFER_OK is not applicable. 1884 * 1885 * - multiple bulk requests can be queued 1886 * 1887 * - Splitting large Bulk xfer: 1888 * The HCD driver, due to internal constraints, can only do a limited size bulk 1889 * data xfer per request. The current limitations are 32K for UHCI and 128K 1890 * for OHCI. So, a client driver may first determine this limitation (by 1891 * calling the USBA interface usb_pipe_bulk_transfer_size()); and restrict 1892 * itself to doing xfers in multiples of this fixed size. This forces a client 1893 * driver to do data xfers in a loop for a large request, splitting it into 1894 * multiple chunks of fixed size. 1895 */ 1896 typedef struct usb_bulk_req { 1897 uint_t bulk_len; /* number of bytes to xfer */ 1898 mblk_t *bulk_data; /* the data for the data phase */ 1899 /* IN: allocated by HCD */ 1900 /* OUT: allocated by client */ 1901 uint_t bulk_timeout; /* xfer timeout value in secs */ 1902 usb_opaque_t bulk_client_private; /* Client specific information */ 1903 usb_req_attrs_t bulk_attributes; /* xfer-attributes */ 1904 1905 /* Normal Callback function (For synch xfers) */ 1906 void (*bulk_cb)(usb_pipe_handle_t ph, 1907 struct usb_bulk_req *req); 1908 1909 /* Exception Callback function (For asynch xfers) */ 1910 void (*bulk_exc_cb)(usb_pipe_handle_t ph, 1911 struct usb_bulk_req *req); 1912 1913 /* set by USBA/HCD on completion */ 1914 usb_cr_t bulk_completion_reason; /* set by HCD */ 1915 usb_cb_flags_t bulk_cb_flags; /* Callback context / handling flgs */ 1916 } usb_bulk_req_t; 1917 1918 1919 /* 1920 * Allocate/free usb bulk request 1921 * 1922 * Arguments: 1923 * dip - pointer to dev_info_t of the client driver 1924 * len - 0 or length of mblk to be allocated 1925 * flags - USB_FLAGS_SLEEP: 1926 * wait for resources 1927 * 1928 * Return Values: 1929 * usb_bulk_req_t on success, NULL on failure 1930 */ 1931 usb_bulk_req_t *usb_alloc_bulk_req( 1932 dev_info_t *dip, 1933 size_t len, 1934 usb_flags_t flags); 1935 1936 1937 void usb_free_bulk_req( 1938 usb_bulk_req_t *reqp); 1939 1940 1941 /* 1942 * usb_pipe_bulk_xfer(): 1943 * 1944 * Client drivers call this function to issue the bulk xfer to the USBA 1945 * which will queue or transfer it to the device 1946 * 1947 * Arguments: 1948 * pipe_handle - bulk pipe handle (obtained via usb_pipe_open() 1949 * reqp - pointer to bulk data xfer request (IN or OUT) 1950 * flags - USB_FLAGS_SLEEP: 1951 * wait for the request to complete 1952 * 1953 * Return Values: 1954 * USB_SUCCESS - success 1955 * USB_FAILURE - unspecified failure 1956 * USB_NO_RESOURCES - no resources 1957 * 1958 */ 1959 int usb_pipe_bulk_xfer( 1960 usb_pipe_handle_t pipe_handle, 1961 usb_bulk_req_t *reqp, 1962 usb_flags_t flags); 1963 1964 /* Get maximum bulk transfer size */ 1965 int usb_pipe_get_max_bulk_transfer_size( 1966 dev_info_t *dip, 1967 size_t *size); 1968 1969 1970 /* 1971 * =========================================================================== 1972 * USB interrupt pipe request management 1973 * =========================================================================== 1974 */ 1975 1976 /* 1977 * A client driver allocates and uses the usb_intr_req_t for 1978 * all interrupt pipe transfers. 1979 * 1980 * USB_FLAGS_SLEEP indicates here just to wait for resources except 1981 * for ONE_XFER where we also wait for completion 1982 * 1983 * semantics flags and attribute combinations: 1984 * 1985 * Notes: 1986 * none attributes indicates neither ONE_XFER nor SHORT_XFER_OK 1987 * 1988 * flags Type attributes data timeout semantics 1989 * ---------------------------------------------------------------- 1990 * x IN x != NULL x illegal 1991 * x IN ONE_XFER=0 x !=0 illegal 1992 * 1993 * x IN ONE_XFER=0 NULL 0 continuous polling, 1994 * many callbacks 1995 * request is returned on 1996 * stop polling 1997 * 1998 * no sleep IN ONE_XFER NULL 0 one time poll, no timeout, 1999 * one callback 2000 * no sleep IN ONE_XFER NULL !=0 one time poll, with 2001 * timeout, one callback 2002 * 2003 * sleep IN ONE_XFER NULL 0 one time poll, no timeout, 2004 * no callback, 2005 * block for completion 2006 * sleep IN ONE_XFER NULL !=0 one time poll, with timeout, 2007 * no callback 2008 * block for completion 2009 * 2010 * x OUT x NULL x illegal 2011 * x OUT ONE_XFER x x illegal 2012 * x OUT SHORT_XFER_OK x x illegal 2013 * 2014 * x OUT none != NULL 0 xfer until data exhausted, 2015 * no timeout, one callback 2016 * x OUT none != NULL !=0 xfer until data exhausted, 2017 * with timeout, one callback 2018 * 2019 * - Reads (IN): 2020 * 2021 * The client driver does *not* provide a data buffer. 2022 * By default, a READ request would mean continuous polling for data IN. The 2023 * HCD typically reads "wMaxPacketSize" amount of 'periodic data'. A client 2024 * driver may force the HCD to read instead intr_len 2025 * amount of 'periodic data' (See section 1). 2026 * 2027 * The HCD issues a callback to the client after each polling interval if 2028 * it has read in some data. Note that the amount of data read IN is either 2029 * intr_len or 'wMaxPacketSize' in length. 2030 * 2031 * Normally, the HCD keeps polling interrupt pipe forever even if there is 2032 * no data to be read IN. A client driver may stop this polling by 2033 * calling usb_pipe_stop_intr_polling(). 2034 * 2035 * If a client driver chooses to pass USB_ATTRS_ONE_XFER as 2036 * 'xfer_attributes' the HCD will poll for data until some data is received. 2037 * HCD reads in the data and does a callback and stops polling for any more 2038 * data. In this case, the client driver need not explicitly call 2039 * usb_pipe_stop_intr_polling(). 2040 * 2041 * When continuous polling is stopped, the original request is returned with 2042 * USB_CR_STOPPED_POLLING. 2043 * 2044 * - Writes (OUT): 2045 * 2046 * A client driver provides the data buffer, and data, needed for intr write. 2047 * There is no continuous write mode, a la read (See previous section). 2048 * The USB_ATTRS_ONE_XFER attribute is illegal. 2049 * By default USBA keeps writing intr data until the provided data buffer 2050 * has been written out. The HCD does ONE callback to the client driver. 2051 * Queueing is supported. 2052 * Max size is 8k 2053 */ 2054 typedef struct usb_intr_req { 2055 uint_t intr_len; /* OUT: size of total xfer */ 2056 /* IN : packet size */ 2057 mblk_t *intr_data; /* the data for the data phase */ 2058 /* IN: allocated by HCD */ 2059 /* OUT: allocated by client */ 2060 usb_opaque_t intr_client_private; /* Client specific information */ 2061 uint_t intr_timeout; /* only with ONE TIME POLL, in secs */ 2062 usb_req_attrs_t intr_attributes; 2063 2064 /* Normal callback function (For synch transfers) */ 2065 void (*intr_cb)(usb_pipe_handle_t ph, 2066 struct usb_intr_req *req); 2067 2068 /* Exception callback function (For asynch transfers) */ 2069 void (*intr_exc_cb)(usb_pipe_handle_t ph, 2070 struct usb_intr_req *req); 2071 2072 /* set by USBA/HCD on completion */ 2073 usb_cr_t intr_completion_reason; /* set by HCD */ 2074 usb_cb_flags_t intr_cb_flags; /* Callback context / handling flgs */ 2075 } usb_intr_req_t; 2076 2077 2078 /* 2079 * Allocate/free usb interrupt pipe request 2080 * 2081 * Arguments: 2082 * dip - pointer to dev_info_t of the client driver 2083 * reqp - pointer to request structure 2084 * len - 0 or length of mblk for this interrupt request 2085 * flags - USB_FLAGS_SLEEP: 2086 * Sleep if resources are not available 2087 * 2088 * Return Values: 2089 * usb_intr_req_t on success, NULL on failure 2090 */ 2091 usb_intr_req_t *usb_alloc_intr_req( 2092 dev_info_t *dip, 2093 size_t len, 2094 usb_flags_t flags); 2095 2096 2097 void usb_free_intr_req( 2098 usb_intr_req_t *reqp); 2099 2100 2101 /* 2102 * usb_pipe_intr_xfer(): 2103 * 2104 * Client drivers call this function to issue the intr xfer to USBA/HCD 2105 * which starts polling the device 2106 * 2107 * Arguments: 2108 * pipe_handle - interrupt pipe handle (obtained via usb_pipe_open() 2109 * reqp - pointer tothe interrupt pipe xfer request (IN or OUT) 2110 * flags - USB_FLAGS_SLEEP: 2111 * wait for resources to be available 2112 * 2113 * return values: 2114 * USB_SUCCESS - success 2115 * USB_FAILURE - unspecified failure 2116 * USB_NO_RESOURCES - no resources 2117 * 2118 * NOTE: start polling on an IN pipe that is already being polled is a NOP. 2119 * We don't queue requests on OUT pipe 2120 */ 2121 int usb_pipe_intr_xfer( 2122 usb_pipe_handle_t pipe_handle, 2123 usb_intr_req_t *req, 2124 usb_flags_t flags); 2125 2126 2127 /* 2128 * usb_pipe_stop_intr_polling(): 2129 * 2130 * Client drivers call this function to stop the automatic data-in/out transfers 2131 * without closing the pipe. 2132 * 2133 * If USB_FLAGS_SLEEP has been specified then this function will block until 2134 * polling has been stopped and all callbacks completed. If USB_FLAGS_SLEEP 2135 * has NOT been specified then polling is terminated when the original 2136 * request that started the polling has been returned with 2137 * USB_CR_STOPPED_POLLING 2138 * 2139 * Stop polling should never fail. 2140 * 2141 * Args:- 2142 * pipe_handle - interrupt pipe handle (obtained via usb_pipe_open()). 2143 * flags - USB_FLAGS_SLEEP: 2144 * wait for the resources to be available. 2145 */ 2146 void usb_pipe_stop_intr_polling( 2147 usb_pipe_handle_t pipe_handle, 2148 usb_flags_t flags); 2149 2150 2151 /* 2152 * =========================================================================== 2153 * USB isochronous xfer management 2154 * =========================================================================== 2155 */ 2156 2157 /* 2158 * The usb frame number is an absolute number since boot and incremented 2159 * every 1 ms. 2160 */ 2161 typedef uint64_t usb_frame_number_t; 2162 2163 /* 2164 * USB ischronous packet descriptor 2165 * 2166 * An array of structures of type usb_isoc_pkt_descr_t must be allocated and 2167 * initialized by the client driver using usb_alloc_isoc_req(). The client 2168 * driver must set isoc_pkt_length in each packet descriptor before submitting 2169 * the request. 2170 */ 2171 typedef struct usb_isoc_pkt_descr { 2172 /* 2173 * Set by the client driver, for all isochronous requests, to the 2174 * number of bytes to transfer in a frame. 2175 */ 2176 ushort_t isoc_pkt_length; 2177 2178 /* 2179 * Set by HCD to actual number of bytes sent/received in frame. 2180 */ 2181 ushort_t isoc_pkt_actual_length; 2182 2183 /* 2184 * Per frame status set by HCD both for the isochronous IN and OUT 2185 * requests. If any status is non-zero then isoc_error_count in the 2186 * isoc_req will be non-zero. 2187 */ 2188 usb_cr_t isoc_pkt_status; 2189 } usb_isoc_pkt_descr_t; 2190 2191 2192 /* 2193 * USB isochronous request 2194 * 2195 * The client driver allocates the usb_isoc_req_t before sending an 2196 * isochronous requests. 2197 * 2198 * USB_FLAGS_SLEEP indicates here just to wait for resources but not 2199 * to wait for completion 2200 * 2201 * Semantics of various combinations for data xfers: 2202 * 2203 * Note: attributes considered in this table are ONE_XFER, START_FRAME, 2204 * XFER_ASAP, SHORT_XFER 2205 * 2206 * 2207 * flags Type attributes data semantics 2208 * --------------------------------------------------------------------- 2209 * x x x NULL illegal 2210 * 2211 * x x ONE_XFER x illegal 2212 * 2213 * x IN x !=NULL continuous polling, 2214 * many callbacks 2215 * 2216 * x IN ISOC_START_FRAME !=NULL invalid if Current_frame# > 2217 * "isoc_frame_no" 2218 * x IN ISOC_XFER_ASAP !=NULL "isoc_frame_no" ignored. 2219 * HCD determines when to 2220 * insert xfer 2221 * 2222 * x OUT ONE_XFER x illegal 2223 * x OUT SHORT_XFER_OK x illegal 2224 * 2225 * x OUT ISOC_START_FRAME !=NULL invalid if Current_frame# > 2226 * "isoc_frame_no" 2227 * x OUT ISOC_XFER_ASAP !=NULL "isoc_frame_no" ignored. 2228 * HCD determines when to 2229 * insert xfer 2230 */ 2231 typedef struct usb_isoc_req { 2232 /* 2233 * Starting frame number will be set by the client driver in which 2234 * to begin this request. This frame number is used to synchronize 2235 * requests queued to different isochronous pipes. The frame number 2236 * is optional and client driver can skip starting frame number by 2237 * setting USB_ISOC_ATTRS_ASAP. In this case, HCD will decide starting 2238 * frame number for this isochronous request. If this field is 0, 2239 * then this indicates an invalid frame number. 2240 */ 2241 usb_frame_number_t isoc_frame_no; 2242 2243 /* 2244 * Number of isochronous data packets. 2245 * The first field is set by client driver and may not exceed 2246 * the maximum number of entries in the usb isochronous packet 2247 * descriptors. 2248 */ 2249 ushort_t isoc_pkts_count; 2250 2251 /* 2252 * The sum of all pkt lengths in the isoc request. Recommend to 2253 * set it to zero, so the sum of isoc_pkt_length in the 2254 * isoc_pkt_descr list will be used automatically and no check 2255 * will be apply to this element. 2256 */ 2257 ushort_t isoc_pkts_length; 2258 2259 /* 2260 * This field will be set by HCD and this field indicates the number 2261 * of packets that completed with errors. 2262 */ 2263 ushort_t isoc_error_count; 2264 2265 /* 2266 * Attributes specific to particular usb isochronous request. 2267 * Supported values are: USB_ATTRS_ISOC_START_FRAME, 2268 * USB_ATTRS_ISOC_XFER_ASAP. 2269 */ 2270 usb_req_attrs_t isoc_attributes; 2271 2272 /* 2273 * Isochronous OUT: 2274 * allocated and set by client driver, freed and zeroed by HCD 2275 * on successful completion 2276 * Isochronous IN: 2277 * allocated and set by HCD, freed by client driver 2278 */ 2279 mblk_t *isoc_data; 2280 2281 /* 2282 * The client driver specific private information. 2283 */ 2284 usb_opaque_t isoc_client_private; 2285 2286 /* 2287 * Isochronous OUT: 2288 * must be allocated & initialized by client driver 2289 * Isochronous IN: 2290 * must be allocated by client driver 2291 */ 2292 struct usb_isoc_pkt_descr *isoc_pkt_descr; 2293 2294 /* Normal callback function (For synch transfers) */ 2295 void (*isoc_cb)(usb_pipe_handle_t ph, 2296 struct usb_isoc_req *req); 2297 2298 /* Exception callback function (For asynch transfers) */ 2299 void (*isoc_exc_cb)(usb_pipe_handle_t ph, 2300 struct usb_isoc_req *req); 2301 2302 /* set by USBA/HCD on completion */ 2303 usb_cr_t isoc_completion_reason; /* set by HCD */ 2304 /* Callback context / handling flgs */ 2305 usb_cb_flags_t isoc_cb_flags; 2306 } usb_isoc_req_t; 2307 2308 2309 /* 2310 * Allocate/free usb isochronous resources 2311 * 2312 * isoc_pkts_count must be > 0 2313 * 2314 * Arguments: 2315 * dip - client driver's devinfo pointer 2316 * isoc_pkts_count - number of pkts required 2317 * len - 0 or size of mblk to allocate 2318 * flags - USB_FLAGS_SLEEP: 2319 * wait for resources 2320 * 2321 * Return Values: 2322 * usb_isoc_req pointer or NULL 2323 */ 2324 usb_isoc_req_t *usb_alloc_isoc_req( 2325 dev_info_t *dip, 2326 uint_t isoc_pkts_count, 2327 size_t len, 2328 usb_flags_t flags); 2329 2330 void usb_free_isoc_req( 2331 usb_isoc_req_t *usb_isoc_req); 2332 2333 /* 2334 * Returns current usb frame number. 2335 */ 2336 usb_frame_number_t usb_get_current_frame_number( 2337 dev_info_t *dip); 2338 2339 /* 2340 * Get maximum isochronous packets per usb isochronous request 2341 */ 2342 uint_t usb_get_max_pkts_per_isoc_request( 2343 dev_info_t *dip); 2344 2345 /* 2346 * usb_pipe_isoc_xfer() 2347 * 2348 * Client drivers call this to issue the isoch xfer (IN and OUT) to the USBA 2349 * which starts polling the device. 2350 * 2351 * Arguments: 2352 * pipe_handle - isoc pipe handle (obtained via usb_pipe_open(). 2353 * reqp - pointer to the isochronous pipe IN xfer request 2354 * allocated by the client driver. 2355 * flags - USB_FLAGS_SLEEP: 2356 * wait for the resources to be available. 2357 * 2358 * return values: 2359 * USB_SUCCESS - success. 2360 * USB_FAILURE - unspecified failure. 2361 * USB_NO_RESOURCES - no resources. 2362 * USB_NO_FRAME_NUMBER - START_FRAME, ASAP flags not specified. 2363 * USB_INVALID_START_FRAME - Starting USB frame number invalid. 2364 * 2365 * Notes: 2366 * - usb_pipe_isoc_xfer on an IN pipe that is already being polled is a NOP. 2367 * - requests can be queued on an OUT pipe. 2368 */ 2369 int usb_pipe_isoc_xfer( 2370 usb_pipe_handle_t pipe_handle, 2371 usb_isoc_req_t *reqp, 2372 usb_flags_t flags); 2373 2374 /* 2375 * usb_pipe_stop_isoc_polling(): 2376 * 2377 * Client drivers call this function to stop the automatic data-in/out 2378 * transfers without closing the isoc pipe. 2379 * 2380 * If USB_FLAGS_SLEEP has been specified then this function will block until 2381 * polling has been stopped and all callbacks completed. If USB_FLAGS_SLEEP 2382 * has NOT been specified then polling is terminated when the original 2383 * request that started the polling has been returned with 2384 * USB_CR_STOPPED_POLLING 2385 * 2386 * Stop polling should never fail. 2387 * 2388 * Arguments: 2389 * pipe_handle - isoc pipe handle (obtained via usb_pipe_open(). 2390 * flags - USB_FLAGS_SLEEP: 2391 * wait for polling to be stopped and all 2392 * callbacks completed. 2393 */ 2394 void usb_pipe_stop_isoc_polling( 2395 usb_pipe_handle_t pipe_handle, 2396 usb_flags_t flags); 2397 2398 /* 2399 * *************************************************************************** 2400 * USB device power management: 2401 * *************************************************************************** 2402 */ 2403 2404 /* 2405 * 2406 * As any usb device will have a max of 4 possible power states 2407 * the #define for them are provided below with mapping to the 2408 * corresponding OS power levels. 2409 */ 2410 #define USB_DEV_PWR_D0 USB_DEV_OS_FULL_PWR 2411 #define USB_DEV_PWR_D1 5 2412 #define USB_DEV_PWR_D2 6 2413 #define USB_DEV_PWR_D3 USB_DEV_OS_PWR_OFF 2414 2415 #define USB_DEV_OS_PWR_0 0 2416 #define USB_DEV_OS_PWR_1 1 2417 #define USB_DEV_OS_PWR_2 2 2418 #define USB_DEV_OS_PWR_3 3 2419 #define USB_DEV_OS_PWR_OFF USB_DEV_OS_PWR_0 2420 #define USB_DEV_OS_FULL_PWR USB_DEV_OS_PWR_3 2421 2422 /* Bit Masks for Power States */ 2423 #define USB_DEV_OS_PWRMASK_D0 1 2424 #define USB_DEV_OS_PWRMASK_D1 2 2425 #define USB_DEV_OS_PWRMASK_D2 4 2426 #define USB_DEV_OS_PWRMASK_D3 8 2427 2428 /* conversion for OS to Dx levels */ 2429 #define USB_DEV_OS_PWR2USB_PWR(l) (USB_DEV_OS_FULL_PWR - (l)) 2430 2431 /* from OS level to Dx mask */ 2432 #define USB_DEV_PWRMASK(l) (1 << (USB_DEV_OS_FULL_PWR - (l))) 2433 2434 /* Macro to check valid power level */ 2435 #define USB_DEV_PWRSTATE_OK(state, level) \ 2436 (((state) & USB_DEV_PWRMASK((level))) == 0) 2437 2438 int usb_handle_remote_wakeup( 2439 dev_info_t *dip, 2440 int cmd); 2441 2442 /* argument to usb_handle_remote wakeup function */ 2443 #define USB_REMOTE_WAKEUP_ENABLE 1 2444 #define USB_REMOTE_WAKEUP_DISABLE 2 2445 2446 int usb_create_pm_components( 2447 dev_info_t *dip, 2448 uint_t *pwrstates); 2449 2450 /* 2451 * *************************************************************************** 2452 * System event registration 2453 * *************************************************************************** 2454 */ 2455 2456 /* Functions for registering hotplug callback functions. */ 2457 2458 int usb_register_hotplug_cbs( 2459 dev_info_t *dip, 2460 int (*disconnect_event_handler)(dev_info_t *dip), 2461 int (*reconnect_event_handler)(dev_info_t *dip)); 2462 2463 void usb_unregister_hotplug_cbs(dev_info_t *dip); 2464 2465 /* 2466 * Reset_level determines the extent to which the device is reset, 2467 * It has the following values: 2468 * 2469 * USB_RESET_LVL_REATTACH - The device is reset, the original driver is 2470 * detached and a new driver attaching process 2471 * is started according to the updated 2472 * compatible name. This reset level applies to 2473 * the firmware download with the descriptors 2474 * changing, or other situations in which the 2475 * device needs to be reenumerated. 2476 * 2477 * USB_RESET_LVL_DEFAULT - Default reset level. The device is reset, all 2478 * error status is cleared, the device state 2479 * machines and registers are also cleared and 2480 * need to be reinitialized in the driver. The 2481 * current driver remains attached. This reset 2482 * level applies to hardware error recovery, or 2483 * firmware download without descriptors 2484 * changing. 2485 */ 2486 typedef enum { 2487 USB_RESET_LVL_REATTACH = 0, 2488 USB_RESET_LVL_DEFAULT = 1 2489 } usb_dev_reset_lvl_t; 2490 2491 /* 2492 * usb_reset_device: 2493 * 2494 * Client drivers call this function to request hardware reset for themselves, 2495 * which may be required in some situations such as: 2496 * 2497 * 1) Some USB devices need the driver to upload firmware into devices' RAM 2498 * and initiate a hardware reset in order to activate the new firmware. 2499 * 2) Hardware reset may help drivers to recover devices from an error state 2500 * caused by physical or firmware defects. 2501 * 2502 * Arguments: 2503 * dip - pointer to devinfo of the client 2504 * reset_level - see above 2505 * 2506 * Return values: 2507 * USB_SUCCESS - With USB_RESET_LVL_DEFAULT: the device was reset 2508 * successfully. 2509 * - With USB_RESET_LVL_REATTACH: reenumeration was 2510 * started successfully or a previous reset is still 2511 * in progress. 2512 * USB_FAILURE - The state of the device's parent hub is invalid 2513 * (disconnected or suspended). 2514 * - Called when the driver being detached. 2515 * - The device failed to be reset with 2516 * USB_RESET_LVL_DEFAULT specified. 2517 * - Reenumeration failed to start up with 2518 * - USB_RESET_LVL_REATTACH specified. 2519 * USB_INVALID_ARGS - Invalid arguments. 2520 * USB_INVALID_PERM - The driver of the dip doesn't own entire device. 2521 * USB_BUSY - One or more pipes other than the default control 2522 * pipe are open on the device with 2523 * USB_RESET_LVL_DEFAULT specified. 2524 * USB_INVALID_CONTEXT - Called from interrupt context with 2525 * USB_RESET_LVL_DEFAULT specified. 2526 */ 2527 2528 int usb_reset_device( 2529 dev_info_t *dip, 2530 usb_dev_reset_lvl_t reset_level); 2531 2532 2533 /* 2534 * ************************************************************************** 2535 * USB device driver registration and callback functions remaining 2536 * Contracted Project Private (for VirtualBox USB Device Capture) 2537 * ************************************************************************** 2538 */ 2539 2540 /* 2541 * getting the device strings of manufacturer, product and serial number 2542 */ 2543 typedef struct usb_dev_str { 2544 char *usb_mfg; /* manufacturer string */ 2545 char *usb_product; /* product string */ 2546 char *usb_serialno; /* serial number string */ 2547 } usb_dev_str_t; 2548 2549 /* 2550 * It is the callback function type for capture driver. 2551 * Arguments: 2552 * dev_descr - pointer to device descriptor 2553 * dev_str - pointer to device strings 2554 * path - pointer to device physical path 2555 * bus - USB bus address 2556 * port - USB port number 2557 * drv - capture driver name. 2558 * It is returned by the callback func. 2559 * Return Values: 2560 * USB_SUCCESS - VirtualBox will capture the device 2561 * USB_FAILURE - VirtualBox will not capture the device 2562 */ 2563 typedef int (*usb_dev_driver_callback_t)( 2564 usb_dev_descr_t *dev_descr, 2565 usb_dev_str_t *dev_str, 2566 char *path, 2567 int bus, 2568 int port, 2569 char **drv, 2570 void *reserved); 2571 2572 /* 2573 * Register the callback function in the usba. 2574 * Argument: 2575 * dip - client driver's devinfo pointer 2576 * cb - callback function 2577 * 2578 * Return Values: 2579 * USB_SUCCESS - the registeration was successful 2580 * USB_FAILURE - the registeration failed 2581 */ 2582 int usb_register_dev_driver( 2583 dev_info_t *dip, 2584 usb_dev_driver_callback_t cb); 2585 2586 /* 2587 * Unregister the callback function in the usba. 2588 */ 2589 void usb_unregister_dev_driver(dev_info_t *dip); 2590 2591 2592 /* 2593 * *************************************************************************** 2594 * USB Device and interface class, subclass and protocol codes 2595 * *************************************************************************** 2596 */ 2597 2598 /* 2599 * Available device and interface class codes. 2600 * Those which are device class codes are noted. 2601 */ 2602 2603 #define USB_CLASS_AUDIO 1 2604 #define USB_CLASS_COMM 2 /* Communication device class and */ 2605 #define USB_CLASS_CDC_CTRL 2 /* CDC-control iface class, also 2 */ 2606 #define USB_CLASS_HID 3 2607 #define USB_CLASS_PHYSICAL 5 2608 #define USB_CLASS_IMAGE 6 2609 #define USB_CLASS_PRINTER 7 2610 #define USB_CLASS_MASS_STORAGE 8 2611 #define USB_CLASS_HUB 9 /* Device class */ 2612 #define USB_CLASS_CDC_DATA 10 2613 #define USB_CLASS_CCID 11 2614 #define USB_CLASS_SECURITY 13 2615 #define USB_CLASS_VIDEO 14 2616 #define USB_CLASS_DIAG 220 /* Device class */ 2617 #define USB_CLASS_WIRELESS 224 2618 #define USB_CLASS_MISC 239 /* Device class */ 2619 #define USB_CLASS_APP 254 2620 #define USB_CLASS_VENDOR_SPEC 255 /* Device class */ 2621 2622 #define USB_CLASS_PER_INTERFACE 0 /* Class info is at interface level */ 2623 2624 /* Audio subclass. */ 2625 #define USB_SUBCLS_AUD_CONTROL 0x01 2626 #define USB_SUBCLS_AUD_STREAMING 0x02 2627 #define USB_SUBCLS_AUD_MIDI_STREAMING 0x03 2628 2629 /* Comms subclass. */ 2630 #define USB_SUBCLS_CDCC_DIRECT_LINE 0x01 2631 #define USB_SUBCLS_CDCC_ABSTRCT_CTRL 0x02 2632 #define USB_SUBCLS_CDCC_PHONE_CTRL 0x03 2633 #define USB_SUBCLS_CDCC_MULTCNL_ISDN 0x04 2634 #define USB_SUBCLS_CDCC_ISDN 0x05 2635 #define USB_SUBCLS_CDCC_ETHERNET 0x06 2636 #define USB_SUBCLS_CDCC_ATM_NETWORK 0x07 2637 2638 /* HID subclass and protocols. */ 2639 #define USB_SUBCLS_HID_1 1 2640 2641 #define USB_PROTO_HID_KEYBOARD 0x01 /* legacy keyboard */ 2642 #define USB_PROTO_HID_MOUSE 0x02 /* legacy mouse */ 2643 2644 /* Printer subclass and protocols. */ 2645 #define USB_SUBCLS_PRINTER_1 1 2646 2647 #define USB_PROTO_PRINTER_UNI 0x01 /* Unidirectional interface */ 2648 #define USB_PROTO_PRINTER_BI 0x02 /* Bidirectional interface */ 2649 2650 /* Mass storage subclasses and protocols. */ 2651 #define USB_SUBCLS_MS_RBC_T10 0x1 /* flash */ 2652 #define USB_SUBCLS_MS_SFF8020I 0x2 /* CD-ROM */ 2653 #define USB_SUBCLS_MS_QIC_157 0x3 /* tape */ 2654 #define USB_SUBCLS_MS_UFI 0x4 /* USB Floppy Disk Drive */ 2655 #define USB_SUBCLS_MS_SFF8070I 0x5 /* floppy */ 2656 #define USB_SUBCLS_MS_SCSI 0x6 /* transparent scsi */ 2657 2658 #define USB_PROTO_MS_CBI_WC 0x00 /* USB CBI Proto w/cmp intr */ 2659 #define USB_PROTO_MS_CBI 0x01 /* USB CBI Protocol */ 2660 #define USB_PROTO_MS_ISD_1999_SILICN 0x02 /* ZIP Protocol */ 2661 #define USB_PROTO_MS_BULK_ONLY 0x50 /* USB Bulk Only Protocol */ 2662 2663 /* Hub subclass and protocols */ 2664 #define USB_PROTO_HUB_FULL 0x00 /* Full Speed Protocol */ 2665 #define USB_PROTO_HUB_HIGH_STT 0x01 /* High Speed with STT */ 2666 #define USB_PROTO_HUB_HIGH_MTT 0x02 /* High Speed with MTT */ 2667 #define USB_PROTO_HUB_SUPER 0x03 /* SuperSpeed Protocol */ 2668 2669 /* Application subclasses. */ 2670 #define USB_SUBCLS_APP_FIRMWARE 0x01 /* app spec f/w subclass */ 2671 #define USB_SUBCLS_APP_IRDA 0x02 /* app spec IrDa subclass */ 2672 #define USB_SUBCLS_APP_TEST 0x03 /* app spec test subclass */ 2673 2674 /* Video subclasses */ 2675 #define USB_SUBCLS_VIDEO_CONTROL 0x01 /* video control */ 2676 #define USB_SUBCLS_VIDEO_STREAM 0x02 /* video stream */ 2677 #define USB_SUBCLS_VIDEO_COLLECTION 0x03 /* video interface collection */ 2678 2679 /* Wireless controller subclasses and protocols, refer to WUSB 1.0 chapter 8 */ 2680 #define USB_SUBCLS_WUSB_1 0x01 /* RF controller */ 2681 #define USB_SUBCLS_WUSB_2 0x02 /* Wireless adapter */ 2682 #define USB_PROTO_WUSB_HWA 0x01 /* host wire adapter */ 2683 #define USB_PROTO_WUSB_DWA 0x02 /* device wire adapter */ 2684 #define USB_PROTO_WUSB_DWA_ISO 0x03 /* device wire adapter isoc */ 2685 #define USB_PROTO_WUSB_RC 0x02 /* UWB radio controller */ 2686 2687 /* Association subclass and protocol, Association Model Supplement to WUSB1.0 */ 2688 #define USB_SUBCLS_CBAF 0x03 /* cable association */ 2689 #define USB_PROTO_CBAF 0x01 /* CBAF protocol */ 2690 2691 /* Misc subclasses and protocols, refer to WUSB 1.0 chapter 8 */ 2692 #define USB_SUBCLS_MISC_COMMON 0x02 /* common class */ 2693 #define USB_PROTO_MISC_WA 0x02 /* multifunction wire adapter */ 2694 2695 #ifdef __cplusplus 2696 } 2697 #endif 2698 2699 #endif /* _SYS_USB_USBAI_H */ 2700