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. It may be 40removed 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. It will be called when child 57devices of the root hub are being initialized. A call to this entry 58point will occur before any calls to open a pipe to the child device 59through 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. The HCD may also opt to store private 65data for this device as a result of whatever initialization it 66performed. The data should be stored in the 67.Fa hcd_privatep 68pointer. Data stored this will be accessible to the HCD driver through 69the 70.Xr usba_hcdi_get_device_private 9F 71function. 72.Pp 73The 74.Fn usba_hcdi_device_fini 75entry point is an optional entry point. It will be called when child 76devices of the root hub are being removed. The HCD should perform any 77necessary work with the root controller to finish tearing down the 78device. In addition, if the HCD stored private data it will a pointer to 79it in the 80.Fa hcd_private 81pointer. The HCD driver must release any resources associated with its 82private data. If it does not, the resources will be leaked. 83.Pp 84At the time 85.Fn usba_hcdi_device_fini 86is called, all associated pipes should have been closed through the 87.Xr usba_hcdi_pipe_close 9E 88function. 89.Pp 90The HCD driver is guaranteed that no other entry points will be invoked 91for the USB device 92.Fa usb_device 93while a call to either function is ongoing. However, the entry point may 94be called in parallel on behalf of separate devices. 95.Sh CONTEXT 96This function is called from kernel context only. 97.Sh RETURN VALUES 98Upon successful completion, the 99.Fn usba_hcdi_device_init 100function should return 101.Sy USB_SUCCECSS . 102Otherwise, it should return the appropriate error. 103.Sh SEE ALSO 104.Xr usba_hcd 9E , 105.Xr usba_hcdi_pipe_close 9E , 106.Xr usba_hcdi_pipe_open 9E 107