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.