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  */
  27 
  28 #ifndef _SYS_USB_USBA_USBA_IMPL_H
  29 #define _SYS_USB_USBA_USBA_IMPL_H
  30 
  31 
  32 #include <sys/usb/usba.h>
  33 #include <sys/usb/usba/hcdi.h>
  34 #include <sys/usb/usba/hubdi.h>
  35 #include <sys/usb/usba/usba_private.h>
  36 #include <sys/usb/usba/usba_types.h>
  37 #include <sys/taskq.h>
  38 #include <sys/disp.h>
  39 
  40 #ifdef  __cplusplus
  41 extern "C" {
  42 #endif
  43 
  44 
  45 /*
  46  * UGEN binding values specified in <hcd>.conf files
  47  */
  48 #define USBA_UGEN_DEVICE_BINDING        1
  49 #define USBA_UGEN_INTERFACE_BINDING     2
  50 #define USBA_UGEN_INTERFACE_ASSOCIATION_BINDING         3
  51 
  52 /*
  53  * Allocating a USB address
  54  */
  55 #define USBA_MAX_ADDRESS                127
  56 #define USBA_ADDRESS_ARRAY_SIZE ((USBA_MAX_ADDRESS+8)/8)
  57 
  58 /*
  59  * async execution of usb_pipe_* functions which have a
  60  * completion callback parameter (eg. usb_pipe_close(),
  61  * usb_pipe_reset(), usb_pipe_stop_*_polling()
  62  */
  63 typedef struct usba_pipe_async_req {
  64         dev_info_t              *dip;
  65         struct usba_ph_impl     *ph_impl;
  66         usb_opaque_t            arg;
  67         usb_flags_t             usb_flags;
  68         void                    (*callback)(
  69                                         usb_pipe_handle_t       ph,
  70                                         usb_opaque_t            callback_arg,
  71                                         int                     rval,
  72                                         usb_cb_flags_t          error_code);
  73         usb_opaque_t            callback_arg;
  74         int                     (*sync_func)(dev_info_t *,
  75                                         usba_ph_impl_t *,
  76                                         struct usba_pipe_async_req *,
  77                                         usb_flags_t);
  78 } usba_pipe_async_req_t;
  79 _NOTE(SCHEME_PROTECTS_DATA("unique per call", usba_pipe_async_req_t))
  80 
  81 /* per-pipe taskq */
  82 int     usba_async_ph_req(usba_pipe_handle_data_t *, void (*func)(void *),
  83                                                         void *, usb_flags_t);
  84 
  85 /*
  86  * usb wrapper around pm_request_power_change to allow for
  87  * non blocking behavior
  88  */
  89 typedef struct usba_pm_req {
  90         dev_info_t      *dip;
  91         int             comp;
  92         int             old_level;
  93         int             level;
  94         void            (*cb)(void *, int);
  95         void            *arg;
  96         uint_t          flags;
  97 } usba_pm_req_t;
  98 _NOTE(SCHEME_PROTECTS_DATA("unique per call", usba_pm_req_t))
  99 
 100 
 101 /*
 102  * Request wrappers for control/bulk/interrupt and isoch pipes
 103  * These are hidden from client driver. They serve as place-holders
 104  * for doing callbacks
 105  *
 106  * Request allocation: wrapper + usb_*_req_t alloc'ed together:
 107  *
 108  *              +-----------------------+
 109  *              |       wr_queue        |               for callbacks
 110  *              +-----------------------+
 111  *              |       wr_req  |-------+       wr_req points to
 112  *              +-----------------------+       |       the req below.
 113  *              |                       |       |
 114  *              |       ....            |       |
 115  *              |       req_wrapper_t   |       |
 116  *              |                       |       |
 117  *              +-----------------------+<------+
 118  *              |                       |
 119  *              |       ....            |
 120  *              | ctrl/bulk/intr/isoch  |
 121  *              |       req_t   |
 122  *              |                       |
 123  *              |                       |
 124  *              +-----------------------+
 125  */
 126 typedef struct usba_req_wrapper {
 127         /* queueing in either a request or callback queue */
 128         usba_list_entry_t       wr_queue;
 129 
 130         /*
 131          * The request could be control/bulk/intr/isoc
 132          * See usbai.h usb_ctrl_req_t/usb_bulk_req_t
 133          * usb_intr_req_t/usb_isoc_req_t
 134          */
 135         usb_opaque_t            wr_req;
 136 
 137         /* for allocation tracking in usba_device_t */
 138         usba_list_entry_t       wr_allocated_list;
 139 
 140         /*
 141          * All reqs that are synchronous sleep on this cv
 142          * for completion notification.
 143          * In hcdi soft interrupt handler we call cv_signal()
 144          */
 145         kcondvar_t              wr_cv;
 146 
 147         /*
 148          * This goes hand-in-hand with wr_cv. It is set by the soft intr hdlr
 149          * before doing a cv_signal
 150          */
 151         boolean_t               wr_done;
 152         dev_info_t              *wr_dip;        /* owner */
 153 
 154         usb_opaque_t            wr_hcd_private; /* for HCD's use */
 155 
 156         usba_pipe_handle_data_t *wr_ph_data;    /* ptr to pipe handle */
 157 
 158         usb_cr_t                wr_cr;          /* save cr from HCDI */
 159         usb_cb_flags_t          wr_cb_flags;    /* save cb_flags */
 160         usb_flags_t             wr_usb_flags;   /* save usb flags from HCDI */
 161         usb_req_attrs_t         wr_attrs;       /* save attrs from HCDI */
 162 
 163         /* total lenght of wrapper and request */
 164         size_t                  wr_length;
 165 } usba_req_wrapper_t;
 166 
 167 _NOTE(SCHEME_PROTECTS_DATA("method", usba_req_wrapper))
 168 _NOTE(SCHEME_PROTECTS_DATA("method", usb_ctrl_req))
 169 _NOTE(SCHEME_PROTECTS_DATA("method", usb_bulk_req))
 170 _NOTE(SCHEME_PROTECTS_DATA("method", usb_intr_req))
 171 _NOTE(SCHEME_PROTECTS_DATA("method", usb_isoc_req))
 172 
 173 /* additional flag for wr_usb_flags */
 174 #define USBA_WRP_FLAGS_WAIT     0x01
 175 
 176 /* additional usb flags, not exposed to clients */
 177 #define USBA_FLAGS_PRIVILEGED   0x02    /* for default pipe operations */
 178 
 179 /* Macros to convert wrapper to different request and vice-versa */
 180 
 181 /* to get the wr->wr_req field */
 182 #define USBA_WRP2REQ(wrp)       ((wrp)->wr_req)
 183 
 184 /* to get the wrapper form the wr_req field */
 185 #define USBA_REQ2WRP(req)               (usba_req_wrapper_t *)\
 186                                 ((uintptr_t)(req) - sizeof (usba_req_wrapper_t))
 187 
 188 /* to set the the address in the wr_req field */
 189 #define USBA_SETREQ_ADDR(wrp)   ((uintptr_t)(wrp) + sizeof (*(wrp)))
 190 
 191 /* to get the 4 xfer type requests */
 192 #define USBA_WRP2CTRL_REQ(wrp)  ((usb_ctrl_req_t *)USBA_WRP2REQ((wrp)))
 193 #define USBA_WRP2INTR_REQ(wrp)  ((usb_intr_req_t *)USBA_WRP2REQ((wrp)))
 194 #define USBA_WRP2BULK_REQ(wrp)  ((usb_bulk_req_t *)USBA_WRP2REQ((wrp)))
 195 #define USBA_WRP2ISOC_REQ(wrp)  ((usb_isoc_req_t *)USBA_WRP2REQ((wrp)))
 196 
 197 /* to get pipe_handle from the wrapper */
 198 #define USBA_WRP2PH_DATA(wrp) \
 199         (usba_pipe_handle_data_t *)((wrp)->wr_ph_data)
 200 
 201 /* to get to the wr_queue from the wrapper */
 202 #define USBA_WRQUEUE2WRP(queue) (usba_req_wrapper_t *)(queue)
 203 
 204 /* to get to the wr_allocated queue from the wrapper */
 205 #define USBA_ALLOCQ2WRP(queue)  (usba_req_wrapper_t *)((uintptr_t) \
 206         (queue)  - sizeof (usba_list_entry_t) - sizeof (usb_opaque_t))
 207 
 208 
 209 /* alias for pipe handle member p_usba_private */
 210 #define p_active_cntrl_req_wrp  p_usba_private
 211 
 212 /*
 213  * This function is used to get the HCD private field maintained by USBA.
 214  * HCD calls this function.
 215  */
 216 usb_opaque_t usba_hcdi_get_ctrl_req_hcd_private(usb_ctrl_req_t *);
 217 
 218 /*
 219  * This function is used to set the HCD private field maintained by USBA.
 220  * HCD calls this function.
 221  */
 222 void    usba_hcdi_set_ctrl_req_hcd_private(usb_ctrl_req_t *, usb_opaque_t);
 223 
 224 int     usba_set_usb_address(usba_device_t *);
 225 void    usba_unset_usb_address(usba_device_t *);
 226 
 227 /*
 228  * Per Hub Data Structures
 229  */
 230 typedef  struct usba_hubdi {
 231         usba_list_entry_t hubdi_list;    /* linking in hubdi list */
 232 
 233         dev_info_t      *hubdi_dip;      /* ptr to devinfo struct */
 234 
 235         int             hubdi_flags;    /* flag options */
 236 
 237 } usba_hubdi_t;
 238 
 239 /*
 240  * usba_get_mfg_prod_sn_str:
 241  *      Return a string containing mfg, product, serial number strings.
 242  */
 243 char    *usba_get_mfg_prod_sn_str(dev_info_t *, char *, int);
 244 
 245 /* return value when user doesn't specify configuration index */
 246 #define USBA_DEV_CONFIG_INDEX_UNDEFINED -1
 247 
 248 /*
 249  * prototypes
 250  */
 251 void    usba_usba_initialization();
 252 void    usba_usba_destroy();
 253 
 254 void    usba_usbai_register_initialization();
 255 void    usba_usbai_register_destroy();
 256 
 257 void    usba_usbai_initialization();
 258 void    usba_usbai_destroy();
 259 
 260 void    usba_hubdi_initialization();
 261 void    usba_hubdi_destroy();
 262 
 263 void    usba_devdb_initialization();
 264 void    usba_devdb_destroy();
 265 
 266 int     usba_hubdi_register(dev_info_t  *, uint_t);
 267 int     usba_hubdi_unregister(dev_info_t *);
 268 
 269 int     usba_is_root_hub(dev_info_t *dip);
 270 
 271 usba_device_t *usba_alloc_usba_device(dev_info_t *);
 272 void    usba_free_usba_device(usba_device_t *usba_device_t);
 273 void    usba_clear_data_toggle(usba_device_t *usba_device);
 274 
 275 void    usba_start_next_req(usba_pipe_handle_data_t *ph);
 276 
 277 int     usba_pipe_check_handle(usba_pipe_handle_data_t *);
 278 int     usba_drain_cbs(usba_pipe_handle_data_t *, usb_cb_flags_t,
 279                         usb_cr_t);
 280 int     usba_pipe_setup_func_call(dev_info_t *,
 281                         int (*sync_func)(dev_info_t *,
 282                                 usba_ph_impl_t *, usba_pipe_async_req_t *,
 283                                 usb_flags_t),
 284                         usba_ph_impl_t *,
 285                         usb_opaque_t,
 286                         usb_flags_t,
 287                         void (*cb)(usb_pipe_handle_t, usb_opaque_t,
 288                             int, usb_cb_flags_t),
 289                         usb_opaque_t);
 290 
 291 
 292 void    usba_pipe_new_state(usba_pipe_handle_data_t *, usb_pipe_state_t);
 293 
 294 void usba_add_root_hub(dev_info_t *dip);
 295 void usba_rem_root_hub(dev_info_t *dip);
 296 
 297 /*
 298  * retrieve string descriptors for manufacturer, vendor and serial
 299  * number
 300  */
 301 void usba_get_dev_string_descrs(dev_info_t *, usba_device_t *);
 302 
 303 /*
 304  * Check if we are not in interrupt context and have
 305  * USB_FLAGS_SLEEP flags set.
 306  */
 307 #define USBA_CHECK_CONTEXT()    ASSERT(!(servicing_interrupt()))
 308 
 309 /*
 310  * USBA module Masks
 311  */
 312 #define DPRINT_MASK_USBA                0x00000001
 313 #define DPRINT_MASK_USBAI               0x00000002
 314 #define DPRINT_MASK_HUBDI               0x00000004
 315 #define DPRINT_MASK_HCDI                0x00000008
 316 #define DPRINT_MASK_HCDI_DUMPING        0x00000010
 317 #define DPRINT_MASK_HUBDI_DUMPING       0x00000020
 318 #define DPRINT_MASK_REGISTER            0x00000040
 319 #define DPRINT_MASK_DEVDB               0x00000080
 320 #define DPRINT_MASK_WHCDI               0x00000100
 321 #define DPRINT_MASK_ALL                 0xFFFFFFFF
 322 
 323 typedef struct usba_log_handle_impl {
 324         dev_info_t      *lh_dip;
 325         char            *lh_name;
 326         uint_t          *lh_errlevel;
 327         uint_t          *lh_mask;
 328         uint_t          *lh_instance_filter;
 329         uint_t          lh_flags;
 330 } usba_log_handle_impl_t;
 331 
 332 _NOTE(SCHEME_PROTECTS_DATA("USBA managed data", usba_log_handle_impl))
 333 
 334 /*
 335  * Miscellaneous definitions.
 336  */
 337 
 338 /* possible strlen of a USB driver's name */
 339 #define USBA_DRVNAME_LEN        40
 340 
 341 /* strings passed to usb_dprintfN() are this long */
 342 #define USBA_PRINT_BUF_LEN      256
 343 
 344 /*
 345  * usba_set_node_name() sets a device info node name
 346  * according to class, subclass, and protocol.
 347  * a subclass == -1 or protocol == -1 is considered a "don't care".
 348  */
 349 #define DONTCARE                ((int16_t)-1)
 350 #define FLAG_INTERFACE_NODE     0
 351 #define FLAG_DEVICE_NODE        1
 352 #define FLAG_COMBINED_NODE      2
 353 #define FLAG_INTERFACE_ASSOCIATION_NODE         3
 354 
 355 typedef struct node_name_entry {
 356         int16_t class;
 357         int16_t subclass;
 358         int16_t protocol;
 359         char    *name;
 360 } node_name_entry_t;
 361 
 362 
 363 /*
 364  * USB enumeration statistics support
 365  */
 366 
 367 /* Flags telling which stats usba_update_hotplug_stats should update */
 368 #define USBA_TOTAL_HOTPLUG_SUCCESS      0x01
 369 #define USBA_HOTPLUG_SUCCESS            0x02
 370 #define USBA_TOTAL_HOTPLUG_FAILURE      0x04
 371 #define USBA_HOTPLUG_FAILURE            0x08
 372 
 373 /*
 374  * Increment enumeration stats indicated by the flags
 375  */
 376 void    usba_update_hotplug_stats(dev_info_t *, usb_flags_t);
 377 
 378 /* Retrieve the current enumeration hotplug statistics */
 379 void    usba_get_hotplug_stats(dev_info_t *,
 380                 ulong_t *, ulong_t *, ulong_t *,
 381                 ulong_t *, uchar_t *);
 382 
 383 /* Reset the resetable hotplug stats */
 384 void    usba_reset_hotplug_stats(dev_info_t *);
 385 
 386 
 387 extern usb_log_handle_t usbai_log_handle;
 388 extern  kmutex_t usbai_mutex;
 389 
 390 void    usba_req_normal_cb(usba_req_wrapper_t *);
 391 void    usba_req_exc_cb(usba_req_wrapper_t *, usb_cr_t, usb_cb_flags_t);
 392 void    usba_do_req_exc_cb(usba_req_wrapper_t *, usb_cr_t,
 393                                                 usb_cb_flags_t);
 394 void    usba_req_set_cb_flags(usba_req_wrapper_t *, usb_cb_flags_t);
 395 
 396 /*
 397  * Creating/Destroying children (root hub, and hub children)
 398  */
 399 int     usba_create_child_devi(dev_info_t *, char *, usba_hcdi_ops_t *,
 400                 dev_info_t *, usb_port_status_t,
 401                 usba_device_t *, dev_info_t **);
 402 
 403 int     usba_destroy_child_devi(dev_info_t *, uint_t);
 404 
 405 /* utility function to map rval to a meaningful cr */
 406 usb_cr_t usba_rval2cr(int);
 407 
 408 /* various conversion functions */
 409 usb_pipe_handle_t       usba_get_dflt_pipe_handle(dev_info_t *);
 410 dev_info_t              *usba_get_dip(usb_pipe_handle_t);
 411 usb_pipe_handle_t       usba_usbdev_to_dflt_pipe_handle(usba_device_t *);
 412 usb_pipe_handle_t       usba_get_pipe_handle(usba_pipe_handle_data_t *);
 413 usba_pipe_handle_data_t *usba_get_ph_data(usb_pipe_handle_t);
 414 usb_pipe_state_t        usba_get_ph_state(usba_pipe_handle_data_t *);
 415 int                     usba_get_ph_ref_count(usba_pipe_handle_data_t *);
 416 
 417 /* increment and decrement ref_count */
 418 usba_pipe_handle_data_t *usba_hold_ph_data(usb_pipe_handle_t);
 419 void                    usba_release_ph_data(usba_ph_impl_t *);
 420 
 421 /* close all pipe and mark them persistent */
 422 void                    usba_persistent_pipe_close(usba_device_t *);
 423 
 424 /* reopen pipes that are marked persistent */
 425 int                     usba_persistent_pipe_open(usba_device_t *);
 426 
 427 /* check for leaks in hubd and usb_mid */
 428 void    usba_check_for_leaks(usba_device_t *);
 429 
 430 /* free request wrappers */
 431 void    usba_req_wrapper_free(usba_req_wrapper_t *);
 432 
 433 /* usb device capture for the specific client driver */
 434 typedef struct usb_dev_cap {
 435         dev_info_t                      *dip;
 436         usb_dev_driver_callback_t       usba_dev_driver_cb;
 437 } usb_dev_cap_t;
 438 
 439 usb_dev_cap_t usb_cap;
 440 _NOTE(SCHEME_PROTECTS_DATA("unique device capture data", usb_cap))
 441 
 442 #ifdef __cplusplus
 443 }
 444 #endif
 445 
 446 #endif /* _SYS_USB_USBA_USBA_IMPL_H */