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, Version 1.0 only 6 * (the "License"). You may not use this file except in compliance 7 * with the License. 8 * 9 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10 * or http://www.opensolaris.org/os/licensing. 11 * See the License for the specific language governing permissions 12 * and limitations under the License. 13 * 14 * When distributing Covered Code, include this CDDL HEADER in each 15 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16 * If applicable, add the following below this CDDL HEADER, with the 17 * fields enclosed by brackets "[]" replaced with your own identifying 18 * information: Portions Copyright [yyyy] [name of copyright owner] 19 * 20 * CDDL HEADER END 21 */ 22 /* 23 * Copyright 2004 Sun Microsystems, Inc. All rights reserved. 24 * Use is subject to license terms. 25 */ 26 27 #ifndef _SYS_USB_USBA_USBA_PRIVATE_H 28 #define _SYS_USB_USBA_USBA_PRIVATE_H 29 30 #pragma ident "%Z%%M% %I% %E% SMI" 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 * 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_if_descr( 104 uchar_t *buf, /* from GET_DESCRIPTOR(CONFIGURATION) */ 105 size_t buflen, 106 uint_t if_index, 107 uint_t alt_if_setting, 108 usb_if_descr_t *ret_descr, 109 size_t ret_buf_len); 110 111 112 /* 113 * the endpoint index is relative to the interface. index 0 is 114 * the first endpoint 115 */ 116 size_t usb_parse_ep_descr( 117 uchar_t *buf, /* from GET_DESCRIPTOR(CONFIGURATION) */ 118 size_t buflen, 119 uint_t if_index, 120 uint_t alt_if_setting, 121 uint_t ep_index, 122 usb_ep_descr_t *ret_descr, 123 size_t ret_buf_len); 124 125 /* 126 * functions to handle arbitrary descriptors. USBA doesn't know the format 127 * and therefore cannot do any automatic pre-processing. 128 * 129 * In the following: 130 * buf buffer containing data returned by GET_DESCRIPTOR 131 * buflen length of the data at buf allowing for padding 132 * fmt a null terminated string describing the format of 133 * the data structure for general-purpose byte swapping, 134 * use NULL for raw access. 135 * The letters "c", "s", "l", and "L" 136 * represent 1, 2, 4, and 8 byte quantities, 137 * respectively. A descriptor that consists of a 138 * short and two bytes would be described by "scc\0". 139 * descr_type type of the desired descriptor, USB_DESCR_TYPE_ANY 140 * to get any type. 141 * descr_index index of the desired descriptor 142 * ret_descr buffer the data is to be returned in 143 * ret_buf_len size of the buffer at ret_descr 144 * 145 * Specifying descr_index=0 returns the first descriptor of the specified 146 * type, specifying descr_index=1 returns the second, and so on. 147 * 148 * No error is returned if ret_buf_len is too small. This allows successful 149 * parsing of descriptors that have been extended in a later rev of the spec. 150 */ 151 #define USB_DESCR_TYPE_ANY -1 /* Wild card */ 152 153 size_t usb_parse_CV_cfg_descr( 154 uchar_t *buf, /* from GET_DESCRIPTOR(CONFIGURATION) */ 155 size_t buflen, 156 char *fmt, 157 uint_t descr_type, 158 uint_t descr_index, 159 void *ret_descr, 160 size_t ret_buf_len); 161 162 163 size_t usb_parse_CV_if_descr( 164 uchar_t *buf, /* from GET_DESCRIPTOR(CONFIGURATION) */ 165 size_t buflen, 166 char *fmt, 167 uint_t if_index, 168 uint_t alt_if_setting, 169 uint_t descr_type, 170 uint_t descr_index, 171 void *ret_descr, 172 size_t ret_buf_len); 173 174 175 size_t usb_parse_CV_ep_descr( 176 uchar_t *buf, /* from GET_DESCRIPTOR(CONFIGURATION) */ 177 size_t buflen, 178 char *fmt, 179 uint_t if_index, 180 uint_t alt_if_setting, 181 uint_t ep_index, 182 uint_t descr_type, 183 uint_t descr_index, 184 void *ret_descr, 185 size_t ret_buf_len); 186 187 188 /* 189 * for unpacking any kind of LE data 190 */ 191 size_t usb_parse_CV_descr( 192 char *format, 193 uchar_t *data, 194 size_t datalen, 195 void *structure, 196 size_t structlen); 197 198 /* 199 * Returns pointer to the raw config cloud. The client should 200 * not free this space. 201 */ 202 uchar_t *usb_get_raw_cfg_data( 203 dev_info_t *dip, 204 size_t *length); 205 206 /* 207 * Return pointer to device descriptor 208 */ 209 usb_dev_descr_t *usb_get_dev_descr( 210 dev_info_t *dip); 211 212 213 /* 214 * ************************************************************************** 215 * List entry functions and definitions 216 * ************************************************************************** 217 */ 218 219 /* 220 * Data structure for maintaining lists 221 * This data structure private to USBA and not exposed to HCD or client 222 * driver or hub driver 223 */ 224 typedef struct usba_list_entry { 225 struct usba_list_entry *next; /* ptr to next element */ 226 struct usba_list_entry *prev; /* ptr to previous element */ 227 kmutex_t list_mutex; /* mutex that protects queue */ 228 usb_opaque_t private; /* ptr to private data */ 229 int count; /* for head of the list */ 230 /* counts of entries */ 231 } usba_list_entry_t; 232 233 _NOTE(MUTEX_PROTECTS_DATA(usba_list_entry::list_mutex, usba_list_entry)) 234 235 236 /* list entry functions. */ 237 void usba_init_list(usba_list_entry_t *, usb_opaque_t, 238 ddi_iblock_cookie_t); 239 void usba_destroy_list(usba_list_entry_t *); 240 void usba_add_to_list(usba_list_entry_t *, usba_list_entry_t *); 241 int usba_rm_from_list(usba_list_entry_t *, usba_list_entry_t *); 242 void usba_move_list(usba_list_entry_t *, usba_list_entry_t *, 243 ddi_iblock_cookie_t); 244 int usba_check_in_list(usba_list_entry_t *, usba_list_entry_t *); 245 int usba_list_entry_leaks(usba_list_entry_t *, char *); 246 int usba_list_entry_count(usba_list_entry_t *); 247 248 usb_opaque_t usba_rm_first_pvt_from_list(usba_list_entry_t *); 249 usba_list_entry_t *usba_rm_first_from_list(usba_list_entry_t *); 250 251 /* 252 * ************************************************************************** 253 * Kernel interface definitions and functionality 254 * ************************************************************************** 255 */ 256 257 /* 258 * USBA private event definitions 259 */ 260 typedef enum usba_event { 261 USBA_EVENT_TAG_HOT_REMOVAL = 0, 262 USBA_EVENT_TAG_HOT_INSERTION = 1, 263 USBA_EVENT_TAG_PRE_SUSPEND = 2, 264 USBA_EVENT_TAG_POST_RESUME = 3, 265 USBA_EVENT_TAG_CPR = -1 266 } usba_event_t; 267 268 #define USBA_PRE_SUSPEND_EVENT "SUNW,USBA:USBA_PRE_SUSPEND" 269 #define USBA_POST_RESUME_EVENT "SUNW,USBA:USBA_POST_RESUME" 270 271 /* 272 * Get dma attributes from HC. 273 */ 274 ddi_dma_attr_t *usba_get_hc_dma_attr(dev_info_t *dip); 275 276 /* 277 * This function calls ndi_devi_bind_driver() to bind the 278 * driver to the device. If the call fails it reports an 279 * error on the console. Attaching of the driver is done 280 * later by devfs framework. 281 */ 282 int usba_bind_driver(dev_info_t *); 283 284 /* 285 * Driver binding functions 286 */ 287 dev_info_t *usba_ready_device_node(dev_info_t *); 288 dev_info_t *usba_ready_interface_node(dev_info_t *, uint_t); 289 290 /* Some Nexus driver functions. */ 291 292 /* 293 * Common bus ctl for hcd, usb_mid and hubd. 294 */ 295 int usba_bus_ctl(dev_info_t *, dev_info_t *, ddi_ctl_enum_t, 296 void *, void *); 297 298 void usb_enable_parent_notification(dev_info_t *); 299 300 /* 301 * Some functions for setting/getting usba_device from dip. 302 */ 303 struct usba_device *usba_get_usba_device(dev_info_t *); 304 struct usba_device *usba_polled_get_usba_device(dev_info_t *); 305 void usba_set_usba_device(dev_info_t *, struct usba_device *); 306 307 /* extract NDI event registration info */ 308 struct usba_evdata *usba_get_evdata(dev_info_t *); 309 310 /* 311 * ************************************************************************** 312 * Misc private USBA functions 313 * ************************************************************************** 314 */ 315 316 /* 317 * Get policy of a pipe while holding only opaque pipe handle. 318 */ 319 usb_pipe_policy_t *usba_pipe_get_policy(usb_pipe_handle_t); 320 321 /* 322 * Check interrupt context and or in USB_CB_INTR_CONTEXT to cb_flags as needed. 323 */ 324 usb_cb_flags_t usba_check_intr_context(usb_cb_flags_t); 325 326 /* returns interface number, zero if driver owns the device */ 327 uint8_t usba_get_ifno(dev_info_t *); 328 329 /* 330 * ************************************************************************** 331 * Misc private descriptor definitions and functionality 332 * ************************************************************************** 333 */ 334 335 /* default endpoint descriptor */ 336 extern usb_ep_descr_t usba_default_ep_descr; 337 338 /* 339 * The compiler pads the above structures; the following represent the 340 * unpadded, aggregate data sizes. 341 */ 342 #define USB_DEV_DESCR_SIZE 18 /* device descr size */ 343 #define USB_CFG_DESCR_SIZE 9 /* configuration desc. size */ 344 #define USBA_CFG_PWR_DESCR_SIZE 18 /* configuration pwr desc. size */ 345 #define USB_IF_DESCR_SIZE 9 /* interface descr size */ 346 #define USBA_IF_PWR_DESCR_SIZE 15 /* interface pwr descr size */ 347 #define USB_EP_DESCR_SIZE 7 /* endpoint descr size */ 348 349 /* 350 * For compatibility with old code. 351 */ 352 #define USBA_DESCR_TYPE_CFG_PWR_1_1 0xfe 353 #define USBA_DESCR_TYPE_IF_PWR_1_1 0xff 354 355 /* 356 * Configuration Power Descriptor 357 * This reports the power consuption of the device core 358 * for all types of USB devices. 359 */ 360 typedef struct usba_cfg_pwr_descr { 361 uint8_t bLength; /* size of this descriptor 0x12 */ 362 uint8_t bDescriptorType; /* config pwr descr 0x07 */ 363 uint16_t SelfPowerConsumedD0_l; /* power consumed lower word */ 364 uint8_t SelfPowerConsumedD0_h; /* power consumed upper byte */ 365 uint8_t bPowerSummaryId; /* ID for own power devices */ 366 uint8_t bBusPowerSavingD1; /* power saving in D1 */ 367 uint8_t bSelfPowerSavingD1; /* power saving in D1 */ 368 uint8_t bBusPowerSavingD2; /* power saving in D2 */ 369 uint8_t bSelfPowerSavingD2; /* power saving in D2 */ 370 uint8_t bBusPowerSavingD3; /* power saving in D3 */ 371 uint8_t bSelfPowerSavingD3; /* power saving in D3 */ 372 uint16_t TransitionTimeFromD1; /* D1 -> D0 transition time */ 373 uint16_t TransitionTimeFromD2; /* D2 -> D0 transition time */ 374 uint16_t TransitionTimeFromD3; /* D3 -> D0 transition time */ 375 } usba_cfg_pwr_descr_t; 376 377 /* 378 * Interface Power Descriptor 379 * This reports the power states implemented by the interface 380 * and its wake-up capabilities. 381 */ 382 typedef struct usba_if_pwr_descr { 383 uint8_t bLength; /* size of this descriptor 0x0F */ 384 uint8_t bDescriptorType; /* i/f pwr descr 0x08 */ 385 uint8_t bmCapabilitiesFlags; /* wakeup & pwr transition */ 386 uint8_t bBusPowerSavingD1; /* power saving in D1 */ 387 uint8_t bSelfPowerSavingD1; /* power saving in D1 */ 388 uint8_t bBusPowerSavingD2; /* power saving in D2 */ 389 uint8_t bSelfPowerSavingD2; /* power saving in D2 */ 390 uint8_t bBusPowerSavingD3; /* power saving in D3 */ 391 uint8_t bSelfPowerSavingD3; /* power saving in D3 */ 392 uint16_t TransitionTimeFromD1; /* D1 -> D0 transition time */ 393 uint16_t TransitionTimeFromD2; /* D2 -> D0 transition time */ 394 uint16_t TransitionTimeFromD3; /* D3 -> D0 transition time */ 395 } usba_if_pwr_descr_t; 396 397 size_t usba_parse_cfg_pwr_descr(uchar_t *, size_t, usba_cfg_pwr_descr_t *, 398 size_t); 399 400 size_t usba_parse_if_pwr_descr(uchar_t *, size_t buflen, uint_t, 401 uint_t, usba_if_pwr_descr_t *, size_t); 402 403 /* 404 * Returns (at ret_descr) a null-terminated string. Null termination is 405 * guaranteed, even if the string is longer than the buffer. Thus, a 406 * maximum of (ret_buf_len - 1) characters are returned. 407 * 408 * XXX is this needed when there is usb_get_string_descriptor 409 * If so, then more comments about how it differs? 410 */ 411 size_t usba_ascii_string_descr(uchar_t *, size_t, char *, size_t); 412 413 #ifdef __cplusplus 414 } 415 #endif 416 417 #endif /* _SYS_USB_USBA_USBA_PRIVATE_H */ 418