illumos: manual page: usba_hubdi_bind_root

USBA_HCDI_BIND_ROOT_HUB(9F) Kernel Functions for Drivers

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.