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 - 36illumos USB HCD private function 37.Pp 38This is a private function that is not part of the stable DDI. It may be 39removed or changed at any time. 40.Sh PARAMETERS 41.Bl -tag -width Fa 42.It Fa dip 43Pointer to the device's 44.Sy dev_info 45structure. 46.It Fa hub_descr 47Pointer to a byte array that contains the standard descriptors for a USB 48Hub device. 49.It Fa descr_len 50The length in bytes of the 51.Fa hub_descr 52byte array. 53.It Fa dev_descr 54A filled in standard USB device descriptor. 55.El 56.Sh DESCRIPTION 57The 58.Fn usba_hubdi_bind_root_hub 59and 60.Fn usba_hubdi_unbind_root_hub 61functions are used to bind and unbind the root USB hub that is a part of 62every HCD driver. See 63.Xr usba_hcdi 9E 64for more information on this relationship. 65.Pp 66The 67.Fn usba_hubdi_root_bind_driver 68is used after calling the 69.Xr usba_hcdi_register 9F 70function during a device's 71.Xr attach 9E 72entry point. 73.Pp 74Because the root hub is generally a virtual hub, the HCD driver is 75responsible for making it appear to the system as a normal USB hub. 76.Pp 77The contents of the 78.Fa hub_descr 79should be the standard USB Hub class-specific descriptor. This hub 80descriptor should match a hub of a similar class of speed. For example, 81with the xhci controller, a USB 3.x Hub class-specific descriptor is 82used, where as for the ehci controller, a USB 2.x Hub class-specific 83descriptor is used. For more information, see the USB 3.1 84specification, section 10.15.2 85.Em Class-specific Descriptors . 86.Pp 87Similarly, the contents of the 88.Fa dev_descr 89need to be a filled in USB device descriptor that indicates that the 90root hub corresponds to the appropriate USB generation. For more 91information on the contents, see 92.Xr usb_dev_descr 9S 93and the USB 3.1 specification, section 10.15.1 94.Em Standard Descriptors for Hub Class . 95.Pp 96The 97.Fn usba_hubdi_unbind_root_hub 98function is used to detach the root hub associated with the HCD driver. 99This should be called during a device's 100.Xr detach 9E 101routine before calling 102.Xr usba_hcdi_unregister . 103.Pp 104If a call to the 105.Fn usba_hubdi_unbind_root_hub 106function fails during a device's 107.Xr detach 9E 108function, then it should fail the call to 109.Xr detach 9E . 110.Sh CONTEXT 111The 112.Fn usba_hubdi_bind_root_hub 113function should only be called during a device's 114.Xr attach 9E 115entry point. 116.Pp 117The 118.Fn usba_hubdi_unbind_root_hub 119function should only be called during a device's 120.Xr detach 9E entry point. 121.Sh RETURN VALUES 122Upon successful completion, the 123.Fn usba_hubdi_bind_root_hub 124and 125.Fn usba_hubdi_unbind_root_hub 126functions return 127.Sy USB_SUCCESS . 128Otherwise, they return 129.Sy USB_FAILURE 130to indicate that they could not proceed. 131.Sh SEE ALSO 132.Xr attach 9E , 133.Xr detach 9E , 134.Xr usba_hcdi 9E , 135.Xr usba_hcdi_register 9F , 136.Xr usba_hcdi_unregister 9F , 137.Xr usb_dev_Descr 9S 138