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