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