2 * Copyright (c) 2011 Vojtech Horky
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
9 * - Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * - Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 * - The name of the author may not be used to endorse or promote products
15 * derived from this software without specific prior written permission.
17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 /** @addtogroup libusbdev
33 * USB device driver framework - automatic interrupt polling.
36 #include <usb/dev/device.h>
37 #include <usb/dev/pipes.h>
38 #include <usb/dev/poll.h>
39 #include <usb/dev/request.h>
40 #include <usb/classes/classes.h>
41 #include <usb/debug.h>
42 #include <usb/descriptor.h>
51 #include <str_error.h>
55 /** Maximum number of failed consecutive requests before announcing failure. */
56 #define MAX_FAILED_ATTEMPTS 3
58 /** Data needed for polling. */
60 /** Parameters for automated polling. */
61 usb_device_auto_polling_t auto_polling
;
63 /** USB device to poll. */
65 /** Device enpoint mapping to use for polling. */
66 usb_endpoint_mapping_t
*polling_mapping
;
67 /** Size of the recieved data. */
76 * @param arg Pointer to polling_data_t.
79 static errno_t
polling_fibril(void *arg
)
82 polling_data_t
*data
= arg
;
83 /* Helper to reduce typing. */
84 const usb_device_auto_polling_t
*params
= &data
->auto_polling
;
86 usb_pipe_t
*pipe
= &data
->polling_mapping
->pipe
;
88 if (params
->debug
> 0) {
89 const usb_endpoint_mapping_t
*mapping
=
90 data
->polling_mapping
;
91 usb_log_debug("Poll (%p): started polling of `%s' - " \
92 "interface %d (%s,%d,%d), %zuB/%zu.\n",
93 data
, usb_device_get_name(data
->dev
),
94 (int) mapping
->interface
->interface_number
,
95 usb_str_class(mapping
->interface
->interface_class
),
96 (int) mapping
->interface
->interface_subclass
,
97 (int) mapping
->interface
->interface_protocol
,
98 data
->request_size
, pipe
->max_packet_size
);
101 size_t failed_attempts
= 0;
102 while (failed_attempts
<= params
->max_failures
) {
104 const errno_t rc
= usb_pipe_read(pipe
, data
->buffer
,
105 data
->request_size
, &actual_size
);
108 if (params
->debug
> 1) {
110 "Poll%p: received: '%s' (%zuB).\n",
112 usb_debug_str_buffer(data
->buffer
,
118 "Poll%p: polling failed: %s.\n",
119 data
, str_error(rc
));
122 /* If the pipe stalled, we can try to reset the stall. */
123 if ((rc
== ESTALL
) && (params
->auto_clear_halt
)) {
125 * We ignore error here as this is usually a futile
128 usb_request_clear_endpoint_halt(
129 usb_device_get_default_pipe(data
->dev
),
135 const bool cont
= (params
->on_error
== NULL
) ? true :
136 params
->on_error(data
->dev
, rc
, params
->arg
);
138 failed_attempts
= params
->max_failures
;
143 /* We have the data, execute the callback now. */
144 assert(params
->on_data
);
145 const bool carry_on
= params
->on_data(
146 data
->dev
, data
->buffer
, actual_size
, params
->arg
);
149 /* This is user requested abort, erases failures. */
154 /* Reset as something might be only a temporary problem. */
157 /* Take a rest before next request. */
159 // FIXME TODO: This is broken, the time is in ms not us.
160 // but first we need to fix drivers to actually stop using this,
161 // since polling delay should be implemented in HC schedule
162 async_usleep(params
->delay
);
165 const bool failed
= failed_attempts
> 0;
167 if (params
->on_polling_end
!= NULL
) {
168 params
->on_polling_end(data
->dev
, failed
, params
->arg
);
171 if (params
->debug
> 0) {
173 usb_log_error("Polling of device `%s' terminated: "
174 "recurring failures.\n",
175 usb_device_get_name(data
->dev
));
177 usb_log_debug("Polling of device `%s' terminated: "
179 usb_device_get_name(data
->dev
));
183 /* Free the allocated memory. */
191 /** Start automatic device polling over interrupt in pipe.
193 * The polling settings is copied thus it is okay to destroy the structure
194 * after this function returns.
196 * @warning There is no guarantee when the request to the device
197 * will be sent for the first time (it is possible that this
198 * first request would be executed prior to return from this function).
200 * @param dev Device to be periodically polled.
201 * @param epm Endpoint mapping to use.
202 * @param polling Polling settings.
203 * @param request_size How many bytes to ask for in each request.
204 * @param arg Custom argument (passed as is to the callbacks).
205 * @return Error code.
206 * @retval EOK New fibril polling the device was already started.
208 static errno_t
usb_device_auto_polling_internal(usb_device_t
*dev
,
209 usb_endpoint_mapping_t
*epm
, const usb_device_auto_polling_t
*polling
,
212 if ((dev
== NULL
) || (polling
== NULL
) || (polling
->on_data
== NULL
)) {
216 if (request_size
== 0)
219 if (!epm
|| (epm
->pipe
.transfer_type
!= USB_TRANSFER_INTERRUPT
) ||
220 (epm
->pipe
.direction
!= USB_DIRECTION_IN
))
224 polling_data_t
*polling_data
= malloc(sizeof(polling_data_t
));
225 if (polling_data
== NULL
) {
229 /* Fill-in the data. */
230 polling_data
->buffer
= malloc(sizeof(request_size
));
231 if (polling_data
->buffer
== NULL
) {
235 polling_data
->request_size
= request_size
;
236 polling_data
->dev
= dev
;
237 polling_data
->polling_mapping
= epm
;
239 /* Copy provided settings. */
240 polling_data
->auto_polling
= *polling
;
242 /* Negative value means use descriptor provided value. */
243 if (polling
->delay
< 0) {
244 polling_data
->auto_polling
.delay
=
245 epm
->descriptor
->poll_interval
;
248 fid_t fibril
= fibril_create(polling_fibril
, polling_data
);
250 free(polling_data
->buffer
);
254 fibril_add_ready(fibril
);
256 /* Fibril launched. That fibril will free the allocated data. */
260 /** Start automatic device polling over interrupt in pipe.
262 * The polling settings is copied thus it is okay to destroy the structure
263 * after this function returns.
265 * @warning There is no guarantee when the request to the device
266 * will be sent for the first time (it is possible that this
267 * first request would be executed prior to return from this function).
269 * @param dev Device to be periodically polled.
270 * @param pipe_index Index of the endpoint pipe used for polling.
271 * @param polling Polling settings.
272 * @param req_size How many bytes to ask for in each request.
273 * @param arg Custom argument (passed as is to the callbacks).
274 * @return Error code.
275 * @retval EOK New fibril polling the device was already started.
277 errno_t
usb_device_auto_polling(usb_device_t
*usb_dev
, usb_endpoint_t ep
,
278 const usb_device_auto_polling_t
*polling
, size_t req_size
)
280 usb_endpoint_mapping_t
*epm
= usb_device_get_mapped_ep(usb_dev
, ep
);
281 return usb_device_auto_polling_internal(usb_dev
, epm
, polling
, req_size
);
284 /** Start automatic device polling over interrupt in pipe.
286 * @warning It is up to the callback to produce delays between individual
289 * @warning There is no guarantee when the request to the device
290 * will be sent for the first time (it is possible that this
291 * first request would be executed prior to return from this function).
293 * @param dev Device to be periodically polled.
294 * @param ep Endpoint used for polling.
295 * @param callback Callback when data are available.
296 * @param request_size How many bytes to ask for in each request.
297 * @param delay NUmber of ms to wait between queries, -1 to use descriptor val.
298 * @param terminated_callback Callback when polling is terminated.
299 * @param arg Custom argument (passed as is to the callbacks).
300 * @return Error code.
301 * @retval EOK New fibril polling the device was already started.
303 errno_t
usb_device_auto_poll(usb_device_t
*dev
, usb_endpoint_t ep
,
304 usb_polling_callback_t callback
, size_t request_size
, int delay
,
305 usb_polling_terminted_callback_t terminated_callback
, void *arg
)
307 const usb_device_auto_polling_t auto_polling
= {
309 .auto_clear_halt
= true,
311 .max_failures
= MAX_FAILED_ATTEMPTS
,
313 .on_polling_end
= terminated_callback
,
318 usb_endpoint_mapping_t
*epm
= usb_device_get_mapped_ep(dev
, ep
);
319 return usb_device_auto_polling_internal(
320 dev
, epm
, &auto_polling
, request_size
);
323 errno_t
usb_device_auto_polling_desc(usb_device_t
*usb_dev
,
324 const usb_endpoint_description_t
*desc
,
325 const usb_device_auto_polling_t
*polling
, size_t req_size
)
327 usb_endpoint_mapping_t
*epm
=
328 usb_device_get_mapped_ep_desc(usb_dev
, desc
);
329 return usb_device_auto_polling_internal(usb_dev
, epm
, polling
, req_size
);
332 errno_t
usb_device_auto_poll_desc(usb_device_t
* usb_dev
,
333 const usb_endpoint_description_t
*desc
, usb_polling_callback_t callback
,
334 size_t req_size
, int delay
,
335 usb_polling_terminted_callback_t terminated_callback
, void *arg
)
337 const usb_device_auto_polling_t auto_polling
= {
339 .auto_clear_halt
= true,
341 .max_failures
= MAX_FAILED_ATTEMPTS
,
343 .on_polling_end
= terminated_callback
,
348 usb_endpoint_mapping_t
*epm
=
349 usb_device_get_mapped_ep_desc(usb_dev
, desc
);
350 return usb_device_auto_polling_internal(
351 usb_dev
, epm
, &auto_polling
, req_size
);