1 USBA_HCDI_BIND_ROOT_HUB(9F)                       Kernel Functions for Drivers
   2 
   3 NAME
   4      usba_hubdi_bind_root_hub, usba_hubdi_unbind_root_hub - bind and unbind
   5      the root USB hub
   6 
   7 SYNOPSIS
   8      #include <sys/usb/usba/hubdi.h>
   9 
  10      int
  11      usba_hubdi_bind_root_hub(dev_info_t *dip, uchar_t *hub_descr,
  12          size_t descr_len, usb_dev_descr_t *dev_descr);
  13 
  14      int
  15      usba_hubdi_unbind_root_hub(dev_info_t *dip);
  16 
  17 INTERFACE LEVEL
  18      Volatile - illumos USB HCD private function
  19 
  20      This is a private function that is not part of the stable DDI.  It may be
  21      removed or changed at any time.
  22 
  23 PARAMETERS
  24      dip           Pointer to the device's dev_info structure.
  25 
  26      hub_descr     Pointer to a byte array that contains the standard
  27                    descriptors for a USB Hub device.
  28 
  29      descr_len     The length in bytes of the hub_descr byte array.
  30 
  31      dev_descr     A filled in standard USB device descriptor.
  32 
  33 DESCRIPTION
  34      The usba_hubdi_bind_root_hub() and usba_hubdi_unbind_root_hub() functions
  35      are used to bind and unbind the root USB hub that is a part of every HCD
  36      driver.  See usba_hcdi(9E) for more information on this relationship.
  37 
  38      The usba_hubdi_root_bind_driver() is used after calling the
  39      usba_hcdi_register(9F) function during a device's attach(9E) entry point.
  40 
  41      Because the root hub is generally a virtual hub, the HCD driver is
  42      responsible for making it appear to the system as a normal USB hub.
  43 
  44      The contents of the hub_descr should be the standard USB Hub class-
  45      specific descriptor.  This hub descriptor should match a hub of a similar
  46      class of speed.  For example, with the xhci controller, a USB 3.x Hub
  47      class-specific descriptor is used, where as for the ehci controller, a
  48      USB 2.x Hub class-specific descriptor is used.  For more information, see
  49      the USB 3.1 specification, section 10.15.2 Class-specific Descriptors.
  50 
  51      Similarly, the contents of the dev_descr need to be a filled in USB
  52      device descriptor that indicates that the root hub corresponds to the
  53      appropriate USB generation.  For more information on the contents, see
  54      usb_dev_descr(9S) and the USB 3.1 specification, section 10.15.1 Standard
  55      Descriptors for Hub Class.
  56 
  57      The usba_hubdi_unbind_root_hub() function is used to detach the root hub
  58      associated with the HCD driver.  This should be called during a device's
  59      detach(9E) routine before calling usba_hcdi_unregister(9F).
  60 
  61      If a call to the usba_hubdi_unbind_root_hub() function fails during a
  62      device's detach(9E) function, then it should fail the call to detach(9E).
  63 
  64 CONTEXT
  65      The usba_hubdi_bind_root_hub() function should only be called during a
  66      device's attach(9E) entry point.
  67 
  68      The usba_hubdi_unbind_root_hub() function should only be called during a
  69      device's detach(9E) entry point.
  70 
  71 RETURN VALUES
  72      Upon successful completion, the usba_hubdi_bind_root_hub() and
  73      usba_hubdi_unbind_root_hub() functions return USB_SUCCESS.  Otherwise,
  74      they return USB_FAILURE to indicate that they could not proceed.
  75 
  76 SEE ALSO
  77      attach(9E), detach(9E), usba_hcdi(9E), usba_hcdi_register(9F),
  78      usba_hcdi_unregister(9F), usb_dev_descr(9S)
  79 
  80 illumos                       September 16, 2016                       illumos