.\"
.\" 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 May 7, 2016
.Dt USBA_HCDI_DEVICE_INIT 9E
.Os
.Sh NAME
.Nm usba_hcdi_device_init ,
.Nm usba_hcdi_device_fini
.Nd USB device initialization and finalization
.Sh SYNOPSIS
.In sys/usb/usba/hcdi.h
.Ft int
.Fo prefix_hcdi_device_init
.Fa "usba_device_t *usb_device"
.Fa "usb_port_t port"
.Fa "void **hcd_privatep"
.Fc
.Ft void
.Fo prefix_hcdi_device_fini
.Fa "usba_device_t *usb_device"
.Fa "usb_port_t port"
.Fa "void *hcd_private"
.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 usb_device
Pointer to a USB device structure.
.It Fa port
The port number the device was detected on.
.It Fa hcd_privatep
Pointer to storage space for a HCD driver to store private data for the
device.
.It Fa hcd_private
Pointer to the HCD driver's private data for the device.
.El
.Sh DESCRIPTION
The
.Fn usba_hcdi_device_init
entry point is an optional entry point.
It will be called when child devices of the root hub are being initialized.
A call to this entry point will occur before any calls to open a pipe to the
child device through the
.Xr usba_hcdi_pipe_open 9E
entry point.
.Pp
During this time, the HCD driver should do any required initialization
required by the host controller.
The HCD may also opt to store private data for this device as a result of
whatever initialization it performed.
The data should be stored in the
.Fa hcd_privatep
pointer.
Data stored this will be accessible to the HCD driver through the
.Xr usba_hcdi_get_device_private 9F
function.
.Pp
The
.Fn usba_hcdi_device_fini
entry point is an optional entry point.
It will be called when child devices of the root hub are being removed.
The HCD should perform any necessary work with the root controller to finish
tearing down the device.
In addition, if the HCD stored private data it will a pointer to it in the
.Fa hcd_private
pointer.
The HCD driver must release any resources associated with its private data.
If it does not, the resources will be leaked.
.Pp
At the time
.Fn usba_hcdi_device_fini
is called, all associated pipes should have been closed through the
.Xr usba_hcdi_pipe_close 9E
function.
.Pp
The HCD driver is guaranteed that no other entry points will be invoked
for the USB device
.Fa usb_device
while a call to either function is ongoing.
However, the entry point may be called in parallel on behalf of separate
devices.
.Sh CONTEXT
This function is called from kernel context only.
.Sh RETURN VALUES
Upon successful completion, the
.Fn usba_hcdi_device_init
function should return
.Sy USB_SUCCESS .
Otherwise, it should return the appropriate error.
.Sh SEE ALSO
.Xr usba_hcdi 9E ,
.Xr usba_hcdi_pipe_close 9E ,
.Xr usba_hcdi_pipe_open 9E