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