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 May 7, 2016 15.Dt USBA_HCDI_DEVICE_INIT 9E 16.Os 17.Sh NAME 18.Nm usba_hcdi_device_init , 19.Nm usba_hcdi_device_fini 20.Nd USB device initialization and finalization 21.Sh SYNOPSIS 22.In sys/usb/usba/hcdi.h 23.Ft int 24.Fo prefix_hcdi_device_init 25.Fa "usba_device_t *usb_device" 26.Fa "usb_port_t port" 27.Fa "void **hcd_privatep" 28.Fc 29.Ft void 30.Fo prefix_hcdi_device_fini 31.Fa "usba_device_t *usb_device" 32.Fa "usb_port_t port" 33.Fa "void *hcd_private" 34.Fc 35.Sh INTERFACE LEVEL 36.Sy Volatile - 37illumos USB HCD private function 38.Pp 39This is a private function that is not part of the stable DDI. 40It may be removed or changed at any time. 41.Sh PARAMETERS 42.Bl -tag -width Fa 43.It Fa usb_device 44Pointer to a USB device structure. 45.It Fa port 46The port number the device was detected on. 47.It Fa hcd_privatep 48Pointer to storage space for a HCD driver to store private data for the 49device. 50.It Fa hcd_private 51Pointer to the HCD driver's private data for the device. 52.El 53.Sh DESCRIPTION 54The 55.Fn usba_hcdi_device_init 56entry point is an optional entry point. 57It will be called when child devices of the root hub are being initialized. 58A call to this entry point will occur before any calls to open a pipe to the 59child device through the 60.Xr usba_hcdi_pipe_open 9E 61entry point. 62.Pp 63During this time, the HCD driver should do any required initialization 64required by the host controller. 65The HCD may also opt to store private data for this device as a result of 66whatever initialization it performed. 67The data should be stored in the 68.Fa hcd_privatep 69pointer. 70Data stored this will be accessible to the HCD driver through the 71.Xr usba_hcdi_get_device_private 9F 72function. 73.Pp 74The 75.Fn usba_hcdi_device_fini 76entry point is an optional entry point. 77It will be called when child devices of the root hub are being removed. 78The HCD should perform any necessary work with the root controller to finish 79tearing down the device. 80In addition, if the HCD stored private data it will a pointer to it in the 81.Fa hcd_private 82pointer. 83The HCD driver must release any resources associated with its private data. 84If it does not, the resources will be leaked. 85.Pp 86At the time 87.Fn usba_hcdi_device_fini 88is called, all associated pipes should have been closed through the 89.Xr usba_hcdi_pipe_close 9E 90function. 91.Pp 92The HCD driver is guaranteed that no other entry points will be invoked 93for the USB device 94.Fa usb_device 95while a call to either function is ongoing. 96However, the entry point may be called in parallel on behalf of separate 97devices. 98.Sh CONTEXT 99This function is called from kernel context only. 100.Sh RETURN VALUES 101Upon successful completion, the 102.Fn usba_hcdi_device_init 103function should return 104.Sy USB_SUCCESS . 105Otherwise, it should return the appropriate error. 106.Sh SEE ALSO 107.Xr usba_hcdi 9E , 108.Xr usba_hcdi_pipe_close 9E , 109.Xr usba_hcdi_pipe_open 9E 110