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 */
27
28 #ifndef _SYS_USB_USBA_USBA_PRIVATE_H
29 #define _SYS_USB_USBA_USBA_PRIVATE_H
30
31
32 #include <sys/sunndi.h>
33
34 /*
35 * Header file for items to be shared within usba but not to be used
36 * by drivers
37 */
38
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42
43 /*
44 * **************************************************************************
45 * DDK version 0.8 binaries are supported.
46 * **************************************************************************
47 */
48
49 /* USBA supports (obsolete) legacy version 0.8 of the S8/S9 DDK. */
50 #define USBA_LEG_MAJOR_VER 0
51 #define USBA_LEG_MINOR_VER 8
52
53 /*
54 * **************************************************************************
55 * Descriptor definitions and parsing functions.
56 * **************************************************************************
57 */
58
59 /*
60 * functions to return a pre-processed device descriptor to the client driver.
61 * These all extract data from the raw config cloud returned by a
62 * usb_get_raw_cfg_data()
63 *
64 * The pre-processed descriptor is returned into a buffer supplied by
65 * the caller
66 * The size of the buffer should allow for padding
67 *
68 * In the following:
69 * buf buffer containing data returned by GET_DESCRIPTOR
70 * buflen length of the data at buf
71 * ret_descr buffer the data is to be returned in
72 * ret_buf_len size of the buffer at ret_descr
73 *
74 * first_if the first interace associated with current iad
75 * if_index the index in the array of concurrent interfaces
76 * supported by this configuration
77 * alt_if_setting alternate setting for the interface identified
78 * by if_index
79 * ep_index the index in the array of endpoints supported by
80 * this configuration
81 *
82 * These functions return the length of the returned descriptor structure,
83 * or USB_PARSE_ERROR on error.
84 *
85 * No error is returned if ret_buf_len is too small but
86 * the data is truncated
87 * This allows successful parsing of descriptors that have been
88 * extended in a later rev of the spec.
89 */
90 size_t usb_parse_dev_descr(
91 uchar_t *buf, /* from GET_DESCRIPTOR(DEVICE) */
92 size_t buflen,
93 usb_dev_descr_t *ret_descr,
94 size_t ret_buf_len);
95
96
97 size_t usb_parse_cfg_descr(
98 uchar_t *buf, /* from GET_DESCRIPTOR(CONFIGURATION) */
99 size_t buflen,
100 usb_cfg_descr_t *ret_descr,
101 size_t ret_buf_len);
102
103
104 size_t usb_parse_ia_descr(
105 uchar_t *buf, /* from GET_DESCRIPTOR(CONFIGURATION) */
106 size_t buflen,
107 size_t first_if,
108 usb_ia_descr_t *ret_descr,
109 size_t ret_buf_len);
110
111
112 size_t usb_parse_if_descr(
113 uchar_t *buf, /* from GET_DESCRIPTOR(CONFIGURATION) */
114 size_t buflen,
115 uint_t if_index,
116 uint_t alt_if_setting,
117 usb_if_descr_t *ret_descr,
118 size_t ret_buf_len);
119
120
121 /*
122 * the endpoint index is relative to the interface. index 0 is
123 * the first endpoint
124 */
125 size_t usb_parse_ep_descr(
126 uchar_t *buf, /* from GET_DESCRIPTOR(CONFIGURATION) */
127 size_t buflen,
128 uint_t if_index,
129 uint_t alt_if_setting,
130 uint_t ep_index,
131 usb_ep_descr_t *ret_descr,
132 size_t ret_buf_len);
133
134 /*
135 * functions to handle arbitrary descriptors. USBA doesn't know the format
136 * and therefore cannot do any automatic pre-processing.
137 *
138 * In the following:
139 * buf buffer containing data returned by GET_DESCRIPTOR
140 * buflen length of the data at buf allowing for padding
141 * fmt a null terminated string describing the format of
142 * the data structure for general-purpose byte swapping,
143 * use NULL for raw access.
144 * The letters "c", "s", "l", and "L"
145 * represent 1, 2, 4, and 8 byte quantities,
146 * respectively. A descriptor that consists of a
147 * short and two bytes would be described by "scc\0".
148 * descr_type type of the desired descriptor, USB_DESCR_TYPE_ANY
149 * to get any type.
150 * descr_index index of the desired descriptor
151 * ret_descr buffer the data is to be returned in
152 * ret_buf_len size of the buffer at ret_descr
153 *
154 * Specifying descr_index=0 returns the first descriptor of the specified
155 * type, specifying descr_index=1 returns the second, and so on.
156 *
157 * No error is returned if ret_buf_len is too small. This allows successful
158 * parsing of descriptors that have been extended in a later rev of the spec.
159 */
160 #define USB_DESCR_TYPE_ANY -1 /* Wild card */
161
162 size_t usb_parse_CV_cfg_descr(
163 uchar_t *buf, /* from GET_DESCRIPTOR(CONFIGURATION) */
164 size_t buflen,
165 char *fmt,
166 uint_t descr_type,
167 uint_t descr_index,
168 void *ret_descr,
169 size_t ret_buf_len);
170
171
172 size_t usb_parse_CV_if_descr(
173 uchar_t *buf, /* from GET_DESCRIPTOR(CONFIGURATION) */
174 size_t buflen,
175 char *fmt,
176 uint_t if_index,
177 uint_t alt_if_setting,
178 uint_t descr_type,
179 uint_t descr_index,
180 void *ret_descr,
181 size_t ret_buf_len);
182
183
184 size_t usb_parse_CV_ep_descr(
185 uchar_t *buf, /* from GET_DESCRIPTOR(CONFIGURATION) */
186 size_t buflen,
187 char *fmt,
188 uint_t if_index,
189 uint_t alt_if_setting,
190 uint_t ep_index,
191 uint_t descr_type,
192 uint_t descr_index,
193 void *ret_descr,
194 size_t ret_buf_len);
195
196
197 /*
198 * for unpacking any kind of LE data
199 */
200 size_t usb_parse_CV_descr(
201 char *format,
202 uchar_t *data,
203 size_t datalen,
204 void *structure,
205 size_t structlen);
206
207 /*
208 * Returns pointer to the raw config cloud. The client should
209 * not free this space.
210 */
211 uchar_t *usb_get_raw_cfg_data(
212 dev_info_t *dip,
213 size_t *length);
214
215 /*
216 * Return pointer to device descriptor
217 */
218 usb_dev_descr_t *usb_get_dev_descr(
219 dev_info_t *dip);
220
221
222 /*
223 * **************************************************************************
224 * List entry functions and definitions
225 * **************************************************************************
226 */
227
228 /*
229 * Data structure for maintaining lists
230 * This data structure private to USBA and not exposed to HCD or client
231 * driver or hub driver
232 */
233 typedef struct usba_list_entry {
234 struct usba_list_entry *next; /* ptr to next element */
235 struct usba_list_entry *prev; /* ptr to previous element */
236 kmutex_t list_mutex; /* mutex that protects queue */
237 usb_opaque_t private; /* ptr to private data */
238 int count; /* for head of the list */
239 /* counts of entries */
240 } usba_list_entry_t;
241
242 _NOTE(MUTEX_PROTECTS_DATA(usba_list_entry::list_mutex, usba_list_entry))
243
244
245 /* list entry functions. */
246 void usba_init_list(usba_list_entry_t *, usb_opaque_t,
247 ddi_iblock_cookie_t);
248 void usba_destroy_list(usba_list_entry_t *);
249 void usba_add_to_list(usba_list_entry_t *, usba_list_entry_t *);
250 int usba_rm_from_list(usba_list_entry_t *, usba_list_entry_t *);
251 void usba_move_list(usba_list_entry_t *, usba_list_entry_t *,
252 ddi_iblock_cookie_t);
253 int usba_check_in_list(usba_list_entry_t *, usba_list_entry_t *);
254 int usba_list_entry_leaks(usba_list_entry_t *, char *);
255 int usba_list_entry_count(usba_list_entry_t *);
256
257 usb_opaque_t usba_rm_first_pvt_from_list(usba_list_entry_t *);
258 usba_list_entry_t *usba_rm_first_from_list(usba_list_entry_t *);
259
260 /*
261 * **************************************************************************
262 * Kernel interface definitions and functionality
263 * **************************************************************************
264 */
265
266 /*
267 * USBA private event definitions
268 */
269 typedef enum usba_event {
270 USBA_EVENT_TAG_HOT_REMOVAL = 0,
271 USBA_EVENT_TAG_HOT_INSERTION = 1,
272 USBA_EVENT_TAG_PRE_SUSPEND = 2,
273 USBA_EVENT_TAG_POST_RESUME = 3,
274 USBA_EVENT_TAG_CPR = -1
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(uchar_t *, size_t, usba_cfg_pwr_descr_t *,
413 size_t);
414
415 size_t usba_parse_if_pwr_descr(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(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 */