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_device_address
19.Nd Assign USB address to device
20.Sh SYNOPSIS
21.In sys/usb/usba/hcdi.h
22.Ft int
23.Fo prefix_hcdi_device_address
24.Fa "usba_device_t *ud"
25.Fc
26.Sh INTERFACE LEVEL
27.Sy Volatile -
28illumos USB HCD private function
29.Pp
30This is a private function that is not part of the stable DDI.
31It may be removed or changed at any time.
32.Sh PARAMETERS
33.Bl -tag -width Fa
34.It Fa ud
35Pointer to a USB device structure being updated.
36See
37.Xr usba_device 9S
38for more information.
39.El
40.Sh DESCRIPTION
41The
42.Fn usba_hcdi_device_address
43entry point is an optional entry point for USB host controller drivers.
44Some USB host controllers do not allow the USB SET_ADDRESS command to be
45issued to a device.
46Instead, they will be responsible for setting the address in a
47controller-specific way.
48If the host controller driver requires this behavior, then it must implement
49this function.
50Otherwise, if the host controller does not require this functionality, it should
51set the entry point in the
52.Xr usba_hcdi_ops 9S
53structure to
54.Dv NULL .
55.Pp
56The USBA will always set an address for the USBA device
57.Fa ud
58regardless of whether or not this function is implemented.
59If the HCD implements this entry point and it needs the addressing information
60for whatever reason, then it is the responsibility of the driver to keep
61track of it separately.
62.Pp
63This entry point will be called after the
64.Xr usba_hcdi_device_init 9E
65entry point has been called.
66Any private data stored on the device will be available through the
67.Xr usba_hcdi_get_device_private 9F
68function.
69.Pp
70Upon completion of the function, the device is expected to be addressed
71and thus able to have endpoints opened and transfers performed on them.
72If this function fails, the device's enumeration will halt.
73.Sh CONTEXT
74This function is called from kernel context ontly.
75.Sh RETURN VALUES
76Upon successful completion, the
77.Fn usba_hcdi_device_address
78function should return
79.Sy USB_SUCCESS .
80Otherwise, it should return the appropriate USB error.
81If uncertain, use
82.Sy USB_FAILURE .
83.Sh SEE ALSO
84.Xr usba_hcdi_device_init 9E ,
85.Xr usba_hcdi_get_device_private 9F ,
86.Xr usba_device 9S ,
87.Xr usba_hcdi_ops 9S
88