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