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