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