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