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