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_INTR_XFER 9E 16.Os 17.Sh NAME 18.Nm usba_hcdi_pipe_intr_xfer 19.Nd perform a USB interrupt transfer 20.Sh SYNOPSIS 21.In sys/usb/usba/hcdi.h 22.Ft int 23.Fo prefix_hcdi_pipe_intr_xfer 24.Fa "usba_pipe_handle_data_t *ph" 25.Fa "usb_intr_req_t *uirp" 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 uirp 40A pointer to a USB interrupt transfer request. The structure's members 41are documented in 42.Xr usb_intr_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_intr_xfer 62entry point is used to initiate an 63.Em asynchronous 64USB interrupt 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, rather than 73initiating an I/O transfer, the driver may need to emulate it. 74.Pp 75Unlike other transfers, interrupt transfers may be periodic. If the 76transfer is meant to be a one-shot, then the 77.Sy USB_ATTRS_ONE_XFER 78flag will be set in the 79.Sy intr_attributes 80member of the 81.Fa uirp 82structure. If the 83.Sy USB_ATTRS_ONE_XFER 84flag is not set, then the transfer begins a periodic transfer. Periodic 85transfers have different handling and behavior. 86.Pp 87Interrupt transfers may send data to the device or receive data from the 88device. A given interrupt endpoint is uni-directional. The direction can 89be determined from the endpoint address based on the 90.Sy p_ep 91member of 92.Fa ubrp . 93See 94.Xr usb_ep_descr 9S 95for more information on how to determine the direction of the endpoint. 96.Pp 97The device driver should allocate memory, whether memory suitable for a 98DMA transfer or otherwise, to perform the transfer. For all memory 99allocated, it should honor the values in 100.Fa usb_flags 101to determine whether or not it should block for allocations. 102.Pp 103The length of the interrupt transfer and its data can be found in the 104.Sy intr_len 105and 106.Sy intr_data 107members of 108.Fa uirp 109respectively. 110 The 111.Xr mblk 9S 112structure that should not be used directly and data should be copied to 113or from the data buffer that will go the controller. 114.Pp 115Unlike bulk and control transfers, the 116.Fa intr_data 117member may not be allocated for interrupt-IN transfers. In such cases, 118the device driver is required to allocate the message block through 119something like 120.Xr allocb 9F 121and assign it to the 122.Sy intr_data 123member. 124.Pp 125If the driver successfully schedules the I/O, then it should return 126.Sy USB_SUCCESS . 127When the I/O completes, it must call 128.Xr usba_hcdi_cb 9F 129with 130.Fa uirp . 131If the transfer fails, but the driver returned 132.Sy USB_SUCCESS , 133it still must call 134.Xr usba_hcdi_cb 9F 135and should specify an error there. 136.Pp 137It is the driver's responsibility to time out one-shot interrupt transfer 138requests. If the timeout in the request as indicated in the 139.Sy intr_timeout 140member of 141.Fa uirp 142is set to zero, then the driver should use the USBA default timeout of 143.Sy HCDI_DEFAULT_TIMEOUT . 144All timeout values are in 145.Em seconds . 146.Ss Periodic Transfers 147When the 148.Sy USB_ATTRS_ONE_XFER 149flag is not present, it indicates that a periodic interrupt transfer is 150being initiated. Once a periodic interrupt transfer is initiated, every 151time data is received the driver should call 152.Xr usba_hcdi_cb 9F 153with the updated data. 154.Pp 155When a periodic transfer is initiated, many controller drivers will 156allocate multiple transfers up front and schedule them all. Many drivers 157do this to ensure that data isn't lost between servicing the first 158transfer and scheduling the next. The number of such transfers used 159depends on the polling frequency specified in the endpoint descriptor. 160.Pp 161Unless an error occurs, the driver must not use the original interrupt 162request, 163.Fa uirp . 164Instead, it should duplicate the request through the 165.Xr usba_hcdi_dup_intr_req 9F 166function before calling 167.Xr usba_hcdi_cb 9F . 168.Pp 169The driver should return the original transfer in one of the following 170conditions: 171.Bl -bullet 172.It 173A pipe reset request came in from the 174.Xr usba_hcdi_pipe_rest 9E 175entry point. 176.It 177A request to stop polling came in from the 178.Xr usba_hcdi_pipe_stop_intr_polling 9E 179entry point. 180.It 181A request to close the pipe came in from the 182.Xr usba_hcdi_pipe_close 9E 183entry point. 184.It 185An out of memory condition occurred. The caller should call 186.Xr usba_hcdi_cb 9F 187with the code 188.Sy USB_CR_NO_RESOURCES . 189.It 190Some other transfer error occurred. 191.El 192.Pp 193If the periodic interrupt transfer is for the root hub, the driver will 194need to emulate the behavior of a hub as specified in the USB 195specification. For more information, see the 196.Sx Root Hub Management 197section in 198.Xr usba_hcdi 9E . 199.Ss Callback Handling 200When the interrupt transfer completes, the driver should consider the 201following items to determine what actions it should take on the 202callback: 203.Sy USB_SUCCESS . 204Otherwise, it should return the appropriate USB error. If uncertain, use 205.Sy USB_FAILURE . 206.Bl -bullet 207.It 208If the transfer timed out, it should remove the transfer from the 209outstanding list, queue the next transfer, and return the transfer back 210to the OS with the error code 211.Sy USB_CR_TIMEOUT 212with 213.Xr usba_hcdi_cb 9F . 214.It 215If the transfer failed, it should find the appropriate error and call 216.Xr usba_hcdi_cb 9F 217with that error. 218.It 219If the transfer succeeded, but less data was transferred than expected, 220consult the 221.Sy intr_attributes 222member of the 223.Fa uirp . 224If the 225.Sy USB_ATTRS_SHORT_XFER_OK 226flag is not present, then the driver should call 227.Xr usba_hcdi_cb 9F 228with the error 229.Sy USB_CR_DATA_UNDERRUN . 230.It 231If the transfer was going to the host, then the driver should copy the 232data into the transfer's message block and update the 233.Sy b_wptr 234member of the 235.Xr mblk 9S . 236.It 237If everything was successful, call 238.Xr usba_hcdi_cb 9F 239with the code 240.Sy USB_CR_OK . 241.It 242If this was a periodic transfer, it should reschedule the transfer. 243.El 244.Sh RETURN VALUES 245Upon successful completion, the 246.Fn usba_hcdi_pipe_intr_xfer 247function should return 248function should return 249.Sy USB_SUCCESS . 250Otherwise, it should return the appropriate USB error. If uncertain, use 251.Sy USB_FAILURE . 252.Sh SEE ALSO 253.Xr usba_hcdi 9E , 254.Xr usba_hcdi_pipe_close 9E , 255.Xr usba_hcdi_pipe_rest 9E , 256.Xr usba_hcdi_pipe_stop_intr_polling 9E , 257.Xr allocb 9F , 258.Xr usba_hcdi_cb 9F , 259.Xr usba_hcdi_dup_intr_req 9F , 260.Xr mblk 9S , 261.Xr usb_ep_descr 9S , 262.Xr usb_intr_req 9S , 263.Xr usba_pipe_handle_data 9S 264