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