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