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