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 */ 474