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