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 Sep 16, 2016 15.Dt USBA_HCDI_CB 9F 16.Os 17.Sh NAME 18.Nm usba_hcdi_cb 19.Nd USBA transfer callback 20.Sh SYNOPSIS 21.In sys/usb/usba/hcdi.h 22.Ft void 23.Fo usba_hcdi_cb 24.Fa "usba_pipe_handle_data_t *ph" 25.Fa "usb_opaque_t req" 26.Fa "ucb_cr_t cr" 27.Fc 28.Sh INTERFACE LEVEL 29.Sy Volatile - 30illumos USB HCD private function 31.Pp 32This is a private function that is not part of the stable DDI. It may be 33removed or changed at any time. 34.Sh PARAMETERS 35.Bl -tag -width Fa 36.It Fa ph 37A pointer to the USBA pipe handle that was passed to the HCD driver 38during a call to the 39.Xr usba_hcdi_pipe_open 40entry point. 41.It Fa req 42A pointer to the request structure that is being completed. 43.It Fa cr 44The completion code for the request. 45.El 46.Sh DESCRIPTION 47The 48.Fn usba_hcdi_cb 49function is used when the HCD controller has completed processing a USB 50transfer request, whether 51successfully or not. 52.Pp 53The USB transfer will have been initiated by a call to 54.Xr usba_hcdi_pipe_bulk_xfer 9E , 55.Xr usba_hcdi_pipe_ctrl_xfer 9E , 56.Xr usba_hcdi_pipe_intr_xfer 9E , 57or 58.Xr usba_hcdi_pipe_isoc_xfer 9E . 59If the transfer initiated was a periodic transfer (certain Interrupt-IN 60and Isochronous-IN transfers), then there may be more than one callback 61performed over the life of the transfer. 62.Pp 63This function must not be used if the HCD driver returned a value 64other than 65.Sy USB_SUCCESS 66to one of the transfer initialization functions listed above. For more 67information on transfer request handling, see 68.Xr usba_hcdi 9E . 69.Pp 70The 71.Fa ph 72argument corresponds to the USBA framework's pipe handle that was given 73to the HCDI when the pipe was opened. See 74.Xr usba_hcdi_pipe_open 9E 75and 76.Xr usba_hcdi 9E 77for more information. 78.Pp 79The 80.Fa req 81argument is one of the four request structures, 82.Xr usb_bulk_req 9S , 83.Xr usb_ctrl_req 9S , 84.Xr usb_intr_req 9S , 85or 86.Xr usb_isoc_req 9S , 87which have been cast to the type 88.Ft usb_oapque_t . 89The caller should ensure that all appropriate members of the request 90structure have been filled in. For example, if expecting data from the 91device and the request has completed successfully, then that data 92should be copied into the request structure's 93.Xr mblk 9S 94prior to handing the request structure to the 95.Fn usb_hcdi_cb 96function. 97Similarly, the 98.Xr usb_isoc_req 9S 99structure's 100.Sy isoc_pkt_descr 101member should be filled in with the appropriate data. 102.Pp 103Once the request structure has been passed to the 104.Fn usba_hcdi_cb 105function, the HCD driver must not access the structure ever again. It 106should be treated as freed memory. 107.Pp 108The 109.Fa cr 110argument us used to indicate whether the transfer was successful or not. 111If 112.Fa cr 113is set to 114.Sy USB_CR_OK 115that indicates that the transfer completed successfully. This should 116also be used when a permitted short transfer has occurred. Otherwise, it 117should be set to one of the completion reasons. 118.Ss Locking 119The HCD driver should not hold its own internal locks across a call to 120the 121.Fn usba_hcdi_cb 122function. It is possible that the driver will have once of its 123.Xr usba_hcdi 9E 124entry points called based on the return value specified. 125.Sh CONTEXT 126The 127.Fn usba_hcdi_cb 128function may be called from 129.Sy user , 130.Sy kernel , 131or 132.Sy interrupt 133context. 134.Sh SEE ALSO 135.Xr usba_hcdi 9E , 136.Xr usba_hcdi_pipe_bulk_xfer 9E , 137.Xr usba_hcdi_pipe_ctrl_xfer 9E , 138.Xr usba_hcdi_pipe_intr_xfer 9E , 139.Xr usba_hcdi_pipe_isoc_xfer 9E , 140.Xr usba_hcdi_pipe_open 9E , 141.Xr mblk 9S , 142.Xr usb_bulk_req 9S , 143.Xr usb_ctrl_req 9S , 144.Xr usb_intr_req 9S , 145.Xr usb_isoc_req 9S 146