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 Dec 22, 2016 15.Dt USBA_HCDI_PIPE_CTRL_XFER 9E 16.Os 17.Sh NAME 18.Nm usba_hcdi_pipe_ctrl_xfer 19.Nd perform a USB control transfer 20.Sh SYNOPSIS 21.In sys/usb/usba/hcdi.h 22.Ft int 23.Fo prefix_hcdi_pipe_ctrl_xfer 24.Fa "usba_pipe_handle_data_t *ph" 25.Fa "usb_ctrl_req_t *ucrp" 26.Fa "usb_flags_t usb_flags" 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 a USB pipe handle as defined in 38.Xr usba_pipe_handle_data 9S . 39.It Fa ucrp 40A pointer to a USB control transfer request. The structure's members are 41documented in 42.Xr usb_ctrl_req 9S . 43.It Fa usb_flags 44Flags which describe how allocations should be performed. Valid flags 45are: 46.Bl -tag -width Sy 47.It Sy USB_FLAGS_NOSLEEP 48Do not block waiting for memory. If memory is not available the allocation 49will fail. 50.It Sy USB_FLAGS_SLEEP 51Perform a blocking allocation. If memory is not available, the function 52will wait until memory is made available. 53.Pp 54Note, the request may still fail even if 55.Sy USB_FLAGS_SLEEP 56is specified. 57.El 58.El 59.Sh DESCRIPTION 60The 61.Fn usba_hcdi_pipe_ctrl_xfer 62entry point is used to initiate an 63.Em asynchronous 64USB Control transfer on the pipe 65.Fa ph . 66The specific USB control transfer is provided in 67.Fa ucrp . 68For more background on transfer types, see 69.Xr usba_hcdi 9E . 70.Pp 71The host controller driver should first check the USB address of the 72pipe handle. It may correspond to the root hub. If it does, rather than 73initiating an I/O transfer, the driver may need to emulate it using 74available information. 75.Pp 76Control endpoints are always bi-directional. A given endpoint may 77perform transfer data from the OS to the device, or from the device to 78the OS. The driver will need to look at the control transfer request and 79transform that into the appropriate format for the controller. 80.Pp 81Control transfers are made up of three parts. A setup stage, an optional 82data stage, and a status stage. Depending on the controller, the driver 83may need to transform the transfer request into a format that matches 84this. Refer to the device's controller specification for more 85information on whether this is required or not. 86.Pp 87The device driver should a request based on the information present in 88the control request 89.Fa ucrp . 90If there is a non-zero length for the transfer, indicated by the 91.Sy ctrl_wLength 92member of 93.Fa ucrp 94being greater than zero, then the controller needs to allocate a 95separate memory buffer for the request. The corresponding data will be 96found in an 97.Xr mblk 9S 98structure as the 99.Sy ctrl_data 100member of 101.Fa ucrp . 102.Pp 103If this transfer needs to be sent to a device through the controller and 104is not being handled directly by the driver, then the driver should 105allocate a separate region of memory (generally memory suitable for a 106DMA transfer) for the transfer. If sending data to the device, the data 107in the message block should be copied prior to the transfer. Otherwise, 108once the transfer completes, data should be transferred into the message 109block and the write pointer incremented. 110.Pp 111If the driver needs to allocate memory for this transfer, it should 112honor the values set in 113.Fa usb_flags 114to indicate whether or not it should block for memory, whether DMA 115memory or normal kernel memory. 116.Pp 117If the driver successfully schedules the I/O or it can handle the I/O 118itself because it's a synthetic root hub request, then it should return 119.Sy USB_SUCCESS . 120If the driver returns successfully, it must call 121.Xr usba_hcdi_cb 9F 122with 123.Fa ucrp 124either before or after it returns. The only times that a driver would 125call the callback before the function returns are for requests to the 126root hub that it handles inline and does not need to send off 127asynchronous activity to the controller. 128.Pp 129For asynchronous requests, the controller is also responsible for 130timing out the request if it does not complete. If the timeout in the 131request as indicated in the 132.Sy ctrl_timeout 133member is set to zero, then the driver should use the USBA default 134timeout of 135.Sy HCDI_DEFAULT_TIMEOUT . 136All timeout values are in 137.Em seconds . 138.Ss Callback Handling 139When the control transfer completes the driver should consider the 140following items to determine what actions it should take on the callback: 141.Bl -bullet 142.It 143If the transfer timed out, it should remove the transfer from the 144outstanding list, queue the next transfer, and return the transfer back 145to the OS with the error code 146.Sy USB_CR_TIMEOUT 147with 148.Xr usba_hcdi_cb 9F . 149.It 150If the transfer failed, it should find the appropriate error and call 151.Xr usba_hcdi_cb 9F 152with that error. 153.It 154If the transfer succeeded, but less data was transferred than expected, 155consult the 156.Sy ctrl_attributes 157member of the 158.Fa ucrp . 159If the 160.Sy USB_ATTRS_SHORT_XFER_OK 161flag is not present, then the driver should call 162.Xr usba_hcdi_cb 9F 163with the error 164.Sy USB_CR_DATA_UNDERRUN . 165.It 166If the transfer was going to the host, then the driver should copy the 167data into the transfer's message block and update the 168.Sy b_wptr 169member of the 170.Xr mblk 9S . 171.It 172If everything was successful, call 173.Xr usba_hcdi_cb 9F 174with the code 175.Sy USB_CR_OK . 176.El 177.Sh RETURN VALUES 178Upon successful completion, the 179.Fn usba_hcdi_pipe_ctrl_xfer 180function should return 181.Sy USB_SUCCESS . 182Otherwise, it should return the appropriate USB error. If uncertain, use 183.Sy USB_FAILURE . 184.Sh SEE ALSO 185.Xr usba_hcdi 9E , 186.Xr usba_hcdi_cb 9F , 187.Xr mblk 9S , 188.Xr usb_ctrl_req 9S , 189.Xr usba_pipe_handle_data 9S 190