1.\"
2.\" This file and its contents are supplied under the terms of the
3.\" Common Development and Distribution License ("CDDL"), version 1.0.
4.\" You may only use this file in accordance with the terms of version
5.\" 1.0 of the CDDL.
6.\"
7.\" A full copy of the text of the CDDL should have accompanied this
8.\" source.  A copy of the CDDL is also available via the Internet at
9.\" http://www.illumos.org/license/CDDL.
10.\"
11.\"
12.\" Copyright 2016 Joyent, Inc.
13.\"
14.Dd Dec 20, 2016
15.Dt USBA_HCDI_HUB_UPDATE 9E
16.Os
17.Sh NAME
18.Nm usba_hcdi_hub_update
19.Nd USB HCD hub update entry point
20.Sh SYNOPSIS
21.In sys/usb/usba/hcdi.h
22.Ft int
23.Fo prefix_hcdi_hub_update
24.Fa "usba_device_t *ud"
25.Fa "uint8_t nports"
26.Fa "uint8_t tt"
27.Fc
28.Sh INTERFACE LEVEL
29.Sy Volatile -
30illumos USB HCD private function
31.Pp
32This is a private function that is not part of the stable DDI. It may be
33removed or changed at any time.
34.Sh PARAMETERS
35.Bl -tag -width Fa
36.It Fa ud
37Pointer to a USB device structure being updated. See
38.Xr usba_device 9S
39for more information.
40.It Fa nports
41The number of ports present on the hub.
42.It Fa tt
43The value of the Think Time property as defined in the USB
44specification's hub descriptor.
45.El
46.Sh DESCRIPTION
47The
48.Fn usba_hcdi_hub_update
49entry point is an optional entry point for USB host controller drivers.
50It is used by some controllers to allow them to update information about
51a device in the controller after a device has been determined to be a
52hub during enumeration. If a host controller does not need to take any
53specific action after enumerating a hub, then it should simply set this
54entry point in the
55.Xr usba_hcdi_ops 9S
56structure to
57.Dv NULL .
58.Pp
59The
60.Fa nports
61and
62.Fa tt
63members provide relevant information from the device's hub class
64descriptor which can be used to help program the host controller. Any
65programming should be performed synchronously and be completed before
66this function returns.
67.Pp
68This function will be called after
69.Xr usba_hcdi_device_init 9E
70has been called. Any private data registered with that function will be
71available.
72.Pp
73If this function fails, the enumeration of this device will fail, the
74hub driver will not attach to this USB device, and all devices plugged
75into this hub will not be detected by the system.
76.Sh CONTEXT
77This functin is called from kernel context only.
78.Sh RETURN VALUES
79Upon successful completion, the
80.Fn usba_hcdi_hub_update
81function should return
82.Sy USB_SUCCESS .
83Otherwise, it should return the appropriate USB error. If uncertain, use
84.Sy USB_FAILURE .
85.Sh SEE ALSO
86.Xr usba_hcdi_device_init 9E ,
87.Xr usba_device 9S ,
88.Xr usba_hcdi_ops 9S
89