io.c revision 5821806d5e7f356e8fa4b058a389a808ea183019
1/* 2 * I/O functions for libusb 3 * Copyright (C) 2007-2009 Daniel Drake <dsd@gentoo.org> 4 * Copyright (c) 2001 Johannes Erdfelt <johannes@erdfelt.com> 5 * 6 * This library is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Lesser General Public 8 * License as published by the Free Software Foundation; either 9 * version 2.1 of the License, or (at your option) any later version. 10 * 11 * This library is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Lesser General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public 17 * License along with this library; if not, write to the Free Software 18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 19 */ 20 21#include <config.h> 22#include <errno.h> 23#include <signal.h> 24#include <stdint.h> 25#include <stdlib.h> 26#include <string.h> 27#include <time.h> 28 29#ifdef HAVE_SYS_TIME_H 30#include <sys/time.h> 31#endif 32 33#ifdef USBI_TIMERFD_AVAILABLE 34#include <sys/timerfd.h> 35#endif 36 37#include "libusbi.h" 38 39/** 40 * \page io Synchronous and asynchronous device I/O 41 * 42 * \section intro Introduction 43 * 44 * If you're using libusb in your application, you're probably wanting to 45 * perform I/O with devices - you want to perform USB data transfers. 46 * 47 * libusb offers two separate interfaces for device I/O. This page aims to 48 * introduce the two in order to help you decide which one is more suitable 49 * for your application. You can also choose to use both interfaces in your 50 * application by considering each transfer on a case-by-case basis. 51 * 52 * Once you have read through the following discussion, you should consult the 53 * detailed API documentation pages for the details: 54 * - \ref syncio 55 * - \ref asyncio 56 * 57 * \section theory Transfers at a logical level 58 * 59 * At a logical level, USB transfers typically happen in two parts. For 60 * example, when reading data from a endpoint: 61 * -# A request for data is sent to the device 62 * -# Some time later, the incoming data is received by the host 63 * 64 * or when writing data to an endpoint: 65 * 66 * -# The data is sent to the device 67 * -# Some time later, the host receives acknowledgement from the device that 68 * the data has been transferred. 69 * 70 * There may be an indefinite delay between the two steps. Consider a 71 * fictional USB input device with a button that the user can press. In order 72 * to determine when the button is pressed, you would likely submit a request 73 * to read data on a bulk or interrupt endpoint and wait for data to arrive. 74 * Data will arrive when the button is pressed by the user, which is 75 * potentially hours later. 76 * 77 * libusb offers both a synchronous and an asynchronous interface to performing 78 * USB transfers. The main difference is that the synchronous interface 79 * combines both steps indicated above into a single function call, whereas 80 * the asynchronous interface separates them. 81 * 82 * \section sync The synchronous interface 83 * 84 * The synchronous I/O interface allows you to perform a USB transfer with 85 * a single function call. When the function call returns, the transfer has 86 * completed and you can parse the results. 87 * 88 * If you have used the libusb-0.1 before, this I/O style will seem familar to 89 * you. libusb-0.1 only offered a synchronous interface. 90 * 91 * In our input device example, to read button presses you might write code 92 * in the following style: 93\code 94unsigned char data[4]; 95int actual_length; 96int r = libusb_bulk_transfer(handle, LIBUSB_ENDPOINT_IN, data, sizeof(data), &actual_length, 0); 97if (r == 0 && actual_length == sizeof(data)) { 98 // results of the transaction can now be found in the data buffer 99 // parse them here and report button press 100} else { 101 error(); 102} 103\endcode 104 * 105 * The main advantage of this model is simplicity: you did everything with 106 * a single simple function call. 107 * 108 * However, this interface has its limitations. Your application will sleep 109 * inside libusb_bulk_transfer() until the transaction has completed. If it 110 * takes the user 3 hours to press the button, your application will be 111 * sleeping for that long. Execution will be tied up inside the library - 112 * the entire thread will be useless for that duration. 113 * 114 * Another issue is that by tieing up the thread with that single transaction 115 * there is no possibility of performing I/O with multiple endpoints and/or 116 * multiple devices simultaneously, unless you resort to creating one thread 117 * per transaction. 118 * 119 * Additionally, there is no opportunity to cancel the transfer after the 120 * request has been submitted. 121 * 122 * For details on how to use the synchronous API, see the 123 * \ref syncio "synchronous I/O API documentation" pages. 124 * 125 * \section async The asynchronous interface 126 * 127 * Asynchronous I/O is the most significant new feature in libusb-1.0. 128 * Although it is a more complex interface, it solves all the issues detailed 129 * above. 130 * 131 * Instead of providing which functions that block until the I/O has complete, 132 * libusb's asynchronous interface presents non-blocking functions which 133 * begin a transfer and then return immediately. Your application passes a 134 * callback function pointer to this non-blocking function, which libusb will 135 * call with the results of the transaction when it has completed. 136 * 137 * Transfers which have been submitted through the non-blocking functions 138 * can be cancelled with a separate function call. 139 * 140 * The non-blocking nature of this interface allows you to be simultaneously 141 * performing I/O to multiple endpoints on multiple devices, without having 142 * to use threads. 143 * 144 * This added flexibility does come with some complications though: 145 * - In the interest of being a lightweight library, libusb does not create 146 * threads and can only operate when your application is calling into it. Your 147 * application must call into libusb from it's main loop when events are ready 148 * to be handled, or you must use some other scheme to allow libusb to 149 * undertake whatever work needs to be done. 150 * - libusb also needs to be called into at certain fixed points in time in 151 * order to accurately handle transfer timeouts. 152 * - Memory handling becomes more complex. You cannot use stack memory unless 153 * the function with that stack is guaranteed not to return until the transfer 154 * callback has finished executing. 155 * - You generally lose some linearity from your code flow because submitting 156 * the transfer request is done in a separate function from where the transfer 157 * results are handled. This becomes particularly obvious when you want to 158 * submit a second transfer based on the results of an earlier transfer. 159 * 160 * Internally, libusb's synchronous interface is expressed in terms of function 161 * calls to the asynchronous interface. 162 * 163 * For details on how to use the asynchronous API, see the 164 * \ref asyncio "asynchronous I/O API" documentation pages. 165 */ 166 167 168/** 169 * \page packetoverflow Packets and overflows 170 * 171 * \section packets Packet abstraction 172 * 173 * The USB specifications describe how data is transmitted in packets, with 174 * constraints on packet size defined by endpoint descriptors. The host must 175 * not send data payloads larger than the endpoint's maximum packet size. 176 * 177 * libusb and the underlying OS abstract out the packet concept, allowing you 178 * to request transfers of any size. Internally, the request will be divided 179 * up into correctly-sized packets. You do not have to be concerned with 180 * packet sizes, but there is one exception when considering overflows. 181 * 182 * \section overflow Bulk/interrupt transfer overflows 183 * 184 * When requesting data on a bulk endpoint, libusb requires you to supply a 185 * buffer and the maximum number of bytes of data that libusb can put in that 186 * buffer. However, the size of the buffer is not communicated to the device - 187 * the device is just asked to send any amount of data. 188 * 189 * There is no problem if the device sends an amount of data that is less than 190 * or equal to the buffer size. libusb reports this condition to you through 191 * the \ref libusb_transfer::actual_length "libusb_transfer.actual_length" 192 * field. 193 * 194 * Problems may occur if the device attempts to send more data than can fit in 195 * the buffer. libusb reports LIBUSB_TRANSFER_OVERFLOW for this condition but 196 * other behaviour is largely undefined: actual_length may or may not be 197 * accurate, the chunk of data that can fit in the buffer (before overflow) 198 * may or may not have been transferred. 199 * 200 * Overflows are nasty, but can be avoided. Even though you were told to 201 * ignore packets above, think about the lower level details: each transfer is 202 * split into packets (typically small, with a maximum size of 512 bytes). 203 * Overflows can only happen if the final packet in an incoming data transfer 204 * is smaller than the actual packet that the device wants to transfer. 205 * Therefore, you will never see an overflow if your transfer buffer size is a 206 * multiple of the endpoint's packet size: the final packet will either 207 * fill up completely or will be only partially filled. 208 */ 209 210/** 211 * @defgroup asyncio Asynchronous device I/O 212 * 213 * This page details libusb's asynchronous (non-blocking) API for USB device 214 * I/O. This interface is very powerful but is also quite complex - you will 215 * need to read this page carefully to understand the necessary considerations 216 * and issues surrounding use of this interface. Simplistic applications 217 * may wish to consider the \ref syncio "synchronous I/O API" instead. 218 * 219 * The asynchronous interface is built around the idea of separating transfer 220 * submission and handling of transfer completion (the synchronous model 221 * combines both of these into one). There may be a long delay between 222 * submission and completion, however the asynchronous submission function 223 * is non-blocking so will return control to your application during that 224 * potentially long delay. 225 * 226 * \section asyncabstraction Transfer abstraction 227 * 228 * For the asynchronous I/O, libusb implements the concept of a generic 229 * transfer entity for all types of I/O (control, bulk, interrupt, 230 * isochronous). The generic transfer object must be treated slightly 231 * differently depending on which type of I/O you are performing with it. 232 * 233 * This is represented by the public libusb_transfer structure type. 234 * 235 * \section asynctrf Asynchronous transfers 236 * 237 * We can view asynchronous I/O as a 5 step process: 238 * -# <b>Allocation</b>: allocate a libusb_transfer 239 * -# <b>Filling</b>: populate the libusb_transfer instance with information 240 * about the transfer you wish to perform 241 * -# <b>Submission</b>: ask libusb to submit the transfer 242 * -# <b>Completion handling</b>: examine transfer results in the 243 * libusb_transfer structure 244 * -# <b>Deallocation</b>: clean up resources 245 * 246 * 247 * \subsection asyncalloc Allocation 248 * 249 * This step involves allocating memory for a USB transfer. This is the 250 * generic transfer object mentioned above. At this stage, the transfer 251 * is "blank" with no details about what type of I/O it will be used for. 252 * 253 * Allocation is done with the libusb_alloc_transfer() function. You must use 254 * this function rather than allocating your own transfers. 255 * 256 * \subsection asyncfill Filling 257 * 258 * This step is where you take a previously allocated transfer and fill it 259 * with information to determine the message type and direction, data buffer, 260 * callback function, etc. 261 * 262 * You can either fill the required fields yourself or you can use the 263 * helper functions: libusb_fill_control_transfer(), libusb_fill_bulk_transfer() 264 * and libusb_fill_interrupt_transfer(). 265 * 266 * \subsection asyncsubmit Submission 267 * 268 * When you have allocated a transfer and filled it, you can submit it using 269 * libusb_submit_transfer(). This function returns immediately but can be 270 * regarded as firing off the I/O request in the background. 271 * 272 * \subsection asynccomplete Completion handling 273 * 274 * After a transfer has been submitted, one of four things can happen to it: 275 * 276 * - The transfer completes (i.e. some data was transferred) 277 * - The transfer has a timeout and the timeout expires before all data is 278 * transferred 279 * - The transfer fails due to an error 280 * - The transfer is cancelled 281 * 282 * Each of these will cause the user-specified transfer callback function to 283 * be invoked. It is up to the callback function to determine which of the 284 * above actually happened and to act accordingly. 285 * 286 * The user-specified callback is passed a pointer to the libusb_transfer 287 * structure which was used to setup and submit the transfer. At completion 288 * time, libusb has populated this structure with results of the transfer: 289 * success or failure reason, number of bytes of data transferred, etc. See 290 * the libusb_transfer structure documentation for more information. 291 * 292 * \subsection Deallocation 293 * 294 * When a transfer has completed (i.e. the callback function has been invoked), 295 * you are advised to free the transfer (unless you wish to resubmit it, see 296 * below). Transfers are deallocated with libusb_free_transfer(). 297 * 298 * It is undefined behaviour to free a transfer which has not completed. 299 * 300 * \section asyncresubmit Resubmission 301 * 302 * You may be wondering why allocation, filling, and submission are all 303 * separated above where they could reasonably be combined into a single 304 * operation. 305 * 306 * The reason for separation is to allow you to resubmit transfers without 307 * having to allocate new ones every time. This is especially useful for 308 * common situations dealing with interrupt endpoints - you allocate one 309 * transfer, fill and submit it, and when it returns with results you just 310 * resubmit it for the next interrupt. 311 * 312 * \section asynccancel Cancellation 313 * 314 * Another advantage of using the asynchronous interface is that you have 315 * the ability to cancel transfers which have not yet completed. This is 316 * done by calling the libusb_cancel_transfer() function. 317 * 318 * libusb_cancel_transfer() is asynchronous/non-blocking in itself. When the 319 * cancellation actually completes, the transfer's callback function will 320 * be invoked, and the callback function should check the transfer status to 321 * determine that it was cancelled. 322 * 323 * Freeing the transfer after it has been cancelled but before cancellation 324 * has completed will result in undefined behaviour. 325 * 326 * When a transfer is cancelled, some of the data may have been transferred. 327 * libusb will communicate this to you in the transfer callback. Do not assume 328 * that no data was transferred. 329 * 330 * \section bulk_overflows Overflows on device-to-host bulk/interrupt endpoints 331 * 332 * If your device does not have predictable transfer sizes (or it misbehaves), 333 * your application may submit a request for data on an IN endpoint which is 334 * smaller than the data that the device wishes to send. In some circumstances 335 * this will cause an overflow, which is a nasty condition to deal with. See 336 * the \ref packetoverflow page for discussion. 337 * 338 * \section asyncctrl Considerations for control transfers 339 * 340 * The <tt>libusb_transfer</tt> structure is generic and hence does not 341 * include specific fields for the control-specific setup packet structure. 342 * 343 * In order to perform a control transfer, you must place the 8-byte setup 344 * packet at the start of the data buffer. To simplify this, you could 345 * cast the buffer pointer to type struct libusb_control_setup, or you can 346 * use the helper function libusb_fill_control_setup(). 347 * 348 * The wLength field placed in the setup packet must be the length you would 349 * expect to be sent in the setup packet: the length of the payload that 350 * follows (or the expected maximum number of bytes to receive). However, 351 * the length field of the libusb_transfer object must be the length of 352 * the data buffer - i.e. it should be wLength <em>plus</em> the size of 353 * the setup packet (LIBUSB_CONTROL_SETUP_SIZE). 354 * 355 * If you use the helper functions, this is simplified for you: 356 * -# Allocate a buffer of size LIBUSB_CONTROL_SETUP_SIZE plus the size of the 357 * data you are sending/requesting. 358 * -# Call libusb_fill_control_setup() on the data buffer, using the transfer 359 * request size as the wLength value (i.e. do not include the extra space you 360 * allocated for the control setup). 361 * -# If this is a host-to-device transfer, place the data to be transferred 362 * in the data buffer, starting at offset LIBUSB_CONTROL_SETUP_SIZE. 363 * -# Call libusb_fill_control_transfer() to associate the data buffer with 364 * the transfer (and to set the remaining details such as callback and timeout). 365 * - Note that there is no parameter to set the length field of the transfer. 366 * The length is automatically inferred from the wLength field of the setup 367 * packet. 368 * -# Submit the transfer. 369 * 370 * The multi-byte control setup fields (wValue, wIndex and wLength) must 371 * be given in little-endian byte order (the endianness of the USB bus). 372 * Endianness conversion is transparently handled by 373 * libusb_fill_control_setup() which is documented to accept host-endian 374 * values. 375 * 376 * Further considerations are needed when handling transfer completion in 377 * your callback function: 378 * - As you might expect, the setup packet will still be sitting at the start 379 * of the data buffer. 380 * - If this was a device-to-host transfer, the received data will be sitting 381 * at offset LIBUSB_CONTROL_SETUP_SIZE into the buffer. 382 * - The actual_length field of the transfer structure is relative to the 383 * wLength of the setup packet, rather than the size of the data buffer. So, 384 * if your wLength was 4, your transfer's <tt>length</tt> was 12, then you 385 * should expect an <tt>actual_length</tt> of 4 to indicate that the data was 386 * transferred in entirity. 387 * 388 * To simplify parsing of setup packets and obtaining the data from the 389 * correct offset, you may wish to use the libusb_control_transfer_get_data() 390 * and libusb_control_transfer_get_setup() functions within your transfer 391 * callback. 392 * 393 * Even though control endpoints do not halt, a completed control transfer 394 * may have a LIBUSB_TRANSFER_STALL status code. This indicates the control 395 * request was not supported. 396 * 397 * \section asyncintr Considerations for interrupt transfers 398 * 399 * All interrupt transfers are performed using the polling interval presented 400 * by the bInterval value of the endpoint descriptor. 401 * 402 * \section asynciso Considerations for isochronous transfers 403 * 404 * Isochronous transfers are more complicated than transfers to 405 * non-isochronous endpoints. 406 * 407 * To perform I/O to an isochronous endpoint, allocate the transfer by calling 408 * libusb_alloc_transfer() with an appropriate number of isochronous packets. 409 * 410 * During filling, set \ref libusb_transfer::type "type" to 411 * \ref libusb_transfer_type::LIBUSB_TRANSFER_TYPE_ISOCHRONOUS 412 * "LIBUSB_TRANSFER_TYPE_ISOCHRONOUS", and set 413 * \ref libusb_transfer::num_iso_packets "num_iso_packets" to a value less than 414 * or equal to the number of packets you requested during allocation. 415 * libusb_alloc_transfer() does not set either of these fields for you, given 416 * that you might not even use the transfer on an isochronous endpoint. 417 * 418 * Next, populate the length field for the first num_iso_packets entries in 419 * the \ref libusb_transfer::iso_packet_desc "iso_packet_desc" array. Section 420 * 5.6.3 of the USB2 specifications describe how the maximum isochronous 421 * packet length is determined by the wMaxPacketSize field in the endpoint 422 * descriptor. 423 * Two functions can help you here: 424 * 425 * - libusb_get_max_iso_packet_size() is an easy way to determine the max 426 * packet size for an isochronous endpoint. Note that the maximum packet 427 * size is actually the maximum number of bytes that can be transmitted in 428 * a single microframe, therefore this function multiplies the maximum number 429 * of bytes per transaction by the number of transaction opportunities per 430 * microframe. 431 * - libusb_set_iso_packet_lengths() assigns the same length to all packets 432 * within a transfer, which is usually what you want. 433 * 434 * For outgoing transfers, you'll obviously fill the buffer and populate the 435 * packet descriptors in hope that all the data gets transferred. For incoming 436 * transfers, you must ensure the buffer has sufficient capacity for 437 * the situation where all packets transfer the full amount of requested data. 438 * 439 * Completion handling requires some extra consideration. The 440 * \ref libusb_transfer::actual_length "actual_length" field of the transfer 441 * is meaningless and should not be examined; instead you must refer to the 442 * \ref libusb_iso_packet_descriptor::actual_length "actual_length" field of 443 * each individual packet. 444 * 445 * The \ref libusb_transfer::status "status" field of the transfer is also a 446 * little misleading: 447 * - If the packets were submitted and the isochronous data microframes 448 * completed normally, status will have value 449 * \ref libusb_transfer_status::LIBUSB_TRANSFER_COMPLETED 450 * "LIBUSB_TRANSFER_COMPLETED". Note that bus errors and software-incurred 451 * delays are not counted as transfer errors; the transfer.status field may 452 * indicate COMPLETED even if some or all of the packets failed. Refer to 453 * the \ref libusb_iso_packet_descriptor::status "status" field of each 454 * individual packet to determine packet failures. 455 * - The status field will have value 456 * \ref libusb_transfer_status::LIBUSB_TRANSFER_ERROR 457 * "LIBUSB_TRANSFER_ERROR" only when serious errors were encountered. 458 * - Other transfer status codes occur with normal behaviour. 459 * 460 * The data for each packet will be found at an offset into the buffer that 461 * can be calculated as if each prior packet completed in full. The 462 * libusb_get_iso_packet_buffer() and libusb_get_iso_packet_buffer_simple() 463 * functions may help you here. 464 * 465 * \section asyncmem Memory caveats 466 * 467 * In most circumstances, it is not safe to use stack memory for transfer 468 * buffers. This is because the function that fired off the asynchronous 469 * transfer may return before libusb has finished using the buffer, and when 470 * the function returns it's stack gets destroyed. This is true for both 471 * host-to-device and device-to-host transfers. 472 * 473 * The only case in which it is safe to use stack memory is where you can 474 * guarantee that the function owning the stack space for the buffer does not 475 * return until after the transfer's callback function has completed. In every 476 * other case, you need to use heap memory instead. 477 * 478 * \section asyncflags Fine control 479 * 480 * Through using this asynchronous interface, you may find yourself repeating 481 * a few simple operations many times. You can apply a bitwise OR of certain 482 * flags to a transfer to simplify certain things: 483 * - \ref libusb_transfer_flags::LIBUSB_TRANSFER_SHORT_NOT_OK 484 * "LIBUSB_TRANSFER_SHORT_NOT_OK" results in transfers which transferred 485 * less than the requested amount of data being marked with status 486 * \ref libusb_transfer_status::LIBUSB_TRANSFER_ERROR "LIBUSB_TRANSFER_ERROR" 487 * (they would normally be regarded as COMPLETED) 488 * - \ref libusb_transfer_flags::LIBUSB_TRANSFER_FREE_BUFFER 489 * "LIBUSB_TRANSFER_FREE_BUFFER" allows you to ask libusb to free the transfer 490 * buffer when freeing the transfer. 491 * - \ref libusb_transfer_flags::LIBUSB_TRANSFER_FREE_TRANSFER 492 * "LIBUSB_TRANSFER_FREE_TRANSFER" causes libusb to automatically free the 493 * transfer after the transfer callback returns. 494 * 495 * \section asyncevent Event handling 496 * 497 * In accordance of the aim of being a lightweight library, libusb does not 498 * create threads internally. This means that libusb code does not execute 499 * at any time other than when your application is calling a libusb function. 500 * However, an asynchronous model requires that libusb perform work at various 501 * points in time - namely processing the results of previously-submitted 502 * transfers and invoking the user-supplied callback function. 503 * 504 * This gives rise to the libusb_handle_events() function which your 505 * application must call into when libusb has work do to. This gives libusb 506 * the opportunity to reap pending transfers, invoke callbacks, etc. 507 * 508 * The first issue to discuss here is how your application can figure out 509 * when libusb has work to do. In fact, there are two naive options which 510 * do not actually require your application to know this: 511 * -# Periodically call libusb_handle_events() in non-blocking mode at fixed 512 * short intervals from your main loop 513 * -# Repeatedly call libusb_handle_events() in blocking mode from a dedicated 514 * thread. 515 * 516 * The first option is plainly not very nice, and will cause unnecessary 517 * CPU wakeups leading to increased power usage and decreased battery life. 518 * The second option is not very nice either, but may be the nicest option 519 * available to you if the "proper" approach can not be applied to your 520 * application (read on...). 521 * 522 * The recommended option is to integrate libusb with your application main 523 * event loop. libusb exposes a set of file descriptors which allow you to do 524 * this. Your main loop is probably already calling poll() or select() or a 525 * variant on a set of file descriptors for other event sources (e.g. keyboard 526 * button presses, mouse movements, network sockets, etc). You then add 527 * libusb's file descriptors to your poll()/select() calls, and when activity 528 * is detected on such descriptors you know it is time to call 529 * libusb_handle_events(). 530 * 531 * There is one final event handling complication. libusb supports 532 * asynchronous transfers which time out after a specified time period, and 533 * this requires that libusb is called into at or after the timeout so that 534 * the timeout can be handled. So, in addition to considering libusb's file 535 * descriptors in your main event loop, you must also consider that libusb 536 * sometimes needs to be called into at fixed points in time even when there 537 * is no file descriptor activity. 538 * 539 * For the details on retrieving the set of file descriptors and determining 540 * the next timeout, see the \ref poll "polling and timing" API documentation. 541 */ 542 543/** 544 * @defgroup poll Polling and timing 545 * 546 * This page documents libusb's functions for polling events and timing. 547 * These functions are only necessary for users of the 548 * \ref asyncio "asynchronous API". If you are only using the simpler 549 * \ref syncio "synchronous API" then you do not need to ever call these 550 * functions. 551 * 552 * The justification for the functionality described here has already been 553 * discussed in the \ref asyncevent "event handling" section of the 554 * asynchronous API documentation. In summary, libusb does not create internal 555 * threads for event processing and hence relies on your application calling 556 * into libusb at certain points in time so that pending events can be handled. 557 * In order to know precisely when libusb needs to be called into, libusb 558 * offers you a set of pollable file descriptors and information about when 559 * the next timeout expires. 560 * 561 * If you are using the asynchronous I/O API, you must take one of the two 562 * following options, otherwise your I/O will not complete. 563 * 564 * \section pollsimple The simple option 565 * 566 * If your application revolves solely around libusb and does not need to 567 * handle other event sources, you can have a program structure as follows: 568\code 569// initialize libusb 570// find and open device 571// maybe fire off some initial async I/O 572 573while (user_has_not_requested_exit) 574 libusb_handle_events(ctx); 575 576// clean up and exit 577\endcode 578 * 579 * With such a simple main loop, you do not have to worry about managing 580 * sets of file descriptors or handling timeouts. libusb_handle_events() will 581 * handle those details internally. 582 * 583 * \section pollmain The more advanced option 584 * 585 * \note This functionality is currently only available on Unix-like platforms. 586 * On Windows, libusb_get_pollfds() simply returns NULL. Exposing event sources 587 * on Windows will require some further thought and design. 588 * 589 * In more advanced applications, you will already have a main loop which 590 * is monitoring other event sources: network sockets, X11 events, mouse 591 * movements, etc. Through exposing a set of file descriptors, libusb is 592 * designed to cleanly integrate into such main loops. 593 * 594 * In addition to polling file descriptors for the other event sources, you 595 * take a set of file descriptors from libusb and monitor those too. When you 596 * detect activity on libusb's file descriptors, you call 597 * libusb_handle_events_timeout() in non-blocking mode. 598 * 599 * What's more, libusb may also need to handle events at specific moments in 600 * time. No file descriptor activity is generated at these times, so your 601 * own application needs to be continually aware of when the next one of these 602 * moments occurs (through calling libusb_get_next_timeout()), and then it 603 * needs to call libusb_handle_events_timeout() in non-blocking mode when 604 * these moments occur. This means that you need to adjust your 605 * poll()/select() timeout accordingly. 606 * 607 * libusb provides you with a set of file descriptors to poll and expects you 608 * to poll all of them, treating them as a single entity. The meaning of each 609 * file descriptor in the set is an internal implementation detail, 610 * platform-dependent and may vary from release to release. Don't try and 611 * interpret the meaning of the file descriptors, just do as libusb indicates, 612 * polling all of them at once. 613 * 614 * In pseudo-code, you want something that looks like: 615\code 616// initialise libusb 617 618libusb_get_pollfds(ctx) 619while (user has not requested application exit) { 620 libusb_get_next_timeout(ctx); 621 poll(on libusb file descriptors plus any other event sources of interest, 622 using a timeout no larger than the value libusb just suggested) 623 if (poll() indicated activity on libusb file descriptors) 624 libusb_handle_events_timeout(ctx, &zero_tv); 625 if (time has elapsed to or beyond the libusb timeout) 626 libusb_handle_events_timeout(ctx, &zero_tv); 627 // handle events from other sources here 628} 629 630// clean up and exit 631\endcode 632 * 633 * \subsection polltime Notes on time-based events 634 * 635 * The above complication with having to track time and call into libusb at 636 * specific moments is a bit of a headache. For maximum compatibility, you do 637 * need to write your main loop as above, but you may decide that you can 638 * restrict the supported platforms of your application and get away with 639 * a more simplistic scheme. 640 * 641 * These time-based event complications are \b not required on the following 642 * platforms: 643 * - Darwin 644 * - Linux, provided that the following version requirements are satisfied: 645 * - Linux v2.6.27 or newer, compiled with timerfd support 646 * - glibc v2.9 or newer 647 * - libusb v1.0.5 or newer 648 * 649 * Under these configurations, libusb_get_next_timeout() will \em always return 650 * 0, so your main loop can be simplified to: 651\code 652// initialise libusb 653 654libusb_get_pollfds(ctx) 655while (user has not requested application exit) { 656 poll(on libusb file descriptors plus any other event sources of interest, 657 using any timeout that you like) 658 if (poll() indicated activity on libusb file descriptors) 659 libusb_handle_events_timeout(ctx, &zero_tv); 660 // handle events from other sources here 661} 662 663// clean up and exit 664\endcode 665 * 666 * Do remember that if you simplify your main loop to the above, you will 667 * lose compatibility with some platforms (including legacy Linux platforms, 668 * and <em>any future platforms supported by libusb which may have time-based 669 * event requirements</em>). The resultant problems will likely appear as 670 * strange bugs in your application. 671 * 672 * You can use the libusb_pollfds_handle_timeouts() function to do a runtime 673 * check to see if it is safe to ignore the time-based event complications. 674 * If your application has taken the shortcut of ignoring libusb's next timeout 675 * in your main loop, then you are advised to check the return value of 676 * libusb_pollfds_handle_timeouts() during application startup, and to abort 677 * if the platform does suffer from these timing complications. 678 * 679 * \subsection fdsetchange Changes in the file descriptor set 680 * 681 * The set of file descriptors that libusb uses as event sources may change 682 * during the life of your application. Rather than having to repeatedly 683 * call libusb_get_pollfds(), you can set up notification functions for when 684 * the file descriptor set changes using libusb_set_pollfd_notifiers(). 685 * 686 * \subsection mtissues Multi-threaded considerations 687 * 688 * Unfortunately, the situation is complicated further when multiple threads 689 * come into play. If two threads are monitoring the same file descriptors, 690 * the fact that only one thread will be woken up when an event occurs causes 691 * some headaches. 692 * 693 * The events lock, event waiters lock, and libusb_handle_events_locked() 694 * entities are added to solve these problems. You do not need to be concerned 695 * with these entities otherwise. 696 * 697 * See the extra documentation: \ref mtasync 698 */ 699 700/** \page mtasync Multi-threaded applications and asynchronous I/O 701 * 702 * libusb is a thread-safe library, but extra considerations must be applied 703 * to applications which interact with libusb from multiple threads. 704 * 705 * The underlying issue that must be addressed is that all libusb I/O 706 * revolves around monitoring file descriptors through the poll()/select() 707 * system calls. This is directly exposed at the 708 * \ref asyncio "asynchronous interface" but it is important to note that the 709 * \ref syncio "synchronous interface" is implemented on top of the 710 * asynchonrous interface, therefore the same considerations apply. 711 * 712 * The issue is that if two or more threads are concurrently calling poll() 713 * or select() on libusb's file descriptors then only one of those threads 714 * will be woken up when an event arrives. The others will be completely 715 * oblivious that anything has happened. 716 * 717 * Consider the following pseudo-code, which submits an asynchronous transfer 718 * then waits for its completion. This style is one way you could implement a 719 * synchronous interface on top of the asynchronous interface (and libusb 720 * does something similar, albeit more advanced due to the complications 721 * explained on this page). 722 * 723\code 724void cb(struct libusb_transfer *transfer) 725{ 726 int *completed = transfer->user_data; 727 *completed = 1; 728} 729 730void myfunc() { 731 struct libusb_transfer *transfer; 732 unsigned char buffer[LIBUSB_CONTROL_SETUP_SIZE]; 733 int completed = 0; 734 735 transfer = libusb_alloc_transfer(0); 736 libusb_fill_control_setup(buffer, 737 LIBUSB_REQUEST_TYPE_VENDOR | LIBUSB_ENDPOINT_OUT, 0x04, 0x01, 0, 0); 738 libusb_fill_control_transfer(transfer, dev, buffer, cb, &completed, 1000); 739 libusb_submit_transfer(transfer); 740 741 while (!completed) { 742 poll(libusb file descriptors, 120*1000); 743 if (poll indicates activity) 744 libusb_handle_events_timeout(ctx, &zero_tv); 745 } 746 printf("completed!"); 747 // other code here 748} 749\endcode 750 * 751 * Here we are <em>serializing</em> completion of an asynchronous event 752 * against a condition - the condition being completion of a specific transfer. 753 * The poll() loop has a long timeout to minimize CPU usage during situations 754 * when nothing is happening (it could reasonably be unlimited). 755 * 756 * If this is the only thread that is polling libusb's file descriptors, there 757 * is no problem: there is no danger that another thread will swallow up the 758 * event that we are interested in. On the other hand, if there is another 759 * thread polling the same descriptors, there is a chance that it will receive 760 * the event that we were interested in. In this situation, <tt>myfunc()</tt> 761 * will only realise that the transfer has completed on the next iteration of 762 * the loop, <em>up to 120 seconds later.</em> Clearly a two-minute delay is 763 * undesirable, and don't even think about using short timeouts to circumvent 764 * this issue! 765 * 766 * The solution here is to ensure that no two threads are ever polling the 767 * file descriptors at the same time. A naive implementation of this would 768 * impact the capabilities of the library, so libusb offers the scheme 769 * documented below to ensure no loss of functionality. 770 * 771 * Before we go any further, it is worth mentioning that all libusb-wrapped 772 * event handling procedures fully adhere to the scheme documented below. 773 * This includes libusb_handle_events() and its variants, and all the 774 * synchronous I/O functions - libusb hides this headache from you. 775 * 776 * \section Using libusb_handle_events() from multiple threads 777 * 778 * Even when only using libusb_handle_events() and synchronous I/O functions, 779 * you can still have a race condition. You might be tempted to solve the 780 * above with libusb_handle_events() like so: 781 * 782\code 783 libusb_submit_transfer(transfer); 784 785 while (!completed) { 786 libusb_handle_events(ctx); 787 } 788 printf("completed!"); 789\endcode 790 * 791 * This however has a race between the checking of completed and 792 * libusb_handle_events() acquiring the events lock, so another thread 793 * could have completed the transfer, resulting in this thread hanging 794 * until either a timeout or another event occurs. See also commit 795 * 6696512aade99bb15d6792af90ae329af270eba6 which fixes this in the 796 * synchronous API implementation of libusb. 797 * 798 * Fixing this race requires checking the variable completed only after 799 * taking the event lock, which defeats the concept of just calling 800 * libusb_handle_events() without worrying about locking. This is why 801 * libusb-1.0.9 introduces the new libusb_handle_events_timeout_completed() 802 * and libusb_handle_events_completed() functions, which handles doing the 803 * completion check for you after they have acquired the lock: 804 * 805\code 806 libusb_submit_transfer(transfer); 807 808 while (!completed) { 809 libusb_handle_events_completed(ctx, &completed); 810 } 811 printf("completed!"); 812\endcode 813 * 814 * This nicely fixes the race in our example. Note that if all you want to 815 * do is submit a single transfer and wait for its completion, then using 816 * one of the synchronous I/O functions is much easier. 817 * 818 * \section eventlock The events lock 819 * 820 * The problem is when we consider the fact that libusb exposes file 821 * descriptors to allow for you to integrate asynchronous USB I/O into 822 * existing main loops, effectively allowing you to do some work behind 823 * libusb's back. If you do take libusb's file descriptors and pass them to 824 * poll()/select() yourself, you need to be aware of the associated issues. 825 * 826 * The first concept to be introduced is the events lock. The events lock 827 * is used to serialize threads that want to handle events, such that only 828 * one thread is handling events at any one time. 829 * 830 * You must take the events lock before polling libusb file descriptors, 831 * using libusb_lock_events(). You must release the lock as soon as you have 832 * aborted your poll()/select() loop, using libusb_unlock_events(). 833 * 834 * \section threadwait Letting other threads do the work for you 835 * 836 * Although the events lock is a critical part of the solution, it is not 837 * enough on it's own. You might wonder if the following is sufficient... 838\code 839 libusb_lock_events(ctx); 840 while (!completed) { 841 poll(libusb file descriptors, 120*1000); 842 if (poll indicates activity) 843 libusb_handle_events_timeout(ctx, &zero_tv); 844 } 845 libusb_unlock_events(ctx); 846\endcode 847 * ...and the answer is that it is not. This is because the transfer in the 848 * code shown above may take a long time (say 30 seconds) to complete, and 849 * the lock is not released until the transfer is completed. 850 * 851 * Another thread with similar code that wants to do event handling may be 852 * working with a transfer that completes after a few milliseconds. Despite 853 * having such a quick completion time, the other thread cannot check that 854 * status of its transfer until the code above has finished (30 seconds later) 855 * due to contention on the lock. 856 * 857 * To solve this, libusb offers you a mechanism to determine when another 858 * thread is handling events. It also offers a mechanism to block your thread 859 * until the event handling thread has completed an event (and this mechanism 860 * does not involve polling of file descriptors). 861 * 862 * After determining that another thread is currently handling events, you 863 * obtain the <em>event waiters</em> lock using libusb_lock_event_waiters(). 864 * You then re-check that some other thread is still handling events, and if 865 * so, you call libusb_wait_for_event(). 866 * 867 * libusb_wait_for_event() puts your application to sleep until an event 868 * occurs, or until a thread releases the events lock. When either of these 869 * things happen, your thread is woken up, and should re-check the condition 870 * it was waiting on. It should also re-check that another thread is handling 871 * events, and if not, it should start handling events itself. 872 * 873 * This looks like the following, as pseudo-code: 874\code 875retry: 876if (libusb_try_lock_events(ctx) == 0) { 877 // we obtained the event lock: do our own event handling 878 while (!completed) { 879 if (!libusb_event_handling_ok(ctx)) { 880 libusb_unlock_events(ctx); 881 goto retry; 882 } 883 poll(libusb file descriptors, 120*1000); 884 if (poll indicates activity) 885 libusb_handle_events_locked(ctx, 0); 886 } 887 libusb_unlock_events(ctx); 888} else { 889 // another thread is doing event handling. wait for it to signal us that 890 // an event has completed 891 libusb_lock_event_waiters(ctx); 892 893 while (!completed) { 894 // now that we have the event waiters lock, double check that another 895 // thread is still handling events for us. (it may have ceased handling 896 // events in the time it took us to reach this point) 897 if (!libusb_event_handler_active(ctx)) { 898 // whoever was handling events is no longer doing so, try again 899 libusb_unlock_event_waiters(ctx); 900 goto retry; 901 } 902 903 libusb_wait_for_event(ctx, NULL); 904 } 905 libusb_unlock_event_waiters(ctx); 906} 907printf("completed!\n"); 908\endcode 909 * 910 * A naive look at the above code may suggest that this can only support 911 * one event waiter (hence a total of 2 competing threads, the other doing 912 * event handling), because the event waiter seems to have taken the event 913 * waiters lock while waiting for an event. However, the system does support 914 * multiple event waiters, because libusb_wait_for_event() actually drops 915 * the lock while waiting, and reaquires it before continuing. 916 * 917 * We have now implemented code which can dynamically handle situations where 918 * nobody is handling events (so we should do it ourselves), and it can also 919 * handle situations where another thread is doing event handling (so we can 920 * piggyback onto them). It is also equipped to handle a combination of 921 * the two, for example, another thread is doing event handling, but for 922 * whatever reason it stops doing so before our condition is met, so we take 923 * over the event handling. 924 * 925 * Four functions were introduced in the above pseudo-code. Their importance 926 * should be apparent from the code shown above. 927 * -# libusb_try_lock_events() is a non-blocking function which attempts 928 * to acquire the events lock but returns a failure code if it is contended. 929 * -# libusb_event_handling_ok() checks that libusb is still happy for your 930 * thread to be performing event handling. Sometimes, libusb needs to 931 * interrupt the event handler, and this is how you can check if you have 932 * been interrupted. If this function returns 0, the correct behaviour is 933 * for you to give up the event handling lock, and then to repeat the cycle. 934 * The following libusb_try_lock_events() will fail, so you will become an 935 * events waiter. For more information on this, read \ref fullstory below. 936 * -# libusb_handle_events_locked() is a variant of 937 * libusb_handle_events_timeout() that you can call while holding the 938 * events lock. libusb_handle_events_timeout() itself implements similar 939 * logic to the above, so be sure not to call it when you are 940 * "working behind libusb's back", as is the case here. 941 * -# libusb_event_handler_active() determines if someone is currently 942 * holding the events lock 943 * 944 * You might be wondering why there is no function to wake up all threads 945 * blocked on libusb_wait_for_event(). This is because libusb can do this 946 * internally: it will wake up all such threads when someone calls 947 * libusb_unlock_events() or when a transfer completes (at the point after its 948 * callback has returned). 949 * 950 * \subsection fullstory The full story 951 * 952 * The above explanation should be enough to get you going, but if you're 953 * really thinking through the issues then you may be left with some more 954 * questions regarding libusb's internals. If you're curious, read on, and if 955 * not, skip to the next section to avoid confusing yourself! 956 * 957 * The immediate question that may spring to mind is: what if one thread 958 * modifies the set of file descriptors that need to be polled while another 959 * thread is doing event handling? 960 * 961 * There are 2 situations in which this may happen. 962 * -# libusb_open() will add another file descriptor to the poll set, 963 * therefore it is desirable to interrupt the event handler so that it 964 * restarts, picking up the new descriptor. 965 * -# libusb_close() will remove a file descriptor from the poll set. There 966 * are all kinds of race conditions that could arise here, so it is 967 * important that nobody is doing event handling at this time. 968 * 969 * libusb handles these issues internally, so application developers do not 970 * have to stop their event handlers while opening/closing devices. Here's how 971 * it works, focusing on the libusb_close() situation first: 972 * 973 * -# During initialization, libusb opens an internal pipe, and it adds the read 974 * end of this pipe to the set of file descriptors to be polled. 975 * -# During libusb_close(), libusb writes some dummy data on this control pipe. 976 * This immediately interrupts the event handler. libusb also records 977 * internally that it is trying to interrupt event handlers for this 978 * high-priority event. 979 * -# At this point, some of the functions described above start behaving 980 * differently: 981 * - libusb_event_handling_ok() starts returning 1, indicating that it is NOT 982 * OK for event handling to continue. 983 * - libusb_try_lock_events() starts returning 1, indicating that another 984 * thread holds the event handling lock, even if the lock is uncontended. 985 * - libusb_event_handler_active() starts returning 1, indicating that 986 * another thread is doing event handling, even if that is not true. 987 * -# The above changes in behaviour result in the event handler stopping and 988 * giving up the events lock very quickly, giving the high-priority 989 * libusb_close() operation a "free ride" to acquire the events lock. All 990 * threads that are competing to do event handling become event waiters. 991 * -# With the events lock held inside libusb_close(), libusb can safely remove 992 * a file descriptor from the poll set, in the safety of knowledge that 993 * nobody is polling those descriptors or trying to access the poll set. 994 * -# After obtaining the events lock, the close operation completes very 995 * quickly (usually a matter of milliseconds) and then immediately releases 996 * the events lock. 997 * -# At the same time, the behaviour of libusb_event_handling_ok() and friends 998 * reverts to the original, documented behaviour. 999 * -# The release of the events lock causes the threads that are waiting for 1000 * events to be woken up and to start competing to become event handlers 1001 * again. One of them will succeed; it will then re-obtain the list of poll 1002 * descriptors, and USB I/O will then continue as normal. 1003 * 1004 * libusb_open() is similar, and is actually a more simplistic case. Upon a 1005 * call to libusb_open(): 1006 * 1007 * -# The device is opened and a file descriptor is added to the poll set. 1008 * -# libusb sends some dummy data on the control pipe, and records that it 1009 * is trying to modify the poll descriptor set. 1010 * -# The event handler is interrupted, and the same behaviour change as for 1011 * libusb_close() takes effect, causing all event handling threads to become 1012 * event waiters. 1013 * -# The libusb_open() implementation takes its free ride to the events lock. 1014 * -# Happy that it has successfully paused the events handler, libusb_open() 1015 * releases the events lock. 1016 * -# The event waiter threads are all woken up and compete to become event 1017 * handlers again. The one that succeeds will obtain the list of poll 1018 * descriptors again, which will include the addition of the new device. 1019 * 1020 * \subsection concl Closing remarks 1021 * 1022 * The above may seem a little complicated, but hopefully I have made it clear 1023 * why such complications are necessary. Also, do not forget that this only 1024 * applies to applications that take libusb's file descriptors and integrate 1025 * them into their own polling loops. 1026 * 1027 * You may decide that it is OK for your multi-threaded application to ignore 1028 * some of the rules and locks detailed above, because you don't think that 1029 * two threads can ever be polling the descriptors at the same time. If that 1030 * is the case, then that's good news for you because you don't have to worry. 1031 * But be careful here; remember that the synchronous I/O functions do event 1032 * handling internally. If you have one thread doing event handling in a loop 1033 * (without implementing the rules and locking semantics documented above) 1034 * and another trying to send a synchronous USB transfer, you will end up with 1035 * two threads monitoring the same descriptors, and the above-described 1036 * undesirable behaviour occuring. The solution is for your polling thread to 1037 * play by the rules; the synchronous I/O functions do so, and this will result 1038 * in them getting along in perfect harmony. 1039 * 1040 * If you do have a dedicated thread doing event handling, it is perfectly 1041 * legal for it to take the event handling lock for long periods of time. Any 1042 * synchronous I/O functions you call from other threads will transparently 1043 * fall back to the "event waiters" mechanism detailed above. The only 1044 * consideration that your event handling thread must apply is the one related 1045 * to libusb_event_handling_ok(): you must call this before every poll(), and 1046 * give up the events lock if instructed. 1047 */ 1048 1049int usbi_io_init(struct libusb_context *ctx) 1050{ 1051 int r; 1052 1053 usbi_mutex_init(&ctx->flying_transfers_lock, NULL); 1054 usbi_mutex_init(&ctx->pollfds_lock, NULL); 1055 usbi_mutex_init(&ctx->pollfd_modify_lock, NULL); 1056 usbi_mutex_init_recursive(&ctx->events_lock, NULL); 1057 usbi_mutex_init(&ctx->event_waiters_lock, NULL); 1058 usbi_cond_init(&ctx->event_waiters_cond, NULL); 1059 list_init(&ctx->flying_transfers); 1060 list_init(&ctx->pollfds); 1061 1062 /* FIXME should use an eventfd on kernels that support it */ 1063 r = usbi_pipe(ctx->ctrl_pipe); 1064 if (r < 0) { 1065 r = LIBUSB_ERROR_OTHER; 1066 goto err; 1067 } 1068 1069 r = usbi_add_pollfd(ctx, ctx->ctrl_pipe[0], POLLIN); 1070 if (r < 0) 1071 goto err_close_pipe; 1072 1073#ifdef USBI_TIMERFD_AVAILABLE 1074 ctx->timerfd = timerfd_create(usbi_backend->get_timerfd_clockid(), 1075 TFD_NONBLOCK); 1076 if (ctx->timerfd >= 0) { 1077 usbi_dbg("using timerfd for timeouts"); 1078 r = usbi_add_pollfd(ctx, ctx->timerfd, POLLIN); 1079 if (r < 0) { 1080 usbi_remove_pollfd(ctx, ctx->ctrl_pipe[0]); 1081 close(ctx->timerfd); 1082 goto err_close_pipe; 1083 } 1084 } else { 1085 usbi_dbg("timerfd not available (code %d error %d)", ctx->timerfd, errno); 1086 ctx->timerfd = -1; 1087 } 1088#endif 1089 1090 return 0; 1091 1092err_close_pipe: 1093 usbi_close(ctx->ctrl_pipe[0]); 1094 usbi_close(ctx->ctrl_pipe[1]); 1095err: 1096 usbi_mutex_destroy(&ctx->flying_transfers_lock); 1097 usbi_mutex_destroy(&ctx->pollfds_lock); 1098 usbi_mutex_destroy(&ctx->pollfd_modify_lock); 1099 usbi_mutex_destroy(&ctx->events_lock); 1100 usbi_mutex_destroy(&ctx->event_waiters_lock); 1101 usbi_cond_destroy(&ctx->event_waiters_cond); 1102 return r; 1103} 1104 1105void usbi_io_exit(struct libusb_context *ctx) 1106{ 1107 usbi_remove_pollfd(ctx, ctx->ctrl_pipe[0]); 1108 usbi_close(ctx->ctrl_pipe[0]); 1109 usbi_close(ctx->ctrl_pipe[1]); 1110#ifdef USBI_TIMERFD_AVAILABLE 1111 if (usbi_using_timerfd(ctx)) { 1112 usbi_remove_pollfd(ctx, ctx->timerfd); 1113 close(ctx->timerfd); 1114 } 1115#endif 1116 usbi_mutex_destroy(&ctx->flying_transfers_lock); 1117 usbi_mutex_destroy(&ctx->pollfds_lock); 1118 usbi_mutex_destroy(&ctx->pollfd_modify_lock); 1119 usbi_mutex_destroy(&ctx->events_lock); 1120 usbi_mutex_destroy(&ctx->event_waiters_lock); 1121 usbi_cond_destroy(&ctx->event_waiters_cond); 1122} 1123 1124static int calculate_timeout(struct usbi_transfer *transfer) 1125{ 1126 int r; 1127 struct timespec current_time; 1128 unsigned int timeout = 1129 USBI_TRANSFER_TO_LIBUSB_TRANSFER(transfer)->timeout; 1130 1131 if (!timeout) 1132 return 0; 1133 1134 r = usbi_backend->clock_gettime(USBI_CLOCK_MONOTONIC, ¤t_time); 1135 if (r < 0) { 1136 usbi_err(ITRANSFER_CTX(transfer), 1137 "failed to read monotonic clock, errno=%d", errno); 1138 return r; 1139 } 1140 1141 current_time.tv_sec += timeout / 1000; 1142 current_time.tv_nsec += (timeout % 1000) * 1000000; 1143 1144 if (current_time.tv_nsec > 1000000000) { 1145 current_time.tv_nsec -= 1000000000; 1146 current_time.tv_sec++; 1147 } 1148 1149 TIMESPEC_TO_TIMEVAL(&transfer->timeout, ¤t_time); 1150 return 0; 1151} 1152 1153/* add a transfer to the (timeout-sorted) active transfers list. 1154 * returns 1 if the transfer has a timeout and it is the timeout next to 1155 * expire */ 1156static int add_to_flying_list(struct usbi_transfer *transfer) 1157{ 1158 struct usbi_transfer *cur; 1159 struct timeval *timeout = &transfer->timeout; 1160 struct libusb_context *ctx = ITRANSFER_CTX(transfer); 1161 int r = 0; 1162 int first = 1; 1163 1164 usbi_mutex_lock(&ctx->flying_transfers_lock); 1165 1166 /* if we have no other flying transfers, start the list with this one */ 1167 if (list_empty(&ctx->flying_transfers)) { 1168 list_add(&transfer->list, &ctx->flying_transfers); 1169 if (timerisset(timeout)) 1170 r = 1; 1171 goto out; 1172 } 1173 1174 /* if we have infinite timeout, append to end of list */ 1175 if (!timerisset(timeout)) { 1176 list_add_tail(&transfer->list, &ctx->flying_transfers); 1177 goto out; 1178 } 1179 1180 /* otherwise, find appropriate place in list */ 1181 list_for_each_entry(cur, &ctx->flying_transfers, list, struct usbi_transfer) { 1182 /* find first timeout that occurs after the transfer in question */ 1183 struct timeval *cur_tv = &cur->timeout; 1184 1185 if (!timerisset(cur_tv) || (cur_tv->tv_sec > timeout->tv_sec) || 1186 (cur_tv->tv_sec == timeout->tv_sec && 1187 cur_tv->tv_usec > timeout->tv_usec)) { 1188 list_add_tail(&transfer->list, &cur->list); 1189 r = first; 1190 goto out; 1191 } 1192 first = 0; 1193 } 1194 1195 /* otherwise we need to be inserted at the end */ 1196 list_add_tail(&transfer->list, &ctx->flying_transfers); 1197out: 1198 usbi_mutex_unlock(&ctx->flying_transfers_lock); 1199 return r; 1200} 1201 1202/** \ingroup asyncio 1203 * Allocate a libusb transfer with a specified number of isochronous packet 1204 * descriptors. The returned transfer is pre-initialized for you. When the new 1205 * transfer is no longer needed, it should be freed with 1206 * libusb_free_transfer(). 1207 * 1208 * Transfers intended for non-isochronous endpoints (e.g. control, bulk, 1209 * interrupt) should specify an iso_packets count of zero. 1210 * 1211 * For transfers intended for isochronous endpoints, specify an appropriate 1212 * number of packet descriptors to be allocated as part of the transfer. 1213 * The returned transfer is not specially initialized for isochronous I/O; 1214 * you are still required to set the 1215 * \ref libusb_transfer::num_iso_packets "num_iso_packets" and 1216 * \ref libusb_transfer::type "type" fields accordingly. 1217 * 1218 * It is safe to allocate a transfer with some isochronous packets and then 1219 * use it on a non-isochronous endpoint. If you do this, ensure that at time 1220 * of submission, num_iso_packets is 0 and that type is set appropriately. 1221 * 1222 * \param iso_packets number of isochronous packet descriptors to allocate 1223 * \returns a newly allocated transfer, or NULL on error 1224 */ 1225DEFAULT_VISIBILITY 1226struct libusb_transfer * LIBUSB_CALL libusb_alloc_transfer( 1227 int iso_packets) 1228{ 1229 size_t os_alloc_size = usbi_backend->transfer_priv_size 1230 + (usbi_backend->add_iso_packet_size * iso_packets); 1231 size_t alloc_size = sizeof(struct usbi_transfer) 1232 + sizeof(struct libusb_transfer) 1233 + (sizeof(struct libusb_iso_packet_descriptor) * iso_packets) 1234 + os_alloc_size; 1235 struct usbi_transfer *itransfer = malloc(alloc_size); 1236 if (!itransfer) 1237 return NULL; 1238 1239 memset(itransfer, 0, alloc_size); 1240 itransfer->num_iso_packets = iso_packets; 1241 usbi_mutex_init(&itransfer->lock, NULL); 1242 return USBI_TRANSFER_TO_LIBUSB_TRANSFER(itransfer); 1243} 1244 1245/** \ingroup asyncio 1246 * Free a transfer structure. This should be called for all transfers 1247 * allocated with libusb_alloc_transfer(). 1248 * 1249 * If the \ref libusb_transfer_flags::LIBUSB_TRANSFER_FREE_BUFFER 1250 * "LIBUSB_TRANSFER_FREE_BUFFER" flag is set and the transfer buffer is 1251 * non-NULL, this function will also free the transfer buffer using the 1252 * standard system memory allocator (e.g. free()). 1253 * 1254 * It is legal to call this function with a NULL transfer. In this case, 1255 * the function will simply return safely. 1256 * 1257 * It is not legal to free an active transfer (one which has been submitted 1258 * and has not yet completed). 1259 * 1260 * \param transfer the transfer to free 1261 */ 1262void API_EXPORTED libusb_free_transfer(struct libusb_transfer *transfer) 1263{ 1264 struct usbi_transfer *itransfer; 1265 if (!transfer) 1266 return; 1267 1268 if (transfer->flags & LIBUSB_TRANSFER_FREE_BUFFER && transfer->buffer) 1269 free(transfer->buffer); 1270 1271 itransfer = LIBUSB_TRANSFER_TO_USBI_TRANSFER(transfer); 1272 usbi_mutex_destroy(&itransfer->lock); 1273 free(itransfer); 1274} 1275 1276/** \ingroup asyncio 1277 * Submit a transfer. This function will fire off the USB transfer and then 1278 * return immediately. 1279 * 1280 * \param transfer the transfer to submit 1281 * \returns 0 on success 1282 * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 1283 * \returns LIBUSB_ERROR_BUSY if the transfer has already been submitted. 1284 * \returns another LIBUSB_ERROR code on other failure 1285 */ 1286int API_EXPORTED libusb_submit_transfer(struct libusb_transfer *transfer) 1287{ 1288 struct libusb_context *ctx = TRANSFER_CTX(transfer); 1289 struct usbi_transfer *itransfer = 1290 LIBUSB_TRANSFER_TO_USBI_TRANSFER(transfer); 1291 int r; 1292 int first; 1293 1294 usbi_mutex_lock(&itransfer->lock); 1295 itransfer->transferred = 0; 1296 itransfer->flags = 0; 1297 r = calculate_timeout(itransfer); 1298 if (r < 0) { 1299 r = LIBUSB_ERROR_OTHER; 1300 goto out; 1301 } 1302 1303 first = add_to_flying_list(itransfer); 1304 r = usbi_backend->submit_transfer(itransfer); 1305 if (r) { 1306 usbi_mutex_lock(&ctx->flying_transfers_lock); 1307 list_del(&itransfer->list); 1308 usbi_mutex_unlock(&ctx->flying_transfers_lock); 1309 } 1310#ifdef USBI_TIMERFD_AVAILABLE 1311 else if (first && usbi_using_timerfd(ctx)) { 1312 /* if this transfer has the lowest timeout of all active transfers, 1313 * rearm the timerfd with this transfer's timeout */ 1314 const struct itimerspec it = { {0, 0}, 1315 { itransfer->timeout.tv_sec, itransfer->timeout.tv_usec * 1000 } }; 1316 usbi_dbg("arm timerfd for timeout in %dms (first in line)", transfer->timeout); 1317 r = timerfd_settime(ctx->timerfd, TFD_TIMER_ABSTIME, &it, NULL); 1318 if (r < 0) 1319 r = LIBUSB_ERROR_OTHER; 1320 } 1321#else 1322 (void)first; 1323#endif 1324 1325out: 1326 usbi_mutex_unlock(&itransfer->lock); 1327 return r; 1328} 1329 1330/** \ingroup asyncio 1331 * Asynchronously cancel a previously submitted transfer. 1332 * This function returns immediately, but this does not indicate cancellation 1333 * is complete. Your callback function will be invoked at some later time 1334 * with a transfer status of 1335 * \ref libusb_transfer_status::LIBUSB_TRANSFER_CANCELLED 1336 * "LIBUSB_TRANSFER_CANCELLED." 1337 * 1338 * \param transfer the transfer to cancel 1339 * \returns 0 on success 1340 * \returns LIBUSB_ERROR_NOT_FOUND if the transfer is already complete or 1341 * cancelled. 1342 * \returns a LIBUSB_ERROR code on failure 1343 */ 1344int API_EXPORTED libusb_cancel_transfer(struct libusb_transfer *transfer) 1345{ 1346 struct usbi_transfer *itransfer = 1347 LIBUSB_TRANSFER_TO_USBI_TRANSFER(transfer); 1348 int r; 1349 1350 usbi_dbg(""); 1351 usbi_mutex_lock(&itransfer->lock); 1352 r = usbi_backend->cancel_transfer(itransfer); 1353 if (r < 0) { 1354 usbi_err(TRANSFER_CTX(transfer), 1355 "cancel transfer failed error %d", r); 1356 1357 if (r == LIBUSB_ERROR_NO_DEVICE) 1358 itransfer->flags |= USBI_TRANSFER_DEVICE_DISAPPEARED; 1359 } 1360 1361 itransfer->flags |= USBI_TRANSFER_CANCELLING; 1362 1363 usbi_mutex_unlock(&itransfer->lock); 1364 return r; 1365} 1366 1367#ifdef USBI_TIMERFD_AVAILABLE 1368static int disarm_timerfd(struct libusb_context *ctx) 1369{ 1370 const struct itimerspec disarm_timer = { { 0, 0 }, { 0, 0 } }; 1371 int r; 1372 1373 usbi_dbg(""); 1374 r = timerfd_settime(ctx->timerfd, 0, &disarm_timer, NULL); 1375 if (r < 0) 1376 return LIBUSB_ERROR_OTHER; 1377 else 1378 return 0; 1379} 1380 1381/* iterates through the flying transfers, and rearms the timerfd based on the 1382 * next upcoming timeout. 1383 * must be called with flying_list locked. 1384 * returns 0 if there was no timeout to arm, 1 if the next timeout was armed, 1385 * or a LIBUSB_ERROR code on failure. 1386 */ 1387static int arm_timerfd_for_next_timeout(struct libusb_context *ctx) 1388{ 1389 struct usbi_transfer *transfer; 1390 1391 list_for_each_entry(transfer, &ctx->flying_transfers, list, struct usbi_transfer) { 1392 struct timeval *cur_tv = &transfer->timeout; 1393 1394 /* if we've reached transfers of infinite timeout, then we have no 1395 * arming to do */ 1396 if (!timerisset(cur_tv)) 1397 return 0; 1398 1399 /* act on first transfer that is not already cancelled */ 1400 if (!(transfer->flags & USBI_TRANSFER_TIMED_OUT)) { 1401 int r; 1402 const struct itimerspec it = { {0, 0}, 1403 { cur_tv->tv_sec, cur_tv->tv_usec * 1000 } }; 1404 usbi_dbg("next timeout originally %dms", USBI_TRANSFER_TO_LIBUSB_TRANSFER(transfer)->timeout); 1405 r = timerfd_settime(ctx->timerfd, TFD_TIMER_ABSTIME, &it, NULL); 1406 if (r < 0) 1407 return LIBUSB_ERROR_OTHER; 1408 return 1; 1409 } 1410 } 1411 1412 return 0; 1413} 1414#else 1415static int disarm_timerfd(struct libusb_context *ctx) 1416{ 1417 (void)ctx; 1418 return 0; 1419} 1420static int arm_timerfd_for_next_timeout(struct libusb_context *ctx) 1421{ 1422 (void)ctx; 1423 return 0; 1424} 1425#endif 1426 1427/* Handle completion of a transfer (completion might be an error condition). 1428 * This will invoke the user-supplied callback function, which may end up 1429 * freeing the transfer. Therefore you cannot use the transfer structure 1430 * after calling this function, and you should free all backend-specific 1431 * data before calling it. 1432 * Do not call this function with the usbi_transfer lock held. User-specified 1433 * callback functions may attempt to directly resubmit the transfer, which 1434 * will attempt to take the lock. */ 1435int usbi_handle_transfer_completion(struct usbi_transfer *itransfer, 1436 enum libusb_transfer_status status) 1437{ 1438 struct libusb_transfer *transfer = 1439 USBI_TRANSFER_TO_LIBUSB_TRANSFER(itransfer); 1440 struct libusb_context *ctx = TRANSFER_CTX(transfer); 1441 uint8_t flags; 1442 int r; 1443 1444 /* FIXME: could be more intelligent with the timerfd here. we don't need 1445 * to disarm the timerfd if there was no timer running, and we only need 1446 * to rearm the timerfd if the transfer that expired was the one with 1447 * the shortest timeout. */ 1448 1449 usbi_mutex_lock(&ctx->flying_transfers_lock); 1450 list_del(&itransfer->list); 1451 r = arm_timerfd_for_next_timeout(ctx); 1452 usbi_mutex_unlock(&ctx->flying_transfers_lock); 1453 1454 if (r < 0) { 1455 return r; 1456 } else if (r == 0) { 1457 r = disarm_timerfd(ctx); 1458 if (r < 0) 1459 return r; 1460 } 1461 1462 if (status == LIBUSB_TRANSFER_COMPLETED 1463 && transfer->flags & LIBUSB_TRANSFER_SHORT_NOT_OK) { 1464 int rqlen = transfer->length; 1465 if (transfer->type == LIBUSB_TRANSFER_TYPE_CONTROL) 1466 rqlen -= LIBUSB_CONTROL_SETUP_SIZE; 1467 if (rqlen != itransfer->transferred) { 1468 usbi_dbg("interpreting short transfer as error"); 1469 status = LIBUSB_TRANSFER_ERROR; 1470 } 1471 } 1472 1473 flags = transfer->flags; 1474 transfer->status = status; 1475 transfer->actual_length = itransfer->transferred; 1476 if (transfer->callback) 1477 transfer->callback(transfer); 1478 /* transfer might have been freed by the above call, do not use from 1479 * this point. */ 1480 if (flags & LIBUSB_TRANSFER_FREE_TRANSFER) 1481 libusb_free_transfer(transfer); 1482 usbi_mutex_lock(&ctx->event_waiters_lock); 1483 usbi_cond_broadcast(&ctx->event_waiters_cond); 1484 usbi_mutex_unlock(&ctx->event_waiters_lock); 1485 return 0; 1486} 1487 1488/* Similar to usbi_handle_transfer_completion() but exclusively for transfers 1489 * that were asynchronously cancelled. The same concerns w.r.t. freeing of 1490 * transfers exist here. 1491 * Do not call this function with the usbi_transfer lock held. User-specified 1492 * callback functions may attempt to directly resubmit the transfer, which 1493 * will attempt to take the lock. */ 1494int usbi_handle_transfer_cancellation(struct usbi_transfer *transfer) 1495{ 1496 /* if the URB was cancelled due to timeout, report timeout to the user */ 1497 if (transfer->flags & USBI_TRANSFER_TIMED_OUT) { 1498 usbi_dbg("detected timeout cancellation"); 1499 return usbi_handle_transfer_completion(transfer, LIBUSB_TRANSFER_TIMED_OUT); 1500 } 1501 1502 /* otherwise its a normal async cancel */ 1503 return usbi_handle_transfer_completion(transfer, LIBUSB_TRANSFER_CANCELLED); 1504} 1505 1506/** \ingroup poll 1507 * Attempt to acquire the event handling lock. This lock is used to ensure that 1508 * only one thread is monitoring libusb event sources at any one time. 1509 * 1510 * You only need to use this lock if you are developing an application 1511 * which calls poll() or select() on libusb's file descriptors directly. 1512 * If you stick to libusb's event handling loop functions (e.g. 1513 * libusb_handle_events()) then you do not need to be concerned with this 1514 * locking. 1515 * 1516 * While holding this lock, you are trusted to actually be handling events. 1517 * If you are no longer handling events, you must call libusb_unlock_events() 1518 * as soon as possible. 1519 * 1520 * \param ctx the context to operate on, or NULL for the default context 1521 * \returns 0 if the lock was obtained successfully 1522 * \returns 1 if the lock was not obtained (i.e. another thread holds the lock) 1523 * \see \ref mtasync 1524 */ 1525int API_EXPORTED libusb_try_lock_events(libusb_context *ctx) 1526{ 1527 int r; 1528 USBI_GET_CONTEXT(ctx); 1529 1530 /* is someone else waiting to modify poll fds? if so, don't let this thread 1531 * start event handling */ 1532 usbi_mutex_lock(&ctx->pollfd_modify_lock); 1533 r = ctx->pollfd_modify; 1534 usbi_mutex_unlock(&ctx->pollfd_modify_lock); 1535 if (r) { 1536 usbi_dbg("someone else is modifying poll fds"); 1537 return 1; 1538 } 1539 1540 r = usbi_mutex_trylock(&ctx->events_lock); 1541 if (r) 1542 return 1; 1543 1544 ctx->event_handler_active = 1; 1545 return 0; 1546} 1547 1548/** \ingroup poll 1549 * Acquire the event handling lock, blocking until successful acquisition if 1550 * it is contended. This lock is used to ensure that only one thread is 1551 * monitoring libusb event sources at any one time. 1552 * 1553 * You only need to use this lock if you are developing an application 1554 * which calls poll() or select() on libusb's file descriptors directly. 1555 * If you stick to libusb's event handling loop functions (e.g. 1556 * libusb_handle_events()) then you do not need to be concerned with this 1557 * locking. 1558 * 1559 * While holding this lock, you are trusted to actually be handling events. 1560 * If you are no longer handling events, you must call libusb_unlock_events() 1561 * as soon as possible. 1562 * 1563 * \param ctx the context to operate on, or NULL for the default context 1564 * \see \ref mtasync 1565 */ 1566void API_EXPORTED libusb_lock_events(libusb_context *ctx) 1567{ 1568 USBI_GET_CONTEXT(ctx); 1569 usbi_mutex_lock(&ctx->events_lock); 1570 ctx->event_handler_active = 1; 1571} 1572 1573/** \ingroup poll 1574 * Release the lock previously acquired with libusb_try_lock_events() or 1575 * libusb_lock_events(). Releasing this lock will wake up any threads blocked 1576 * on libusb_wait_for_event(). 1577 * 1578 * \param ctx the context to operate on, or NULL for the default context 1579 * \see \ref mtasync 1580 */ 1581void API_EXPORTED libusb_unlock_events(libusb_context *ctx) 1582{ 1583 USBI_GET_CONTEXT(ctx); 1584 ctx->event_handler_active = 0; 1585 usbi_mutex_unlock(&ctx->events_lock); 1586 1587 /* FIXME: perhaps we should be a bit more efficient by not broadcasting 1588 * the availability of the events lock when we are modifying pollfds 1589 * (check ctx->pollfd_modify)? */ 1590 usbi_mutex_lock(&ctx->event_waiters_lock); 1591 usbi_cond_broadcast(&ctx->event_waiters_cond); 1592 usbi_mutex_unlock(&ctx->event_waiters_lock); 1593} 1594 1595/** \ingroup poll 1596 * Determine if it is still OK for this thread to be doing event handling. 1597 * 1598 * Sometimes, libusb needs to temporarily pause all event handlers, and this 1599 * is the function you should use before polling file descriptors to see if 1600 * this is the case. 1601 * 1602 * If this function instructs your thread to give up the events lock, you 1603 * should just continue the usual logic that is documented in \ref mtasync. 1604 * On the next iteration, your thread will fail to obtain the events lock, 1605 * and will hence become an event waiter. 1606 * 1607 * This function should be called while the events lock is held: you don't 1608 * need to worry about the results of this function if your thread is not 1609 * the current event handler. 1610 * 1611 * \param ctx the context to operate on, or NULL for the default context 1612 * \returns 1 if event handling can start or continue 1613 * \returns 0 if this thread must give up the events lock 1614 * \see \ref fullstory "Multi-threaded I/O: the full story" 1615 */ 1616int API_EXPORTED libusb_event_handling_ok(libusb_context *ctx) 1617{ 1618 int r; 1619 USBI_GET_CONTEXT(ctx); 1620 1621 /* is someone else waiting to modify poll fds? if so, don't let this thread 1622 * continue event handling */ 1623 usbi_mutex_lock(&ctx->pollfd_modify_lock); 1624 r = ctx->pollfd_modify; 1625 usbi_mutex_unlock(&ctx->pollfd_modify_lock); 1626 if (r) { 1627 usbi_dbg("someone else is modifying poll fds"); 1628 return 0; 1629 } 1630 1631 return 1; 1632} 1633 1634 1635/** \ingroup poll 1636 * Determine if an active thread is handling events (i.e. if anyone is holding 1637 * the event handling lock). 1638 * 1639 * \param ctx the context to operate on, or NULL for the default context 1640 * \returns 1 if a thread is handling events 1641 * \returns 0 if there are no threads currently handling events 1642 * \see \ref mtasync 1643 */ 1644int API_EXPORTED libusb_event_handler_active(libusb_context *ctx) 1645{ 1646 int r; 1647 USBI_GET_CONTEXT(ctx); 1648 1649 /* is someone else waiting to modify poll fds? if so, don't let this thread 1650 * start event handling -- indicate that event handling is happening */ 1651 usbi_mutex_lock(&ctx->pollfd_modify_lock); 1652 r = ctx->pollfd_modify; 1653 usbi_mutex_unlock(&ctx->pollfd_modify_lock); 1654 if (r) { 1655 usbi_dbg("someone else is modifying poll fds"); 1656 return 1; 1657 } 1658 1659 return ctx->event_handler_active; 1660} 1661 1662/** \ingroup poll 1663 * Acquire the event waiters lock. This lock is designed to be obtained under 1664 * the situation where you want to be aware when events are completed, but 1665 * some other thread is event handling so calling libusb_handle_events() is not 1666 * allowed. 1667 * 1668 * You then obtain this lock, re-check that another thread is still handling 1669 * events, then call libusb_wait_for_event(). 1670 * 1671 * You only need to use this lock if you are developing an application 1672 * which calls poll() or select() on libusb's file descriptors directly, 1673 * <b>and</b> may potentially be handling events from 2 threads simultaenously. 1674 * If you stick to libusb's event handling loop functions (e.g. 1675 * libusb_handle_events()) then you do not need to be concerned with this 1676 * locking. 1677 * 1678 * \param ctx the context to operate on, or NULL for the default context 1679 * \see \ref mtasync 1680 */ 1681void API_EXPORTED libusb_lock_event_waiters(libusb_context *ctx) 1682{ 1683 USBI_GET_CONTEXT(ctx); 1684 usbi_mutex_lock(&ctx->event_waiters_lock); 1685} 1686 1687/** \ingroup poll 1688 * Release the event waiters lock. 1689 * \param ctx the context to operate on, or NULL for the default context 1690 * \see \ref mtasync 1691 */ 1692void API_EXPORTED libusb_unlock_event_waiters(libusb_context *ctx) 1693{ 1694 USBI_GET_CONTEXT(ctx); 1695 usbi_mutex_unlock(&ctx->event_waiters_lock); 1696} 1697 1698/** \ingroup poll 1699 * Wait for another thread to signal completion of an event. Must be called 1700 * with the event waiters lock held, see libusb_lock_event_waiters(). 1701 * 1702 * This function will block until any of the following conditions are met: 1703 * -# The timeout expires 1704 * -# A transfer completes 1705 * -# A thread releases the event handling lock through libusb_unlock_events() 1706 * 1707 * Condition 1 is obvious. Condition 2 unblocks your thread <em>after</em> 1708 * the callback for the transfer has completed. Condition 3 is important 1709 * because it means that the thread that was previously handling events is no 1710 * longer doing so, so if any events are to complete, another thread needs to 1711 * step up and start event handling. 1712 * 1713 * This function releases the event waiters lock before putting your thread 1714 * to sleep, and reacquires the lock as it is being woken up. 1715 * 1716 * \param ctx the context to operate on, or NULL for the default context 1717 * \param tv maximum timeout for this blocking function. A NULL value 1718 * indicates unlimited timeout. 1719 * \returns 0 after a transfer completes or another thread stops event handling 1720 * \returns 1 if the timeout expired 1721 * \see \ref mtasync 1722 */ 1723int API_EXPORTED libusb_wait_for_event(libusb_context *ctx, struct timeval *tv) 1724{ 1725 struct timespec timeout; 1726 int r; 1727 1728 USBI_GET_CONTEXT(ctx); 1729 if (tv == NULL) { 1730 usbi_cond_wait(&ctx->event_waiters_cond, &ctx->event_waiters_lock); 1731 return 0; 1732 } 1733 1734 r = usbi_backend->clock_gettime(USBI_CLOCK_REALTIME, &timeout); 1735 if (r < 0) { 1736 usbi_err(ctx, "failed to read realtime clock, error %d", errno); 1737 return LIBUSB_ERROR_OTHER; 1738 } 1739 1740 timeout.tv_sec += tv->tv_sec; 1741 timeout.tv_nsec += tv->tv_usec * 1000; 1742 if (timeout.tv_nsec > 1000000000) { 1743 timeout.tv_nsec -= 1000000000; 1744 timeout.tv_sec++; 1745 } 1746 1747 r = usbi_cond_timedwait(&ctx->event_waiters_cond, 1748 &ctx->event_waiters_lock, &timeout); 1749 return (r == ETIMEDOUT); 1750} 1751 1752static void handle_timeout(struct usbi_transfer *itransfer) 1753{ 1754 struct libusb_transfer *transfer = 1755 USBI_TRANSFER_TO_LIBUSB_TRANSFER(itransfer); 1756 int r; 1757 1758 itransfer->flags |= USBI_TRANSFER_TIMED_OUT; 1759 r = libusb_cancel_transfer(transfer); 1760 if (r < 0) 1761 usbi_warn(TRANSFER_CTX(transfer), 1762 "async cancel failed %d errno=%d", r, errno); 1763} 1764 1765static int handle_timeouts_locked(struct libusb_context *ctx) 1766{ 1767 int r; 1768 struct timespec systime_ts; 1769 struct timeval systime; 1770 struct usbi_transfer *transfer; 1771 1772 if (list_empty(&ctx->flying_transfers)) 1773 return 0; 1774 1775 /* get current time */ 1776 r = usbi_backend->clock_gettime(USBI_CLOCK_MONOTONIC, &systime_ts); 1777 if (r < 0) 1778 return r; 1779 1780 TIMESPEC_TO_TIMEVAL(&systime, &systime_ts); 1781 1782 /* iterate through flying transfers list, finding all transfers that 1783 * have expired timeouts */ 1784 list_for_each_entry(transfer, &ctx->flying_transfers, list, struct usbi_transfer) { 1785 struct timeval *cur_tv = &transfer->timeout; 1786 1787 /* if we've reached transfers of infinite timeout, we're all done */ 1788 if (!timerisset(cur_tv)) 1789 return 0; 1790 1791 /* ignore timeouts we've already handled */ 1792 if (transfer->flags & (USBI_TRANSFER_TIMED_OUT | USBI_TRANSFER_OS_HANDLES_TIMEOUT)) 1793 continue; 1794 1795 /* if transfer has non-expired timeout, nothing more to do */ 1796 if ((cur_tv->tv_sec > systime.tv_sec) || 1797 (cur_tv->tv_sec == systime.tv_sec && 1798 cur_tv->tv_usec > systime.tv_usec)) 1799 return 0; 1800 1801 /* otherwise, we've got an expired timeout to handle */ 1802 handle_timeout(transfer); 1803 } 1804 return 0; 1805} 1806 1807static int handle_timeouts(struct libusb_context *ctx) 1808{ 1809 int r; 1810 USBI_GET_CONTEXT(ctx); 1811 usbi_mutex_lock(&ctx->flying_transfers_lock); 1812 r = handle_timeouts_locked(ctx); 1813 usbi_mutex_unlock(&ctx->flying_transfers_lock); 1814 return r; 1815} 1816 1817#ifdef USBI_TIMERFD_AVAILABLE 1818static int handle_timerfd_trigger(struct libusb_context *ctx) 1819{ 1820 int r; 1821 1822 r = disarm_timerfd(ctx); 1823 if (r < 0) 1824 return r; 1825 1826 usbi_mutex_lock(&ctx->flying_transfers_lock); 1827 1828 /* process the timeout that just happened */ 1829 r = handle_timeouts_locked(ctx); 1830 if (r < 0) 1831 goto out; 1832 1833 /* arm for next timeout*/ 1834 r = arm_timerfd_for_next_timeout(ctx); 1835 1836out: 1837 usbi_mutex_unlock(&ctx->flying_transfers_lock); 1838 return r; 1839} 1840#endif 1841 1842/* do the actual event handling. assumes that no other thread is concurrently 1843 * doing the same thing. */ 1844static int handle_events(struct libusb_context *ctx, struct timeval *tv) 1845{ 1846 int r; 1847 struct usbi_pollfd *ipollfd; 1848 POLL_NFDS_TYPE nfds = 0; 1849 struct pollfd *fds; 1850 int i = -1; 1851 int timeout_ms; 1852 1853 usbi_mutex_lock(&ctx->pollfds_lock); 1854 list_for_each_entry(ipollfd, &ctx->pollfds, list, struct usbi_pollfd) 1855 nfds++; 1856 1857 /* TODO: malloc when number of fd's changes, not on every poll */ 1858 fds = malloc(sizeof(*fds) * nfds); 1859 if (!fds) { 1860 usbi_mutex_unlock(&ctx->pollfds_lock); 1861 return LIBUSB_ERROR_NO_MEM; 1862 } 1863 1864 list_for_each_entry(ipollfd, &ctx->pollfds, list, struct usbi_pollfd) { 1865 struct libusb_pollfd *pollfd = &ipollfd->pollfd; 1866 int fd = pollfd->fd; 1867 i++; 1868 fds[i].fd = fd; 1869 fds[i].events = pollfd->events; 1870 fds[i].revents = 0; 1871 } 1872 usbi_mutex_unlock(&ctx->pollfds_lock); 1873 1874 timeout_ms = (tv->tv_sec * 1000) + (tv->tv_usec / 1000); 1875 1876 /* round up to next millisecond */ 1877 if (tv->tv_usec % 1000) 1878 timeout_ms++; 1879 1880 usbi_dbg("poll() %d fds with timeout in %dms", nfds, timeout_ms); 1881 r = usbi_poll(fds, nfds, timeout_ms); 1882 usbi_dbg("poll() returned %d", r); 1883 if (r == 0) { 1884 free(fds); 1885 return handle_timeouts(ctx); 1886 } else if (r == -1 && errno == EINTR) { 1887 free(fds); 1888 return LIBUSB_ERROR_INTERRUPTED; 1889 } else if (r < 0) { 1890 free(fds); 1891 usbi_err(ctx, "poll failed %d err=%d\n", r, errno); 1892 return LIBUSB_ERROR_IO; 1893 } 1894 1895 /* fd[0] is always the ctrl pipe */ 1896 if (fds[0].revents) { 1897 /* another thread wanted to interrupt event handling, and it succeeded! 1898 * handle any other events that cropped up at the same time, and 1899 * simply return */ 1900 usbi_dbg("caught a fish on the control pipe"); 1901 1902 if (r == 1) { 1903 r = 0; 1904 goto handled; 1905 } else { 1906 /* prevent OS backend from trying to handle events on ctrl pipe */ 1907 fds[0].revents = 0; 1908 r--; 1909 } 1910 } 1911 1912#ifdef USBI_TIMERFD_AVAILABLE 1913 /* on timerfd configurations, fds[1] is the timerfd */ 1914 if (usbi_using_timerfd(ctx) && fds[1].revents) { 1915 /* timerfd indicates that a timeout has expired */ 1916 int ret; 1917 usbi_dbg("timerfd triggered"); 1918 1919 ret = handle_timerfd_trigger(ctx); 1920 if (ret < 0) { 1921 /* return error code */ 1922 r = ret; 1923 goto handled; 1924 } else if (r == 1) { 1925 /* no more active file descriptors, nothing more to do */ 1926 r = 0; 1927 goto handled; 1928 } else { 1929 /* more events pending... 1930 * prevent OS backend from trying to handle events on timerfd */ 1931 fds[1].revents = 0; 1932 r--; 1933 } 1934 } 1935#endif 1936 1937 r = usbi_backend->handle_events(ctx, fds, nfds, r); 1938 if (r) 1939 usbi_err(ctx, "backend handle_events failed with error %d", r); 1940 1941handled: 1942 free(fds); 1943 return r; 1944} 1945 1946/* returns the smallest of: 1947 * 1. timeout of next URB 1948 * 2. user-supplied timeout 1949 * returns 1 if there is an already-expired timeout, otherwise returns 0 1950 * and populates out 1951 */ 1952static int get_next_timeout(libusb_context *ctx, struct timeval *tv, 1953 struct timeval *out) 1954{ 1955 struct timeval timeout; 1956 int r = libusb_get_next_timeout(ctx, &timeout); 1957 if (r) { 1958 /* timeout already expired? */ 1959 if (!timerisset(&timeout)) 1960 return 1; 1961 1962 /* choose the smallest of next URB timeout or user specified timeout */ 1963 if (timercmp(&timeout, tv, <)) 1964 *out = timeout; 1965 else 1966 *out = *tv; 1967 } else { 1968 *out = *tv; 1969 } 1970 return 0; 1971} 1972 1973/** \ingroup poll 1974 * Handle any pending events. 1975 * 1976 * libusb determines "pending events" by checking if any timeouts have expired 1977 * and by checking the set of file descriptors for activity. 1978 * 1979 * If a zero timeval is passed, this function will handle any already-pending 1980 * events and then immediately return in non-blocking style. 1981 * 1982 * If a non-zero timeval is passed and no events are currently pending, this 1983 * function will block waiting for events to handle up until the specified 1984 * timeout. If an event arrives or a signal is raised, this function will 1985 * return early. 1986 * 1987 * If the parameter completed is not NULL then <em>after obtaining the event 1988 * handling lock</em> this function will return immediately if the integer 1989 * pointed to is not 0. This allows for race free waiting for the completion 1990 * of a specific transfer. 1991 * 1992 * \param ctx the context to operate on, or NULL for the default context 1993 * \param tv the maximum time to block waiting for events, or an all zero 1994 * timeval struct for non-blocking mode 1995 * \param completed pointer to completion integer to check, or NULL 1996 * \returns 0 on success, or a LIBUSB_ERROR code on failure 1997 * \see \ref mtasync 1998 */ 1999int API_EXPORTED libusb_handle_events_timeout_completed(libusb_context *ctx, 2000 struct timeval *tv, int *completed) 2001{ 2002 int r; 2003 struct timeval poll_timeout; 2004 2005 USBI_GET_CONTEXT(ctx); 2006 r = get_next_timeout(ctx, tv, &poll_timeout); 2007 if (r) { 2008 /* timeout already expired */ 2009 return handle_timeouts(ctx); 2010 } 2011 2012retry: 2013 if (libusb_try_lock_events(ctx) == 0) { 2014 if (completed == NULL || !*completed) { 2015 /* we obtained the event lock: do our own event handling */ 2016 usbi_dbg("doing our own event handling"); 2017 r = handle_events(ctx, &poll_timeout); 2018 } 2019 libusb_unlock_events(ctx); 2020 return r; 2021 } 2022 2023 /* another thread is doing event handling. wait for pthread events that 2024 * notify event completion. */ 2025 libusb_lock_event_waiters(ctx); 2026 2027 if (completed && *completed) 2028 goto already_done; 2029 2030 if (!libusb_event_handler_active(ctx)) { 2031 /* we hit a race: whoever was event handling earlier finished in the 2032 * time it took us to reach this point. try the cycle again. */ 2033 libusb_unlock_event_waiters(ctx); 2034 usbi_dbg("event handler was active but went away, retrying"); 2035 goto retry; 2036 } 2037 2038 usbi_dbg("another thread is doing event handling"); 2039 r = libusb_wait_for_event(ctx, &poll_timeout); 2040 2041already_done: 2042 libusb_unlock_event_waiters(ctx); 2043 2044 if (r < 0) 2045 return r; 2046 else if (r == 1) 2047 return handle_timeouts(ctx); 2048 else 2049 return 0; 2050} 2051 2052/** \ingroup poll 2053 * Handle any pending events 2054 * 2055 * Like libusb_handle_events_timeout_completed(), but without the completed 2056 * parameter, calling this function is equivalent to calling 2057 * libusb_handle_events_timeout_completed() with a NULL completed parameter. 2058 * 2059 * This function is kept primarily for backwards compatibility. 2060 * All new code should call libusb_handle_events_completed() or 2061 * libusb_handle_events_timeout_completed() to avoid race conditions. 2062 * 2063 * \param ctx the context to operate on, or NULL for the default context 2064 * \param tv the maximum time to block waiting for events, or an all zero 2065 * timeval struct for non-blocking mode 2066 * \returns 0 on success, or a LIBUSB_ERROR code on failure 2067 */ 2068int API_EXPORTED libusb_handle_events_timeout(libusb_context *ctx, 2069 struct timeval *tv) 2070{ 2071 return libusb_handle_events_timeout_completed(ctx, tv, NULL); 2072} 2073 2074/** \ingroup poll 2075 * Handle any pending events in blocking mode. There is currently a timeout 2076 * hardcoded at 60 seconds but we plan to make it unlimited in future. For 2077 * finer control over whether this function is blocking or non-blocking, or 2078 * for control over the timeout, use libusb_handle_events_timeout_completed() 2079 * instead. 2080 * 2081 * This function is kept primarily for backwards compatibility. 2082 * All new code should call libusb_handle_events_completed() or 2083 * libusb_handle_events_timeout_completed() to avoid race conditions. 2084 * 2085 * \param ctx the context to operate on, or NULL for the default context 2086 * \returns 0 on success, or a LIBUSB_ERROR code on failure 2087 */ 2088int API_EXPORTED libusb_handle_events(libusb_context *ctx) 2089{ 2090 struct timeval tv; 2091 tv.tv_sec = 60; 2092 tv.tv_usec = 0; 2093 return libusb_handle_events_timeout_completed(ctx, &tv, NULL); 2094} 2095 2096/** \ingroup poll 2097 * Handle any pending events in blocking mode. 2098 * 2099 * Like libusb_handle_events(), with the addition of a completed parameter 2100 * to allow for race free waiting for the completion of a specific transfer. 2101 * 2102 * See libusb_handle_events_timeout_completed() for details on the completed 2103 * parameter. 2104 * 2105 * \param ctx the context to operate on, or NULL for the default context 2106 * \param completed pointer to completion integer to check, or NULL 2107 * \returns 0 on success, or a LIBUSB_ERROR code on failure 2108 * \see \ref mtasync 2109 */ 2110int API_EXPORTED libusb_handle_events_completed(libusb_context *ctx, 2111 int *completed) 2112{ 2113 struct timeval tv; 2114 tv.tv_sec = 60; 2115 tv.tv_usec = 0; 2116 return libusb_handle_events_timeout_completed(ctx, &tv, completed); 2117} 2118 2119/** \ingroup poll 2120 * Handle any pending events by polling file descriptors, without checking if 2121 * any other threads are already doing so. Must be called with the event lock 2122 * held, see libusb_lock_events(). 2123 * 2124 * This function is designed to be called under the situation where you have 2125 * taken the event lock and are calling poll()/select() directly on libusb's 2126 * file descriptors (as opposed to using libusb_handle_events() or similar). 2127 * You detect events on libusb's descriptors, so you then call this function 2128 * with a zero timeout value (while still holding the event lock). 2129 * 2130 * \param ctx the context to operate on, or NULL for the default context 2131 * \param tv the maximum time to block waiting for events, or zero for 2132 * non-blocking mode 2133 * \returns 0 on success, or a LIBUSB_ERROR code on failure 2134 * \see \ref mtasync 2135 */ 2136int API_EXPORTED libusb_handle_events_locked(libusb_context *ctx, 2137 struct timeval *tv) 2138{ 2139 int r; 2140 struct timeval poll_timeout; 2141 2142 USBI_GET_CONTEXT(ctx); 2143 r = get_next_timeout(ctx, tv, &poll_timeout); 2144 if (r) { 2145 /* timeout already expired */ 2146 return handle_timeouts(ctx); 2147 } 2148 2149 return handle_events(ctx, &poll_timeout); 2150} 2151 2152/** \ingroup poll 2153 * Determines whether your application must apply special timing considerations 2154 * when monitoring libusb's file descriptors. 2155 * 2156 * This function is only useful for applications which retrieve and poll 2157 * libusb's file descriptors in their own main loop (\ref pollmain). 2158 * 2159 * Ordinarily, libusb's event handler needs to be called into at specific 2160 * moments in time (in addition to times when there is activity on the file 2161 * descriptor set). The usual approach is to use libusb_get_next_timeout() 2162 * to learn about when the next timeout occurs, and to adjust your 2163 * poll()/select() timeout accordingly so that you can make a call into the 2164 * library at that time. 2165 * 2166 * Some platforms supported by libusb do not come with this baggage - any 2167 * events relevant to timing will be represented by activity on the file 2168 * descriptor set, and libusb_get_next_timeout() will always return 0. 2169 * This function allows you to detect whether you are running on such a 2170 * platform. 2171 * 2172 * Since v1.0.5. 2173 * 2174 * \param ctx the context to operate on, or NULL for the default context 2175 * \returns 0 if you must call into libusb at times determined by 2176 * libusb_get_next_timeout(), or 1 if all timeout events are handled internally 2177 * or through regular activity on the file descriptors. 2178 * \see \ref pollmain "Polling libusb file descriptors for event handling" 2179 */ 2180int API_EXPORTED libusb_pollfds_handle_timeouts(libusb_context *ctx) 2181{ 2182#if defined(USBI_TIMERFD_AVAILABLE) 2183 USBI_GET_CONTEXT(ctx); 2184 return usbi_using_timerfd(ctx); 2185#else 2186 (void)ctx; 2187 return 0; 2188#endif 2189} 2190 2191/** \ingroup poll 2192 * Determine the next internal timeout that libusb needs to handle. You only 2193 * need to use this function if you are calling poll() or select() or similar 2194 * on libusb's file descriptors yourself - you do not need to use it if you 2195 * are calling libusb_handle_events() or a variant directly. 2196 * 2197 * You should call this function in your main loop in order to determine how 2198 * long to wait for select() or poll() to return results. libusb needs to be 2199 * called into at this timeout, so you should use it as an upper bound on 2200 * your select() or poll() call. 2201 * 2202 * When the timeout has expired, call into libusb_handle_events_timeout() 2203 * (perhaps in non-blocking mode) so that libusb can handle the timeout. 2204 * 2205 * This function may return 1 (success) and an all-zero timeval. If this is 2206 * the case, it indicates that libusb has a timeout that has already expired 2207 * so you should call libusb_handle_events_timeout() or similar immediately. 2208 * A return code of 0 indicates that there are no pending timeouts. 2209 * 2210 * On some platforms, this function will always returns 0 (no pending 2211 * timeouts). See \ref polltime. 2212 * 2213 * \param ctx the context to operate on, or NULL for the default context 2214 * \param tv output location for a relative time against the current 2215 * clock in which libusb must be called into in order to process timeout events 2216 * \returns 0 if there are no pending timeouts, 1 if a timeout was returned, 2217 * or LIBUSB_ERROR_OTHER on failure 2218 */ 2219int API_EXPORTED libusb_get_next_timeout(libusb_context *ctx, 2220 struct timeval *tv) 2221{ 2222 struct usbi_transfer *transfer; 2223 struct timespec cur_ts; 2224 struct timeval cur_tv; 2225 struct timeval *next_timeout; 2226 int r; 2227 int found = 0; 2228 2229 USBI_GET_CONTEXT(ctx); 2230 if (usbi_using_timerfd(ctx)) 2231 return 0; 2232 2233 usbi_mutex_lock(&ctx->flying_transfers_lock); 2234 if (list_empty(&ctx->flying_transfers)) { 2235 usbi_mutex_unlock(&ctx->flying_transfers_lock); 2236 usbi_dbg("no URBs, no timeout!"); 2237 return 0; 2238 } 2239 2240 /* find next transfer which hasn't already been processed as timed out */ 2241 list_for_each_entry(transfer, &ctx->flying_transfers, list, struct usbi_transfer) { 2242 if (transfer->flags & (USBI_TRANSFER_TIMED_OUT | USBI_TRANSFER_OS_HANDLES_TIMEOUT)) 2243 continue; 2244 2245 /* no timeout for this transfer? */ 2246 if (!timerisset(&transfer->timeout)) 2247 continue; 2248 2249 found = 1; 2250 break; 2251 } 2252 usbi_mutex_unlock(&ctx->flying_transfers_lock); 2253 2254 if (!found) { 2255 usbi_dbg("no URB with timeout or all handled by OS; no timeout!"); 2256 return 0; 2257 } 2258 2259 next_timeout = &transfer->timeout; 2260 2261 r = usbi_backend->clock_gettime(USBI_CLOCK_MONOTONIC, &cur_ts); 2262 if (r < 0) { 2263 usbi_err(ctx, "failed to read monotonic clock, errno=%d", errno); 2264 return LIBUSB_ERROR_OTHER; 2265 } 2266 TIMESPEC_TO_TIMEVAL(&cur_tv, &cur_ts); 2267 2268 if (!timercmp(&cur_tv, next_timeout, <)) { 2269 usbi_dbg("first timeout already expired"); 2270 timerclear(tv); 2271 } else { 2272 timersub(next_timeout, &cur_tv, tv); 2273 usbi_dbg("next timeout in %d.%06ds", tv->tv_sec, tv->tv_usec); 2274 } 2275 2276 return 1; 2277} 2278 2279/** \ingroup poll 2280 * Register notification functions for file descriptor additions/removals. 2281 * These functions will be invoked for every new or removed file descriptor 2282 * that libusb uses as an event source. 2283 * 2284 * To remove notifiers, pass NULL values for the function pointers. 2285 * 2286 * Note that file descriptors may have been added even before you register 2287 * these notifiers (e.g. at libusb_init() time). 2288 * 2289 * Additionally, note that the removal notifier may be called during 2290 * libusb_exit() (e.g. when it is closing file descriptors that were opened 2291 * and added to the poll set at libusb_init() time). If you don't want this, 2292 * remove the notifiers immediately before calling libusb_exit(). 2293 * 2294 * \param ctx the context to operate on, or NULL for the default context 2295 * \param added_cb pointer to function for addition notifications 2296 * \param removed_cb pointer to function for removal notifications 2297 * \param user_data User data to be passed back to callbacks (useful for 2298 * passing context information) 2299 */ 2300void API_EXPORTED libusb_set_pollfd_notifiers(libusb_context *ctx, 2301 libusb_pollfd_added_cb added_cb, libusb_pollfd_removed_cb removed_cb, 2302 void *user_data) 2303{ 2304 USBI_GET_CONTEXT(ctx); 2305 ctx->fd_added_cb = added_cb; 2306 ctx->fd_removed_cb = removed_cb; 2307 ctx->fd_cb_user_data = user_data; 2308} 2309 2310/* Add a file descriptor to the list of file descriptors to be monitored. 2311 * events should be specified as a bitmask of events passed to poll(), e.g. 2312 * POLLIN and/or POLLOUT. */ 2313int usbi_add_pollfd(struct libusb_context *ctx, int fd, short events) 2314{ 2315 struct usbi_pollfd *ipollfd = malloc(sizeof(*ipollfd)); 2316 if (!ipollfd) 2317 return LIBUSB_ERROR_NO_MEM; 2318 2319 usbi_dbg("add fd %d events %d", fd, events); 2320 ipollfd->pollfd.fd = fd; 2321 ipollfd->pollfd.events = events; 2322 usbi_mutex_lock(&ctx->pollfds_lock); 2323 list_add_tail(&ipollfd->list, &ctx->pollfds); 2324 usbi_mutex_unlock(&ctx->pollfds_lock); 2325 2326 if (ctx->fd_added_cb) 2327 ctx->fd_added_cb(fd, events, ctx->fd_cb_user_data); 2328 return 0; 2329} 2330 2331/* Remove a file descriptor from the list of file descriptors to be polled. */ 2332void usbi_remove_pollfd(struct libusb_context *ctx, int fd) 2333{ 2334 struct usbi_pollfd *ipollfd; 2335 int found = 0; 2336 2337 usbi_dbg("remove fd %d", fd); 2338 usbi_mutex_lock(&ctx->pollfds_lock); 2339 list_for_each_entry(ipollfd, &ctx->pollfds, list, struct usbi_pollfd) 2340 if (ipollfd->pollfd.fd == fd) { 2341 found = 1; 2342 break; 2343 } 2344 2345 if (!found) { 2346 usbi_dbg("couldn't find fd %d to remove", fd); 2347 usbi_mutex_unlock(&ctx->pollfds_lock); 2348 return; 2349 } 2350 2351 list_del(&ipollfd->list); 2352 usbi_mutex_unlock(&ctx->pollfds_lock); 2353 free(ipollfd); 2354 if (ctx->fd_removed_cb) 2355 ctx->fd_removed_cb(fd, ctx->fd_cb_user_data); 2356} 2357 2358/** \ingroup poll 2359 * Retrieve a list of file descriptors that should be polled by your main loop 2360 * as libusb event sources. 2361 * 2362 * The returned list is NULL-terminated and should be freed with free() when 2363 * done. The actual list contents must not be touched. 2364 * 2365 * As file descriptors are a Unix-specific concept, this function is not 2366 * available on Windows and will always return NULL. 2367 * 2368 * \param ctx the context to operate on, or NULL for the default context 2369 * \returns a NULL-terminated list of libusb_pollfd structures 2370 * \returns NULL on error 2371 * \returns NULL on platforms where the functionality is not available 2372 */ 2373DEFAULT_VISIBILITY 2374const struct libusb_pollfd ** LIBUSB_CALL libusb_get_pollfds( 2375 libusb_context *ctx) 2376{ 2377#ifndef OS_WINDOWS 2378 struct libusb_pollfd **ret = NULL; 2379 struct usbi_pollfd *ipollfd; 2380 size_t i = 0; 2381 size_t cnt = 0; 2382 USBI_GET_CONTEXT(ctx); 2383 2384 usbi_mutex_lock(&ctx->pollfds_lock); 2385 list_for_each_entry(ipollfd, &ctx->pollfds, list, struct usbi_pollfd) 2386 cnt++; 2387 2388 ret = calloc(cnt + 1, sizeof(struct libusb_pollfd *)); 2389 if (!ret) 2390 goto out; 2391 2392 list_for_each_entry(ipollfd, &ctx->pollfds, list, struct usbi_pollfd) 2393 ret[i++] = (struct libusb_pollfd *) ipollfd; 2394 ret[cnt] = NULL; 2395 2396out: 2397 usbi_mutex_unlock(&ctx->pollfds_lock); 2398 return (const struct libusb_pollfd **) ret; 2399#else 2400 return NULL; 2401#endif 2402} 2403 2404/* Backends call this from handle_events to report disconnection of a device. 2405 * The transfers get cancelled appropriately. 2406 */ 2407void usbi_handle_disconnect(struct libusb_device_handle *handle) 2408{ 2409 struct usbi_transfer *cur; 2410 struct usbi_transfer *to_cancel; 2411 2412 usbi_dbg("device %d.%d", 2413 handle->dev->bus_number, handle->dev->device_address); 2414 2415 /* terminate all pending transfers with the LIBUSB_TRANSFER_NO_DEVICE 2416 * status code. 2417 * 2418 * this is a bit tricky because: 2419 * 1. we can't do transfer completion while holding flying_transfers_lock 2420 * 2. the transfers list can change underneath us - if we were to build a 2421 * list of transfers to complete (while holding look), the situation 2422 * might be different by the time we come to free them 2423 * 2424 * so we resort to a loop-based approach as below 2425 * FIXME: is this still potentially racy? 2426 */ 2427 2428 while (1) { 2429 usbi_mutex_lock(&HANDLE_CTX(handle)->flying_transfers_lock); 2430 to_cancel = NULL; 2431 list_for_each_entry(cur, &HANDLE_CTX(handle)->flying_transfers, list, struct usbi_transfer) 2432 if (USBI_TRANSFER_TO_LIBUSB_TRANSFER(cur)->dev_handle == handle) { 2433 to_cancel = cur; 2434 break; 2435 } 2436 usbi_mutex_unlock(&HANDLE_CTX(handle)->flying_transfers_lock); 2437 2438 if (!to_cancel) 2439 break; 2440 2441 usbi_backend->clear_transfer_priv(to_cancel); 2442 usbi_handle_transfer_completion(to_cancel, LIBUSB_TRANSFER_NO_DEVICE); 2443 } 2444 2445} 2446