Tribblix: 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.