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