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 2008 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 * Returns pointer to the raw config cloud. The client should 207 * not free this space. 208 */ 209 uchar_t *usb_get_raw_cfg_data( 210 dev_info_t *dip, 211 size_t *length); 212 213 /* 214 * Return pointer to device descriptor 215 */ 216 usb_dev_descr_t *usb_get_dev_descr( 217 dev_info_t *dip); 218 219 220 /* 221 * ************************************************************************** 222 * List entry functions and definitions 223 * ************************************************************************** 224 */ 225 226 /* 227 * Data structure for maintaining lists 228 * This data structure private to USBA and not exposed to HCD or client 229 * driver or hub driver 230 */ 231 typedef struct usba_list_entry { 232 struct usba_list_entry *next; /* ptr to next element */ 233 struct usba_list_entry *prev; /* ptr to previous element */ 234 kmutex_t list_mutex; /* mutex that protects queue */ 235 usb_opaque_t private; /* ptr to private data */ 236 int count; /* for head of the list */ 237 /* counts of entries */ 238 } usba_list_entry_t; 239 240 _NOTE(MUTEX_PROTECTS_DATA(usba_list_entry::list_mutex, usba_list_entry)) 241 242 243 /* list entry functions. */ 244 void usba_init_list(usba_list_entry_t *, usb_opaque_t, 245 ddi_iblock_cookie_t); 246 void usba_destroy_list(usba_list_entry_t *); 247 void usba_add_to_list(usba_list_entry_t *, usba_list_entry_t *); 248 int usba_rm_from_list(usba_list_entry_t *, usba_list_entry_t *); 249 void usba_move_list(usba_list_entry_t *, usba_list_entry_t *, 250 ddi_iblock_cookie_t); 251 int usba_check_in_list(usba_list_entry_t *, usba_list_entry_t *); 252 int usba_list_entry_leaks(usba_list_entry_t *, char *); 253 int usba_list_entry_count(usba_list_entry_t *); 254 255 usb_opaque_t usba_rm_first_pvt_from_list(usba_list_entry_t *); 256 usba_list_entry_t *usba_rm_first_from_list(usba_list_entry_t *); 257 258 /* 259 * ************************************************************************** 260 * Kernel interface definitions and functionality 261 * ************************************************************************** 262 */ 263 264 /* 265 * USBA private event definitions 266 */ 267 typedef enum usba_event { 268 USBA_EVENT_TAG_HOT_REMOVAL = 0, 269 USBA_EVENT_TAG_HOT_INSERTION = 1, 270 USBA_EVENT_TAG_PRE_SUSPEND = 2, 271 USBA_EVENT_TAG_POST_RESUME = 3, 272 USBA_EVENT_TAG_CPR = -1 273 } usba_event_t; 274 275 #define USBA_PRE_SUSPEND_EVENT "SUNW,USBA:USBA_PRE_SUSPEND" 276 #define USBA_POST_RESUME_EVENT "SUNW,USBA:USBA_POST_RESUME" 277 278 /* 279 * Get dma attributes from HC. 280 */ 281 ddi_dma_attr_t *usba_get_hc_dma_attr(dev_info_t *dip); 282 283 /* 284 * This function calls ndi_devi_bind_driver() to bind the 285 * driver to the device. If the call fails it reports an 286 * error on the console. Attaching of the driver is done 287 * later by devfs framework. 288 */ 289 int usba_bind_driver(dev_info_t *); 290 291 /* check whether the dip owns an interface-associaiton */ 292 boolean_t usba_owns_ia(dev_info_t *dip); 293 294 /* 295 * Driver binding functions 296 */ 297 dev_info_t *usba_ready_device_node(dev_info_t *); 298 dev_info_t *usba_ready_interface_association_node(dev_info_t *, 299 uint_t, uint_t *); 300 dev_info_t *usba_ready_interface_node(dev_info_t *, uint_t); 301 302 /* Some Nexus driver functions. */ 303 304 /* 305 * Common bus ctl for hcd, usb_mid and hubd. 306 */ 307 int usba_bus_ctl(dev_info_t *, dev_info_t *, ddi_ctl_enum_t, 308 void *, void *); 309 310 void usb_enable_parent_notification(dev_info_t *); 311 312 /* 313 * Some functions for setting/getting usba_device from dip. 314 */ 315 struct usba_device *usba_get_usba_device(dev_info_t *); 316 struct usba_device *usba_polled_get_usba_device(dev_info_t *); 317 void usba_set_usba_device(dev_info_t *, struct usba_device *); 318 319 /* extract NDI event registration info */ 320 struct usba_evdata *usba_get_evdata(dev_info_t *); 321 322 /* 323 * ************************************************************************** 324 * Misc private USBA functions 325 * ************************************************************************** 326 */ 327 328 /* 329 * Get policy of a pipe while holding only opaque pipe handle. 330 */ 331 usb_pipe_policy_t *usba_pipe_get_policy(usb_pipe_handle_t); 332 333 /* 334 * Check interrupt context and or in USB_CB_INTR_CONTEXT to cb_flags as needed. 335 */ 336 usb_cb_flags_t usba_check_intr_context(usb_cb_flags_t); 337 338 /* returns interface number, zero if driver owns the device */ 339 uint8_t usba_get_ifno(dev_info_t *); 340 341 /* 342 * ************************************************************************** 343 * Misc private descriptor definitions and functionality 344 * ************************************************************************** 345 */ 346 347 /* default endpoint descriptor */ 348 extern usb_ep_descr_t usba_default_ep_descr; 349 350 /* 351 * The compiler pads the above structures; the following represent the 352 * unpadded, aggregate data sizes. 353 */ 354 #define USB_DEV_DESCR_SIZE 18 /* device descr size */ 355 #define USB_CFG_DESCR_SIZE 9 /* configuration desc. size */ 356 #define USBA_CFG_PWR_DESCR_SIZE 18 /* configuration pwr desc. size */ 357 #define USB_IF_DESCR_SIZE 9 /* interface descr size */ 358 #define USBA_IF_PWR_DESCR_SIZE 15 /* interface pwr descr size */ 359 #define USB_EP_DESCR_SIZE 7 /* endpoint descr size */ 360 #define USB_IA_DESCR_SIZE 8 /* interface association descr size */ 361 362 /* 363 * For compatibility with old code. 364 */ 365 #define USBA_DESCR_TYPE_CFG_PWR_1_1 0xfe 366 #define USBA_DESCR_TYPE_IF_PWR_1_1 0xff 367 368 /* 369 * Configuration Power Descriptor 370 * This reports the power consuption of the device core 371 * for all types of USB devices. 372 */ 373 typedef struct usba_cfg_pwr_descr { 374 uint8_t bLength; /* size of this descriptor 0x12 */ 375 uint8_t bDescriptorType; /* config pwr descr 0x07 */ 376 uint16_t SelfPowerConsumedD0_l; /* power consumed lower word */ 377 uint8_t SelfPowerConsumedD0_h; /* power consumed upper byte */ 378 uint8_t bPowerSummaryId; /* ID for own power devices */ 379 uint8_t bBusPowerSavingD1; /* power saving in D1 */ 380 uint8_t bSelfPowerSavingD1; /* power saving in D1 */ 381 uint8_t bBusPowerSavingD2; /* power saving in D2 */ 382 uint8_t bSelfPowerSavingD2; /* power saving in D2 */ 383 uint8_t bBusPowerSavingD3; /* power saving in D3 */ 384 uint8_t bSelfPowerSavingD3; /* power saving in D3 */ 385 uint16_t TransitionTimeFromD1; /* D1 -> D0 transition time */ 386 uint16_t TransitionTimeFromD2; /* D2 -> D0 transition time */ 387 uint16_t TransitionTimeFromD3; /* D3 -> D0 transition time */ 388 } usba_cfg_pwr_descr_t; 389 390 /* 391 * Interface Power Descriptor 392 * This reports the power states implemented by the interface 393 * and its wake-up capabilities. 394 */ 395 typedef struct usba_if_pwr_descr { 396 uint8_t bLength; /* size of this descriptor 0x0F */ 397 uint8_t bDescriptorType; /* i/f pwr descr 0x08 */ 398 uint8_t bmCapabilitiesFlags; /* wakeup & pwr transition */ 399 uint8_t bBusPowerSavingD1; /* power saving in D1 */ 400 uint8_t bSelfPowerSavingD1; /* power saving in D1 */ 401 uint8_t bBusPowerSavingD2; /* power saving in D2 */ 402 uint8_t bSelfPowerSavingD2; /* power saving in D2 */ 403 uint8_t bBusPowerSavingD3; /* power saving in D3 */ 404 uint8_t bSelfPowerSavingD3; /* power saving in D3 */ 405 uint16_t TransitionTimeFromD1; /* D1 -> D0 transition time */ 406 uint16_t TransitionTimeFromD2; /* D2 -> D0 transition time */ 407 uint16_t TransitionTimeFromD3; /* D3 -> D0 transition time */ 408 } usba_if_pwr_descr_t; 409 410 size_t usba_parse_cfg_pwr_descr(uchar_t *, size_t, usba_cfg_pwr_descr_t *, 411 size_t); 412 413 size_t usba_parse_if_pwr_descr(uchar_t *, size_t buflen, uint_t, 414 uint_t, usba_if_pwr_descr_t *, size_t); 415 416 /* 417 * Returns (at ret_descr) a null-terminated string. Null termination is 418 * guaranteed, even if the string is longer than the buffer. Thus, a 419 * maximum of (ret_buf_len - 1) characters are returned. 420 * 421 * XXX is this needed when there is usb_get_string_descriptor 422 * If so, then more comments about how it differs? 423 */ 424 size_t usba_ascii_string_descr(uchar_t *, size_t, char *, size_t); 425 426 427 /* 428 * usb common power management, for usb_mid, usb_ia and maybe other simple 429 * drivers. 430 */ 431 typedef struct usb_common_power_struct { 432 void *uc_usb_statep; /* points back to state structure */ 433 434 uint8_t uc_wakeup_enabled; 435 436 /* this is the bit mask of the power states that device has */ 437 uint8_t uc_pwr_states; 438 439 /* wakeup and power transition capabilites of an interface */ 440 uint8_t uc_pm_capabilities; 441 442 uint8_t uc_current_power; /* current power level */ 443 } usb_common_power_t; 444 445 /* warlock directives, stable data */ 446 447 _NOTE(DATA_READABLE_WITHOUT_LOCK(usb_common_power_t::uc_usb_statep)) 448 _NOTE(DATA_READABLE_WITHOUT_LOCK(usb_common_power_t::uc_wakeup_enabled)) 449 _NOTE(DATA_READABLE_WITHOUT_LOCK(usb_common_power_t::uc_pwr_states)) 450 _NOTE(DATA_READABLE_WITHOUT_LOCK(usb_common_power_t::uc_pm_capabilities)) 451 _NOTE(DATA_READABLE_WITHOUT_LOCK(usb_common_power_t::uc_current_power)) 452 453 /* power management */ 454 int usba_common_power(dev_info_t *, uint8_t *, int *, int); 455 456 /* 457 * usb common events handler for usb_mid, usb_ia and maybe other nexus 458 * drivers. 459 */ 460 461 void usba_common_register_events(dev_info_t *, uint_t, 462 void (*)(dev_info_t *, ddi_eventcookie_t, void *, void *)); 463 464 void usba_common_unregister_events(dev_info_t *, uint_t); 465 466 467 #ifdef __cplusplus 468 } 469 #endif 470 471 #endif /* _SYS_USB_USBA_USBA_PRIVATE_H */ 472