.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2016 Joyent, Inc.
.\"
.Dd Dec 20, 2016
.Dt USBA_HCDI_HUB_UPDATE 9E
.Os
.Sh NAME
.Nm usba_hcdi_hub_update
.Nd USB HCD hub update entry point
.Sh SYNOPSIS
.In sys/usb/usba/hcdi.h
.Ft int
.Fo prefix_hcdi_hub_update
.Fa "usba_device_t *ud"
.Fa "uint8_t nports"
.Fa "uint8_t tt"
.Fc
.Sh INTERFACE LEVEL
.Sy Volatile -
illumos USB HCD private function
.Pp
This is a private function that is not part of the stable DDI.
It may be removed or changed at any time.
.Sh PARAMETERS
.Bl -tag -width Fa
.It Fa ud
Pointer to a USB device structure being updated.
See
.Xr usba_device 9S
for more information.
.It Fa nports
The number of ports present on the hub.
.It Fa tt
The value of the Think Time property as defined in the USB
specification's hub descriptor.
.El
.Sh DESCRIPTION
The
.Fn usba_hcdi_hub_update
entry point is an optional entry point for USB host controller drivers.
It is used by some controllers to allow them to update information about
a device in the controller after a device has been determined to be a
hub during enumeration.
If a host controller does not need to take any specific action after enumerating
a hub, then it should simply set this entry point in the
.Xr usba_hcdi_ops 9S
structure to
.Dv NULL .
.Pp
The
.Fa nports
and
.Fa tt
members provide relevant information from the device's hub class
descriptor which can be used to help program the host controller.
Any programming should be performed synchronously and be completed before
this function returns.
.Pp
This function will be called after
.Xr usba_hcdi_device_init 9E
has been called.
Any private data registered with that function will be available.
.Pp
If this function fails, the enumeration of this device will fail, the
hub driver will not attach to this USB device, and all devices plugged
into this hub will not be detected by the system.
.Sh CONTEXT
This functin is called from kernel context only.
.Sh RETURN VALUES
Upon successful completion, the
.Fn usba_hcdi_hub_update
function should return
.Sy USB_SUCCESS .
Otherwise, it should return the appropriate USB error.
If uncertain, use
.Sy USB_FAILURE .
.Sh SEE ALSO
.Xr usba_hcdi_device_init 9E ,
.Xr usba_device 9S ,
.Xr usba_hcdi_ops 9S