.\"
.\" 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_device_address
.Nd Assign USB address to device
.Sh SYNOPSIS
.In sys/usb/usba/hcdi.h
.Ft int
.Fo prefix_hcdi_device_address
.Fa "usba_device_t *ud"
.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.
.El
.Sh DESCRIPTION
The
.Fn usba_hcdi_device_address
entry point is an optional entry point for USB host controller drivers.
Some USB host controllers do not allow the USB SET_ADDRESS command to be
issued to a device.
Instead, they will be responsible for setting the address in a
controller-specific way.
If the host controller driver requires this behavior, then it must implement
this function.
Otherwise, if the host controller does not require this functionality, it should
set the entry point in the
.Xr usba_hcdi_ops 9S
structure to
.Dv NULL .
.Pp
The USBA will always set an address for the USBA device
.Fa ud
regardless of whether or not this function is implemented.
If the HCD implements this entry point and it needs the addressing information
for whatever reason, then it is the responsibility of the driver to keep
track of it separately.
.Pp
This entry point will be called after the
.Xr usba_hcdi_device_init 9E
entry point has been called.
Any private data stored on the device will be available through the
.Xr usba_hcdi_get_device_private 9F
function.
.Pp
Upon completion of the function, the device is expected to be addressed
and thus able to have endpoints opened and transfers performed on them.
If this function fails, the device's enumeration will halt.
.Sh CONTEXT
This function is called from kernel context ontly.
.Sh RETURN VALUES
Upon successful completion, the
.Fn usba_hcdi_device_address
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_hcdi_get_device_private 9F ,
.Xr usba_device 9S ,
.Xr usba_hcdi_ops 9S