share/man/man9f/usba_hubdi_bind_root_hub.9f

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2016 Joyent, Inc.
  13 .\"
  14 .Dd Sep 16, 2016
  15 .Dt USBA_HCDI_BIND_ROOT_HUB 9F
  16 .Os
  17 .Sh NAME
  18 .Nm usba_hubdi_bind_root_hub ,
  19 .Nm usba_hubdi_unbind_root_hub
  20 .Nd bind and unbind the root USB hub
  21 .Sh SYNOPSIS
  22 .In sys/usb/usba/hubdi.h
  23 .Ft int
  24 .Fo usba_hubdi_bind_root_hub
  25 .Fa "dev_info_t *dip"
  26 .Fa "uchar_t *hub_descr"
  27 .Fa "size_t descr_len"
  28 .Fa "usb_dev_descr_t *dev_descr"
  29 .Fc
  30 .Ft int
  31 .Fo usba_hubdi_unbind_root_hub
  32 .Fa "dev_info_t *dip"
  33 .Fc
  34 .Sh INTERFACE LEVEL
  35 .Sy Volatile -
  36 illumos USB HCD private function
  37 .Pp
  38 This is a private function that is not part of the stable DDI.
  39 It may be removed or changed at any time.
  40 .Sh PARAMETERS
  41 .Bl -tag -width Fa
  42 .It Fa dip
  43 Pointer to the device's
  44 .Sy dev_info
  45 structure.
  46 .It Fa hub_descr
  47 Pointer to a byte array that contains the standard descriptors for a USB
  48 Hub device.
  49 .It Fa descr_len
  50 The length in bytes of the
  51 .Fa hub_descr
  52 byte array.
  53 .It Fa dev_descr
  54 A filled in standard USB device descriptor.
  55 .El
  56 .Sh DESCRIPTION
  57 The
  58 .Fn usba_hubdi_bind_root_hub
  59 and
  60 .Fn usba_hubdi_unbind_root_hub
  61 functions are used to bind and unbind the root USB hub that is a part of
  62 every HCD driver.
  63 See
  64 .Xr usba_hcdi 9E
  65 for more information on this relationship.
  66 .Pp
  67 The
  68 .Fn usba_hubdi_root_bind_driver
  69 is used after calling the
  70 .Xr usba_hcdi_register 9F
  71 function during a device's
  72 .Xr attach 9E
  73 entry point.
  74 .Pp
  75 Because the root hub is generally a virtual hub, the HCD driver is
  76 responsible for making it appear to the system as a normal USB hub.
  77 .Pp
  78 The contents of the
  79 .Fa hub_descr
  80 should be the standard USB Hub class-specific descriptor.
  81 This hub descriptor should match a hub of a similar class of speed.
  82 For example, with the xhci controller, a USB 3.x Hub class-specific descriptor
  83 is used, where as for the ehci controller, a USB 2.x Hub class-specific
  84 descriptor is used.
  85 For more information, see the USB 3.1 specification, section 10.15.2
  86 .Em Class-specific Descriptors .
  87 .Pp
  88 Similarly, the contents of the
  89 .Fa dev_descr
  90 need to be a filled in USB device descriptor that indicates that the
  91 root hub corresponds to the appropriate USB generation.
  92 For more information on the contents, see
  93 .Xr usb_dev_descr 9S
  94 and the USB 3.1 specification, section 10.15.1
  95 .Em Standard Descriptors for Hub Class .
  96 .Pp
  97 The
  98 .Fn usba_hubdi_unbind_root_hub
  99 function is used to detach the root hub associated with the HCD driver.
 100 This should be called during a device's
 101 .Xr detach 9E
 102 routine before calling
 103 .Xr usba_hcdi_unregister 9F .
 104 .Pp
 105 If a call to the
 106 .Fn usba_hubdi_unbind_root_hub
 107 function fails during a device's
 108 .Xr detach 9E
 109 function, then it should fail the call to
 110 .Xr detach 9E .
 111 .Sh CONTEXT
 112 The
 113 .Fn usba_hubdi_bind_root_hub
 114 function should only be called during a device's
 115 .Xr attach 9E
 116 entry point.
 117 .Pp
 118 The
 119 .Fn usba_hubdi_unbind_root_hub
 120 function should only be called during a device's
 121 .Xr detach 9E entry point.
 122 .Sh RETURN VALUES
 123 Upon successful completion, the
 124 .Fn usba_hubdi_bind_root_hub
 125 and
 126 .Fn usba_hubdi_unbind_root_hub
 127 functions return
 128 .Sy USB_SUCCESS .
 129 Otherwise, they return
 130 .Sy USB_FAILURE
 131 to indicate that they could not proceed.
 132 .Sh SEE ALSO
 133 .Xr attach 9E ,
 134 .Xr detach 9E ,
 135 .Xr usba_hcdi 9E ,
 136 .Xr usba_hcdi_register 9F ,
 137 .Xr usba_hcdi_unregister 9F ,
 138 .Xr usb_dev_Descr 9S