xref: /illumos-gate/usr/src/uts/common/sys/usb/usba/usba_private.h (revision 0d2006e4703eda0f88de2e571bf9fb317552faa2)
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_USBA_USBA_PRIVATE_H
30 #define	_SYS_USB_USBA_USBA_PRIVATE_H
31 
32 
33 #include <sys/sunndi.h>
34 
35 /*
36  * Header file for items to be shared within usba but not to be used
37  * by drivers
38  */
39 
40 #ifdef	__cplusplus
41 extern "C" {
42 #endif
43 
44 /*
45  * **************************************************************************
46  * DDK version 0.8 binaries are supported.
47  * **************************************************************************
48  */
49 
50 /* USBA supports (obsolete) legacy version 0.8 of the S8/S9 DDK. */
51 #define	USBA_LEG_MAJOR_VER	0
52 #define	USBA_LEG_MINOR_VER	8
53 
54 /*
55  * **************************************************************************
56  * Descriptor definitions and parsing functions.
57  * **************************************************************************
58  */
59 
60 /*
61  * functions to return a pre-processed device descriptor to the client driver.
62  * These all extract data from the raw config cloud  returned by a
63  * usb_get_raw_cfg_data()
64  *
65  * The pre-processed descriptor is returned into a buffer supplied by
66  * the caller
67  * The size of the buffer should allow for padding
68  *
69  * In the following:
70  *	buf		buffer containing data returned by GET_DESCRIPTOR
71  *	buflen		length of the data at buf
72  *	ret_descr	buffer the data is to be returned in
73  *	ret_buf_len	size of the buffer at ret_descr
74  *
75  * 	first_if	the first interace associated with current iad
76  *	if_index	the index in the array of concurrent interfaces
77  *			supported by this configuration
78  *	alt_if_setting	alternate setting for the interface identified
79  *			by if_index
80  *	ep_index	the index in the array of endpoints supported by
81  *			this configuration
82  *
83  * These functions return the length of the returned descriptor structure,
84  * or USB_PARSE_ERROR on error.
85  *
86  * No error is returned if ret_buf_len is too small but
87  * the data is truncated
88  * This allows successful parsing of descriptors that have been
89  * extended in a later rev of the spec.
90  */
91 size_t usb_parse_dev_descr(
92 	const uchar_t		*buf,	/* from GET_DESCRIPTOR(DEVICE) */
93 	size_t			buflen,
94 	usb_dev_descr_t		*ret_descr,
95 	size_t			ret_buf_len);
96 
97 
98 size_t usb_parse_cfg_descr(
99 	const uchar_t		*buf,	/* from GET_DESCRIPTOR(CONFIGURATION) */
100 	size_t			buflen,
101 	usb_cfg_descr_t		*ret_descr,
102 	size_t			ret_buf_len);
103 
104 
105 size_t usb_parse_ia_descr(
106 	const uchar_t		*buf,	/* from GET_DESCRIPTOR(CONFIGURATION) */
107 	size_t			buflen,
108 	size_t			first_if,
109 	usb_ia_descr_t		*ret_descr,
110 	size_t			ret_buf_len);
111 
112 
113 size_t usb_parse_if_descr(
114 	const uchar_t		*buf,	/* from GET_DESCRIPTOR(CONFIGURATION) */
115 	size_t			buflen,
116 	uint_t			if_index,
117 	uint_t			alt_if_setting,
118 	usb_if_descr_t		*ret_descr,
119 	size_t			ret_buf_len);
120 
121 
122 /*
123  * the endpoint index is relative to the interface. index 0 is
124  * the first endpoint
125  */
126 size_t usb_parse_ep_descr(
127 	const uchar_t		*buf,	/* from GET_DESCRIPTOR(CONFIGURATION) */
128 	size_t			buflen,
129 	uint_t			if_index,
130 	uint_t			alt_if_setting,
131 	uint_t			ep_index,
132 	usb_ep_descr_t		*ret_descr,
133 	size_t			ret_buf_len);
134 
135 /*
136  * functions to handle arbitrary descriptors. USBA doesn't know the format
137  * and therefore cannot do any automatic pre-processing.
138  *
139  * In the following:
140  *	buf		buffer containing data returned by GET_DESCRIPTOR
141  *	buflen		length of the data at buf allowing for padding
142  *	fmt		a null terminated string describing the format of
143  *			the data structure for general-purpose byte swapping,
144  *			use NULL for raw access.
145  *			The letters "c", "s", "l", and "L"
146  *			represent 1, 2, 4, and 8 byte quantities,
147  *			respectively.  A descriptor that consists of a
148  *			short and two bytes would be described by "scc\0".
149  *	descr_type	type of the desired descriptor, USB_DESCR_TYPE_ANY
150  *			to get any type.
151  *	descr_index	index of the desired descriptor
152  *	ret_descr	buffer the data is to be returned in
153  *	ret_buf_len	size of the buffer at ret_descr
154  *
155  * Specifying descr_index=0 returns the first descriptor of the specified
156  * type, specifying descr_index=1 returns the second, and so on.
157  *
158  * No error is returned if ret_buf_len is too small. This allows successful
159  * parsing of descriptors that have been extended in a later rev of the spec.
160  */
161 #define	USB_DESCR_TYPE_ANY			-1	/* Wild card */
162 
163 size_t usb_parse_CV_cfg_descr(
164 	const uchar_t		*buf,	/* from GET_DESCRIPTOR(CONFIGURATION) */
165 	size_t			buflen,
166 	char			*fmt,
167 	uint_t			descr_type,
168 	uint_t			descr_index,
169 	void			*ret_descr,
170 	size_t			ret_buf_len);
171 
172 
173 size_t usb_parse_CV_if_descr(
174 	const uchar_t		*buf,	/* from GET_DESCRIPTOR(CONFIGURATION) */
175 	size_t			buflen,
176 	char			*fmt,
177 	uint_t			if_index,
178 	uint_t			alt_if_setting,
179 	uint_t			descr_type,
180 	uint_t			descr_index,
181 	void			*ret_descr,
182 	size_t			ret_buf_len);
183 
184 
185 size_t usb_parse_CV_ep_descr(
186 	const uchar_t		*buf,	/* from GET_DESCRIPTOR(CONFIGURATION) */
187 	size_t			buflen,
188 	char			*fmt,
189 	uint_t			if_index,
190 	uint_t			alt_if_setting,
191 	uint_t			ep_index,
192 	uint_t			descr_type,
193 	uint_t			descr_index,
194 	void			*ret_descr,
195 	size_t			ret_buf_len);
196 
197 
198 /*
199  * for unpacking any kind of LE data
200  */
201 size_t usb_parse_CV_descr(
202 	char			*format,
203 	const uchar_t		*data,
204 	size_t			datalen,
205 	void			*structure,
206 	size_t			structlen);
207 
208 /*
209  * Returns pointer to the raw config cloud. The client should
210  * not free this space.
211  */
212 uchar_t *usb_get_raw_cfg_data(
213 	dev_info_t		*dip,
214 	size_t			*length);
215 
216 /*
217  * Return pointer to device descriptor
218  */
219 usb_dev_descr_t *usb_get_dev_descr(
220 	dev_info_t		*dip);
221 
222 
223 /*
224  * **************************************************************************
225  * List entry functions and definitions
226  * **************************************************************************
227  */
228 
229 /*
230  * Data structure for maintaining lists
231  * This data structure private to USBA and not exposed to HCD or client
232  * driver or hub driver
233  */
234 typedef struct usba_list_entry {
235 	struct usba_list_entry	*next;		/* ptr to next element */
236 	struct usba_list_entry	*prev;		/* ptr to previous element */
237 	kmutex_t		list_mutex;	/* mutex that protects queue */
238 	usb_opaque_t		private;	/* ptr to private data */
239 	int			count;		/* for head of the list */
240 						/* counts of entries */
241 } usba_list_entry_t;
242 
243 _NOTE(MUTEX_PROTECTS_DATA(usba_list_entry::list_mutex, usba_list_entry))
244 
245 
246 /* list entry functions. */
247 void	usba_init_list(usba_list_entry_t *, usb_opaque_t,
248 					ddi_iblock_cookie_t);
249 void	usba_destroy_list(usba_list_entry_t *);
250 void	usba_add_to_list(usba_list_entry_t *, usba_list_entry_t *);
251 int	usba_rm_from_list(usba_list_entry_t *, usba_list_entry_t *);
252 void	usba_move_list(usba_list_entry_t *, usba_list_entry_t *,
253 					ddi_iblock_cookie_t);
254 int	usba_check_in_list(usba_list_entry_t *, usba_list_entry_t *);
255 int	usba_list_entry_leaks(usba_list_entry_t *, char *);
256 int	usba_list_entry_count(usba_list_entry_t *);
257 
258 usb_opaque_t usba_rm_first_pvt_from_list(usba_list_entry_t *);
259 usba_list_entry_t *usba_rm_first_from_list(usba_list_entry_t *);
260 
261 /*
262  * **************************************************************************
263  * Kernel interface definitions and functionality
264  * **************************************************************************
265  */
266 
267 /*
268  * USBA private event definitions
269  */
270 typedef enum usba_event {
271 	USBA_EVENT_TAG_HOT_REMOVAL = 0,
272 	USBA_EVENT_TAG_HOT_INSERTION = 1,
273 	USBA_EVENT_TAG_PRE_SUSPEND = 2,
274 	USBA_EVENT_TAG_POST_RESUME = 3
275 } usba_event_t;
276 
277 #define	USBA_PRE_SUSPEND_EVENT	"SUNW,USBA:USBA_PRE_SUSPEND"
278 #define	USBA_POST_RESUME_EVENT	"SUNW,USBA:USBA_POST_RESUME"
279 
280 /*
281  * Get dma attributes from HC.
282  */
283 ddi_dma_attr_t *usba_get_hc_dma_attr(dev_info_t *dip);
284 
285 /*
286  * This function calls ndi_devi_bind_driver() to bind the
287  * driver to the device. If the call fails it reports an
288  * error on the console. Attaching of the driver is done
289  * later by devfs framework.
290  */
291 int usba_bind_driver(dev_info_t *);
292 
293 /* check whether the dip owns an interface-associaiton */
294 boolean_t usba_owns_ia(dev_info_t *dip);
295 
296 /*
297  * Driver binding functions
298  */
299 dev_info_t *usba_ready_device_node(dev_info_t *);
300 dev_info_t *usba_ready_interface_association_node(dev_info_t *,
301 					uint_t, uint_t *);
302 dev_info_t *usba_ready_interface_node(dev_info_t *, uint_t);
303 
304 /* Some Nexus driver functions. */
305 
306 /*
307  * Common bus ctl for hcd, usb_mid and hubd.
308  */
309 int	usba_bus_ctl(dev_info_t *, dev_info_t *, ddi_ctl_enum_t,
310 					void *, void *);
311 
312 void	usb_enable_parent_notification(dev_info_t *);
313 
314 /*
315  * Some functions for setting/getting usba_device from dip.
316  */
317 struct	usba_device	*usba_get_usba_device(dev_info_t *);
318 struct	usba_device	*usba_polled_get_usba_device(dev_info_t *);
319 void	usba_set_usba_device(dev_info_t *, struct usba_device *);
320 
321 /* extract NDI event registration info */
322 struct	usba_evdata	*usba_get_evdata(dev_info_t *);
323 
324 /*
325  * **************************************************************************
326  * Misc private USBA functions
327  * **************************************************************************
328  */
329 
330 /*
331  * Get policy of a pipe while holding only opaque pipe handle.
332  */
333 usb_pipe_policy_t *usba_pipe_get_policy(usb_pipe_handle_t);
334 
335 /*
336  * Check interrupt context and or in USB_CB_INTR_CONTEXT to cb_flags as needed.
337  */
338 usb_cb_flags_t	usba_check_intr_context(usb_cb_flags_t);
339 
340 /* returns interface number, zero if driver owns the device */
341 uint8_t	usba_get_ifno(dev_info_t *);
342 
343 /*
344  * **************************************************************************
345  * Misc private descriptor definitions and functionality
346  * **************************************************************************
347  */
348 
349 /* default endpoint descriptor */
350 extern usb_ep_descr_t   usba_default_ep_descr;
351 
352 /*
353  * The compiler pads the above structures;  the following represent the
354  * unpadded, aggregate data sizes.
355  */
356 #define	USB_DEV_DESCR_SIZE	18	/* device descr size */
357 #define	USB_CFG_DESCR_SIZE	 9	/* configuration desc. size */
358 #define	USBA_CFG_PWR_DESCR_SIZE	18	/* configuration pwr desc. size */
359 #define	USB_IF_DESCR_SIZE	 9	/* interface descr size */
360 #define	USBA_IF_PWR_DESCR_SIZE	15	/* interface pwr descr size */
361 #define	USB_EP_DESCR_SIZE	 7	/* endpoint descr size */
362 #define	USB_IA_DESCR_SIZE	 8	/* interface association descr size */
363 
364 /*
365  * For compatibility with old code.
366  */
367 #define	USBA_DESCR_TYPE_CFG_PWR_1_1	0xfe
368 #define	USBA_DESCR_TYPE_IF_PWR_1_1	0xff
369 
370 /*
371  * Configuration Power Descriptor
372  *	This reports the power consuption of the device core
373  *	for all types of USB devices.
374  */
375 typedef struct usba_cfg_pwr_descr {
376 	uint8_t		bLength;	/* size of this descriptor 0x12 */
377 	uint8_t		bDescriptorType;	/* config pwr descr 0x07 */
378 	uint16_t	SelfPowerConsumedD0_l;	/* power consumed lower word */
379 	uint8_t		SelfPowerConsumedD0_h;	/* power consumed upper byte */
380 	uint8_t		bPowerSummaryId;	/* ID for own power devices */
381 	uint8_t		bBusPowerSavingD1;	/* power saving in D1 */
382 	uint8_t		bSelfPowerSavingD1;	/* power saving in D1 */
383 	uint8_t		bBusPowerSavingD2;	/* power saving in D2 */
384 	uint8_t		bSelfPowerSavingD2;	/* power saving in D2 */
385 	uint8_t		bBusPowerSavingD3;	/* power saving in D3 */
386 	uint8_t		bSelfPowerSavingD3;	/* power saving in D3 */
387 	uint16_t	TransitionTimeFromD1;	/* D1 -> D0 transition time */
388 	uint16_t	TransitionTimeFromD2;	/* D2 -> D0 transition time */
389 	uint16_t	TransitionTimeFromD3;	/* D3 -> D0 transition time */
390 } usba_cfg_pwr_descr_t;
391 
392 /*
393  * Interface Power Descriptor
394  *	This reports the power states implemented by the interface
395  *	and its wake-up capabilities.
396  */
397 typedef struct usba_if_pwr_descr {
398 	uint8_t		bLength;	/* size of this descriptor 0x0F */
399 	uint8_t		bDescriptorType;	/* i/f pwr descr 0x08 */
400 	uint8_t		bmCapabilitiesFlags;	/* wakeup & pwr transition */
401 	uint8_t		bBusPowerSavingD1;	/* power saving in D1 */
402 	uint8_t		bSelfPowerSavingD1;	/* power saving in D1 */
403 	uint8_t		bBusPowerSavingD2;	/* power saving in D2 */
404 	uint8_t		bSelfPowerSavingD2;	/* power saving in D2 */
405 	uint8_t		bBusPowerSavingD3;	/* power saving in D3 */
406 	uint8_t		bSelfPowerSavingD3;	/* power saving in D3 */
407 	uint16_t	TransitionTimeFromD1;	/* D1 -> D0 transition time */
408 	uint16_t	TransitionTimeFromD2;	/* D2 -> D0 transition time */
409 	uint16_t	TransitionTimeFromD3;	/* D3 -> D0 transition time */
410 } usba_if_pwr_descr_t;
411 
412 size_t usba_parse_cfg_pwr_descr(const uchar_t *, size_t, usba_cfg_pwr_descr_t *,
413     size_t);
414 
415 size_t usba_parse_if_pwr_descr(const uchar_t *, size_t buflen, uint_t,
416     uint_t, usba_if_pwr_descr_t *, size_t);
417 
418 /*
419  * Returns (at ret_descr) a null-terminated string.  Null termination is
420  * guaranteed, even if the string is longer than the buffer.  Thus, a
421  * maximum of (ret_buf_len - 1) characters are returned.
422  *
423  * XXX is this needed when there is usb_get_string_descriptor
424  * If so, then more comments about how it differs?
425  */
426 size_t usba_ascii_string_descr(const uchar_t *, size_t, char *, size_t);
427 
428 
429 /*
430  * usb common power management, for usb_mid, usb_ia and maybe other simple
431  * drivers.
432  */
433 typedef struct usb_common_power_struct {
434 	void		*uc_usb_statep;	/* points back to state structure */
435 
436 	uint8_t		uc_wakeup_enabled;
437 
438 	/* this is the bit mask of the power states that device has */
439 	uint8_t		uc_pwr_states;
440 
441 	/* wakeup and power transition capabilites of an interface */
442 	uint8_t		uc_pm_capabilities;
443 
444 	uint8_t		uc_current_power;	/* current power level */
445 } usb_common_power_t;
446 
447 /* warlock directives, stable data */
448 
449 _NOTE(DATA_READABLE_WITHOUT_LOCK(usb_common_power_t::uc_usb_statep))
450 _NOTE(DATA_READABLE_WITHOUT_LOCK(usb_common_power_t::uc_wakeup_enabled))
451 _NOTE(DATA_READABLE_WITHOUT_LOCK(usb_common_power_t::uc_pwr_states))
452 _NOTE(DATA_READABLE_WITHOUT_LOCK(usb_common_power_t::uc_pm_capabilities))
453 _NOTE(DATA_READABLE_WITHOUT_LOCK(usb_common_power_t::uc_current_power))
454 
455 /* power management */
456 int usba_common_power(dev_info_t *, uint8_t *, int *, int);
457 
458 /*
459  * usb common events handler for usb_mid, usb_ia and maybe other nexus
460  * drivers.
461  */
462 
463 void usba_common_register_events(dev_info_t *, uint_t,
464 	void (*)(dev_info_t *, ddi_eventcookie_t, void *, void *));
465 
466 void usba_common_unregister_events(dev_info_t *, uint_t);
467 
468 
469 #ifdef	__cplusplus
470 }
471 #endif
472 
473 #endif	/* _SYS_USB_USBA_USBA_PRIVATE_H */
474