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