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