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