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_USBAI_PRIVATE_H 27 #define _SYS_USB_USBA_USBAI_PRIVATE_H 28 29 30 /* 31 * Unstable interfaces not part of USBAI but used by Solaris client drivers. 32 * These interfaces may not be present in future releases and are highly 33 * unstable. 34 * 35 * Status key: 36 * C = Remove from Sun client drivers before removing from this file 37 * D = May be needed by legacy (DDK) drivers. 38 */ 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /* 45 * convenience function for getting default config index 46 * as saved in usba_device structure 47 * 48 * Status: C 49 */ 50 uint_t usb_get_current_cfgidx(dev_info_t *); 51 52 /* 53 * ************************************************************************** 54 * Error and status definitions, and reporting functions 55 * ************************************************************************** 56 */ 57 58 59 /* 60 * convenience functions to get string corresponding to value 61 * usb_cb_flags_name requires a workbuffer of sufficient length 62 * for the concatenation of all strings as usb_cb_flags_t is a bit 63 * mask 64 * 65 * Status: C and D 66 */ 67 const char *usb_str_cr(usb_cr_t cr); 68 char *usb_str_cb_flags(usb_cb_flags_t cb_flags, 69 char *buffer, size_t length); 70 const char *usb_str_pipe_state(usb_pipe_state_t state); 71 const char *usb_str_dev_state(int state); 72 const char *usb_str_rval(int rval); 73 74 /* function convert a USB return value to an errno */ 75 int usb_rval2errno(int rval); 76 77 /* 78 * ************************************************************************** 79 * Transfer-related definitions and functions 80 * ************************************************************************** 81 */ 82 83 /* Status C and D for whole section. */ 84 85 /* Serialize callbacks per interface or device. */ 86 #define USB_FLAGS_SERIALIZED_CB 0x8000 87 88 /* default timeout for control requests (in seconds) */ 89 #define USB_PIPE_TIMEOUT 3 90 91 /* 92 * usb_pipe_sync_ctrl_xfer(): 93 * for simple synchronous control transactions this wrapper function 94 * will perform the allocation, xfer, and deallocation. 95 * USB_ATTRS_AUTOCLEARING will be enabled 96 * 97 * ARGUMENTS: 98 * dip - pointer to clients devinfo. 99 * pipe_handle - control pipe pipehandle (obtained via usb_pipe_open(). 100 * bmRequestType - characteristics of request. 101 * bRequest - specific request. 102 * wValue - varies according to request. 103 * wIndex - index or offset. 104 * wLength - number of bytes to xfer. 105 * data - pointer to pointer to data 106 * IN: HCD will allocate data 107 * OUT: clients driver allocates data. 108 * attrs - required request attributes. 109 * completion_reason - completion status. 110 * cb_flags - request completions flags. 111 * flags - none. 112 * 113 * RETURN VALUES: 114 * USB_SUCCESS - request successfully executed. 115 * USB_FAILURE - request failed. 116 * 117 * NOTES: 118 * - in the case of failure, the client should check completion_reason and 119 * and cb_flags and determine further recovery action 120 * - the client should check data and if non-zero, free the data on 121 * completion 122 */ 123 int usb_pipe_sync_ctrl_xfer( 124 dev_info_t *dip, 125 usb_pipe_handle_t pipe_handle, 126 uchar_t bmRequestType, 127 uchar_t bRequest, 128 uint16_t wValue, 129 uint16_t wIndex, 130 uint16_t wLength, 131 mblk_t **data, 132 usb_req_attrs_t attrs, 133 usb_cr_t *completion_reason, 134 usb_cb_flags_t *cb_flags, 135 usb_flags_t flags); 136 137 /* 138 * ************************************************************************** 139 * Event registration / pre-suspend and post-resume handling 140 * ************************************************************************** 141 */ 142 143 /* Status: C and D for whole section. */ 144 145 /* 146 * Event registration info for both hotplug and pre-suspend/post-resume 147 * callbacks. Eventually pre-suspend and post-resume callbacks will not be 148 * needed, so this is for this OS release only and will go away in a 149 * subsequent release. 150 */ 151 typedef struct usb_event { 152 /* device disconnected/unplugged */ 153 int (*disconnect_event_handler)(dev_info_t *dip); 154 155 /* device reconnected */ 156 int (*reconnect_event_handler)(dev_info_t *dip); 157 158 /* notification that system is about to checkpoint */ 159 int (*pre_suspend_event_handler)(dev_info_t *dip); 160 161 /* notification that system resumed after a checkpoint */ 162 int (*post_resume_event_handler)(dev_info_t *dip); 163 } usb_event_t; 164 165 /* 166 * Event callbacks 167 * the callbacks should always return USB_SUCCESS. 168 */ 169 int usb_register_event_cbs( 170 dev_info_t *dip, 171 usb_event_t *usb_evt_data, 172 usb_flags_t flags); 173 174 void usb_unregister_event_cbs( 175 dev_info_t *dip, 176 usb_event_t *usb_evt_data); 177 178 /* 179 * USB CPR support 180 * A client driver must call this funtion in pre-suspend event handler 181 * to inform the USBA framework that it can't suspend because 182 * driver instance or device could not be quiesced. 183 */ 184 void usb_fail_checkpoint( 185 dev_info_t *dip, 186 usb_flags_t flags); 187 188 189 /* 190 * ************************************************************************** 191 * Logging functions remaining Contracted Consolidation Private 192 * ************************************************************************** 193 */ 194 195 /* Status: C and D for whole section. */ 196 197 /* 198 * Usb logging, debug and console message handling. 199 */ 200 typedef struct usb_log_handle *usb_log_handle_t; 201 202 #define USB_LOG_L0 0 /* warnings, console & syslog buffer */ 203 #define USB_LOG_L1 1 /* errors, syslog buffer */ 204 #define USB_LOG_L2 2 /* recoverable errors, debug only */ 205 #define USB_LOG_L3 3 /* interesting data, debug only */ 206 #define USB_LOG_L4 4 /* tracing, debug only */ 207 208 #ifdef DEBUG 209 #define USB_DPRINTF_L4(...) usb_dprintf4(__VA_ARGS__) 210 #define USB_DPRINTF_L3(...) usb_dprintf3(__VA_ARGS__) 211 212 /*PRINTFLIKE3*/ 213 void usb_dprintf4( 214 uint_t mask, 215 usb_log_handle_t handle, 216 char *fmt, ...); 217 /*PRINTFLIKE3*/ 218 void usb_dprintf3( 219 uint_t mask, 220 usb_log_handle_t handle, 221 char *fmt, ...); 222 #else 223 #define USB_DPRINTF_L4(...) ((void)0) 224 #define USB_DPRINTF_L3(...) ((void)0) 225 #endif 226 227 #define USB_DPRINTF_L2 usb_dprintf2 228 #define USB_DPRINTF_L1 usb_dprintf1 229 #define USB_DPRINTF_L0 usb_dprintf0 230 231 /*PRINTFLIKE3*/ 232 void usb_dprintf2( 233 uint_t mask, 234 usb_log_handle_t handle, 235 char *fmt, ...); 236 /*PRINTFLIKE3*/ 237 void usb_dprintf1( 238 uint_t mask, 239 usb_log_handle_t handle, 240 char *fmt, ...); 241 /*PRINTFLIKE3*/ 242 void usb_dprintf0( 243 uint_t mask, 244 usb_log_handle_t handle, 245 char *fmt, ...); 246 247 usb_log_handle_t usb_alloc_log_hdl( 248 dev_info_t *dip, 249 char *name, 250 uint_t *errlevel, 251 uint_t *mask, 252 uint_t *instance_filter, 253 usb_flags_t flags); 254 255 /* free the log handle */ 256 void usb_free_log_hdl( 257 usb_log_handle_t handle); 258 259 /* log message */ 260 /*PRINTFLIKE4*/ 261 int usb_log( 262 usb_log_handle_t handle, 263 uint_t level, 264 uint_t mask, 265 char *fmt, ...); 266 267 /* 268 * usb_check_same_device: 269 * Check if the device connected to the port is the same as 270 * the previous device that was in the port. The previous device is 271 * represented by the dip on record for the port. Print a message 272 * if the device is different. If device_string arg is not NULL, it is 273 * included in the message. Can block. 274 * 275 * Arguments: 276 * dip - pointer to devinfo of the client 277 * log_handle - handle to which messages are logged 278 * log_level - one of USB_LOG_* 279 * log_mask - logging mask 280 * check_mask - one mask containing things to check: 281 * USB_CHK_BASIC: empty mask; 282 * these checks are always done. 283 * USB_CHK_SERIAL: check match on device 284 * serial number. 285 * USB_CHK_CFG: compare config clouds 286 * byte by byte 287 * USB_CHK_VIDPID: compare product 288 * and vendor ID 289 * USB_CHK_ALL: perform all checks 290 * 291 * NOTE: descr length and content always checked 292 * device_string - Device string to appear in error message 293 * 294 * return values: 295 * USB_SUCCESS: same device 296 * USB_INVALID_VERSION not same device 297 * USB_FAILURE: Failure processing request 298 * USB_INVALID_ARG: dip is invalid 299 */ 300 301 /* Checking bits for checks made by usb_check_same_device */ 302 #define USB_CHK_BASIC 0 /* Empty mask. Basics always done. */ 303 #define USB_CHK_SERIAL 0x00000001 /* Compare device serial numbers. */ 304 #define USB_CHK_CFG 0x00000002 /* Compare raw config clouds. */ 305 #define USB_CHK_VIDPID 0x00000004 /* Compare product and vendor ID. */ 306 #define USB_CHK_ALL 0xFFFFFFFF /* Perform maximum checking. */ 307 308 int usb_check_same_device( 309 dev_info_t *dip, 310 usb_log_handle_t log_handle, 311 int log_level, 312 int log_mask, 313 uint_t check_mask, 314 char *device_string); 315 316 /* 317 * ************************************************************************** 318 * Power management functions remaining Contracted Consolidation Private 319 * ************************************************************************** 320 */ 321 322 /* 323 * usb wrapper around pm_raise_power & pm_lower_power to allow for 324 * non blocking behavior 325 * 326 * Arguments: 327 * dip - pointer to devinfo node of client. 328 * comp - component. 329 * level - power level. 330 * flags - USB_FLAGS_SLEEP: 331 * wait for completion. 332 * cb - function called on completion, may be NULL. 333 * arg - callback argument. 334 * rval - USB_SUCCESS or USB_FAILURE. 335 * 336 * Return Values: 337 * USB_SUCCESS - if no USB_FLAGS_SLEEP has been specified, the request 338 * has been queued for async execution. If 339 * USB_FLAGS_SLEEP has been specified, the raising or 340 * lowering of power 341 * succeeded. 342 * USB_FAILURE - request could not be queued or raising or lowering 343 * of power failed. 344 */ 345 346 /* Status: C and D */ 347 int usb_req_raise_power( 348 dev_info_t *dip, 349 int comp, 350 int level, 351 void (*cb)(void *arg, int rval), 352 void *arg, 353 usb_flags_t flags); 354 355 /* Status: D */ 356 int usb_req_lower_power( 357 dev_info_t *dip, 358 int comp, 359 int level, 360 void (*cb)(void *arg, int rval), 361 void *arg, 362 usb_flags_t flags); 363 364 /* 365 * USB wrapper functions to set usb device power level. 366 * Note : Power levels indicated here are USB power levels 367 * and not OS power levels. 368 * 369 * Note that these were never implemented, and are noops. However, they are 370 * included here as the skeleton driver in DDK 0.8 and 0.9 mentioned them. 371 * 372 * Status: C and D. 373 */ 374 int usb_set_device_pwrlvl0( 375 dev_info_t *dip); 376 int usb_set_device_pwrlvl1( 377 dev_info_t *dip); 378 int usb_set_device_pwrlvl2( 379 dev_info_t *dip); 380 int usb_set_device_pwrlvl3( 381 dev_info_t *dip); 382 383 384 /* 385 * ************************************************************************** 386 * Serialization functions remaining Contracted Consolidation Private 387 * ************************************************************************** 388 */ 389 390 /* This whole section: status: C and D. */ 391 392 /* 393 * opaque serialization handle. 394 * Used by all usb_serialization routines. 395 * 396 * This handle is opaque to the client driver. 397 */ 398 typedef struct usb_serialization *usb_serialization_t; 399 400 /* 401 * usb_init_serialization 402 * setup for serialization 403 * 404 * ARGUMENTS: 405 * s_dip - devinfo pointer 406 * flag - USB_INIT_SER_CHECK_SAME_THREAD 407 * when set, usb_release_access() will 408 * verify that the same thread releases 409 * access. If not, a console warning will 410 * be issued but access will be released 411 * anyways. 412 * 413 * RETURNS: 414 * usb_serialization handle 415 * 416 */ 417 usb_serialization_t usb_init_serialization( 418 dev_info_t *s_dip, 419 uint_t flag); 420 421 #define USB_INIT_SER_CHECK_SAME_THREAD 1 422 423 /* fini for serialization */ 424 void usb_fini_serialization( 425 usb_serialization_t usb_serp); 426 427 /* 428 * Various ways of calling usb_serialize_access. These correspond to 429 * their cv_*wait* function counterparts for usb_serialize_access. 430 */ 431 #define USB_WAIT 0 432 #define USB_WAIT_SIG 1 433 #define USB_TIMEDWAIT 2 434 #define USB_TIMEDWAIT_SIG 3 435 436 /* 437 * usb_serialize_access: 438 * acquire serialized access 439 * ARGUMENTS: 440 * usb_serp - usb_serialization handle 441 * how_to_wait - Which cv_*wait* function to wait for condition. 442 * USB_WAIT: use cv_wait 443 * USB_WAIT_SIG: use cv_wait_sig 444 * USB_TIMEDWAIT: use cv_timedwait 445 * USB_TIMEDWAIT_SIG: use cv_timedwait_sig 446 * delta_timeout - Time in ms from current time to timeout. Checked 447 * only if USB_TIMEDWAIT or USB_TIMEDWAIT_SIG 448 * specified in how_to_wait. 449 * RETURNS: 450 * Same as values returned by cv_*wait* functions, 451 * except for when how_to_wait == USB_WAIT, where 0 is always returned. 452 * For calls where a timeout or signal could be expected, use this value 453 * to tell whether a kill(2) signal or timeout occurred. 454 */ 455 int usb_serialize_access( 456 usb_serialization_t usb_serp, 457 uint_t how_to_wait, 458 uint_t delta_timeout); 459 460 /* 461 * usb_try_serialize_access: 462 * try acquiring serialized access 463 * 464 * ARGUMENTS: 465 * usb_serp - usb_serialization handle 466 * flag - unused 467 * 468 * RETURNS: 469 * USB_SUCCESS - access has been acquired 470 * USB_FAILURE - access has not been acquired 471 */ 472 int usb_try_serialize_access(usb_serialization_t usb_serp, uint_t flag); 473 474 /* 475 * usb_release_access: 476 * release serialized access 477 * 478 * ARGUMENTS: 479 * usb_serp - usb_serialization handle 480 */ 481 void usb_release_access(usb_serialization_t usb_serp); 482 483 484 /* 485 * ************************************************************************** 486 * Asynchronous functions remaining Contracted Consolidation Private 487 * ************************************************************************** 488 */ 489 490 /* This whole section: status: C and D. */ 491 492 /* For async_req functions. */ 493 #define USB_FLAGS_NOQUEUE 0x200 494 495 /* 496 * Issue a request to the asynchronous request service 497 * All async request functions return USB_SUCCESS or USB_FAILURE 498 * Arguments: 499 * dip - pointer to devinfo node 500 * func - pointer of function to execute asynchronously 501 * arg - argument to function 502 * flag - USB_FLAGS_SLEEP or USB_FLAGS_NOSLEEP or 503 * USB_FLAGS_NOQUEUE 504 * Return Values: 505 * USB_SUCCESS - function was scheduled 506 * USB_FAILURE - function could not be scheduled 507 * 508 * Flag combinations: 509 * SLEEP - block waiting for resources. always succeeds 510 * NOSLEEP - do not wait for resources, may fail. 511 * NOSLEEP+NOQUEUE - do not wait for resources, do not queue 512 * SLEEP+NOQUEUE - block waiting for resources but may still fail 513 * if no thread available 514 */ 515 int usb_async_req( 516 dev_info_t *dip, 517 void (*func)(void *), 518 void *arg, 519 usb_flags_t flag); 520 521 522 /* 523 * index for getting to usb_pipehandle_list in usba_device 524 */ 525 uchar_t usb_get_ep_index(uint8_t ep_addr); 526 527 528 #ifdef ALLOCB_TEST 529 #define allocb(s, p) usba_test_allocb(s, p) 530 mblk_t *usba_test_allocb(size_t, uint_t); 531 #endif /* ALLOCB_TEST */ 532 533 /* create an USB style M_CTL message */ 534 mblk_t *usba_mk_mctl(struct iocblk, void *, size_t); 535 536 #ifdef __cplusplus 537 } 538 #endif 539 540 #endif /* _SYS_USB_USBA_USBAI_PRIVATE_H */ 541