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. 39It may be removed 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. 63See 64.Xr usba_hcdi 9E 65for more information on this relationship. 66.Pp 67The 68.Fn usba_hubdi_root_bind_driver 69is used after calling the 70.Xr usba_hcdi_register 9F 71function during a device's 72.Xr attach 9E 73entry point. 74.Pp 75Because the root hub is generally a virtual hub, the HCD driver is 76responsible for making it appear to the system as a normal USB hub. 77.Pp 78The contents of the 79.Fa hub_descr 80should be the standard USB Hub class-specific descriptor. 81This hub descriptor should match a hub of a similar class of speed. 82For example, with the xhci controller, a USB 3.x Hub class-specific descriptor 83is used, where as for the ehci controller, a USB 2.x Hub class-specific 84descriptor is used. 85For more information, see the USB 3.1 specification, section 10.15.2 86.Em Class-specific Descriptors . 87.Pp 88Similarly, the contents of the 89.Fa dev_descr 90need to be a filled in USB device descriptor that indicates that the 91root hub corresponds to the appropriate USB generation. 92For more information on the contents, see 93.Xr usb_dev_descr 9S 94and the USB 3.1 specification, section 10.15.1 95.Em Standard Descriptors for Hub Class . 96.Pp 97The 98.Fn usba_hubdi_unbind_root_hub 99function is used to detach the root hub associated with the HCD driver. 100This should be called during a device's 101.Xr detach 9E 102routine before calling 103.Xr usba_hcdi_unregister 9F . 104.Pp 105If a call to the 106.Fn usba_hubdi_unbind_root_hub 107function fails during a device's 108.Xr detach 9E 109function, then it should fail the call to 110.Xr detach 9E . 111.Sh CONTEXT 112The 113.Fn usba_hubdi_bind_root_hub 114function should only be called during a device's 115.Xr attach 9E 116entry point. 117.Pp 118The 119.Fn usba_hubdi_unbind_root_hub 120function should only be called during a device's 121.Xr detach 9E entry point. 122.Sh RETURN VALUES 123Upon successful completion, the 124.Fn usba_hubdi_bind_root_hub 125and 126.Fn usba_hubdi_unbind_root_hub 127functions return 128.Sy USB_SUCCESS . 129Otherwise, they return 130.Sy USB_FAILURE 131to 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 139