1bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/* 2bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Core functions for libusb 3bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Copyright (C) 2007-2008 Daniel Drake <dsd@gentoo.org> 4bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Copyright (c) 2001 Johannes Erdfelt <johannes@erdfelt.com> 5bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 6bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This library is free software; you can redistribute it and/or 7bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * modify it under the terms of the GNU Lesser General Public 8bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * License as published by the Free Software Foundation; either 9bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * version 2.1 of the License, or (at your option) any later version. 10bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 11bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This library is distributed in the hope that it will be useful, 12bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * but WITHOUT ANY WARRANTY; without even the implied warranty of 13bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Lesser General Public License for more details. 15bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 16bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * You should have received a copy of the GNU Lesser General Public 17bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * License along with this library; if not, write to the Free Software 18bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 19bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 20bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 21bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#include <config.h> 22bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 23bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#include <errno.h> 24bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#include <poll.h> 25bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#include <stdarg.h> 26bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#include <stdio.h> 27bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#include <stdlib.h> 28bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#include <string.h> 29bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#include <sys/types.h> 30bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#include <unistd.h> 31bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 32bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#include "libusb.h" 33bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#include "libusbi.h" 34bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 35bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#if defined(OS_LINUX) 36bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevconst struct usbi_os_backend * const usbi_backend = &linux_usbfs_backend; 37bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#elif defined(OS_DARWIN) 38bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevconst struct usbi_os_backend * const usbi_backend = &darwin_backend; 39bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#else 40bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#error "Unsupported OS" 41bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#endif 42bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 43bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevstruct libusb_context *usbi_default_context = NULL; 44bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevstatic pthread_mutex_t default_context_lock = PTHREAD_MUTEX_INITIALIZER; 45bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 46bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** 47bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \mainpage libusb-1.0 API Reference 48bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 49bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \section intro Introduction 50bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 51bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb is an open source library that allows you to communicate with USB 52bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * devices from userspace. For more info, see the 53bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * <a href="http://libusb.sourceforge.net">libusb homepage</a>. 54bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 55bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This documentation is aimed at application developers wishing to 56bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * communicate with USB peripherals from their own software. After reviewing 57bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * this documentation, feedback and questions can be sent to the 58bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * <a href="http://sourceforge.net/mail/?group_id=1674">libusb-devel mailing 59bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * list</a>. 60bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 61bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This documentation assumes knowledge of how to operate USB devices from 62bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * a software standpoint (descriptors, configurations, interfaces, endpoints, 63bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * control/bulk/interrupt/isochronous transfers, etc). Full information 64bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * can be found in the <a href="http://www.usb.org/developers/docs/">USB 2.0 65bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Specification</a> which is available for free download. You can probably 66bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * find less verbose introductions by searching the web. 67bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 68bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \section features Library features 69bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 70bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - All transfer types supported (control/bulk/interrupt/isochronous) 71bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - 2 transfer interfaces: 72bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * -# Synchronous (simple) 73bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * -# Asynchronous (more complicated, but more powerful) 74bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - Thread safe (although the asynchronous interface means that you 75bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * usually won't need to thread) 76bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - Lightweight with lean API 77bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - Compatible with libusb-0.1 through the libusb-compat-0.1 translation layer 78bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 79bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \section gettingstarted Getting Started 80bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 81bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * To begin reading the API documentation, start with the Modules page which 82bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * links to the different categories of libusb's functionality. 83bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 84bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * One decision you will have to make is whether to use the synchronous 85bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * or the asynchronous data transfer interface. The \ref io documentation 86bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * provides some insight into this topic. 87bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 88bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Some example programs can be found in the libusb source distribution under 89bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * the "examples" subdirectory. The libusb homepage includes a list of 90bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * real-life project examples which use libusb. 91bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 92bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \section errorhandling Error handling 93bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 94bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb functions typically return 0 on success or a negative error code 95bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * on failure. These negative error codes relate to LIBUSB_ERROR constants 96bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * which are listed on the \ref misc "miscellaneous" documentation page. 97bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 98bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \section msglog Debug message logging 99bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 100bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb does not log any messages by default. Your application is therefore 101bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * free to close stdout/stderr and those descriptors may be reused without 102bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * worry. 103bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 104bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The libusb_set_debug() function can be used to enable stdout/stderr logging 105bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * of certain messages. Under standard configuration, libusb doesn't really 106bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * log much at all, so you are advised to use this function to enable all 107bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * error/warning/informational messages. It will help you debug problems with 108bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * your software. 109bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 110bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The logged messages are unstructured. There is no one-to-one correspondence 111bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * between messages being logged and success or failure return codes from 112bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb functions. There is no format to the messages, so you should not 113bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * try to capture or parse them. They are not and will not be localized. 114bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * These messages are not suitable for being passed to your application user; 115bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * instead, you should interpret the error codes returned from libusb functions 116bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * and provide appropriate notification to the user. The messages are simply 117bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * there to aid you as a programmer, and if you're confused because you're 118bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * getting a strange error code from a libusb function, enabling message 119bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * logging may give you a suitable explanation. 120bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 121bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The LIBUSB_DEBUG environment variable can be used to enable message logging 122bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * at run-time. This environment variable should be set to a number, which is 123bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * interpreted the same as the libusb_set_debug() parameter. When this 124bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * environment variable is set, the message logging verbosity level is fixed 125bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * and libusb_set_debug() effectively does nothing. 126bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 127bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb can be compiled without any logging functions, useful for embedded 128bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * systems. In this case, libusb_set_debug() and the LIBUSB_DEBUG environment 129bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * variable have no effects. 130bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 131bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb can also be compiled with verbose debugging messages. When the 132bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * library is compiled in this way, all messages of all verbosities are always 133bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * logged. libusb_set_debug() and the LIBUSB_DEBUG environment variable have 134bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * no effects. 135bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 136bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \section remarks Other remarks 137bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 138bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb does have imperfections. The \ref caveats "caveats" page attempts 139bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * to document these. 140bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 141bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 142bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** 143bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \page caveats Caveats 144bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 145bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \section devresets Device resets 146bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 147bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The libusb_reset_device() function allows you to reset a device. If your 148bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * program has to call such a function, it should obviously be aware that 149bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * the reset will cause device state to change (e.g. register values may be 150bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * reset). 151bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 152bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The problem is that any other program could reset the device your program 153bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * is working with, at any time. libusb does not offer a mechanism to inform 154bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * you when this has happened, so if someone else resets your device it will 155bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * not be clear to your own program why the device state has changed. 156bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 157bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Ultimately, this is a limitation of writing drivers in userspace. 158bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Separation from the USB stack in the underlying kernel makes it difficult 159bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * for the operating system to deliver such notifications to your program. 160bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The Linux kernel USB stack allows such reset notifications to be delivered 161bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * to in-kernel USB drivers, but it is not clear how such notifications could 162bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * be delivered to second-class drivers that live in userspace. 163bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 164bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \section blockonly Blocking-only functionality 165bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 166bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The functionality listed below is only available through synchronous, 167bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * blocking functions. There are no asynchronous/non-blocking alternatives, 168bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * and no clear ways of implementing these. 169bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 170bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - Configuration activation (libusb_set_configuration()) 171bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - Interface/alternate setting activation (libusb_set_interface_alt_setting()) 172bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - Releasing of interfaces (libusb_release_interface()) 173bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - Clearing of halt/stall condition (libusb_clear_halt()) 174bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - Device resets (libusb_reset_device()) 175bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 176bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \section nohotplug No hotplugging 177bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 178bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb-1.0 lacks functionality for providing notifications of when devices 179bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * are added or removed. This functionality is planned to be implemented 180bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * for libusb-1.1. 181bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 182bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * That said, there is basic disconnection handling for open device handles: 183bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - If there are ongoing transfers, libusb's handle_events loop will detect 184bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * disconnections and complete ongoing transfers with the 185bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * LIBUSB_TRANSFER_NO_DEVICE status code. 186bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - Many functions such as libusb_set_configuration() return the special 187bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * LIBUSB_ERROR_NO_DEVICE error code when the device has been disconnected. 188bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 189bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \section configsel Configuration selection and handling 190bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 191bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * When libusb presents a device handle to an application, there is a chance 192bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * that the corresponding device may be in unconfigured state. For devices 193bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * with multiple configurations, there is also a chance that the configuration 194bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * currently selected is not the one that the application wants to use. 195bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 196bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The obvious solution is to add a call to libusb_set_configuration() early 197bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * on during your device initialization routines, but there are caveats to 198bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * be aware of: 199bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * -# If the device is already in the desired configuration, calling 200bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb_set_configuration() using the same configuration value will cause 201bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * a lightweight device reset. This may not be desirable behaviour. 202bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * -# libusb will be unable to change configuration if the device is in 203bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * another configuration and other programs or drivers have claimed 204bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * interfaces under that configuration. 205bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * -# In the case where the desired configuration is already active, libusb 206bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * may not even be able to perform a lightweight device reset. For example, 207bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * take my USB keyboard with fingerprint reader: I'm interested in driving 208bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * the fingerprint reader interface through libusb, but the kernel's 209bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * USB-HID driver will almost always have claimed the keyboard interface. 210bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Because the kernel has claimed an interface, it is not even possible to 211bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * perform the lightweight device reset, so libusb_set_configuration() will 212bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * fail. (Luckily the device in question only has a single configuration.) 213bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 214bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * One solution to some of the above problems is to consider the currently 215bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * active configuration. If the configuration we want is already active, then 216bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * we don't have to select any configuration: 217bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev\code 218bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevcfg = libusb_get_configuration(dev); 219bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevif (cfg != desired) 220bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev libusb_set_configuration(dev, desired); 221bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev\endcode 222bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 223bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This is probably suitable for most scenarios, but is inherently racy: 224bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * another application or driver may change the selected configuration 225bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * <em>after</em> the libusb_get_configuration() call. 226bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 227bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Even in cases where libusb_set_configuration() succeeds, consider that other 228bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * applications or drivers may change configuration after your application 229bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * calls libusb_set_configuration(). 230bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 231bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * One possible way to lock your device into a specific configuration is as 232bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * follows: 233bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * -# Set the desired configuration (or use the logic above to realise that 234bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * it is already in the desired configuration) 235bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * -# Claim the interface that you wish to use 236bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * -# Check that the currently active configuration is the one that you want 237bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * to use. 238bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 239bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The above method works because once an interface is claimed, no application 240bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * or driver is able to select another configuration. 241bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 242bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \section earlycomp Early transfer completion 243bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 244bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * NOTE: This section is currently Linux-centric. I am not sure if any of these 245bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * considerations apply to Darwin or other platforms. 246bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 247bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * When a transfer completes early (i.e. when less data is received/sent in 248bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * any one packet than the transfer buffer allows for) then libusb is designed 249bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * to terminate the transfer immediately, not transferring or receiving any 250bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * more data unless other transfers have been queued by the user. 251bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 252bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * On legacy platforms, libusb is unable to do this in all situations. After 253bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * the incomplete packet occurs, "surplus" data may be transferred. Prior to 254bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb v1.0.2, this information was lost (and for device-to-host transfers, 255bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * the corresponding data was discarded). As of libusb v1.0.3, this information 256bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * is kept (the data length of the transfer is updated) and, for device-to-host 257bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * transfesr, any surplus data was added to the buffer. Still, this is not 258bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * a nice solution because it loses the information about the end of the short 259bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * packet, and the user probably wanted that surplus data to arrive in the next 260bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * logical transfer. 261bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 262bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * A previous workaround was to only ever submit transfers of size 16kb or 263bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * less. 264bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 265bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * As of libusb v1.0.4 and Linux v2.6.32, this is fixed. A technical 266bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * explanation of this issue follows. 267bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 268bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * When you ask libusb to submit a bulk transfer larger than 16kb in size, 269bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb breaks it up into a number of smaller subtransfers. This is because 270bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * the usbfs kernel interface only accepts transfers of up to 16kb in size. 271bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The subtransfers are submitted all at once so that the kernel can queue 272bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * them at the hardware level, therefore maximizing bus throughput. 273bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 274bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * On legacy platforms, this caused problems when transfers completed early 275bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Upon this event, the kernel would terminate all further packets in that 276bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * subtransfer (but not any following ones). libusb would note this event and 277bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * immediately cancel any following subtransfers that had been queued, 278bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * but often libusb was not fast enough, and the following subtransfers had 279bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * started before libusb got around to cancelling them. 280bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 281bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Thanks to an API extension to usbfs, this is fixed with recent kernel and 282bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb releases. The solution was to allow libusb to communicate to the 283bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * kernel where boundaries occur between logical libusb-level transfers. When 284bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * a short transfer (or other error) occurs, the kernel will cancel all the 285bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * subtransfers until the boundary without allowing those transfers to start. 286bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 287bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 288bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** 289bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \page contexts Contexts 290bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 291bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * It is possible that libusb may be used simultaneously from two independent 292bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libraries linked into the same executable. For example, if your application 293bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * has a plugin-like system which allows the user to dynamically load a range 294bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * of modules into your program, it is feasible that two independently 295bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * developed modules may both use libusb. 296bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 297bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb is written to allow for these multiple user scenarios. The two 298bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * "instances" of libusb will not interfere: libusb_set_debug() calls 299bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * from one user will not affect the same settings for other users, other 300bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * users can continue using libusb after one of them calls libusb_exit(), etc. 301bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 302bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This is made possible through libusb's <em>context</em> concept. When you 303bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * call libusb_init(), you are (optionally) given a context. You can then pass 304bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * this context pointer back into future libusb functions. 305bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 306bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * In order to keep things simple for more simplistic applications, it is 307bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * legal to pass NULL to all functions requiring a context pointer (as long as 308bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * you're sure no other code will attempt to use libusb from the same process). 309bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * When you pass NULL, the default context will be used. The default context 310bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * is created the first time a process calls libusb_init() when no other 311bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * context is alive. Contexts are destroyed during libusb_exit(). 312bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 313bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * You may be wondering why only a subset of libusb functions require a 314bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * context pointer in their function definition. Internally, libusb stores 315bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * context pointers in other objects (e.g. libusb_device instances) and hence 316bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * can infer the context from those objects. 317bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 318bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 319bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** 320bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * @defgroup lib Library initialization/deinitialization 321bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This page details how to initialize and deinitialize libusb. Initialization 322bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * must be performed before using any libusb functionality, and similarly you 323bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * must not call any libusb functions after deinitialization. 324bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 325bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 326bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** 327bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * @defgroup dev Device handling and enumeration 328bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The functionality documented below is designed to help with the following 329bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * operations: 330bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - Enumerating the USB devices currently attached to the system 331bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - Choosing a device to operate from your software 332bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - Opening and closing the chosen device 333bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 334bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \section nutshell In a nutshell... 335bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 336bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The description below really makes things sound more complicated than they 337bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * actually are. The following sequence of function calls will be suitable 338bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * for almost all scenarios and does not require you to have such a deep 339bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * understanding of the resource management issues: 340bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \code 341bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev// discover devices 342bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevlibusb_device **list; 343bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevlibusb_device *found = NULL; 344bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevssize_t cnt = libusb_get_device_list(NULL, &list); 345bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevssize_t i = 0; 346bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevint err = 0; 347bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevif (cnt < 0) 348bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev error(); 349bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 350bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevfor (i = 0; i < cnt; i++) { 351bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev libusb_device *device = list[i]; 352bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (is_interesting(device)) { 353bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev found = device; 354bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev break; 355bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 356bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 357bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 358bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevif (found) { 359bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev libusb_device_handle *handle; 360bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 361bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev err = libusb_open(found, &handle); 362bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (err) 363bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev error(); 364bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev // etc 365bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 366bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 367bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevlibusb_free_device_list(list, 1); 368bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev\endcode 369bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 370bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The two important points: 371bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - You asked libusb_free_device_list() to unreference the devices (2nd 372bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * parameter) 373bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - You opened the device before freeing the list and unreferencing the 374bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * devices 375bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 376bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * If you ended up with a handle, you can now proceed to perform I/O on the 377bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * device. 378bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 379bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \section devshandles Devices and device handles 380bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb has a concept of a USB device, represented by the 381bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \ref libusb_device opaque type. A device represents a USB device that 382bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * is currently or was previously connected to the system. Using a reference 383bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * to a device, you can determine certain information about the device (e.g. 384bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * you can read the descriptor data). 385bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 386bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The libusb_get_device_list() function can be used to obtain a list of 387bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * devices currently connected to the system. This is known as device 388bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * discovery. 389bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 390bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Just because you have a reference to a device does not mean it is 391bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * necessarily usable. The device may have been unplugged, you may not have 392bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * permission to operate such device, or another program or driver may be 393bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * using the device. 394bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 395bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * When you've found a device that you'd like to operate, you must ask 396bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb to open the device using the libusb_open() function. Assuming 397bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * success, libusb then returns you a <em>device handle</em> 398bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * (a \ref libusb_device_handle pointer). All "real" I/O operations then 399bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * operate on the handle rather than the original device pointer. 400bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 401bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \section devref Device discovery and reference counting 402bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 403bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Device discovery (i.e. calling libusb_get_device_list()) returns a 404bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * freshly-allocated list of devices. The list itself must be freed when 405bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * you are done with it. libusb also needs to know when it is OK to free 406bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * the contents of the list - the devices themselves. 407bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 408bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * To handle these issues, libusb provides you with two separate items: 409bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - A function to free the list itself 410bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - A reference counting system for the devices inside 411bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 412bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * New devices presented by the libusb_get_device_list() function all have a 413bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * reference count of 1. You can increase and decrease reference count using 414bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb_ref_device() and libusb_unref_device(). A device is destroyed when 415bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * its reference count reaches 0. 416bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 417bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * With the above information in mind, the process of opening a device can 418bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * be viewed as follows: 419bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * -# Discover devices using libusb_get_device_list(). 420bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * -# Choose the device that you want to operate, and call libusb_open(). 421bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * -# Unref all devices in the discovered device list. 422bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * -# Free the discovered device list. 423bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 424bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The order is important - you must not unreference the device before 425bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * attempting to open it, because unreferencing it may destroy the device. 426bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 427bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * For convenience, the libusb_free_device_list() function includes a 428bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * parameter to optionally unreference all the devices in the list before 429bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * freeing the list itself. This combines steps 3 and 4 above. 430bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 431bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * As an implementation detail, libusb_open() actually adds a reference to 432bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * the device in question. This is because the device remains available 433bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * through the handle via libusb_get_device(). The reference is deleted during 434bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb_close(). 435bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 436bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 437bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** @defgroup misc Miscellaneous */ 438bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 439bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/* we traverse usbfs without knowing how many devices we are going to find. 440bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * so we create this discovered_devs model which is similar to a linked-list 441bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * which grows when required. it can be freed once discovery has completed, 442bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * eliminating the need for a list node in the libusb_device structure 443bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * itself. */ 444bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#define DISCOVERED_DEVICES_SIZE_STEP 8 445bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 446bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevstatic struct discovered_devs *discovered_devs_alloc(void) 447bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 448bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct discovered_devs *ret = 449bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev malloc(sizeof(*ret) + (sizeof(void *) * DISCOVERED_DEVICES_SIZE_STEP)); 450bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 451bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (ret) { 452bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ret->len = 0; 453bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ret->capacity = DISCOVERED_DEVICES_SIZE_STEP; 454bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 455bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return ret; 456bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 457bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 458bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/* append a device to the discovered devices collection. may realloc itself, 459bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * returning new discdevs. returns NULL on realloc failure. */ 460bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevstruct discovered_devs *discovered_devs_append( 461bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct discovered_devs *discdevs, struct libusb_device *dev) 462bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 463bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev size_t len = discdevs->len; 464bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev size_t capacity; 465bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 466bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* if there is space, just append the device */ 467bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (len < discdevs->capacity) { 468bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev discdevs->devices[len] = libusb_ref_device(dev); 469bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev discdevs->len++; 470bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return discdevs; 471bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 472bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 473bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* exceeded capacity, need to grow */ 474bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg("need to increase capacity"); 475bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev capacity = discdevs->capacity + DISCOVERED_DEVICES_SIZE_STEP; 476bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev discdevs = realloc(discdevs, 477bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev sizeof(*discdevs) + (sizeof(void *) * capacity)); 478bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (discdevs) { 479bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev discdevs->capacity = capacity; 480bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev discdevs->devices[len] = libusb_ref_device(dev); 481bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev discdevs->len++; 482bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 483bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 484bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return discdevs; 485bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 486bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 487bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevstatic void discovered_devs_free(struct discovered_devs *discdevs) 488bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 489bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev size_t i; 490bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 491bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev for (i = 0; i < discdevs->len; i++) 492bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev libusb_unref_device(discdevs->devices[i]); 493bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 494bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev free(discdevs); 495bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 496bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 497bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/* Allocate a new device with a specific session ID. The returned device has 498bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * a reference count of 1. */ 499bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevstruct libusb_device *usbi_alloc_device(struct libusb_context *ctx, 500bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev unsigned long session_id) 501bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 502bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev size_t priv_size = usbi_backend->device_priv_size; 503bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_device *dev = malloc(sizeof(*dev) + priv_size); 504bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int r; 505bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 506bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (!dev) 507bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return NULL; 508bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 509bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = pthread_mutex_init(&dev->lock, NULL); 510bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r) 511bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return NULL; 512bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 513bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev dev->ctx = ctx; 514bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev dev->refcnt = 1; 515bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev dev->session_data = session_id; 516bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev memset(&dev->os_priv, 0, priv_size); 517bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 518bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&ctx->usb_devs_lock); 519bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev list_add(&dev->list, &ctx->usb_devs); 520bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&ctx->usb_devs_lock); 521bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return dev; 522bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 523bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 524bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/* Perform some final sanity checks on a newly discovered device. If this 525bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * function fails (negative return code), the device should not be added 526bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * to the discovered device list. */ 527bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevint usbi_sanitize_device(struct libusb_device *dev) 528bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 529bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int r; 530bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev unsigned char raw_desc[DEVICE_DESC_LENGTH]; 531bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev uint8_t num_configurations; 532bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int host_endian; 533bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 534bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = usbi_backend->get_device_descriptor(dev, raw_desc, &host_endian); 535bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r < 0) 536bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return r; 537bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 538bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev num_configurations = raw_desc[DEVICE_DESC_LENGTH - 1]; 539bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (num_configurations > USB_MAXCONFIG) { 540bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_err(DEVICE_CTX(dev), "too many configurations"); 541bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return LIBUSB_ERROR_IO; 542bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } else if (num_configurations < 1) { 543bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg("no configurations?"); 544bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return LIBUSB_ERROR_IO; 545bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 546bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 547bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev dev->num_configurations = num_configurations; 548bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return 0; 549bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 550bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 551bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/* Examine libusb's internal list of known devices, looking for one with 552bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * a specific session ID. Returns the matching device if it was found, and 553bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * NULL otherwise. */ 554bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevstruct libusb_device *usbi_get_device_by_session_id(struct libusb_context *ctx, 555bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev unsigned long session_id) 556bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 557bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_device *dev; 558bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_device *ret = NULL; 559bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 560bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&ctx->usb_devs_lock); 561bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev list_for_each_entry(dev, &ctx->usb_devs, list) 562bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (dev->session_data == session_id) { 563bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ret = dev; 564bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev break; 565bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 566bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&ctx->usb_devs_lock); 567bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 568bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return ret; 569bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 570bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 571bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** @ingroup dev 572bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Returns a list of USB devices currently attached to the system. This is 573bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * your entry point into finding a USB device to operate. 574bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 575bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * You are expected to unreference all the devices when you are done with 576bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * them, and then free the list with libusb_free_device_list(). Note that 577bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb_free_device_list() can unref all the devices for you. Be careful 578bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * not to unreference a device you are about to open until after you have 579bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * opened it. 580bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 581bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This return value of this function indicates the number of devices in 582bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * the resultant list. The list is actually one element larger, as it is 583bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * NULL-terminated. 584bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 585bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param ctx the context to operate on, or NULL for the default context 586bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param list output location for a list of devices. Must be later freed with 587bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb_free_device_list(). 588bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns the number of devices in the outputted list, or LIBUSB_ERROR_NO_MEM 589bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * on memory allocation failure. 590bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 591bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED ssize_t libusb_get_device_list(libusb_context *ctx, 592bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev libusb_device ***list) 593bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 594bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct discovered_devs *discdevs = discovered_devs_alloc(); 595bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_device **ret; 596bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int r = 0; 597bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev size_t i; 598bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ssize_t len; 599bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev USBI_GET_CONTEXT(ctx); 600bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg(""); 601bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 602bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (!discdevs) 603bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return LIBUSB_ERROR_NO_MEM; 604bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 605bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = usbi_backend->get_device_list(ctx, &discdevs); 606bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r < 0) { 607bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev len = r; 608bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev goto out; 609bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 610bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 611bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* convert discovered_devs into a list */ 612bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev len = discdevs->len; 613bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ret = malloc(sizeof(void *) * (len + 1)); 614bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (!ret) { 615bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev len = LIBUSB_ERROR_NO_MEM; 616bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev goto out; 617bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 618bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 619bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ret[len] = NULL; 620bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev for (i = 0; i < len; i++) { 621bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_device *dev = discdevs->devices[i]; 622bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ret[i] = libusb_ref_device(dev); 623bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 624bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev *list = ret; 625bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 626bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevout: 627bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev discovered_devs_free(discdevs); 628bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return len; 629bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 630bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 631bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 632bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Frees a list of devices previously discovered using 633bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb_get_device_list(). If the unref_devices parameter is set, the 634bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * reference count of each device in the list is decremented by 1. 635bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param list the list to free 636bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param unref_devices whether to unref the devices in the list 637bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 638bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED void libusb_free_device_list(libusb_device **list, 639bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int unref_devices) 640bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 641bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (!list) 642bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return; 643bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 644bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (unref_devices) { 645bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int i = 0; 646bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_device *dev; 647bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 648bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev while ((dev = list[i++]) != NULL) 649bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev libusb_unref_device(dev); 650bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 651bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev free(list); 652bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 653bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 654bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 655bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Get the number of the bus that a device is connected to. 656bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev a device 657bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns the bus number 658bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 659bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED uint8_t libusb_get_bus_number(libusb_device *dev) 660bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 661bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return dev->bus_number; 662bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 663bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 664bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 665bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Get the address of the device on the bus it is connected to. 666bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev a device 667bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns the device address 668bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 669bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED uint8_t libusb_get_device_address(libusb_device *dev) 670bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 671bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return dev->device_address; 672bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 673bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 674bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevstatic const struct libusb_endpoint_descriptor *find_endpoint( 675bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_config_descriptor *config, unsigned char endpoint) 676bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 677bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int iface_idx; 678bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev for (iface_idx = 0; iface_idx < config->bNumInterfaces; iface_idx++) { 679bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev const struct libusb_interface *iface = &config->interface[iface_idx]; 680bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int altsetting_idx; 681bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 682bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev for (altsetting_idx = 0; altsetting_idx < iface->num_altsetting; 683bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev altsetting_idx++) { 684bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev const struct libusb_interface_descriptor *altsetting 685bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev = &iface->altsetting[altsetting_idx]; 686bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int ep_idx; 687bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 688bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev for (ep_idx = 0; ep_idx < altsetting->bNumEndpoints; ep_idx++) { 689bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev const struct libusb_endpoint_descriptor *ep = 690bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev &altsetting->endpoint[ep_idx]; 691bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (ep->bEndpointAddress == endpoint) 692bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return ep; 693bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 694bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 695bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 696bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return NULL; 697bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 698bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 699bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 700bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Convenience function to retrieve the wMaxPacketSize value for a particular 701bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * endpoint in the active device configuration. 702bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 703bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This function was originally intended to be of assistance when setting up 704bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * isochronous transfers, but a design mistake resulted in this function 705bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * instead. It simply returns the wMaxPacketSize value without considering 706bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * its contents. If you're dealing with isochronous transfers, you probably 707bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * want libusb_get_max_iso_packet_size() instead. 708bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 709bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev a device 710bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param endpoint address of the endpoint in question 711bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns the wMaxPacketSize value 712bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist 713bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_OTHER on other failure 714bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 715bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED int libusb_get_max_packet_size(libusb_device *dev, 716bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev unsigned char endpoint) 717bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 718bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_config_descriptor *config; 719bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev const struct libusb_endpoint_descriptor *ep; 720bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int r; 721bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 722bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = libusb_get_active_config_descriptor(dev, &config); 723bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r < 0) { 724bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_err(DEVICE_CTX(dev), 725bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev "could not retrieve active config descriptor"); 726bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return LIBUSB_ERROR_OTHER; 727bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 728bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 729bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ep = find_endpoint(config, endpoint); 730bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (!ep) 731bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return LIBUSB_ERROR_NOT_FOUND; 732bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 733bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = ep->wMaxPacketSize; 734bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev libusb_free_config_descriptor(config); 735bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return r; 736bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 737bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 738bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 739bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Calculate the maximum packet size which a specific endpoint is capable is 740bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * sending or receiving in the duration of 1 microframe 741bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 742bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Only the active configution is examined. The calculation is based on the 743bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * wMaxPacketSize field in the endpoint descriptor as described in section 744bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 9.6.6 in the USB 2.0 specifications. 745bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 746bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * If acting on an isochronous or interrupt endpoint, this function will 747bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * multiply the value found in bits 0:10 by the number of transactions per 748bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * microframe (determined by bits 11:12). Otherwise, this function just 749bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * returns the numeric value found in bits 0:10. 750bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 751bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This function is useful for setting up isochronous transfers, for example 752bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * you might pass the return value from this function to 753bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb_set_iso_packet_lengths() in order to set the length field of every 754bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * isochronous packet in a transfer. 755bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 756bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Since v1.0.3. 757bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 758bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev a device 759bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param endpoint address of the endpoint in question 760bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns the maximum packet size which can be sent/received on this endpoint 761bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist 762bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_OTHER on other failure 763bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 764bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED int libusb_get_max_iso_packet_size(libusb_device *dev, 765bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev unsigned char endpoint) 766bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 767bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_config_descriptor *config; 768bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev const struct libusb_endpoint_descriptor *ep; 769bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev enum libusb_transfer_type ep_type; 770bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev uint16_t val; 771bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int r; 772bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 773bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = libusb_get_active_config_descriptor(dev, &config); 774bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r < 0) { 775bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_err(DEVICE_CTX(dev), 776bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev "could not retrieve active config descriptor"); 777bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return LIBUSB_ERROR_OTHER; 778bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 779bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 780bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ep = find_endpoint(config, endpoint); 781bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (!ep) 782bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return LIBUSB_ERROR_NOT_FOUND; 783bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 784bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev val = ep->wMaxPacketSize; 785bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ep_type = ep->bmAttributes & 0x3; 786bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev libusb_free_config_descriptor(config); 787bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 788bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = val & 0x07ff; 789bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (ep_type == LIBUSB_TRANSFER_TYPE_ISOCHRONOUS 790bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev || ep_type == LIBUSB_TRANSFER_TYPE_INTERRUPT) 791bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r *= (1 + ((val >> 11) & 3)); 792bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return r; 793bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 794bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 795bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 796bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Increment the reference count of a device. 797bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev the device to reference 798bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns the same device 799bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 800bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED libusb_device *libusb_ref_device(libusb_device *dev) 801bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 802bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&dev->lock); 803bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev dev->refcnt++; 804bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&dev->lock); 805bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return dev; 806bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 807bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 808bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 809bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Decrement the reference count of a device. If the decrement operation 810bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * causes the reference count to reach zero, the device shall be destroyed. 811bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev the device to unreference 812bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 813bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED void libusb_unref_device(libusb_device *dev) 814bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 815bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int refcnt; 816bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 817bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (!dev) 818bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return; 819bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 820bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&dev->lock); 821bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev refcnt = --dev->refcnt; 822bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&dev->lock); 823bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 824bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (refcnt == 0) { 825bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg("destroy device %d.%d", dev->bus_number, dev->device_address); 826bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 827bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (usbi_backend->destroy_device) 828bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_backend->destroy_device(dev); 829bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 830bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&dev->ctx->usb_devs_lock); 831bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev list_del(&dev->list); 832bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&dev->ctx->usb_devs_lock); 833bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 834bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev free(dev); 835bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 836bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 837bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 838bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 839bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Open a device and obtain a device handle. A handle allows you to perform 840bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * I/O on the device in question. 841bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 842bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Internally, this function adds a reference to the device and makes it 843bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * available to you through libusb_get_device(). This reference is removed 844bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * during libusb_close(). 845bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 846bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This is a non-blocking function; no requests are sent over the bus. 847bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 848bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev the device to open 849bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param handle output location for the returned device handle pointer. Only 850bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * populated when the return code is 0. 851bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns 0 on success 852bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NO_MEM on memory allocation failure 853bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_ACCESS if the user has insufficient permissions 854bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 855bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns another LIBUSB_ERROR code on other failure 856bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 857bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED int libusb_open(libusb_device *dev, libusb_device_handle **handle) 858bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 859bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_context *ctx = DEVICE_CTX(dev); 860bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_device_handle *_handle; 861bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev size_t priv_size = usbi_backend->device_handle_priv_size; 862bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev unsigned char dummy = 1; 863bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int r; 864bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg("open %d.%d", dev->bus_number, dev->device_address); 865bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 866bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev _handle = malloc(sizeof(*_handle) + priv_size); 867bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (!_handle) 868bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return LIBUSB_ERROR_NO_MEM; 869bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 870bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = pthread_mutex_init(&_handle->lock, NULL); 871bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r) 872bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return LIBUSB_ERROR_OTHER; 873bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 874bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev _handle->dev = libusb_ref_device(dev); 875bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev _handle->claimed_interfaces = 0; 876bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev memset(&_handle->os_priv, 0, priv_size); 877bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 878bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = usbi_backend->open(_handle); 879bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r < 0) { 880bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev libusb_unref_device(dev); 881bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev free(_handle); 882bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return r; 883bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 884bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 885bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&ctx->open_devs_lock); 886bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev list_add(&_handle->list, &ctx->open_devs); 887bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&ctx->open_devs_lock); 888bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev *handle = _handle; 889bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 890bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 891bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* At this point, we want to interrupt any existing event handlers so 892bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * that they realise the addition of the new device's poll fd. One 893bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * example when this is desirable is if the user is running a separate 894bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * dedicated libusb events handling thread, which is running with a long 895bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * or infinite timeout. We want to interrupt that iteration of the loop, 896bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * so that it picks up the new fd, and then continues. */ 897bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 898bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* record that we are messing with poll fds */ 899bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&ctx->pollfd_modify_lock); 900bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ctx->pollfd_modify++; 901bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&ctx->pollfd_modify_lock); 902bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 903bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* write some data on control pipe to interrupt event handlers */ 904bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = write(ctx->ctrl_pipe[1], &dummy, sizeof(dummy)); 905bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r <= 0) { 906bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_warn(ctx, "internal signalling write failed"); 907bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&ctx->pollfd_modify_lock); 908bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ctx->pollfd_modify--; 909bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&ctx->pollfd_modify_lock); 910bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return 0; 911bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 912bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 913bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* take event handling lock */ 914bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev libusb_lock_events(ctx); 915bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 916bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* read the dummy data */ 917bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = read(ctx->ctrl_pipe[0], &dummy, sizeof(dummy)); 918bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r <= 0) 919bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_warn(ctx, "internal signalling read failed"); 920bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 921bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* we're done with modifying poll fds */ 922bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&ctx->pollfd_modify_lock); 923bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ctx->pollfd_modify--; 924bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&ctx->pollfd_modify_lock); 925bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 926bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* Release event handling lock and wake up event waiters */ 927bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev libusb_unlock_events(ctx); 928bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 929bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return 0; 930bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 931bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 932bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 933bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Convenience function for finding a device with a particular 934bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * <tt>idVendor</tt>/<tt>idProduct</tt> combination. This function is intended 935bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * for those scenarios where you are using libusb to knock up a quick test 936bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * application - it allows you to avoid calling libusb_get_device_list() and 937bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * worrying about traversing/freeing the list. 938bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 939bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This function has limitations and is hence not intended for use in real 940bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * applications: if multiple devices have the same IDs it will only 941bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * give you the first one, etc. 942bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 943bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param ctx the context to operate on, or NULL for the default context 944bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param vendor_id the idVendor value to search for 945bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param product_id the idProduct value to search for 946bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns a handle for the first found device, or NULL on error or if the 947bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * device could not be found. */ 948bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED libusb_device_handle *libusb_open_device_with_vid_pid( 949bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev libusb_context *ctx, uint16_t vendor_id, uint16_t product_id) 950bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 951bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_device **devs; 952bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_device *found = NULL; 953bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_device *dev; 954bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_device_handle *handle = NULL; 955bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev size_t i = 0; 956bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int r; 957bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 958bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (libusb_get_device_list(ctx, &devs) < 0) 959bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return NULL; 960bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 961bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev while ((dev = devs[i++]) != NULL) { 962bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_device_descriptor desc; 963bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = libusb_get_device_descriptor(dev, &desc); 964bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r < 0) 965bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev goto out; 966bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (desc.idVendor == vendor_id && desc.idProduct == product_id) { 967bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev found = dev; 968bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev break; 969bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 970bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 971bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 972bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (found) { 973bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = libusb_open(found, &handle); 974bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r < 0) 975bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev handle = NULL; 976bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 977bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 978bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevout: 979bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev libusb_free_device_list(devs, 1); 980bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return handle; 981bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 982bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 983bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevstatic void do_close(struct libusb_context *ctx, 984bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_device_handle *dev_handle) 985bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 986bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&ctx->open_devs_lock); 987bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev list_del(&dev_handle->list); 988bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&ctx->open_devs_lock); 989bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 990bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_backend->close(dev_handle); 991bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev libusb_unref_device(dev_handle->dev); 992bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev free(dev_handle); 993bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 994bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 995bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 996bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Close a device handle. Should be called on all open handles before your 997bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * application exits. 998bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 999bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Internally, this function destroys the reference that was added by 1000bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb_open() on the given device. 1001bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1002bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This is a non-blocking function; no requests are sent over the bus. 1003bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1004bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev_handle the handle to close 1005bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 1006bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED void libusb_close(libusb_device_handle *dev_handle) 1007bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 1008bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_context *ctx; 1009bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev unsigned char dummy = 1; 1010bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ssize_t r; 1011bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1012bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (!dev_handle) 1013bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return; 1014bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg(""); 1015bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1016bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ctx = HANDLE_CTX(dev_handle); 1017bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1018bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* Similarly to libusb_open(), we want to interrupt all event handlers 1019bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * at this point. More importantly, we want to perform the actual close of 1020bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * the device while holding the event handling lock (preventing any other 1021bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * thread from doing event handling) because we will be removing a file 1022bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * descriptor from the polling loop. */ 1023bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1024bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* record that we are messing with poll fds */ 1025bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&ctx->pollfd_modify_lock); 1026bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ctx->pollfd_modify++; 1027bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&ctx->pollfd_modify_lock); 1028bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1029bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* write some data on control pipe to interrupt event handlers */ 1030bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = write(ctx->ctrl_pipe[1], &dummy, sizeof(dummy)); 1031bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r <= 0) { 1032bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_warn(ctx, "internal signalling write failed, closing anyway"); 1033bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev do_close(ctx, dev_handle); 1034bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&ctx->pollfd_modify_lock); 1035bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ctx->pollfd_modify--; 1036bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&ctx->pollfd_modify_lock); 1037bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return; 1038bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 1039bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1040bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* take event handling lock */ 1041bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev libusb_lock_events(ctx); 1042bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1043bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* read the dummy data */ 1044bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = read(ctx->ctrl_pipe[0], &dummy, sizeof(dummy)); 1045bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r <= 0) 1046bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_warn(ctx, "internal signalling read failed, closing anyway"); 1047bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1048bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* Close the device */ 1049bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev do_close(ctx, dev_handle); 1050bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1051bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* we're done with modifying poll fds */ 1052bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&ctx->pollfd_modify_lock); 1053bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ctx->pollfd_modify--; 1054bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&ctx->pollfd_modify_lock); 1055bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1056bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* Release event handling lock and wake up event waiters */ 1057bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev libusb_unlock_events(ctx); 1058bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 1059bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1060bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 1061bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Get the underlying device for a handle. This function does not modify 1062bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * the reference count of the returned device, so do not feel compelled to 1063bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * unreference it when you are done. 1064bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev_handle a device handle 1065bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns the underlying device 1066bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 1067bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED libusb_device *libusb_get_device(libusb_device_handle *dev_handle) 1068bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 1069bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return dev_handle->dev; 1070bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 1071bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1072bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 1073bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Determine the bConfigurationValue of the currently active configuration. 1074bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1075bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * You could formulate your own control request to obtain this information, 1076bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * but this function has the advantage that it may be able to retrieve the 1077bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * information from operating system caches (no I/O involved). 1078bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1079bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * If the OS does not cache this information, then this function will block 1080bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * while a control transfer is submitted to retrieve the information. 1081bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1082bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This function will return a value of 0 in the <tt>config</tt> output 1083bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * parameter if the device is in unconfigured state. 1084bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1085bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev a device handle 1086bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param config output location for the bConfigurationValue of the active 1087bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * configuration (only valid for return code 0) 1088bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns 0 on success 1089bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 1090bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns another LIBUSB_ERROR code on other failure 1091bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 1092bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED int libusb_get_configuration(libusb_device_handle *dev, 1093bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int *config) 1094bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 1095bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int r = LIBUSB_ERROR_NOT_SUPPORTED; 1096bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1097bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg(""); 1098bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (usbi_backend->get_configuration) 1099bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = usbi_backend->get_configuration(dev, config); 1100bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1101bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r == LIBUSB_ERROR_NOT_SUPPORTED) { 1102bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev uint8_t tmp = 0; 1103bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg("falling back to control message"); 1104bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = libusb_control_transfer(dev, LIBUSB_ENDPOINT_IN, 1105bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev LIBUSB_REQUEST_GET_CONFIGURATION, 0, 0, &tmp, 1, 1000); 1106bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r == 0) { 1107bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_err(HANDLE_CTX(dev), "zero bytes returned in ctrl transfer?"); 1108bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = LIBUSB_ERROR_IO; 1109bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } else if (r == 1) { 1110bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = 0; 1111bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev *config = tmp; 1112bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } else { 1113bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg("control failed, error %d", r); 1114bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 1115bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 1116bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1117bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r == 0) 1118bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg("active config %d", *config); 1119bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1120bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return r; 1121bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 1122bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1123bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 1124bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Set the active configuration for a device. 1125bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1126bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The operating system may or may not have already set an active 1127bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * configuration on the device. It is up to your application to ensure the 1128bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * correct configuration is selected before you attempt to claim interfaces 1129bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * and perform other operations. 1130bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1131bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * If you call this function on a device already configured with the selected 1132bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * configuration, then this function will act as a lightweight device reset: 1133bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * it will issue a SET_CONFIGURATION request using the current configuration, 1134bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * causing most USB-related device state to be reset (altsetting reset to zero, 1135bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * endpoint halts cleared, toggles reset). 1136bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1137bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * You cannot change/reset configuration if your application has claimed 1138bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * interfaces - you should free them with libusb_release_interface() first. 1139bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * You cannot change/reset configuration if other applications or drivers have 1140bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * claimed interfaces. 1141bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1142bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * A configuration value of -1 will put the device in unconfigured state. 1143bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The USB specifications state that a configuration value of 0 does this, 1144bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * however buggy devices exist which actually have a configuration 0. 1145bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1146bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * You should always use this function rather than formulating your own 1147bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * SET_CONFIGURATION control request. This is because the underlying operating 1148bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * system needs to know when such changes happen. 1149bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1150bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This is a blocking function. 1151bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1152bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev a device handle 1153bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param configuration the bConfigurationValue of the configuration you 1154bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * wish to activate, or -1 if you wish to put the device in unconfigured state 1155bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns 0 on success 1156bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NOT_FOUND if the requested configuration does not exist 1157bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_BUSY if interfaces are currently claimed 1158bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 1159bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns another LIBUSB_ERROR code on other failure 1160bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 1161bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED int libusb_set_configuration(libusb_device_handle *dev, 1162bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int configuration) 1163bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 1164bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg("configuration %d", configuration); 1165bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return usbi_backend->set_configuration(dev, configuration); 1166bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 1167bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1168bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 1169bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Claim an interface on a given device handle. You must claim the interface 1170bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * you wish to use before you can perform I/O on any of its endpoints. 1171bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1172bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * It is legal to attempt to claim an already-claimed interface, in which 1173bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * case libusb just returns 0 without doing anything. 1174bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1175bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Claiming of interfaces is a purely logical operation; it does not cause 1176bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * any requests to be sent over the bus. Interface claiming is used to 1177bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * instruct the underlying operating system that your application wishes 1178bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * to take ownership of the interface. 1179bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1180bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This is a non-blocking function. 1181bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1182bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev a device handle 1183bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param interface_number the <tt>bInterfaceNumber</tt> of the interface you 1184bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * wish to claim 1185bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns 0 on success 1186bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NOT_FOUND if the requested interface does not exist 1187bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_BUSY if another program or driver has claimed the 1188bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * interface 1189bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 1190bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns a LIBUSB_ERROR code on other failure 1191bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 1192bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED int libusb_claim_interface(libusb_device_handle *dev, 1193bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int interface_number) 1194bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 1195bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int r = 0; 1196bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1197bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg("interface %d", interface_number); 1198bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (interface_number >= sizeof(dev->claimed_interfaces) * 8) 1199bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return LIBUSB_ERROR_INVALID_PARAM; 1200bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1201bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&dev->lock); 1202bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (dev->claimed_interfaces & (1 << interface_number)) 1203bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev goto out; 1204bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1205bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = usbi_backend->claim_interface(dev, interface_number); 1206bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r == 0) 1207bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev dev->claimed_interfaces |= 1 << interface_number; 1208bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1209bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevout: 1210bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&dev->lock); 1211bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return r; 1212bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 1213bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1214bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 1215bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Release an interface previously claimed with libusb_claim_interface(). You 1216bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * should release all claimed interfaces before closing a device handle. 1217bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1218bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This is a blocking function. A SET_INTERFACE control request will be sent 1219bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * to the device, resetting interface state to the first alternate setting. 1220bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1221bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev a device handle 1222bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param interface_number the <tt>bInterfaceNumber</tt> of the 1223bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * previously-claimed interface 1224bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns 0 on success 1225bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NOT_FOUND if the interface was not claimed 1226bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 1227bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns another LIBUSB_ERROR code on other failure 1228bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 1229bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED int libusb_release_interface(libusb_device_handle *dev, 1230bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int interface_number) 1231bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 1232bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int r; 1233bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1234bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg("interface %d", interface_number); 1235bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (interface_number >= sizeof(dev->claimed_interfaces) * 8) 1236bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return LIBUSB_ERROR_INVALID_PARAM; 1237bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1238bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&dev->lock); 1239bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (!(dev->claimed_interfaces & (1 << interface_number))) { 1240bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = LIBUSB_ERROR_NOT_FOUND; 1241bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev goto out; 1242bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 1243bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1244bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = usbi_backend->release_interface(dev, interface_number); 1245bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r == 0) 1246bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev dev->claimed_interfaces &= ~(1 << interface_number); 1247bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1248bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevout: 1249bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&dev->lock); 1250bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return r; 1251bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 1252bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1253bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 1254bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Activate an alternate setting for an interface. The interface must have 1255bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * been previously claimed with libusb_claim_interface(). 1256bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1257bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * You should always use this function rather than formulating your own 1258bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * SET_INTERFACE control request. This is because the underlying operating 1259bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * system needs to know when such changes happen. 1260bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1261bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This is a blocking function. 1262bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1263bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev a device handle 1264bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param interface_number the <tt>bInterfaceNumber</tt> of the 1265bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * previously-claimed interface 1266bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param alternate_setting the <tt>bAlternateSetting</tt> of the alternate 1267bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * setting to activate 1268bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns 0 on success 1269bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NOT_FOUND if the interface was not claimed, or the 1270bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * requested alternate setting does not exist 1271bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 1272bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns another LIBUSB_ERROR code on other failure 1273bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 1274bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED int libusb_set_interface_alt_setting(libusb_device_handle *dev, 1275bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int interface_number, int alternate_setting) 1276bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 1277bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg("interface %d altsetting %d", 1278bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev interface_number, alternate_setting); 1279bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (interface_number >= sizeof(dev->claimed_interfaces) * 8) 1280bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return LIBUSB_ERROR_INVALID_PARAM; 1281bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1282bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&dev->lock); 1283bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (!(dev->claimed_interfaces & (1 << interface_number))) { 1284bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&dev->lock); 1285bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return LIBUSB_ERROR_NOT_FOUND; 1286bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 1287bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&dev->lock); 1288bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1289bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return usbi_backend->set_interface_altsetting(dev, interface_number, 1290bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev alternate_setting); 1291bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 1292bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1293bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 1294bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Clear the halt/stall condition for an endpoint. Endpoints with halt status 1295bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * are unable to receive or transmit data until the halt condition is stalled. 1296bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1297bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * You should cancel all pending transfers before attempting to clear the halt 1298bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * condition. 1299bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1300bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This is a blocking function. 1301bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1302bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev a device handle 1303bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param endpoint the endpoint to clear halt status 1304bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns 0 on success 1305bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist 1306bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 1307bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns another LIBUSB_ERROR code on other failure 1308bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 1309bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED int libusb_clear_halt(libusb_device_handle *dev, 1310bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev unsigned char endpoint) 1311bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 1312bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg("endpoint %x", endpoint); 1313bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return usbi_backend->clear_halt(dev, endpoint); 1314bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 1315bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1316bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 1317bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Perform a USB port reset to reinitialize a device. The system will attempt 1318bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * to restore the previous configuration and alternate settings after the 1319bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * reset has completed. 1320bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1321bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * If the reset fails, the descriptors change, or the previous state cannot be 1322bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * restored, the device will appear to be disconnected and reconnected. This 1323bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * means that the device handle is no longer valid (you should close it) and 1324bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * rediscover the device. A return code of LIBUSB_ERROR_NOT_FOUND indicates 1325bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * when this is the case. 1326bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1327bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * This is a blocking function which usually incurs a noticeable delay. 1328bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1329bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev a handle of the device to reset 1330bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns 0 on success 1331bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NOT_FOUND if re-enumeration is required, or if the 1332bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * device has been disconnected 1333bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns another LIBUSB_ERROR code on other failure 1334bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 1335bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED int libusb_reset_device(libusb_device_handle *dev) 1336bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 1337bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg(""); 1338bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return usbi_backend->reset_device(dev); 1339bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 1340bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1341bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 1342bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Determine if a kernel driver is active on an interface. If a kernel driver 1343bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * is active, you cannot claim the interface, and libusb will be unable to 1344bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * perform I/O. 1345bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1346bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev a device handle 1347bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param interface the interface to check 1348bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns 0 if no kernel driver is active 1349bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns 1 if a kernel driver is active 1350bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 1351bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns another LIBUSB_ERROR code on other failure 1352bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \see libusb_detach_kernel_driver() 1353bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 1354bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED int libusb_kernel_driver_active(libusb_device_handle *dev, 1355bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int interface) 1356bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 1357bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg("interface %d", interface); 1358bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (usbi_backend->kernel_driver_active) 1359bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return usbi_backend->kernel_driver_active(dev, interface); 1360bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev else 1361bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return LIBUSB_ERROR_NOT_SUPPORTED; 1362bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 1363bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1364bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 1365bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Detach a kernel driver from an interface. If successful, you will then be 1366bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * able to claim the interface and perform I/O. 1367bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1368bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev a device handle 1369bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param interface the interface to detach the driver from 1370bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns 0 on success 1371bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NOT_FOUND if no kernel driver was active 1372bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_INVALID_PARAM if the interface does not exist 1373bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 1374bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns another LIBUSB_ERROR code on other failure 1375bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \see libusb_kernel_driver_active() 1376bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 1377bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED int libusb_detach_kernel_driver(libusb_device_handle *dev, 1378bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int interface) 1379bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 1380bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg("interface %d", interface); 1381bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (usbi_backend->detach_kernel_driver) 1382bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return usbi_backend->detach_kernel_driver(dev, interface); 1383bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev else 1384bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return LIBUSB_ERROR_NOT_SUPPORTED; 1385bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 1386bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1387bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup dev 1388bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Re-attach an interface's kernel driver, which was previously detached 1389bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * using libusb_detach_kernel_driver(). 1390bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1391bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param dev a device handle 1392bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param interface the interface to attach the driver from 1393bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns 0 on success 1394bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NOT_FOUND if no kernel driver was active 1395bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_INVALID_PARAM if the interface does not exist 1396bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 1397bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns LIBUSB_ERROR_BUSY if the driver cannot be attached because the 1398bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * interface is claimed by a program or driver 1399bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns another LIBUSB_ERROR code on other failure 1400bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \see libusb_kernel_driver_active() 1401bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 1402bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED int libusb_attach_kernel_driver(libusb_device_handle *dev, 1403bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int interface) 1404bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 1405bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg("interface %d", interface); 1406bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (usbi_backend->attach_kernel_driver) 1407bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return usbi_backend->attach_kernel_driver(dev, interface); 1408bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev else 1409bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return LIBUSB_ERROR_NOT_SUPPORTED; 1410bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 1411bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1412bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup lib 1413bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Set message verbosity. 1414bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - Level 0: no messages ever printed by the library (default) 1415bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - Level 1: error messages are printed to stderr 1416bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - Level 2: warning and error messages are printed to stderr 1417bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * - Level 3: informational messages are printed to stdout, warning and error 1418bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * messages are printed to stderr 1419bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1420bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * The default level is 0, which means no messages are ever printed. If you 1421bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * choose to increase the message verbosity level, ensure that your 1422bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * application does not close the stdout/stderr file descriptors. 1423bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1424bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * You are advised to set level 3. libusb is conservative with its message 1425bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * logging and most of the time, will only log messages that explain error 1426bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * conditions and other oddities. This will help you debug your software. 1427bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1428bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * If the LIBUSB_DEBUG environment variable was set when libusb was 1429bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * initialized, this function does nothing: the message verbosity is fixed 1430bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * to the value in the environment variable. 1431bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1432bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * If libusb was compiled without any message logging, this function does 1433bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * nothing: you'll never get any messages. 1434bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1435bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * If libusb was compiled with verbose debug message logging, this function 1436bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * does nothing: you'll always get messages from all levels. 1437bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * 1438bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param ctx the context to operate on, or NULL for the default context 1439bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param level debug level to set 1440bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 1441bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED void libusb_set_debug(libusb_context *ctx, int level) 1442bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 1443bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev USBI_GET_CONTEXT(ctx); 1444bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (!ctx->debug_fixed) 1445bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ctx->debug = level; 1446bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 1447bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1448bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup lib 1449bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Initialize libusb. This function must be called before calling any other 1450bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * libusb function. 1451bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param context Optional output location for context pointer. 1452bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Only valid on return code 0. 1453bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \returns 0 on success, or a LIBUSB_ERROR code on failure 1454bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 1455bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED int libusb_init(libusb_context **context) 1456bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 1457bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev char *dbg = getenv("LIBUSB_DEBUG"); 1458bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev struct libusb_context *ctx = malloc(sizeof(*ctx)); 1459bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev int r; 1460bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1461bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (!ctx) 1462bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return LIBUSB_ERROR_NO_MEM; 1463bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev memset(ctx, 0, sizeof(*ctx)); 1464bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1465bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (dbg) { 1466bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ctx->debug = atoi(dbg); 1467bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (ctx->debug) 1468bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev ctx->debug_fixed = 1; 1469bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 1470bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1471bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg(""); 1472bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1473bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (usbi_backend->init) { 1474bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = usbi_backend->init(ctx); 1475bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r) 1476bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev goto err; 1477bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 1478bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1479bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_init(&ctx->usb_devs_lock, NULL); 1480bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_init(&ctx->open_devs_lock, NULL); 1481bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev list_init(&ctx->usb_devs); 1482bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev list_init(&ctx->open_devs); 1483bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1484bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev r = usbi_io_init(ctx); 1485bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (r < 0) { 1486bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (usbi_backend->exit) 1487bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_backend->exit(); 1488bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev goto err; 1489bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 1490bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1491bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&default_context_lock); 1492bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (!usbi_default_context) { 1493bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg("created default context"); 1494bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_default_context = ctx; 1495bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 1496bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&default_context_lock); 1497bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1498bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (context) 1499bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev *context = ctx; 1500bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return 0; 1501bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1502bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulisheverr: 1503bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev free(ctx); 1504bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return r; 1505bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 1506bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1507bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev/** \ingroup lib 1508bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * Deinitialize libusb. Should be called after closing all open devices and 1509bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * before your application terminates. 1510bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * \param ctx the context to deinitialize, or NULL for the default context 1511bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev */ 1512bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor GoulishevAPI_EXPORTED void libusb_exit(struct libusb_context *ctx) 1513bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 1514bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev USBI_GET_CONTEXT(ctx); 1515bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg(""); 1516bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1517bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev /* a little sanity check. doesn't bother with open_devs locking because 1518bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev * unless there is an application bug, nobody will be accessing this. */ 1519bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (!list_empty(&ctx->open_devs)) 1520bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_warn(ctx, "application left some devices open"); 1521bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1522bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_io_exit(ctx); 1523bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (usbi_backend->exit) 1524bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_backend->exit(); 1525bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1526bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_lock(&default_context_lock); 1527bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (ctx == usbi_default_context) { 1528bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_dbg("freeing default context"); 1529bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev usbi_default_context = NULL; 1530bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 1531bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev pthread_mutex_unlock(&default_context_lock); 1532bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1533bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev free(ctx); 1534bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 1535bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1536bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishevvoid usbi_log(struct libusb_context *ctx, enum usbi_log_level level, 1537bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev const char *function, const char *format, ...) 1538bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev{ 1539bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev va_list args; 1540bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev FILE *stream = stdout; 1541bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev const char *prefix; 1542bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1543bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#ifndef ENABLE_DEBUG_LOGGING 1544bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev USBI_GET_CONTEXT(ctx); 1545bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (!ctx->debug) 1546bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return; 1547bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (level == LOG_LEVEL_WARNING && ctx->debug < 2) 1548bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return; 1549bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev if (level == LOG_LEVEL_INFO && ctx->debug < 3) 1550bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev return; 1551bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev#endif 1552bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1553bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev switch (level) { 1554bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev case LOG_LEVEL_INFO: 1555bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev prefix = "info"; 1556bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev break; 1557bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev case LOG_LEVEL_WARNING: 1558bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev stream = stderr; 1559bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev prefix = "warning"; 1560bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev break; 1561bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev case LOG_LEVEL_ERROR: 1562bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev stream = stderr; 1563bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev prefix = "error"; 1564bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev break; 1565bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev case LOG_LEVEL_DEBUG: 1566bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev stream = stderr; 1567bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev prefix = "debug"; 1568bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev break; 1569bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev default: 1570bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev stream = stderr; 1571bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev prefix = "unknown"; 1572bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev break; 1573bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev } 1574bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1575bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev fprintf(stream, "libusb:%s [%s] ", prefix, function); 1576bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1577bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev va_start (args, format); 1578bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev vfprintf(stream, format, args); 1579bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev va_end (args); 1580bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1581bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev fprintf(stream, "\n"); 1582bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev} 1583bda86ae8203fd360c4e87c310498da1e1e4c53a7Yavor Goulishev 1584