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