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