xref: /illumos-gate/usr/src/uts/common/sys/usb/usba/usbai_private.h (revision d235eb05fe584753047218e3a6dd344d0154d19b)
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 2008 Sun Microsystems, Inc.  All rights reserved.
23  * Use is subject to license terms.
24  */
25 
26 #ifndef	_SYS_USB_USBA_USBAI_PRIVATE_H
27 #define	_SYS_USB_USBA_USBAI_PRIVATE_H
28 
29 
30 /*
31  * Unstable interfaces not part of USBAI but used by Solaris client drivers.
32  * These interfaces may not be present in future releases and are highly
33  * unstable.
34  *
35  * Status key:
36  *	C = Remove from Sun client drivers before removing from this file
37  *	D = May be needed by legacy (DDK) drivers.
38  */
39 
40 #ifdef	__cplusplus
41 extern "C" {
42 #endif
43 
44 /*
45  * convenience function for getting default config index
46  * as saved in usba_device structure
47  *
48  * Status: C
49  */
50 uint_t usb_get_current_cfgidx(dev_info_t *);
51 
52 /*
53  * **************************************************************************
54  * Error and status definitions, and reporting functions
55  * **************************************************************************
56  */
57 
58 
59 /*
60  * convenience functions to get string corresponding to value
61  * usb_cb_flags_name requires a workbuffer of sufficient length
62  * for the concatenation of all strings as usb_cb_flags_t is a bit
63  * mask
64  *
65  * Status: C and D
66  */
67 const char	*usb_str_cr(usb_cr_t cr);
68 char		*usb_str_cb_flags(usb_cb_flags_t cb_flags,
69 		char *buffer, size_t length);
70 const char	*usb_str_pipe_state(usb_pipe_state_t state);
71 const char	*usb_str_dev_state(int state);
72 const char	*usb_str_rval(int rval);
73 
74 /* function convert a USB return value to an errno */
75 int		usb_rval2errno(int rval);
76 
77 /*
78  * **************************************************************************
79  * Transfer-related definitions and functions
80  * **************************************************************************
81  */
82 
83 /* Status C and D for whole section. */
84 
85 /* Serialize callbacks per interface or device. */
86 #define	USB_FLAGS_SERIALIZED_CB	0x8000
87 
88 /* default timeout for control requests (in seconds) */
89 #define	USB_PIPE_TIMEOUT	3
90 
91 /*
92  * usb_pipe_sync_ctrl_xfer():
93  *	for simple synchronous control transactions this wrapper function
94  *	will perform the allocation, xfer, and deallocation.
95  *	USB_ATTRS_AUTOCLEARING will be enabled
96  *
97  * ARGUMENTS:
98  *	dip		- pointer to clients devinfo.
99  *	pipe_handle	- control pipe pipehandle (obtained via usb_pipe_open().
100  *	bmRequestType	- characteristics of request.
101  *	bRequest	- specific request.
102  *	wValue		- varies according to request.
103  *	wIndex		- index or offset.
104  *	wLength		- number of bytes to xfer.
105  *	data		- pointer to pointer to data
106  *			  IN: HCD will allocate data
107  *			  OUT: clients driver allocates data.
108  *	attrs		- required request attributes.
109  *	completion_reason - completion status.
110  *	cb_flags	- request completions flags.
111  *	flags		- none.
112  *
113  * RETURN VALUES:
114  *	USB_SUCCESS	- request successfully executed.
115  *	USB_FAILURE	- request failed.
116  *
117  * NOTES:
118  * - in the case of failure, the client should check completion_reason and
119  *   and cb_flags and determine further recovery action
120  * - the client should check data and if non-zero, free the data on
121  *   completion
122  */
123 int usb_pipe_sync_ctrl_xfer(
124 	dev_info_t	*dip,
125 	usb_pipe_handle_t pipe_handle,
126 	uchar_t 	bmRequestType,
127 	uchar_t 	bRequest,
128 	uint16_t	wValue,
129 	uint16_t	wIndex,
130 	uint16_t	wLength,
131 	mblk_t		**data,
132 	usb_req_attrs_t attrs,
133 	usb_cr_t	*completion_reason,
134 	usb_cb_flags_t	*cb_flags,
135 	usb_flags_t	flags);
136 
137 /*
138  * **************************************************************************
139  * Event registration / pre-suspend and post-resume handling
140  * **************************************************************************
141  */
142 
143 /* Status: C and D for whole section. */
144 
145 /*
146  * Event registration info for both hotplug and pre-suspend/post-resume
147  * callbacks.  Eventually pre-suspend and post-resume callbacks will not be
148  * needed, so this is for this OS release only and will go away in a
149  * subsequent release.
150  */
151 typedef struct usb_event {
152 	/* device disconnected/unplugged */
153 	int	(*disconnect_event_handler)(dev_info_t *dip);
154 
155 	/* device reconnected */
156 	int	(*reconnect_event_handler)(dev_info_t *dip);
157 
158 	/* notification that system is about to checkpoint */
159 	int	(*pre_suspend_event_handler)(dev_info_t *dip);
160 
161 	/* notification that system resumed after a checkpoint */
162 	int	(*post_resume_event_handler)(dev_info_t *dip);
163 } usb_event_t;
164 
165 /*
166  * Event callbacks
167  *	the callbacks should always return USB_SUCCESS.
168  */
169 int usb_register_event_cbs(
170 	dev_info_t	*dip,
171 	usb_event_t	*usb_evt_data,
172 	usb_flags_t	flags);
173 
174 void usb_unregister_event_cbs(
175 	dev_info_t	*dip,
176 	usb_event_t	*usb_evt_data);
177 
178 /*
179  * USB CPR support
180  *	A client driver must call this funtion in pre-suspend event handler
181  *	to inform the USBA framework that it can't suspend because
182  *	driver instance or device could not be quiesced.
183  */
184 void usb_fail_checkpoint(
185 	dev_info_t	*dip,
186 	usb_flags_t	flags);
187 
188 
189 /*
190  * **************************************************************************
191  * Logging functions remaining Contracted Consolidation Private
192  * **************************************************************************
193  */
194 
195 /* Status: C and D for whole section. */
196 
197 /*
198  * Usb logging, debug and console message handling.
199  */
200 typedef struct usb_log_handle *usb_log_handle_t;
201 
202 #define	USB_LOG_L0	0	/* warnings, console & syslog buffer */
203 #define	USB_LOG_L1	1	/* errors, syslog buffer */
204 #define	USB_LOG_L2	2	/* recoverable errors, debug only */
205 #define	USB_LOG_L3	3	/* interesting data, debug only */
206 #define	USB_LOG_L4	4	/* tracing, debug only */
207 
208 #ifdef DEBUG
209 #define	USB_DPRINTF_L4(...)	usb_dprintf4(__VA_ARGS__)
210 #define	USB_DPRINTF_L3(...)	usb_dprintf3(__VA_ARGS__)
211 
212 /*PRINTFLIKE3*/
213 void usb_dprintf4(
214 	uint_t		mask,
215 	usb_log_handle_t handle,
216 	char		*fmt, ...);
217 /*PRINTFLIKE3*/
218 void usb_dprintf3(
219 	uint_t		mask,
220 	usb_log_handle_t handle,
221 	char		*fmt, ...);
222 #else
223 #define	USB_DPRINTF_L4(...)	((void)0)
224 #define	USB_DPRINTF_L3(...)	((void)0)
225 #endif
226 
227 #define	USB_DPRINTF_L2	usb_dprintf2
228 #define	USB_DPRINTF_L1	usb_dprintf1
229 #define	USB_DPRINTF_L0	usb_dprintf0
230 
231 /*PRINTFLIKE3*/
232 void usb_dprintf2(
233 	uint_t		mask,
234 	usb_log_handle_t handle,
235 	char		*fmt, ...);
236 /*PRINTFLIKE3*/
237 void usb_dprintf1(
238 	uint_t		mask,
239 	usb_log_handle_t handle,
240 	char		*fmt, ...);
241 /*PRINTFLIKE3*/
242 void usb_dprintf0(
243 	uint_t		mask,
244 	usb_log_handle_t handle,
245 	char		*fmt, ...);
246 
247 usb_log_handle_t usb_alloc_log_hdl(
248 	dev_info_t	*dip,
249 	char		*name,
250 	uint_t		*errlevel,
251 	uint_t		*mask,
252 	uint_t		*instance_filter,
253 	usb_flags_t	flags);
254 
255 /* free the log handle */
256 void usb_free_log_hdl(
257 	usb_log_handle_t handle);
258 
259 /* log message */
260 /*PRINTFLIKE4*/
261 int usb_log(
262 	usb_log_handle_t handle,
263 	uint_t		level,
264 	uint_t		mask,
265 	char		*fmt, ...);
266 
267 /*
268  * usb_check_same_device:
269  *	Check if the device connected to the port is the same as
270  *	the previous device that was in the port.  The previous device is
271  *	represented by the dip on record for the port.	Print a message
272  *	if the device is different.  If device_string arg is not NULL, it is
273  *	included in the message.  Can block.
274  *
275  * Arguments:
276  *	dip			- pointer to devinfo of the client
277  *	log_handle		- handle to which messages are logged
278  *	log_level		- one of USB_LOG_*
279  *	log_mask		- logging mask
280  *	check_mask		- one mask containing things to check:
281  *					USB_CHK_BASIC: empty mask;
282  *						these checks are always done.
283  *					USB_CHK_SERIAL: check match on device
284  *						serial number.
285  *					USB_CHK_CFG: compare config clouds
286  *						byte by byte
287  *					USB_CHK_VIDPID: compare product
288  *						and vendor ID
289  *					USB_CHK_ALL: perform all checks
290  *
291  *				NOTE: descr length and content always checked
292  *	device_string		- Device string to appear in error message
293  *
294  * return values:
295  *	USB_SUCCESS:		same device
296  *	USB_INVALID_VERSION	not same device
297  *	USB_FAILURE:		Failure processing request
298  *	USB_INVALID_ARG:	dip is invalid
299  */
300 
301 /* Checking bits for checks made by usb_check_same_device */
302 #define	USB_CHK_BASIC	0		/* Empty mask.	Basics always done. */
303 #define	USB_CHK_SERIAL	0x00000001	/* Compare device serial numbers. */
304 #define	USB_CHK_CFG	0x00000002	/* Compare raw config clouds. */
305 #define	USB_CHK_VIDPID	0x00000004	/* Compare product and vendor ID. */
306 #define	USB_CHK_ALL	0xFFFFFFFF	/* Perform maximum checking. */
307 
308 int usb_check_same_device(
309 	dev_info_t		*dip,
310 	usb_log_handle_t	log_handle,
311 	int			log_level,
312 	int			log_mask,
313 	uint_t			check_mask,
314 	char			*device_string);
315 
316 /*
317  * **************************************************************************
318  * Power management functions remaining Contracted Consolidation Private
319  * **************************************************************************
320  */
321 
322 /*
323  * usb wrapper around pm_raise_power & pm_lower_power to allow for
324  * non blocking behavior
325  *
326  * Arguments:
327  *	dip		- pointer to devinfo node of client.
328  *	comp		- component.
329  *	level		- power level.
330  *	flags		- USB_FLAGS_SLEEP:
331  *				wait for completion.
332  *	cb		- function called on completion, may be NULL.
333  *	arg		- callback argument.
334  *	rval		- USB_SUCCESS or USB_FAILURE.
335  *
336  * Return Values:
337  *	USB_SUCCESS	-  if no USB_FLAGS_SLEEP has been specified, the request
338  *			   has been queued for async execution. If
339  *			   USB_FLAGS_SLEEP has been specified, the raising or
340  *			   lowering of power
341  *			   succeeded.
342  *	USB_FAILURE	-  request could not be queued or raising or lowering
343  *			   of power failed.
344  */
345 
346 /* Status: C and D */
347 int usb_req_raise_power(
348 	dev_info_t	*dip,
349 	int		comp,
350 	int		level,
351 	void		(*cb)(void *arg, int rval),
352 	void		*arg,
353 	usb_flags_t	flags);
354 
355 /* Status: D */
356 int usb_req_lower_power(
357 	dev_info_t	*dip,
358 	int		comp,
359 	int		level,
360 	void		(*cb)(void *arg, int rval),
361 	void		*arg,
362 	usb_flags_t	flags);
363 
364 /*
365  * USB wrapper functions to set usb device power level.
366  * Note : Power levels indicated here are USB power levels
367  * and not OS power levels.
368  *
369  * Note that these were never implemented, and are noops.  However, they are
370  * included here as the skeleton driver in DDK 0.8 and 0.9 mentioned them.
371  *
372  * Status: C and D.
373  */
374 int usb_set_device_pwrlvl0(
375 	dev_info_t	*dip);
376 int usb_set_device_pwrlvl1(
377 	dev_info_t	*dip);
378 int usb_set_device_pwrlvl2(
379 	dev_info_t	*dip);
380 int usb_set_device_pwrlvl3(
381 	dev_info_t	*dip);
382 
383 
384 /*
385  * **************************************************************************
386  * Serialization functions remaining Contracted Consolidation Private
387  * **************************************************************************
388  */
389 
390 /* This whole section: status: C and D. */
391 
392 /*
393  * opaque serialization handle.
394  *	Used by all usb_serialization routines.
395  *
396  *	This handle is opaque to the client driver.
397  */
398 typedef	struct usb_serialization	*usb_serialization_t;
399 
400 /*
401  * usb_init_serialization
402  *	setup for serialization
403  *
404  * ARGUMENTS:
405  *	s_dip		- devinfo pointer
406  *	flag		- USB_INIT_SER_CHECK_SAME_THREAD
407  *			  when set, usb_release_access() will
408  *			  verify that the same thread releases
409  *			  access. If not, a console warning will
410  *			  be issued but access will be released
411  *			  anyways.
412  *
413  * RETURNS:
414  *	usb_serialization handle
415  *
416  */
417 usb_serialization_t usb_init_serialization(
418 	dev_info_t	*s_dip,
419 	uint_t		flag);
420 
421 #define	USB_INIT_SER_CHECK_SAME_THREAD	1
422 
423 /* fini for serialization */
424 void usb_fini_serialization(
425 	usb_serialization_t usb_serp);
426 
427 /*
428  * Various ways of calling usb_serialize_access.  These correspond to
429  * their cv_*wait* function counterparts for usb_serialize_access.
430  */
431 #define	USB_WAIT		0
432 #define	USB_WAIT_SIG		1
433 #define	USB_TIMEDWAIT		2
434 #define	USB_TIMEDWAIT_SIG	3
435 
436 /*
437  * usb_serialize_access:
438  *	acquire serialized access
439  * ARGUMENTS:
440  *	usb_serp	- usb_serialization handle
441  *	how_to_wait	- Which cv_*wait* function to wait for condition.
442  *				USB_WAIT:		use cv_wait
443  *				USB_WAIT_SIG:		use cv_wait_sig
444  *				USB_TIMEDWAIT:		use cv_timedwait
445  *				USB_TIMEDWAIT_SIG:	use cv_timedwait_sig
446  *	delta_timeout	- Time in ms from current time to timeout.  Checked
447  *			  only if USB_TIMEDWAIT or USB_TIMEDWAIT_SIG
448  *			  specified in how_to_wait.
449  * RETURNS:
450  *	Same as values returned by cv_*wait* functions,
451  *	except for when how_to_wait == USB_WAIT, where 0 is always returned.
452  *	For calls where a timeout or signal could be expected, use this value
453  *	to tell whether a kill(2) signal or timeout occurred.
454  */
455 int usb_serialize_access(
456 	usb_serialization_t	usb_serp,
457 	uint_t			how_to_wait,
458 	uint_t			delta_timeout);
459 
460 /*
461  * usb_try_serialize_access:
462  *	try acquiring serialized access
463  *
464  * ARGUMENTS:
465  *	usb_serp	- usb_serialization handle
466  *	flag		- unused
467  *
468  * RETURNS:
469  *	USB_SUCCESS	- access has been acquired
470  *	USB_FAILURE	- access has not been acquired
471  */
472 int usb_try_serialize_access(usb_serialization_t usb_serp, uint_t flag);
473 
474 /*
475  * usb_release_access:
476  *	release serialized access
477  *
478  * ARGUMENTS:
479  *	usb_serp	- usb_serialization handle
480  */
481 void usb_release_access(usb_serialization_t usb_serp);
482 
483 
484 /*
485  * **************************************************************************
486  * Asynchronous functions remaining Contracted Consolidation Private
487  * **************************************************************************
488  */
489 
490 /* This whole section: status: C and D. */
491 
492 /* For async_req functions. */
493 #define	USB_FLAGS_NOQUEUE	0x200
494 
495 /*
496  * Issue a request to the asynchronous request service
497  * All async request functions return USB_SUCCESS or USB_FAILURE
498  * Arguments:
499  *	dip		- pointer to devinfo node
500  *	func		- pointer of function to execute asynchronously
501  *	arg		- argument to function
502  *	flag		- USB_FLAGS_SLEEP or USB_FLAGS_NOSLEEP or
503  *			  USB_FLAGS_NOQUEUE
504  * Return Values:
505  *	USB_SUCCESS	- function was scheduled
506  *	USB_FAILURE	- function could not be scheduled
507  *
508  * Flag combinations:
509  *	SLEEP		- block waiting for resources. always succeeds
510  *	NOSLEEP		- do not wait for resources, may fail.
511  *	NOSLEEP+NOQUEUE - do not wait for resources, do not queue
512  *	SLEEP+NOQUEUE	- block waiting for resources but may still fail
513  *			  if no thread available
514  */
515 int usb_async_req(
516 	dev_info_t	*dip,
517 	void		(*func)(void *),
518 	void		*arg,
519 	usb_flags_t	flag);
520 
521 
522 /*
523  * index for getting to usb_pipehandle_list in usba_device
524  */
525 uchar_t usb_get_ep_index(uint8_t ep_addr);
526 
527 
528 #ifdef ALLOCB_TEST
529 #define	allocb(s, p) usba_test_allocb(s, p)
530 mblk_t *usba_test_allocb(size_t, uint_t);
531 #endif /* ALLOCB_TEST */
532 
533 /* create an USB style M_CTL message */
534 mblk_t *usba_mk_mctl(struct iocblk, void *, size_t);
535 
536 #ifdef __cplusplus
537 }
538 #endif
539 
540 #endif	/* _SYS_USB_USBA_USBAI_PRIVATE_H */
541