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 Nov 26, 2017 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. 33It may be removed 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 9E 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. 67For more information 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. 74See 75.Xr usba_hcdi_pipe_open 9E 76and 77.Xr usba_hcdi 9E 78for more information. 79.Pp 80The 81.Fa req 82argument is one of the four request structures, 83.Xr usb_bulk_req 9S , 84.Xr usb_ctrl_req 9S , 85.Xr usb_intr_req 9S , 86or 87.Xr usb_isoc_req 9S , 88which have been cast to the type 89.Ft usb_opaque_t . 90The caller should ensure that all appropriate members of the request 91structure have been filled in. 92For example, if expecting data from the device and the request has completed 93successfully, then that data should be copied into the request structure's 94.Xr mblk 9S 95prior to handing the request structure to the 96.Fn usb_hcdi_cb 97function. 98Similarly, the 99.Xr usb_isoc_req 9S 100structure's 101.Sy isoc_pkt_descr 102member should be filled in with the appropriate data. 103.Pp 104Once the request structure has been passed to the 105.Fn usba_hcdi_cb 106function, the HCD driver must not access the structure ever again. 107It should be treated as freed memory. 108.Pp 109The 110.Fa cr 111argument us used to indicate whether the transfer was successful or not. 112If 113.Fa cr 114is set to 115.Sy USB_CR_OK 116that indicates that the transfer completed successfully. 117This should also be used when a permitted short transfer has occurred. 118Otherwise, it should be set to one of the completion reasons. 119.Ss Locking 120The HCD driver should not hold its own internal locks across a call to 121the 122.Fn usba_hcdi_cb 123function. 124It is possible that the driver will have once of its 125.Xr usba_hcdi 9E 126entry points called based on the return value specified. 127.Sh CONTEXT 128The 129.Fn usba_hcdi_cb 130function may be called from 131.Sy user , 132.Sy kernel , 133or 134.Sy interrupt 135context. 136.Sh SEE ALSO 137.Xr usba_hcdi 9E , 138.Xr usba_hcdi_pipe_bulk_xfer 9E , 139.Xr usba_hcdi_pipe_ctrl_xfer 9E , 140.Xr usba_hcdi_pipe_intr_xfer 9E , 141.Xr usba_hcdi_pipe_isoc_xfer 9E , 142.Xr usba_hcdi_pipe_open 9E , 143.Xr mblk 9S , 144.Xr usb_bulk_req 9S , 145.Xr usb_ctrl_req 9S , 146.Xr usb_intr_req 9S , 147.Xr usb_isoc_req 9S 148