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_BULK_XFER 9E 16.Os 17.Sh NAME 18.Nm usba_hcdi_pipe_bulk_xfer 19.Nd perform a USB bulk transfer 20.Sh SYNOPSIS 21.In sys/usb/usba/hcdi.h 22.Ft int 23.Fo prefix_hcdi_pipe_bulk_xfer 24.Fa "usba_pipe_handle_data_t *ph" 25.Fa "usb_bulk_req_t *ubrp" 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 ubrp 40A pointer to a USB bulk transfer request. 41The structure's members are documented in 42.Xr usb_bulk_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_bulk_xfer 63entry point is used to initiate an 64.Em asynchronous 65USB bulk transfer on the pipe 66.Fa ph . 67The specific USB bulk transfer is provided in 68.Fa ubrp . 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, the driver should return 76.Sy USB_NOT_SUPPORTED . 77.Pp 78Bulk transfers may send data to the device or receive data from the device. 79A given bulk endpoint is uni-directional. 80The direction can be determined from the endpoint address based on the 81.Sy p_ep 82member of 83.Fa ubrp . 84See 85.Xr usb_ep_descr 9S 86for more information on how to determine the direction of the endpoint. 87.Pp 88The device driver should allocate memory, whether memory suitable for a 89DMA transfer or otherwise, to perform the transfer. 90For all memory allocated, it should honor the values in 91.Fa usb_flags 92to determine whether or not it should block for allocations. 93.Pp 94The length of the bulk transfer and its data can be found in the 95.Sy bulk_len 96and 97.Sy bulk_data 98members of 99.Fa ubrp 100respectively. 101The 102.Xr mblk 9S 103structure that should not be used directly and data should be copied to 104or from the data buffer that will go the controller. 105.Pp 106If the driver successfully schedules the I/O, then it should return 107.Sy USB_SUCCESS . 108When the I/O completes, it must call 109.Xr usba_hcdi_cb 9F 110with 111.Fa ubrp . 112If the transfer fails, but the driver returned 113.Sy USB_SUCCESS , 114it still must call 115.Xr usba_hcdi_cb 9F 116and should specify an error there. 117.Pp 118It is the driver's responsibility to time out bulk transfer requests. 119If the timeout in the request as indicated in the 120.Sy bulk_timeout 121member of 122.Fa ubrp 123is set to zero, then the driver should use the USBA default timeout of 124.Sy HCDI_DEFAULT_TIMEOUT . 125All timeout values are in 126.Em seconds . 127.Ss Callback Handling 128When the bulk transfer completes the driver should consider the 129following items to determine what actions it should take on the 130callback: 131.Bl -bullet 132.It 133If the transfer timed out, it should remove the transfer from the 134outstanding list, queue the next transfer, and return the transfer back 135to the OS with the error code 136.Sy USB_CR_TIMEOUT 137with 138.Xr usba_hcdi_cb 9F . 139.It 140If the transfer failed, it should find the appropriate error and call 141.Xr usba_hcdi_cb 9F 142with that error. 143.It 144If the transfer succeeded, but less data was transferred than expected, 145consult the 146.Sy bulk_attributes 147member of the 148.Fa ubrp . 149If the 150.Sy USB_ATTRS_SHORT_XFER_OK 151flag is not present, then the driver should call 152.Xr usba_hcdi_cb 9F 153with the error 154.Sy USB_CR_DATA_UNDERRUN . 155.It 156If the transfer was going to the host, then the driver should copy the 157data into the transfer's message block and update the 158.Sy b_wptr 159member of the 160.Xr mblk 9S . 161.It 162If everything was successful, call 163.Xr usba_hcdi_cb 9F 164with the code 165.Sy USB_CR_OK . 166.El 167.Sh RETURN VALUES 168Upon successful completion, the 169.Fn usba_hcdi_pipe_bulk_xfer 170function should return 171.Sy USB_SUCCESS . 172Otherwise, it should return the appropriate USB error. 173If uncertain, use 174.Sy USB_FAILURE . 175.Sh SEE ALSO 176.Xr usba_hcdi 9E , 177.Xr usba_hcdi_cb 9F , 178.Xr mblk 9S , 179.Xr usb_bulk_req 9S , 180.Xr usb_ep_descr 9S , 181.Xr usba_pipe_handle_data 9S 182