USBA_HCDI_BIND_ROOT_HUB(9F) Kernel Functions for Drivers
usba_hubdi_bind_root_hub, usba_hubdi_unbind_root_hub - bind and unbind
the root USB hub
#include <sys/usb/usba/hubdi.h>
int
usba_hubdi_bind_root_hub(dev_info_t *dip, uchar_t *hub_descr,
size_t descr_len, usb_dev_descr_t *dev_descr);
int
usba_hubdi_unbind_root_hub(dev_info_t *dip);
Volatile - illumos USB HCD private function
This is a private function that is not part of the stable DDI. It may
be removed or changed at any time.
dip Pointer to the device's dev_info structure.
hub_descr Pointer to a byte array that contains the standard
descriptors for a USB Hub device.
descr_len The length in bytes of the hub_descr byte array.
dev_descr A filled in standard USB device descriptor.
The usba_hubdi_bind_root_hub() and usba_hubdi_unbind_root_hub()
functions are used to bind and unbind the root USB hub that is a part
of every HCD driver. See usba_hcdi(9E) for more information on this
relationship.
The usba_hubdi_root_bind_driver() is used after calling the
usba_hcdi_register(9F) function during a device's attach(9E) entry
point.
Because the root hub is generally a virtual hub, the HCD driver is
responsible for making it appear to the system as a normal USB hub.
The contents of the hub_descr should be the standard USB Hub class-
specific descriptor. This hub descriptor should match a hub of a
similar class of speed. For example, with the xhci controller, a USB
3.x Hub class-specific descriptor is used, where as for the ehci
controller, a USB 2.x Hub class-specific descriptor is used. For more
information, see the USB 3.1 specification, section 10.15.2
Class-specific Descriptors.
Similarly, the contents of the dev_descr need to be a filled in USB
device descriptor that indicates that the root hub corresponds to the
appropriate USB generation. For more information on the contents, see
usb_dev_descr(9S) and the USB 3.1 specification, section 10.15.1
Standard Descriptors for Hub Class.
The usba_hubdi_unbind_root_hub() function is used to detach the root
hub associated with the HCD driver. This should be called during a
device's detach(9E) routine before calling usba_hcdi_unregister(9F).
If a call to the usba_hubdi_unbind_root_hub() function fails during a
device's detach(9E) function, then it should fail the call to
detach(9E).
The usba_hubdi_bind_root_hub() function should only be called during a
device's attach(9E) entry point.
The usba_hubdi_unbind_root_hub() function should only be called during
a device's detach(9E) entry point.
Upon successful completion, the usba_hubdi_bind_root_hub() and
usba_hubdi_unbind_root_hub() functions return USB_SUCCESS. Otherwise,
they return USB_FAILURE to indicate that they could not proceed.
attach(9E), detach(9E), usba_hcdi(9E), usba_hcdi_register(9F),
usba_hcdi_unregister(9F), usb_dev_descr(9S)
illumos September 16, 2016 illumos
NAME
usba_hubdi_bind_root_hub, usba_hubdi_unbind_root_hub - bind and unbind
the root USB hub
SYNOPSIS
#include <sys/usb/usba/hubdi.h>
int
usba_hubdi_bind_root_hub(dev_info_t *dip, uchar_t *hub_descr,
size_t descr_len, usb_dev_descr_t *dev_descr);
int
usba_hubdi_unbind_root_hub(dev_info_t *dip);
INTERFACE LEVEL
Volatile - illumos USB HCD private function
This is a private function that is not part of the stable DDI. It may
be removed or changed at any time.
PARAMETERS
dip Pointer to the device's dev_info structure.
hub_descr Pointer to a byte array that contains the standard
descriptors for a USB Hub device.
descr_len The length in bytes of the hub_descr byte array.
dev_descr A filled in standard USB device descriptor.
DESCRIPTION
The usba_hubdi_bind_root_hub() and usba_hubdi_unbind_root_hub()
functions are used to bind and unbind the root USB hub that is a part
of every HCD driver. See usba_hcdi(9E) for more information on this
relationship.
The usba_hubdi_root_bind_driver() is used after calling the
usba_hcdi_register(9F) function during a device's attach(9E) entry
point.
Because the root hub is generally a virtual hub, the HCD driver is
responsible for making it appear to the system as a normal USB hub.
The contents of the hub_descr should be the standard USB Hub class-
specific descriptor. This hub descriptor should match a hub of a
similar class of speed. For example, with the xhci controller, a USB
3.x Hub class-specific descriptor is used, where as for the ehci
controller, a USB 2.x Hub class-specific descriptor is used. For more
information, see the USB 3.1 specification, section 10.15.2
Class-specific Descriptors.
Similarly, the contents of the dev_descr need to be a filled in USB
device descriptor that indicates that the root hub corresponds to the
appropriate USB generation. For more information on the contents, see
usb_dev_descr(9S) and the USB 3.1 specification, section 10.15.1
Standard Descriptors for Hub Class.
The usba_hubdi_unbind_root_hub() function is used to detach the root
hub associated with the HCD driver. This should be called during a
device's detach(9E) routine before calling usba_hcdi_unregister(9F).
If a call to the usba_hubdi_unbind_root_hub() function fails during a
device's detach(9E) function, then it should fail the call to
detach(9E).
CONTEXT
The usba_hubdi_bind_root_hub() function should only be called during a
device's attach(9E) entry point.
The usba_hubdi_unbind_root_hub() function should only be called during
a device's detach(9E) entry point.
RETURN VALUES
Upon successful completion, the usba_hubdi_bind_root_hub() and
usba_hubdi_unbind_root_hub() functions return USB_SUCCESS. Otherwise,
they return USB_FAILURE to indicate that they could not proceed.
SEE ALSO
attach(9E), detach(9E), usba_hcdi(9E), usba_hcdi_register(9F),
usba_hcdi_unregister(9F), usb_dev_descr(9S)
illumos September 16, 2016 illumos