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