libusb/core.c

   1 /*
   2  * Core functions for libusb
   3  * Copyright (C) 2007-2008 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
  23 #include <errno.h>
  24 #include <poll.h>
  25 #include <stdarg.h>
  26 #include <stdio.h>
  27 #include <stdlib.h>
  28 #include <string.h>
  29
  30 #include "libusb.h"
  31 #include "libusbi.h"
  32
  33 #ifdef OS_LINUX
  34 const struct usbi_os_backend * const usbi_backend = &linux_usbfs_backend;
  35 #else
  36 #error "Unsupported OS"
  37 #endif
  38
  39 static struct list_head usb_devs;
  40 static pthread_mutex_t usb_devs_lock = PTHREAD_MUTEX_INITIALIZER;
  41
  42 struct list_head usbi_open_devs;
  43 pthread_mutex_t usbi_open_devs_lock = PTHREAD_MUTEX_INITIALIZER;
  44
  45 /**
  46  * \mainpage libusb-1.0 API Reference
  47  * libusb is an open source library that allows you to communicate with USB
  48  * devices from userspace. For more info, see the
  49  * <a href="http://libusb.sourceforge.net">libusb homepage</a>.
  50  *
  51  * This documentation is aimed at application developers wishing to
  52  * communicate with USB peripherals from their own software. After reviewing
  53  * this documentation, feedback and questions can be sent to the
  54  * <a href="http://sourceforge.net/mail/?group_id=1674">libusb-devel mailing
  55  * list</a>.
  56  */
  57
  58 /**
  59  * @defgroup lib Library initialization/deinitialization
  60  * This page details how to initialize and deinitialize libusb. Initialization
  61  * must be performed before using any libusb functionality, and similarly you
  62  * must not call any libusb functions after deinitialization.
  63  */
  64
  65 /**
  66  * @defgroup dev Device handling and enumeration
  67  * The functionality documented below is designed to help with the following
  68  * operations:
  69  * - Enumerating the USB devices currently attached to the system
  70  * - Choosing a device to operate from your software
  71  * - Opening and closing the chosen device
  72  *
  73  * \section nutshell In a nutshell...
  74  *
  75  * The description below really makes things sound more complicated than they
  76  * actually are. The following sequence of function calls will be suitable
  77  * for almost all scenarios and does not require you to have such a deep
  78  * understanding of the resource management issues:
  79  * \code
  80 // discover devices
  81 libusb_device **list;
  82 libusb_device *found = NULL;
  83 size_t cnt = libusb_get_device_list(&list);
  84 size_t i = 0;
  85 if (cnt < 0)
  86         error();
  87
  88 for (i = 0; i < cnt; i++) {
  89         libusb_device *device = list[i];
  90         if (is_interesting(device)) {
  91                 found = device;
  92                 break;
  93         }
  94 }
  95
  96 if (found) {
  97         libusb_device_handle *handle = libusb_open(found);
  98         // etc
  99 }
 100
 101 libusb_free_device_list(list, 1);
 102 \endcode
 103  *
 104  * The two important points:
 105  * - You asked libusb_free_device_list() to unreference the devices (2nd
 106  *   parameter)
 107  * - You opened the device before freeing the list and unreferencing the
 108  *   devices
 109  *
 110  * If you ended up with a handle, you can now proceed to perform I/O on the
 111  * device.
 112  *
 113  * \section devshandles Devices and device handles
 114  * libusb has a concept of a USB device, represented by the
 115  * \ref libusb_device opaque type. A device represents a USB device that
 116  * is currently or was previously connected to the system. Using a reference
 117  * to a device, you can determine certain information about the device (e.g.
 118  * you can read the descriptor data).
 119  *
 120  * The libusb_get_device_list() function can be used to obtain a list of
 121  * devices currently connected to the system. This is known as device
 122  * discovery.
 123  *
 124  * Just because you have a reference to a device does not mean it is
 125  * necessarily usable. The device may have been unplugged, you may not have
 126  * permission to operate such device, or another program or driver may be
 127  * using the device.
 128  *
 129  * When you've found a device that you'd like to operate, you must ask
 130  * libusb to open the device using the libusb_open() function. Assuming
 131  * success, libusb then returns you a <em>device handle</em>
 132  * (a \ref libusb_device_handle pointer). All "real" I/O operations then
 133  * operate on the handle rather than the original device pointer.
 134  *
 135  * \section devref Device discovery and reference counting
 136  *
 137  * Device discovery (i.e. calling libusb_get_device_list()) returns a
 138  * freshly-allocated list of devices. The list itself must be freed when
 139  * you are done with it. libusb also needs to know when it is OK to free
 140  * the contents of the list - the devices themselves.
 141  *
 142  * To handle these issues, libusb provides you with two separate items:
 143  * - A function to free the list itself
 144  * - A reference counting system for the devices inside
 145  *
 146  * New devices presented by the libusb_get_device_list() function all have a
 147  * reference count of 1. You can increase and decrease reference count using
 148  * libusb_ref_device() and libusb_unref_device(). A device is destroyed when
 149  * it's reference count reaches 0.
 150  *
 151  * With the above information in mind, the process of opening a device can
 152  * be viewed as follows:
 153  * -# Discover devices using libusb_get_device_list().
 154  * -# Choose the device that you want to operate, and call libusb_open().
 155  * -# Unref all devices in the discovered device list.
 156  * -# Free the discovered device list.
 157  *
 158  * The order is important - you must not unreference the device before
 159  * attempting to open it, because unreferencing it may destroy the device.
 160  *
 161  * For convenience, the libusb_free_device_list() function includes a
 162  * parameter to optionally unreference all the devices in the list before
 163  * freeing the list itself. This combines steps 3 and 4 above.
 164  *
 165  * As an implementation detail, libusb_open() actually adds a reference to
 166  * the device in question. This is because the device remains available
 167  * through the handle via libusb_get_device(). The reference is deleted during
 168  * libusb_close().
 169  */
 170
 171 /**
 172  * @defgroup misc Miscellaneous structures and constants
 173  * This page documents structures and constants that don't belong anywhere
 174  * else
 175  */
 176
 177 /* we traverse usbfs without knowing how many devices we are going to find.
 178  * so we create this discovered_devs model which is similar to a linked-list
 179  * which grows when required. it can be freed once discovery has completed,
 180  * eliminating the need for a list node in the libusb_device structure
 181  * itself. */
 182 #define DISCOVERED_DEVICES_SIZE_STEP 8
 183
 184 static struct discovered_devs *discovered_devs_alloc(void)
 185 {
 186         struct discovered_devs *ret =
 187                 malloc(sizeof(*ret) + (sizeof(void *) * DISCOVERED_DEVICES_SIZE_STEP));
 188
 189         if (ret) {
 190                 ret->len = 0;
 191                 ret->capacity = DISCOVERED_DEVICES_SIZE_STEP;
 192         }
 193         return ret;
 194 }
 195
 196 /* append a device to the discovered devices collection. may realloc itself,
 197  * returning new discdevs. returns NULL on realloc failure. */
 198 struct discovered_devs *discovered_devs_append(
 199         struct discovered_devs *discdevs, struct libusb_device *dev)
 200 {
 201         size_t len = discdevs->len;
 202         size_t capacity;
 203
 204         /* if there is space, just append the device */
 205         if (len < discdevs->capacity) {
 206                 discdevs->devices[len] = libusb_ref_device(dev);
 207                 discdevs->len++;
 208                 return discdevs;
 209         }
 210
 211         /* exceeded capacity, need to grow */
 212         usbi_dbg("need to increase capacity");
 213         capacity = discdevs->capacity + DISCOVERED_DEVICES_SIZE_STEP;
 214         discdevs = realloc(discdevs,
 215                 sizeof(*discdevs) + (sizeof(void *) * capacity));
 216         if (discdevs) {
 217                 discdevs->capacity = capacity;
 218                 discdevs->devices[len] = libusb_ref_device(dev);
 219                 discdevs->len++;
 220         }
 221
 222         return discdevs;
 223 }
 224
 225 static void discovered_devs_free(struct discovered_devs *discdevs)
 226 {
 227         size_t i;
 228
 229         for (i = 0; i < discdevs->len; i++)
 230                 libusb_unref_device(discdevs->devices[i]);
 231
 232         free(discdevs);
 233 }
 234
 235 /* allocate a new device with reference count 1 */
 236 struct libusb_device *usbi_alloc_device(unsigned long session_id)
 237 {
 238         size_t priv_size = usbi_backend->device_priv_size;
 239         struct libusb_device *dev = malloc(sizeof(*dev) + priv_size);
 240         int r;
 241
 242         if (!dev)
 243                 return NULL;
 244
 245         r = pthread_mutex_init(&dev->lock, NULL);
 246         if (r)
 247                 return NULL;
 248
 249         dev->refcnt = 1;
 250         dev->session_data = session_id;
 251         memset(&dev->os_priv, 0, priv_size);
 252
 253         pthread_mutex_lock(&usb_devs_lock);
 254         list_add(&dev->list, &usb_devs);
 255         pthread_mutex_unlock(&usb_devs_lock);
 256         return dev;
 257 }
 258
 259 /* call the OS discovery routines to populate descriptors etc */
 260 int usbi_discover_device(struct libusb_device *dev)
 261 {
 262         int r;
 263         int i;
 264         void *user_data;
 265         unsigned char raw_desc[DEVICE_DESC_LENGTH];
 266         size_t alloc_size;
 267
 268         dev->config = NULL;
 269
 270         r = usbi_backend->begin_discovery(dev, &user_data);
 271         if (r < 0)
 272                 return r;
 273
 274         r = usbi_backend->get_device_descriptor(dev, raw_desc, user_data);
 275         if (r < 0)
 276                 goto err;
 277
 278         usbi_parse_descriptor(raw_desc, "bbWbbbbWWWbbbb", &dev->desc);
 279
 280         if (dev->desc.bNumConfigurations > USB_MAXCONFIG) {
 281                 usbi_err("too many configurations");
 282                 r = -EINVAL;
 283                 goto err;
 284         }
 285
 286         if (dev->desc.bNumConfigurations < 1) {
 287                 usbi_dbg("no configurations?");
 288                 r = -EINVAL;
 289                 goto err;
 290         }
 291
 292         alloc_size = dev->desc.bNumConfigurations
 293                 * sizeof(struct libusb_config_descriptor);
 294         dev->config = malloc(alloc_size);
 295         if (!dev->config) {
 296                 r = LIBUSB_ERROR_NO_MEM;
 297                 goto err;
 298         }
 299
 300         memset(dev->config, 0, alloc_size);
 301         for (i = 0; i < dev->desc.bNumConfigurations; i++) {
 302                 unsigned char tmp[8];
 303                 unsigned char *bigbuffer;
 304                 struct libusb_config_descriptor config;
 305
 306                 r = usbi_backend->get_config_descriptor(dev, i, tmp, sizeof(tmp),
 307                         user_data);
 308                 if (r < 0)
 309                         goto err;
 310
 311                 usbi_parse_descriptor(tmp, "bbw", &config);
 312
 313                 bigbuffer = malloc(config.wTotalLength);
 314                 if (!bigbuffer) {
 315                         r = LIBUSB_ERROR_NO_MEM;
 316                         goto err;
 317                 }
 318
 319                 r = usbi_backend->get_config_descriptor(dev, i, bigbuffer,
 320                         config.wTotalLength, user_data);
 321                 if (r < 0) {
 322                         free(bigbuffer);
 323                         goto err;
 324                 }
 325
 326                 r = usbi_parse_configuration(&dev->config[i], bigbuffer);
 327                 free(bigbuffer);
 328                 if (r < 0) {
 329                         usbi_err("parse_configuration failed with code %d", r);
 330                         goto err;
 331                 } else if (r > 0) {
 332                         usbi_warn("descriptor data still left\n");
 333                 }
 334         }
 335
 336         usbi_backend->end_discovery(dev, user_data);
 337         return 0;
 338
 339 err:
 340         if (dev->config) {
 341                 usbi_clear_configurations(dev);
 342                 free(dev->config);
 343                 dev->config = NULL;
 344         }
 345
 346         usbi_backend->end_discovery(dev, user_data);
 347         return r;
 348 }
 349
 350 struct libusb_device *usbi_get_device_by_session_id(unsigned long session_id)
 351 {
 352         struct libusb_device *dev;
 353         struct libusb_device *ret = NULL;
 354
 355         pthread_mutex_lock(&usb_devs_lock);
 356         list_for_each_entry(dev, &usb_devs, list)
 357                 if (dev->session_data == session_id) {
 358                         ret = dev;
 359                         break;
 360                 }
 361         pthread_mutex_unlock(&usb_devs_lock);
 362
 363         return ret;
 364 }
 365
 366 /** @ingroup dev
 367  * Returns a list of USB devices currently attached to the system. This is
 368  * your entry point into finding a USB device to operate.
 369  *
 370  * You are expected to unreference all the devices when you are done with
 371  * them, and then free the list with libusb_free_device_list(). Note that
 372  * libusb_free_device_list() can unref all the devices for you. Be careful
 373  * not to unreference a device you are about to open until after you have
 374  * opened it.
 375  *
 376  * This return value of this function indicates the number of devices in
 377  * the resultant list. The list is actually one element larger, as it is
 378  * NULL-terminated.
 379  *
 380  * \param list output location for a list of devices. Must be later freed with
 381  * libusb_free_device_list().
 382  * \returns the number of devices in the outputted list, or LIBUSB_ERROR_NO_MEM
 383  * on memory allocation failure.
 384  */
 385 API_EXPORTED size_t libusb_get_device_list(libusb_device ***list)
 386 {
 387         struct discovered_devs *discdevs = discovered_devs_alloc();
 388         struct libusb_device **ret;
 389         int r = 0;
 390         size_t i;
 391         size_t len;
 392         usbi_dbg("");
 393
 394         if (!discdevs)
 395                 return LIBUSB_ERROR_NO_MEM;
 396
 397         r = usbi_backend->get_device_list(&discdevs);
 398         if (r < 0) {
 399                 len = r;
 400                 goto out;
 401         }
 402
 403         /* convert discovered_devs into a list */
 404         len = discdevs->len;
 405         ret = malloc(sizeof(void *) * (len + 1));
 406         if (!ret) {
 407                 len = LIBUSB_ERROR_NO_MEM;
 408                 goto out;
 409         }
 410
 411         ret[len] = NULL;
 412         for (i = 0; i < len; i++) {
 413                 struct libusb_device *dev = discdevs->devices[i];
 414                 ret[i] = libusb_ref_device(dev);
 415         }
 416         *list = ret;
 417
 418 out:
 419         discovered_devs_free(discdevs);
 420         return len;
 421 }
 422
 423 /** \ingroup dev
 424  * Frees a list of devices previously discovered using
 425  * libusb_get_device_list(). If the unref_devices parameter is set, the
 426  * reference count of each device in the list is decremented by 1.
 427  * \param list the list to free
 428  * \param unref_devices whether to unref the devices in the list
 429  */
 430 API_EXPORTED void libusb_free_device_list(libusb_device **list,
 431         int unref_devices)
 432 {
 433         if (!list)
 434                 return;
 435
 436         if (unref_devices) {
 437                 int i = 0;
 438                 struct libusb_device *dev;
 439
 440                 while ((dev = list[i++]) != NULL)
 441                         libusb_unref_device(dev);
 442         }
 443         free(list);
 444 }
 445
 446 /** \ingroup dev
 447  * Get the number of the bus that a device is connected to.
 448  * \param dev a device
 449  * \returns the bus number
 450  */
 451 API_EXPORTED uint8_t libusb_get_bus_number(libusb_device *dev)
 452 {
 453         return dev->bus_number;
 454 }
 455
 456 /** \ingroup dev
 457  * Get the address of the device on the bus it is connected to.
 458  * \param dev a device
 459  * \returns the device address
 460  */
 461 API_EXPORTED uint8_t libusb_get_device_address(libusb_device *dev)
 462 {
 463         return dev->device_address;
 464 }
 465
 466 /** \ingroup dev
 467  * Convenience function to retrieve the wMaxPacketSize value for a particular
 468  * endpoint. This is useful for setting up isochronous transfers.
 469  *
 470  * \param dev a device
 471  * \returns the wMaxPacketSize value, or LIBUSB_ERROR_NOT_FOUND if the endpoint
 472  * does not exist.
 473  */
 474 API_EXPORTED int libusb_get_max_packet_size(libusb_device *dev,
 475         unsigned char endpoint)
 476 {
 477         int iface_idx;
 478         /* FIXME: active config considerations? */
 479         struct libusb_config_descriptor *config = dev->config;
 480
 481         for (iface_idx = 0; iface_idx < config->bNumInterfaces; iface_idx++) {
 482                 const struct libusb_interface *iface = &config->interface[iface_idx];
 483                 int altsetting_idx;
 484
 485                 for (altsetting_idx = 0; altsetting_idx < iface->num_altsetting;
 486                                 altsetting_idx++) {
 487                         const struct libusb_interface_descriptor *altsetting
 488                                 = &iface->altsetting[altsetting_idx];
 489                         int ep_idx;
 490
 491                         for (ep_idx = 0; ep_idx < altsetting->bNumEndpoints; ep_idx++) {
 492                                 const struct libusb_endpoint_descriptor *ep =
 493                                         &altsetting->endpoint[ep_idx];
 494                                 if (ep->bEndpointAddress == endpoint)
 495                                         return ep->wMaxPacketSize;
 496                         }
 497                 }
 498         }
 499
 500         return LIBUSB_ERROR_NOT_FOUND;
 501 }
 502
 503 /** \ingroup dev
 504  * Increment the reference count of a device.
 505  * \param dev the device to reference
 506  * \returns the same device
 507  */
 508 API_EXPORTED libusb_device *libusb_ref_device(libusb_device *dev)
 509 {
 510         pthread_mutex_lock(&dev->lock);
 511         dev->refcnt++;
 512         pthread_mutex_unlock(&dev->lock);
 513         return dev;
 514 }
 515
 516 /** \ingroup dev
 517  * Decrement the reference count of a device. If the decrement operation
 518  * causes the reference count to reach zero, the device shall be destroyed.
 519  * \param dev the device to unreference
 520  */
 521 API_EXPORTED void libusb_unref_device(libusb_device *dev)
 522 {
 523         int refcnt;
 524
 525         if (!dev)
 526                 return;
 527
 528         pthread_mutex_lock(&dev->lock);
 529         refcnt = --dev->refcnt;
 530         pthread_mutex_unlock(&dev->lock);
 531
 532         if (refcnt == 0) {
 533                 usbi_dbg("destroy device %04x:%04x", dev->desc.idVendor,
 534                         dev->desc.idProduct);
 535
 536                 if (usbi_backend->destroy_device)
 537                         usbi_backend->destroy_device(dev);
 538
 539                 pthread_mutex_lock(&usb_devs_lock);
 540                 list_del(&dev->list);
 541                 pthread_mutex_unlock(&usb_devs_lock);
 542
 543                 if (dev->config) {
 544                         usbi_clear_configurations(dev);
 545                         free(dev->config);
 546                 }
 547                 free(dev);
 548         }
 549 }
 550
 551 /** \ingroup dev
 552  * Open a device and obtain a device handle. A handle allows you to perform
 553  * I/O on the device in question.
 554  *
 555  * Internally, this function adds a reference to the device and makes it
 556  * available to you through libusb_get_device(). This reference is removed
 557  * during libusb_close().
 558  *
 559  * \param dev the device to open
 560  * \returns a handle for the device, or NULL on error
 561  */
 562 API_EXPORTED libusb_device_handle *libusb_open(libusb_device *dev)
 563 {
 564         struct libusb_device_handle *handle;
 565         size_t priv_size = usbi_backend->device_handle_priv_size;
 566         int r;
 567         usbi_dbg("open %04x:%04x", dev->desc.idVendor, dev->desc.idProduct);
 568
 569         handle = malloc(sizeof(*handle) + priv_size);
 570         if (!handle)
 571                 return NULL;
 572
 573         r = pthread_mutex_init(&handle->lock, NULL);
 574         if (r)
 575                 return NULL;
 576
 577         handle->dev = libusb_ref_device(dev);
 578         handle->claimed_interfaces = 0;
 579         memset(&handle->os_priv, 0, priv_size);
 580
 581         r = usbi_backend->open(handle);
 582         if (r < 0) {
 583                 libusb_unref_device(dev);
 584                 free(handle);
 585                 return NULL;
 586         }
 587
 588         pthread_mutex_lock(&usbi_open_devs_lock);
 589         list_add(&handle->list, &usbi_open_devs);
 590         pthread_mutex_unlock(&usbi_open_devs_lock);
 591         return handle;
 592 }
 593
 594 /** \ingroup dev
 595  * Convenience function for finding a device with a particular
 596  * <tt>idVendor</tt>/<tt>idProduct</tt> combination. This function is intended
 597  * for those scenarios where you are using libusb to knock up a quick test
 598  * application - it allows you to avoid calling libusb_get_device_list() and
 599  * worrying about traversing/freeing the list.
 600  *
 601  * This function has limitations and is hence not intended for use in real
 602  * applications: if multiple devices have the same IDs it will only
 603  * give you the first one, etc.
 604  *
 605  * \param vendor_id the idVendor value to search for
 606  * \param product_id the idProduct value to search for
 607  * \returns a handle for the first found device, or NULL on error or if the
 608  * device could not be found. */
 609 API_EXPORTED libusb_device_handle *libusb_open_device_with_vid_pid(
 610         uint16_t vendor_id, uint16_t product_id)
 611 {
 612         struct libusb_device **devs;
 613         struct libusb_device *found = NULL;
 614         struct libusb_device *dev;
 615         struct libusb_device_handle *handle = NULL;
 616         size_t i = 0;
 617
 618         if (libusb_get_device_list(&devs) < 0)
 619                 return NULL;
 620
 621         while ((dev = devs[i++]) != NULL) {
 622                 const struct libusb_device_descriptor *desc =
 623                         libusb_get_device_descriptor(dev);
 624                 if (desc->idVendor == vendor_id && desc->idProduct == product_id) {
 625                         found = dev;
 626                         break;
 627                 }
 628         }
 629
 630         if (found)
 631                 handle = libusb_open(found);
 632
 633         libusb_free_device_list(devs, 1);
 634         return handle;
 635 }
 636
 637 static void do_close(struct libusb_device_handle *dev_handle)
 638 {
 639         usbi_backend->close(dev_handle);
 640         libusb_unref_device(dev_handle->dev);
 641 }
 642
 643 /** \ingroup dev
 644  * Close a device handle. Should be called on all open handles before your
 645  * application exits.
 646  *
 647  * Internally, this function destroys the reference that was added by
 648  * libusb_open() on the given device.
 649  *
 650  * \param dev_handle the handle to close
 651  */
 652 API_EXPORTED void libusb_close(libusb_device_handle *dev_handle)
 653 {
 654         if (!dev_handle)
 655                 return;
 656         usbi_dbg("");
 657
 658         pthread_mutex_lock(&usbi_open_devs_lock);
 659         list_del(&dev_handle->list);
 660         pthread_mutex_unlock(&usbi_open_devs_lock);
 661
 662         do_close(dev_handle);
 663         free(dev_handle);
 664 }
 665
 666 /** \ingroup dev
 667  * Get the underlying device for a handle. This function does not modify
 668  * the reference count of the returned device, so do not feel compelled to
 669  * unreference it when you are done.
 670  * \param dev_handle a device handle
 671  * \returns the underlying device
 672  */
 673 API_EXPORTED libusb_device *libusb_get_device(libusb_device_handle *dev_handle)
 674 {
 675         return dev_handle->dev;
 676 }
 677
 678 /** \ingroup dev
 679  * Set the active configuration for a device. The operating system may have
 680  * already set an active configuration on the device, but for portability
 681  * reasons you should use this function to select the configuration you want
 682  * before claiming any interfaces.
 683  *
 684  * If you wish to change to another configuration at some later time, you
 685  * must release all claimed interfaces using libusb_release_interface() before
 686  * setting a new active configuration.
 687  *
 688  * \param dev a device handle
 689  * \param configuration the bConfigurationValue of the configuration you
 690  * wish to activate
 691  * \returns 0 on success
 692  * \returns LIBUSB_ERROR_NOT_FOUND if the requested configuration does not exist
 693  * \returns LIBUSB_ERROR_BUSY if interfaces are currently claimed
 694  * \returns another LIBUSB_ERROR code on other failure
 695  */
 696 API_EXPORTED int libusb_set_configuration(libusb_device_handle *dev,
 697         int configuration)
 698 {
 699         usbi_dbg("configuration %d", configuration);
 700         return usbi_backend->set_configuration(dev, configuration);
 701 }
 702
 703 /** \ingroup dev
 704  * Claim an interface on a given device handle. You must claim the interface
 705  * you wish to use before you can perform I/O on any of its endpoints.
 706  *
 707  * It is legal to attempt to claim an already-claimed interface, in which
 708  * case libusb just returns 0 without doing anything.
 709  *
 710  * \param dev a device handle
 711  * \param interface_number the <tt>bInterfaceNumber</tt> of the interface you
 712  * wish to claim
 713  * \returns 0 on success
 714  * \returns LIBUSB_ERROR_NOT_FOUND if the requested interface does not exist
 715  * \returns LIBUSB_ERROR_BUSY if another program or driver has claimed the
 716  * interface
 717  * \returns a LIBUSB_ERROR code on other failure
 718  */
 719 API_EXPORTED int libusb_claim_interface(libusb_device_handle *dev,
 720         int interface_number)
 721 {
 722         int r = 0;
 723
 724         usbi_dbg("interface %d", interface_number);
 725         if (interface_number >= sizeof(dev->claimed_interfaces) * 8)
 726                 return LIBUSB_ERROR_INVALID_PARAM;
 727
 728         pthread_mutex_lock(&dev->lock);
 729         if (dev->claimed_interfaces & (1 << interface_number))
 730                 goto out;
 731
 732         r = usbi_backend->claim_interface(dev, interface_number);
 733         if (r == 0)
 734                 dev->claimed_interfaces |= 1 << interface_number;
 735
 736 out:
 737         pthread_mutex_unlock(&dev->lock);
 738         return r;
 739 }
 740
 741 /** \ingroup dev
 742  * Release an interface previously claimed with libusb_claim_interface(). You
 743  * should release all claimed interfaces before closing a device handle.
 744  * \param dev a device handle
 745  * \param interface_number the <tt>bInterfaceNumber</tt> of the
 746  * previously-claimed interface
 747  * \returns 0 on success, or a LIBUSB_ERROR code on failure.
 748  * LIBUSB_ERROR_NOT_FOUND indicates that the interface was not claimed.
 749  */
 750 API_EXPORTED int libusb_release_interface(libusb_device_handle *dev,
 751         int interface_number)
 752 {
 753         int r;
 754
 755         usbi_dbg("interface %d", interface_number);
 756         if (interface_number >= sizeof(dev->claimed_interfaces) * 8)
 757                 return LIBUSB_ERROR_INVALID_PARAM;
 758
 759         pthread_mutex_lock(&dev->lock);
 760         if (!(dev->claimed_interfaces & (1 << interface_number))) {
 761                 r = LIBUSB_ERROR_NOT_FOUND;
 762                 goto out;
 763         }
 764
 765         r = usbi_backend->release_interface(dev, interface_number);
 766         if (r == 0)
 767                 dev->claimed_interfaces &= ~(1 << interface_number);
 768
 769 out:
 770         pthread_mutex_unlock(&dev->lock);
 771         return r;
 772 }
 773
 774 /** \ingroup dev
 775  * Activate an alternate setting for an interface. The interface must have
 776  * been previously claimed with libusb_claim_interface().
 777  *
 778  * \param dev a device handle
 779  * \param interface_number the <tt>bInterfaceNumber</tt> of the
 780  * previously-claimed interface
 781  * \param altsetting the <tt>bAlternateSetting</tt> of the alternate setting
 782  * to activate
 783  * \returns 0 on success
 784  * \returns LIBUSB_ERROR_NOT_FOUND if the interface was not claimed, or the
 785  * requested alternate setting does not exist
 786  * \returns another LIBUSB_ERROR code on other failure
 787  */
 788 API_EXPORTED int libusb_set_interface_alt_setting(libusb_device_handle *dev,
 789         int interface_number, int alternate_setting)
 790 {
 791         usbi_dbg("interface %d altsetting %d", interface_number, alternate_setting);
 792         if (interface_number >= sizeof(dev->claimed_interfaces) * 8)
 793                 return LIBUSB_ERROR_INVALID_PARAM;
 794
 795         pthread_mutex_lock(&dev->lock);
 796         if (!(dev->claimed_interfaces & (1 << interface_number))) {
 797                 pthread_mutex_unlock(&dev->lock);
 798                 return LIBUSB_ERROR_NOT_FOUND;
 799         }
 800         pthread_mutex_unlock(&dev->lock);
 801
 802         return usbi_backend->set_interface_altsetting(dev, interface_number,
 803                 alternate_setting);
 804 }
 805
 806 /** \ingroup dev
 807  * Clear the halt/stall condition for an endpoint. Endpoints with halt status
 808  * are unable to receive or transmit data until the halt condition is stalled.
 809  *
 810  * You should cancel all pending transfers before attempting to clear the halt
 811  * condition.
 812  *
 813  * \param dev a device handle
 814  * \param endpoint the endpoint to clear halt status
 815  * \returns 0 on success
 816  * \returns LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist
 817  * \returns another LIBUSB_ERROR code on other failure
 818  */
 819 API_EXPORTED int libusb_clear_halt(libusb_device_handle *dev,
 820         unsigned char endpoint)
 821 {
 822         usbi_dbg("endpoint %x", endpoint);
 823         return usbi_backend->clear_halt(dev, endpoint);
 824 }
 825
 826 /** \ingroup dev
 827  * Perform a USB port reset to reinitialize a device. The system will attempt
 828  * to restore the previous configuration and alternate settings after the
 829  * reset has completed.
 830  *
 831  * If the reset fails, the descriptors change, or the previous state cannot be
 832  * restored, the device will appear to be disconnected and reconnected. This
 833  * means that the device handle is no longer valid (you should close it) and
 834  * rediscover the device. A return code of LIBUSB_ERROR_NOT_FOUND indicates
 835  * when this is the case.
 836  *
 837  * \param dev a handle of the device to reset
 838  * \returns 0 on success
 839  * \returns LIBUSB_ERROR_NOT_FOUND if re-enumeration is required
 840  * \returns another LIBUSB_ERROR code on other failure
 841  */
 842 API_EXPORTED int libusb_reset_device(libusb_device_handle *dev)
 843 {
 844         usbi_dbg("");
 845         return usbi_backend->reset_device(dev);
 846 }
 847
 848 /** \ingroup dev
 849  * Determine if a kernel driver is active on an interface. If a kernel driver
 850  * is active, you cannot claim the interface, and libusb will be unable to
 851  * perform I/O.
 852  *
 853  * \param dev a device handle
 854  * \param interface the interface to check
 855  * \returns 0 if no kernel driver is active
 856  * \returns 1 if a kernel driver is active
 857  * \returns LIBUSB_ERROR code on failure
 858  * \see libusb_detach_kernel_driver()
 859  */
 860 API_EXPORTED int libusb_kernel_driver_active(libusb_device_handle *dev,
 861         int interface)
 862 {
 863         usbi_dbg("interface %d", interface);
 864         if (usbi_backend->kernel_driver_active)
 865                 return usbi_backend->kernel_driver_active(dev, interface);
 866         else
 867                 return LIBUSB_ERROR_NOT_SUPPORTED;
 868 }
 869
 870 /** \ingroup dev
 871  * Detach a kernel driver from an interface. If successful, you will then be
 872  * able to claim the interface and perform I/O.
 873  *
 874  * \param dev a device handle
 875  * \param interface the interface to detach the driver from
 876  * \returns 0 on success
 877  * \returns LIBUSB_ERROR_NOT_FOUND if no kernel driver was active
 878  * \returns LIBUSB_ERROR_INVALID_PARAM if the interface does not exist
 879  * \returns another LIBUSB_ERROR code on other failure
 880  * \see libusb_kernel_driver_active()
 881  */
 882 API_EXPORTED int libusb_detach_kernel_driver(libusb_device_handle *dev,
 883         int interface)
 884 {
 885         usbi_dbg("interface %d", interface);
 886         if (usbi_backend->detach_kernel_driver)
 887                 return usbi_backend->detach_kernel_driver(dev, interface);
 888         else
 889                 return LIBUSB_ERROR_NOT_SUPPORTED;
 890 }
 891
 892 /** \ingroup lib
 893  * Initialize libusb. This function must be called before calling any other
 894  * libusb function.
 895  * \returns 0 on success, or a LIBUSB_ERROR code on failure
 896  */
 897 API_EXPORTED int libusb_init(void)
 898 {
 899         usbi_dbg("");
 900
 901         if (usbi_backend->init) {
 902                 int r = usbi_backend->init();
 903                 if (r)
 904                         return r;
 905         }
 906
 907         list_init(&usb_devs);
 908         list_init(&usbi_open_devs);
 909         usbi_io_init();
 910         return 0;
 911 }
 912
 913 /** \ingroup lib
 914  * Deinitialize libusb. Should be called after closing all open devices and
 915  * before your application terminates.
 916  */
 917 API_EXPORTED void libusb_exit(void)
 918 {
 919         usbi_dbg("");
 920
 921         pthread_mutex_lock(&usbi_open_devs_lock);
 922         if (!list_empty(&usbi_open_devs)) {
 923                 struct libusb_device_handle *devh;
 924                 struct libusb_device_handle *tmp;
 925
 926                 usbi_dbg("naughty app left some devices open!");
 927                 list_for_each_entry_safe(devh, tmp, &usbi_open_devs, list) {
 928                         list_del(&devh->list);
 929                         do_close(devh);
 930                         free(devh);
 931                 }
 932         }
 933         pthread_mutex_unlock(&usbi_open_devs_lock);
 934
 935         if (usbi_backend->exit)
 936                 usbi_backend->exit();
 937 }
 938
 939 void usbi_log(enum usbi_log_level level, const char *function,
 940         const char *format, ...)
 941 {
 942         va_list args;
 943         FILE *stream = stdout;
 944         const char *prefix;
 945
 946         switch (level) {
 947         case LOG_LEVEL_INFO:
 948                 prefix = "info";
 949                 break;
 950         case LOG_LEVEL_WARNING:
 951                 stream = stderr;
 952                 prefix = "warning";
 953                 break;
 954         case LOG_LEVEL_ERROR:
 955                 stream = stderr;
 956                 prefix = "error";
 957                 break;
 958         case LOG_LEVEL_DEBUG:
 959                 stream = stderr;
 960                 prefix = "debug";
 961                 break;
 962         default:
 963                 stream = stderr;
 964                 prefix = "unknown";
 965                 break;
 966         }
 967
 968         fprintf(stream, "libusb:%s [%s] ", prefix, function);
 969
 970         va_start (args, format);
 971         vfprintf(stream, format, args);
 972         va_end (args);
 973
 974         fprintf(stream, "\n");
 975 }
 976