xref: /illumos-gate/usr/src/uts/common/sys/usb/usbai.h (revision e2c88f0c)
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 */
2602