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_ISOC_XFER 9E 16.Os 17.Sh NAME 18.Nm usba_hcdi_pipe_isoc_xfer 19.Nd perform a USB isochronous transfer 20.Sh SYNOPSIS 21.In sys/usb/usba/hcdi.h 22.Ft int 23.Fo prefix_hcdi_pipe_isoc_xfer 24.Fa "usba_pipe_handle_data_t *ph" 25.Fa "usb_isoc_req_t *usrp" 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 usrp 40A pointer to a USB isochronous transfer request. The structure's members 41are documented in 42.Xr usb_isoc_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_isoc_xfer 62entry point is used to initiate an 63.Em asynchronous 64USB isochronous transfer on the pipe 65.Fa ph . 66The specific USB interrupt transfer is provided in 67.Fa uirp . 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 76Isochronous transfers happen once a period. Isochronous transfers may 77just be told to start as son as possible or to line up to a specific 78frame. At this time, nothing in the system uses the later behavior. It 79is reasonable for a new driver to require that the 80.Sy USB_ATTRS_ISOC_XFER_ASAP 81flag be set in the 82.Sy isoc_attributes 83member of the 84.Fa usrp 85argument. In the case where it's not set and the controller driver does 86not support setting the frame, it should return 87.Sy USB_NOT_SUPPORTED . 88.Pp 89Isochronous-IN transfers are 90.Em always periodic . 91Isochronous-OUT transfers are one shot transfers. Periodic transfers 92have slightly different handling and behavior. 93.Pp 94Isochronous transfers may send data to the device or receive data from 95the device. A given isochronous endpoint is uni-directional. The 96direction can be determined from the endpoint address based on the 97.Sy p_ep 98member of 99.Fa ubrp . 100See 101.Xr usb_ep_descr 9S 102for more information on how to determine the direction of the endpoint. 103.Pp 104Isochronous transfers are a little bit different from other transfers. 105While there is still a single 106.Xr mblk 9S 107structure that all the data goes to or from, the transfer may be broken 108up into multiple packets. All of these packets make up a single transfer 109request and each one represents the data that is transferred during a 110single portion of a frame. For the description of them, see 111.Xr usb_isoc_req 9S . 112Because of these data structures, the way that transfers are recorded is 113different and will be discussed later on. 114.Pp 115The device driver should allocate memory, whether memory suitable for a 116DMA transfer or otherwise, to perform the transfer. For all memory 117allocated, it should honor the values in 118.Fa usb_flags 119to determine whether or not it should block for allocations. 120.Pp 121For isochronous-out transfers which are one-shot transfers, the driver 122should verify that the sum of all of the individual packet counts 123matches the message block length of the data. If it does not, then the 124driver should return 125.Sy USB_INVALID_ARGS . 126.Pp 127If the driver successfully schedules the I/O, then it should return 128.Sy USB_SUCCESS . 129When the I/O completes, it must call 130.Xr usba_hcdi_cb 9F 131with 132.Fa usrp . 133If the transfer fails, but the driver returned 134.Sy USB_SUCCESS , 135it still must call 136.Xr usba_hcdi_cb 9F 137and should specify an error there. 138.Pp 139The driver is responsible for timing out all one-shot outgoing requests. 140As there is no timeout member in the isochronous request structure, then 141the timeout should be set to 142.Sy HCDI_DEFAULT_TIMEOUT . 143.Ss Periodic Transfers 144All isochronous-in transfers are periodic transfers. Once a periodic 145transfer is initiated, every time data is received the driver should 146call the 147.Xr usba_hcdi_cb 9F 148function with updated data. 149.Pp 150When a periodic transfer is initiated, many controller drivers will 151allocate multiple transfers up front and schedule them all. Many drivers 152do this to ensure that data isn't lost between servicing the first 153transfer and scheduling the next. The number of such transfers used 154depends on the polling frequency specified in the endpoint descriptor. 155.Pp 156Unless an error occurs, the driver must not use the original isochronous 157request, 158.Fa usrp . 159Instead, it should duplicate the request through the 160.Xr usba_hcdi_dup_isoc_req 9F 161function before calling 162.Xr usba_hcdi_cb 9F . 163.Pp 164The driver should return the original transfer in one of the following 165conditions: 166.Bl -bullet 167.It 168A pipe reset request came in from the 169.Xr usba_hcdi_pipe_rest 9E 170entry point. 171.It 172A request to stop polling came in from the 173.Xr usba_hcdi_pipe_stop_isoc_polling 9E 174entry point. 175.It 176A request to close the pipe came in from the 177.Xr usba_hcdi_pipe_close 9E 178entry point. 179.It 180An out of memory condition occurred. The caller should call 181.Xr usba_hcdi_cb 9F 182with the code 183.Sy USB_CR_NO_RESOURCES . 184.It 185Some other transfer error occurred. 186.El 187.Ss Callback Handling 188When the isochronous transfer completes, the driver should consider the 189following items to determine what actions it should take on the 190callback: 191.Sy USB_SUCCESS . 192Otherwise, it should return the appropriate USB error. If uncertain, use 193.Sy USB_FAILURE . 194.Bl -bullet 195.It 196If the transfer timed out, it should remove the transfer from the 197outstanding list, queue the next transfer, and return the transfer back 198to the OS with the error code 199.Sy USB_CR_TIMEOUT 200with 201.Xr usba_hcdi_cb 9F . 202.It 203If the transfer failed, it should find the appropriate error and call 204.Xr usba_hcdi_cb 9F 205with that error. 206.It 207If the transfer succeeded, but less data was transferred than expected, 208consult the 209.Sy isoc_attributes 210member of the 211.Fa usrp . 212If the 213.Sy USB_ATTRS_SHORT_XFER_OK 214flag is not present, then the driver should call 215.Xr usba_hcdi_cb 9F 216with the error 217.Sy USB_CR_DATA_UNDERRUN . 218.It 219If the transfer was going to the host, then the driver should copy the 220data into the transfer's message block and update the 221.Sy b_wptr 222member of the 223.Xr mblk 9S . 224.It 225The driver should update the 226.Sy isoc_pkt_actual_length 227member of the 228.Sy isoc_pkt_descr 229array of the 230.Xr usb_isoc_req 9S 231structure with the actual transfer amounts. 232.It 233If everything was successful, call 234.Xr usba_hcdi_cb 9F 235with the code 236.Sy USB_CR_OK . 237.It 238If this was a periodic transfer, it should reschedule the transfer. 239.El 240.Sh RETURN VALUES 241Upon successful completion, the 242.Fn usba_hcdi_pipe_isoc_xfer 243function should return 244function should return 245.Sy USB_SUCCESS . 246Otherwise, it should return the appropriate USB error. If uncertain, use 247.Sy USB_FAILURE . 248.Sh SEE ALSO 249.Xr usba_hcdi 9E , 250.Xr usba_hcdi_pipe_close 9E , 251.Xr usba_hcdi_pipe_rest 9E , 252.Xr usba_hcdi_pipe_stop_isoc_polling 9E , 253.Xr usba_hcdi_cb 9F , 254.Xr usba_hcdi_dup_isoc_req 9F , 255.Xr mblk 9S , 256.Xr usb_ep_descr 9S , 257.Xr usb_isoc_req 9S , 258.Xr usba_pipe_handle_data 9S 259