libusbi.h revision 7e3de5de095a493accc77081fb384be8e9144250
1852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake/* 2791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard * Internal header for libusbx 3a544e5972bf2b0ac9e006439576f681a8439d311Pete Batard * Copyright © 2007-2009 Daniel Drake <dsd@gentoo.org> 4a544e5972bf2b0ac9e006439576f681a8439d311Pete Batard * Copyright © 2001 Johannes Erdfelt <johannes@erdfelt.com> 5852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * 6852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * This library is free software; you can redistribute it and/or 7852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * modify it under the terms of the GNU Lesser General Public 8852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * License as published by the Free Software Foundation; either 9852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * version 2.1 of the License, or (at your option) any later version. 10852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * 11852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * This library is distributed in the hope that it will be useful, 12852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * but WITHOUT ANY WARRANTY; without even the implied warranty of 13852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * Lesser General Public License for more details. 15852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * 16852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * You should have received a copy of the GNU Lesser General Public 17852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * License along with this library; if not, write to the Free Software 18852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 19852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake */ 20852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 21d1bd234f7e1b1ff4168b8f605e2038e87a0e361fNathan Hjelm#ifndef LIBUSBI_H 22d1bd234f7e1b1ff4168b8f605e2038e87a0e361fNathan Hjelm#define LIBUSBI_H 23852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 24e39b24ae5a6069b1571ecef3eb510c9e90db4956Sean McBride#include "config.h" 25852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 2667f0c1f100c3ab6b84fa026a47c00e0be147eb8fhjelmn <Nathan Hjelm#include <stdlib.h> 2767f0c1f100c3ab6b84fa026a47c00e0be147eb8fhjelmn <Nathan Hjelm 28852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#include <stddef.h> 29f6d60a9a8fcf06629812da886e3a5de592624b61Pete Batard#include <stdint.h> 30852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#include <time.h> 31a8e2e7cab278fbfcba91909eaf762cf66da9eda5Ludovic Rousseau#include <stdarg.h> 32a120747d561929682cd0276ea4c13fb22fad8554Peter Stuge#ifdef HAVE_POLL_H 33a120747d561929682cd0276ea4c13fb22fad8554Peter Stuge#include <poll.h> 34a120747d561929682cd0276ea4c13fb22fad8554Peter Stuge#endif 35852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 36baf714f5e0f22b968cea0e747c23eeced44f602ePete Batard#ifdef HAVE_MISSING_H 37baf714f5e0f22b968cea0e747c23eeced44f602ePete Batard#include "missing.h" 38baf714f5e0f22b968cea0e747c23eeced44f602ePete Batard#endif 39e39b24ae5a6069b1571ecef3eb510c9e90db4956Sean McBride#include "libusb.h" 4037dfd16c8c2f36c81c86de303072def0dc405e32Pete Batard#include "version.h" 41852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 42791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard/* Inside the libusbx code, mark all public functions as follows: 4329f9f9e3af3340df6a955881a93caf9d2a6d08d6Pete Batard * return_type API_EXPORTED function_name(params) { ... } 4429f9f9e3af3340df6a955881a93caf9d2a6d08d6Pete Batard * But if the function returns a pointer, mark it as follows: 4529f9f9e3af3340df6a955881a93caf9d2a6d08d6Pete Batard * DEFAULT_VISIBILITY return_type * LIBUSB_CALL function_name(params) { ... } 46791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard * In the libusbx public header, mark all declarations as: 4729f9f9e3af3340df6a955881a93caf9d2a6d08d6Pete Batard * return_type LIBUSB_CALL function_name(params); 4829f9f9e3af3340df6a955881a93caf9d2a6d08d6Pete Batard */ 4929f9f9e3af3340df6a955881a93caf9d2a6d08d6Pete Batard#define API_EXPORTED LIBUSB_CALL DEFAULT_VISIBILITY 5029f9f9e3af3340df6a955881a93caf9d2a6d08d6Pete Batard 51852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define DEVICE_DESC_LENGTH 18 52852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 53a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake#define USB_MAXENDPOINTS 32 54a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake#define USB_MAXINTERFACES 32 55a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake#define USB_MAXCONFIG 8 56a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake 57e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard/* Backend specific capabilities */ 58e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard#define USBI_CAP_HAS_HID_ACCESS 0x00010000 59e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard#define USBI_CAP_SUPPORTS_DETACH_KERNEL_DRIVER 0x00020000 60e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard 61fb4c208c33788068bbca67bdd6d11127b5be5a26Toby Gray/* Maximum number of bytes in a log line */ 627b893cc7cee185c0bf771166ca61a05b32800556Pete Batard#define USBI_MAX_LOG_LEN 1024 63fb4c208c33788068bbca67bdd6d11127b5be5a26Toby Gray/* Terminator for log lines */ 647b893cc7cee185c0bf771166ca61a05b32800556Pete Batard#define USBI_LOG_LINE_END "\n" 65fb4c208c33788068bbca67bdd6d11127b5be5a26Toby Gray 660e0cbb6c27efa5a2ae58c30267a4be9486c766ccPete Batard/* The following is used to silence warnings for unused variables */ 67e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard#define UNUSED(var) do { (void)(var); } while(0) 680e0cbb6c27efa5a2ae58c30267a4be9486c766ccPete Batard 69511ed18228dd097dfe6d5c6fd926eaea24435f64Hans de Goede#if !defined(ARRAYSIZE) 70511ed18228dd097dfe6d5c6fd926eaea24435f64Hans de Goede#define ARRAYSIZE(array) (sizeof(array)/sizeof(array[0])) 71511ed18228dd097dfe6d5c6fd926eaea24435f64Hans de Goede#endif 72511ed18228dd097dfe6d5c6fd926eaea24435f64Hans de Goede 73852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestruct list_head { 74852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake struct list_head *prev, *next; 75852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake}; 76852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 77a636df4ca1b87ed3094a87828c022092a80ba613Pete Batard/* Get an entry from the list 787b893cc7cee185c0bf771166ca61a05b32800556Pete Batard * ptr - the address of this list_head element in "type" 797b893cc7cee185c0bf771166ca61a05b32800556Pete Batard * type - the data type that contains "member" 807b893cc7cee185c0bf771166ca61a05b32800556Pete Batard * member - the list_head element in "type" 81852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake */ 82852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define list_entry(ptr, type, member) \ 8379cf539b2a05da5e76841bf51dfa15a5c35e656eSean McBride ((type *)((uintptr_t)(ptr) - (uintptr_t)offsetof(type, member))) 84852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 85852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake/* Get each entry from a list 867b893cc7cee185c0bf771166ca61a05b32800556Pete Batard * pos - A structure pointer has a "member" element 877b893cc7cee185c0bf771166ca61a05b32800556Pete Batard * head - list head 887b893cc7cee185c0bf771166ca61a05b32800556Pete Batard * member - the list_head element in "pos" 897b893cc7cee185c0bf771166ca61a05b32800556Pete Batard * type - the type of the first parameter 90852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake */ 91aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard#define list_for_each_entry(pos, head, member, type) \ 92aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard for (pos = list_entry((head)->next, type, member); \ 93aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard &pos->member != (head); \ 94aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard pos = list_entry(pos->member.next, type, member)) 95aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard 96aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard#define list_for_each_entry_safe(pos, n, head, member, type) \ 97aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard for (pos = list_entry((head)->next, type, member), \ 98aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard n = list_entry(pos->member.next, type, member); \ 99aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard &pos->member != (head); \ 100aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard pos = n, n = list_entry(n->member.next, type, member)) 101852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 102852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define list_empty(entry) ((entry)->next == (entry)) 103852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 104852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestatic inline void list_init(struct list_head *entry) 105852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake{ 106852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->prev = entry->next = entry; 107852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake} 108852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 109852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestatic inline void list_add(struct list_head *entry, struct list_head *head) 110852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake{ 111852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->next = head->next; 112852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->prev = head; 113852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 114852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake head->next->prev = entry; 115852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake head->next = entry; 116852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake} 117852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 118852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestatic inline void list_add_tail(struct list_head *entry, 119852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake struct list_head *head) 120852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake{ 121852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->next = head; 122852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->prev = head->prev; 123852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 124852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake head->prev->next = entry; 125852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake head->prev = entry; 126852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake} 127852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 128852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestatic inline void list_del(struct list_head *entry) 129852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake{ 130852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->next->prev = entry->prev; 131852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->prev->next = entry->next; 132d2e8b37a68b06b8d75e9bd947b8a90d570a77778Orin Eman entry->next = entry->prev = NULL; 133852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake} 134852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 135a983fad006fe39a48517e061bf9f66501ff900bePete Batardstatic inline void *usbi_reallocf(void *ptr, size_t size) 136a983fad006fe39a48517e061bf9f66501ff900bePete Batard{ 137a983fad006fe39a48517e061bf9f66501ff900bePete Batard void *ret = realloc(ptr, size); 138a983fad006fe39a48517e061bf9f66501ff900bePete Batard if (!ret) 139a983fad006fe39a48517e061bf9f66501ff900bePete Batard free(ptr); 140a983fad006fe39a48517e061bf9f66501ff900bePete Batard return ret; 141a983fad006fe39a48517e061bf9f66501ff900bePete Batard} 142a983fad006fe39a48517e061bf9f66501ff900bePete Batard 143852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define container_of(ptr, type, member) ({ \ 144d1bd234f7e1b1ff4168b8f605e2038e87a0e361fNathan Hjelm const typeof( ((type *)0)->member ) *mptr = (ptr); \ 145d1bd234f7e1b1ff4168b8f605e2038e87a0e361fNathan Hjelm (type *)( (char *)mptr - offsetof(type,member) );}) 146852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 147852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define MIN(a, b) ((a) < (b) ? (a) : (b)) 148852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define MAX(a, b) ((a) > (b) ? (a) : (b)) 149852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 150852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define TIMESPEC_IS_SET(ts) ((ts)->tv_sec != 0 || (ts)->tv_nsec != 0) 151852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 1527e3de5de095a493accc77081fb384be8e9144250Kuangye Guo/* Some platforms don't have this define */ 1537e3de5de095a493accc77081fb384be8e9144250Kuangye Guo#ifndef TIMESPEC_TO_TIMEVAL 1547e3de5de095a493accc77081fb384be8e9144250Kuangye Guo#define TIMESPEC_TO_TIMEVAL(tv, ts) \ 1557e3de5de095a493accc77081fb384be8e9144250Kuangye Guo do { \ 1567e3de5de095a493accc77081fb384be8e9144250Kuangye Guo (tv)->tv_sec = (ts)->tv_sec; \ 1577e3de5de095a493accc77081fb384be8e9144250Kuangye Guo (tv)->tv_usec = (ts)->tv_nsec / 1000; \ 1587e3de5de095a493accc77081fb384be8e9144250Kuangye Guo } while (0) 1597e3de5de095a493accc77081fb384be8e9144250Kuangye Guo#endif 1607e3de5de095a493accc77081fb384be8e9144250Kuangye Guo 1617ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batardvoid usbi_log(struct libusb_context *ctx, enum libusb_log_level level, 1621df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake const char *function, const char *format, ...); 163852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 1647ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batardvoid usbi_log_v(struct libusb_context *ctx, enum libusb_log_level level, 165a8e2e7cab278fbfcba91909eaf762cf66da9eda5Ludovic Rousseau const char *function, const char *format, va_list args); 166a8e2e7cab278fbfcba91909eaf762cf66da9eda5Ludovic Rousseau 167974251ba94861d03dbe9837a902d84e83d301cdaPete Batard#if !defined(_MSC_VER) || _MSC_VER >= 1400 168b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante 169852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#ifdef ENABLE_LOGGING 170b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante#define _usbi_log(ctx, level, ...) usbi_log(ctx, level, __FUNCTION__, __VA_ARGS__) 1717ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard#define usbi_dbg(...) _usbi_log(NULL, LIBUSB_LOG_LEVEL_DEBUG, __VA_ARGS__) 172b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante#else 173cf6e68acb116c63f4a8c9d30ee4f2757e8c2e12aPete Batard#define _usbi_log(ctx, level, ...) do { (void)(ctx); } while(0) 174370922dfbe0964c0b8a0c1974bb1d7b85ac10607Peter Stuge#define usbi_dbg(...) do {} while(0) 175b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante#endif 176b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante 1777ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard#define usbi_info(ctx, ...) _usbi_log(ctx, LIBUSB_LOG_LEVEL_INFO, __VA_ARGS__) 1787ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard#define usbi_warn(ctx, ...) _usbi_log(ctx, LIBUSB_LOG_LEVEL_WARNING, __VA_ARGS__) 1797ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard#define usbi_err(ctx, ...) _usbi_log(ctx, LIBUSB_LOG_LEVEL_ERROR, __VA_ARGS__) 180b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante 181974251ba94861d03dbe9837a902d84e83d301cdaPete Batard#else /* !defined(_MSC_VER) || _MSC_VER >= 1400 */ 182b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante 183b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante#ifdef ENABLE_LOGGING 184b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante#define LOG_BODY(ctxt, level) \ 185b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante{ \ 186b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante va_list args; \ 187b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante va_start (args, format); \ 188b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante usbi_log_v(ctxt, level, "", format, args); \ 189b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante va_end(args); \ 190b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante} 191852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#else 192abc3143ba1989a48f62246c2afb0eb4c3c5f7917Peter Stuge#define LOG_BODY(ctxt, level) do { (void)(ctxt); } while(0) 193852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#endif 194852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 195b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plantestatic inline void usbi_info(struct libusb_context *ctx, const char *format, 196b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante ...) 1977ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard LOG_BODY(ctx,LIBUSB_LOG_LEVEL_INFO) 198b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plantestatic inline void usbi_warn(struct libusb_context *ctx, const char *format, 199b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante ...) 2007ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard LOG_BODY(ctx,LIBUSB_LOG_LEVEL_WARNING) 201b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plantestatic inline void usbi_err( struct libusb_context *ctx, const char *format, 202b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante ...) 2037ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard LOG_BODY(ctx,LIBUSB_LOG_LEVEL_ERROR) 204b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante 205b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plantestatic inline void usbi_dbg(const char *format, ...) 2067ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard LOG_BODY(NULL,LIBUSB_LOG_LEVEL_DEBUG) 207852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 208974251ba94861d03dbe9837a902d84e83d301cdaPete Batard#endif /* !defined(_MSC_VER) || _MSC_VER >= 1400 */ 2091df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2101df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define USBI_GET_CONTEXT(ctx) if (!(ctx)) (ctx) = usbi_default_context 2111df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define DEVICE_CTX(dev) ((dev)->ctx) 2121df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define HANDLE_CTX(handle) (DEVICE_CTX((handle)->dev)) 2131df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define TRANSFER_CTX(transfer) (HANDLE_CTX((transfer)->dev_handle)) 2141df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define ITRANSFER_CTX(transfer) \ 215d1bd234f7e1b1ff4168b8f605e2038e87a0e361fNathan Hjelm (TRANSFER_CTX(USBI_TRANSFER_TO_LIBUSB_TRANSFER(transfer))) 2161df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 21776af4c99bd6122c1dd7b58858b669c919d8c8806Peter Stuge#define IS_EPIN(ep) (0 != ((ep) & LIBUSB_ENDPOINT_IN)) 21876af4c99bd6122c1dd7b58858b669c919d8c8806Peter Stuge#define IS_EPOUT(ep) (!IS_EPIN(ep)) 21976af4c99bd6122c1dd7b58858b669c919d8c8806Peter Stuge#define IS_XFERIN(xfer) (0 != ((xfer)->endpoint & LIBUSB_ENDPOINT_IN)) 22076af4c99bd6122c1dd7b58858b669c919d8c8806Peter Stuge#define IS_XFEROUT(xfer) (!IS_XFERIN(xfer)) 22176af4c99bd6122c1dd7b58858b669c919d8c8806Peter Stuge 222790ffc78b008a03c95d10899f53997b504f55c72Toby Gray/* Internal abstraction for thread synchronization */ 2239a4249f8a104b98a15a7e3ba7ecae9a385ed9027Pete Batard#if defined(THREADS_POSIX) 22438e6eb86b2ceb301d67fd4754c5a1493f7911eceLudovic Rousseau#include "os/threads_posix.h" 225244271931a782028fd9bc1cdcdb12200f65cf8d9Toby Gray#elif defined(OS_WINDOWS) || defined(OS_WINCE) 2269a4249f8a104b98a15a7e3ba7ecae9a385ed9027Pete Batard#include <os/threads_windows.h> 2279a4249f8a104b98a15a7e3ba7ecae9a385ed9027Pete Batard#endif 2289a4249f8a104b98a15a7e3ba7ecae9a385ed9027Pete Batard 2291df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakeextern struct libusb_context *usbi_default_context; 2301df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2311df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakestruct libusb_context { 2321df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int debug; 2331df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int debug_fixed; 2341df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 235c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake /* internal control pipe, used for interrupting event handling when 236c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake * something needs to modify poll fds. */ 237c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake int ctrl_pipe[2]; 238c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake 2391df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct list_head usb_devs; 24023b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t usb_devs_lock; 2411df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2421df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* A list of open handles. Backends are free to traverse this if required. 2431df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake */ 2441df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct list_head open_devs; 24523b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t open_devs_lock; 2461df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2477801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm /* A list of registered hotplug callbacks */ 2487801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm struct list_head hotplug_cbs; 2497801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm usbi_mutex_t hotplug_cbs_lock; 2507801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm int hotplug_pipe[2]; 2517801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm 252a636df4ca1b87ed3094a87828c022092a80ba613Pete Batard /* this is a list of in-flight transfer handles, sorted by timeout 2531df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake * expiration. URBs to timeout the soonest are placed at the beginning of 2541df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake * the list, URBs that will time out later are placed after, and urbs with 2551df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake * infinite timeout are always placed at the very end. */ 2561df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct list_head flying_transfers; 25723b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t flying_transfers_lock; 2581df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 259c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake /* list of poll fds */ 2601df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct list_head pollfds; 26123b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t pollfds_lock; 2621df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 263c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake /* a counter that is set when we want to interrupt event handling, in order 264c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake * to modify the poll fd set. and a lock to protect it. */ 265c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake unsigned int pollfd_modify; 26623b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t pollfd_modify_lock; 267c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake 2681df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* user callbacks for pollfd changes */ 2691df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake libusb_pollfd_added_cb fd_added_cb; 2701df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake libusb_pollfd_removed_cb fd_removed_cb; 271819e65f880ca43526036e56c65c415042c91f58fDaniel Drake void *fd_cb_user_data; 2721df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2731df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* ensures that only one thread is handling events at any one time */ 27423b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t events_lock; 2751df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2761df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* used to see if there is an active thread doing event handling */ 2771df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int event_handler_active; 2781df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2791df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* used to wait for event completion in threads other than the one that is 2801df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake * event handling */ 28123b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t event_waiters_lock; 28223b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_cond_t event_waiters_cond; 2834783008b7e711de9cb31631e60dda995f44068deDaniel Drake 2844783008b7e711de9cb31631e60dda995f44068deDaniel Drake#ifdef USBI_TIMERFD_AVAILABLE 2854783008b7e711de9cb31631e60dda995f44068deDaniel Drake /* used for timeout handling, if supported by OS. 2864783008b7e711de9cb31631e60dda995f44068deDaniel Drake * this timerfd is maintained to trigger on the next pending timeout */ 2874783008b7e711de9cb31631e60dda995f44068deDaniel Drake int timerfd; 2884783008b7e711de9cb31631e60dda995f44068deDaniel Drake#endif 289913a233ec20bcabe7c372d423d14c71b2ddf722fNathan Hjelm 290913a233ec20bcabe7c372d423d14c71b2ddf722fNathan Hjelm struct list_head list; 2911df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake}; 292852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 2934783008b7e711de9cb31631e60dda995f44068deDaniel Drake#ifdef USBI_TIMERFD_AVAILABLE 2944783008b7e711de9cb31631e60dda995f44068deDaniel Drake#define usbi_using_timerfd(ctx) ((ctx)->timerfd >= 0) 2954783008b7e711de9cb31631e60dda995f44068deDaniel Drake#else 2964783008b7e711de9cb31631e60dda995f44068deDaniel Drake#define usbi_using_timerfd(ctx) (0) 2974783008b7e711de9cb31631e60dda995f44068deDaniel Drake#endif 2984783008b7e711de9cb31631e60dda995f44068deDaniel Drake 2999cfdb494fccac53a4277da7c8b6d15f1a72a4959Daniel Drakestruct libusb_device { 3001fcdb0678b759569db7cd530457dbc0a5f86fb1dDaniel Drake /* lock protects refcnt, everything else is finalized at initialization 3011fcdb0678b759569db7cd530457dbc0a5f86fb1dDaniel Drake * time */ 30223b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t lock; 3039cfdb494fccac53a4277da7c8b6d15f1a72a4959Daniel Drake int refcnt; 3041fcdb0678b759569db7cd530457dbc0a5f86fb1dDaniel Drake 3051df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct libusb_context *ctx; 3061df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 3073675e978fb7a1042f8601931255658bcd14a2298Daniel Drake uint8_t bus_number; 308cfb8610242394d532778a483570089c2bed52c84Pete Batard uint8_t port_number; 309cfb8610242394d532778a483570089c2bed52c84Pete Batard struct libusb_device* parent_dev; 3103675e978fb7a1042f8601931255658bcd14a2298Daniel Drake uint8_t device_address; 311c3844f7aeb2176636ce6e6ef697659fdb0b30048Daniel Drake uint8_t num_configurations; 312c8c40bcbd22abca922ff31c4ed6a75fd7af78b59Hans de Goede enum libusb_speed speed; 3133675e978fb7a1042f8601931255658bcd14a2298Daniel Drake 3141fcdb0678b759569db7cd530457dbc0a5f86fb1dDaniel Drake struct list_head list; 315f3fdf447916289cd92b7190377681894e8ab611aDaniel Drake unsigned long session_data; 3168399b52062e9aa2877ab6f61622fe9cb241fad57Nathan Hjelm 3178399b52062e9aa2877ab6f61622fe9cb241fad57Nathan Hjelm struct libusb_device_descriptor device_descriptor; 3187801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm int attached; 3198399b52062e9aa2877ab6f61622fe9cb241fad57Nathan Hjelm 3206e501b377dd0bccaefce5604616614deb2abb3fcSean McBride unsigned char os_priv 3216e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) 3226e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [] /* valid C99 code */ 3236e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#else 3246e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [0] /* non-standard, but usually working code */ 3256e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#endif 3266e501b377dd0bccaefce5604616614deb2abb3fcSean McBride ; 327852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake}; 328852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 329ebad1c79688ba603ad017ed0fe2f3c0dc8edd1adDaniel Drakestruct libusb_device_handle { 330e20f8281fb7da32587f81b5eea5818af1eab0fe0Daniel Drake /* lock protects claimed_interfaces */ 33123b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t lock; 332e20f8281fb7da32587f81b5eea5818af1eab0fe0Daniel Drake unsigned long claimed_interfaces; 333e20f8281fb7da32587f81b5eea5818af1eab0fe0Daniel Drake 334852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake struct list_head list; 3359cfdb494fccac53a4277da7c8b6d15f1a72a4959Daniel Drake struct libusb_device *dev; 336fc51f19341af70508b94c06ff763842b396ea72eHans de Goede int auto_detach_kernel_driver; 3376e501b377dd0bccaefce5604616614deb2abb3fcSean McBride unsigned char os_priv 3386e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) 3396e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [] /* valid C99 code */ 3406e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#else 3416e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [0] /* non-standard, but usually working code */ 3426e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#endif 3436e501b377dd0bccaefce5604616614deb2abb3fcSean McBride ; 344852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake}; 345852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 3469196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelmenum { 3479196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm USBI_CLOCK_MONOTONIC, 3489196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm USBI_CLOCK_REALTIME 3499196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm}; 3509196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm 351211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake/* in-memory transfer layout: 352211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 353211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 1. struct usbi_transfer 354211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 2. struct libusb_transfer (which includes iso packets) [variable size] 355211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 3. os private data [variable size] 356211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 357211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * from a libusb_transfer, you can get the usbi_transfer by rewinding the 358211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * appropriate number of bytes. 359211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * the usbi_transfer includes the number of allocated packets, so you can 360211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * determine the size of the transfer and hence the start and length of the 361211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * OS-private data. 362211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake */ 363852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 364211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drakestruct usbi_transfer { 365211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake int num_iso_packets; 366852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake struct list_head list; 367637a8d7ff8a11a23588925d9d3003a609bda8075Daniel Drake struct timeval timeout; 368852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake int transferred; 369852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake uint8_t flags; 37069830057547396f893f0d7b3125a05d016313b10Daniel Drake 37169830057547396f893f0d7b3125a05d016313b10Daniel Drake /* this lock is held during libusb_submit_transfer() and 37269830057547396f893f0d7b3125a05d016313b10Daniel Drake * libusb_cancel_transfer() (allowing the OS backend to prevent duplicate 37369830057547396f893f0d7b3125a05d016313b10Daniel Drake * cancellation, submission-during-cancellation, etc). the OS backend 37469830057547396f893f0d7b3125a05d016313b10Daniel Drake * should also take this lock in the handle_events path, to prevent the user 37569830057547396f893f0d7b3125a05d016313b10Daniel Drake * cancelling the transfer from another thread while you are processing 37669830057547396f893f0d7b3125a05d016313b10Daniel Drake * its completion (presumably there would be races within your OS backend 37769830057547396f893f0d7b3125a05d016313b10Daniel Drake * if this were possible). */ 37823b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t lock; 379852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake}; 380852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 38167d9ef7b6877e17f2deec81cd41dc0948f6bed4bNathan Hjelmenum usbi_transfer_flags { 38267d9ef7b6877e17f2deec81cd41dc0948f6bed4bNathan Hjelm /* The transfer has timed out */ 38367d9ef7b6877e17f2deec81cd41dc0948f6bed4bNathan Hjelm USBI_TRANSFER_TIMED_OUT = 1 << 0, 38467d9ef7b6877e17f2deec81cd41dc0948f6bed4bNathan Hjelm 38567d9ef7b6877e17f2deec81cd41dc0948f6bed4bNathan Hjelm /* Set by backend submit_transfer() if the OS handles timeout */ 3862c85c363cddd72b9ab425f05e2ee03e0b1df24f1Peter Stuge USBI_TRANSFER_OS_HANDLES_TIMEOUT = 1 << 1, 3878f1bc0659136faf312dabe8fe67380a798299d33Vitali Lovich 3888f1bc0659136faf312dabe8fe67380a798299d33Vitali Lovich /* Cancellation was requested via libusb_cancel_transfer() */ 3898f1bc0659136faf312dabe8fe67380a798299d33Vitali Lovich USBI_TRANSFER_CANCELLING = 1 << 2, 3908f1bc0659136faf312dabe8fe67380a798299d33Vitali Lovich 3918f1bc0659136faf312dabe8fe67380a798299d33Vitali Lovich /* Operation on the transfer failed because the device disappeared */ 3928f1bc0659136faf312dabe8fe67380a798299d33Vitali Lovich USBI_TRANSFER_DEVICE_DISAPPEARED = 1 << 3, 3931ed09c7b2a5fc27c3cfea21740584879781bff67Toby Gray 3941ed09c7b2a5fc27c3cfea21740584879781bff67Toby Gray /* Set by backend submit_transfer() if the fds in use have been updated */ 3951ed09c7b2a5fc27c3cfea21740584879781bff67Toby Gray USBI_TRANSFER_UPDATED_FDS = 1 << 4, 39667d9ef7b6877e17f2deec81cd41dc0948f6bed4bNathan Hjelm}; 39767d9ef7b6877e17f2deec81cd41dc0948f6bed4bNathan Hjelm 398d1bd234f7e1b1ff4168b8f605e2038e87a0e361fNathan Hjelm#define USBI_TRANSFER_TO_LIBUSB_TRANSFER(transfer) \ 399d7031ee8e1c449af23b2674fe18d9fc652c9bd80Pete Batard ((struct libusb_transfer *)(((unsigned char *)(transfer)) \ 400211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake + sizeof(struct usbi_transfer))) 401d1bd234f7e1b1ff4168b8f605e2038e87a0e361fNathan Hjelm#define LIBUSB_TRANSFER_TO_USBI_TRANSFER(transfer) \ 402d7031ee8e1c449af23b2674fe18d9fc652c9bd80Pete Batard ((struct usbi_transfer *)(((unsigned char *)(transfer)) \ 403211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake - sizeof(struct usbi_transfer))) 404211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake 405211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drakestatic inline void *usbi_transfer_get_os_priv(struct usbi_transfer *transfer) 406211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake{ 407d7031ee8e1c449af23b2674fe18d9fc652c9bd80Pete Batard return ((unsigned char *)transfer) + sizeof(struct usbi_transfer) 408211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake + sizeof(struct libusb_transfer) 409211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake + (transfer->num_iso_packets 410211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * sizeof(struct libusb_iso_packet_descriptor)); 411211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake} 412211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake 413852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake/* bus structures */ 414852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 415a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake/* All standard descriptors have these 2 fields in common */ 416a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drakestruct usb_descriptor_header { 417a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake uint8_t bLength; 418a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake uint8_t bDescriptorType; 419a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake}; 420a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake 421852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake/* shared data and functions */ 422852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 423c32aa662769b676ff3247778664fccc71fc427ecDaniel Drakeint usbi_io_init(struct libusb_context *ctx); 424c32aa662769b676ff3247778664fccc71fc427ecDaniel Drakevoid usbi_io_exit(struct libusb_context *ctx); 425c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 4261df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakestruct libusb_device *usbi_alloc_device(struct libusb_context *ctx, 4271df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake unsigned long session_id); 4281df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakestruct libusb_device *usbi_get_device_by_session_id(struct libusb_context *ctx, 4291df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake unsigned long session_id); 430fe4adcc99e30115204ab832ad3e0170c9aca7629Daniel Drakeint usbi_sanitize_device(struct libusb_device *dev); 431fec7c84163e25b8f811632828334d75da82bcb16Daniel Drakevoid usbi_handle_disconnect(struct libusb_device_handle *handle); 432c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 4334783008b7e711de9cb31631e60dda995f44068deDaniel Drakeint usbi_handle_transfer_completion(struct usbi_transfer *itransfer, 434c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake enum libusb_transfer_status status); 4354783008b7e711de9cb31631e60dda995f44068deDaniel Drakeint usbi_handle_transfer_cancellation(struct usbi_transfer *transfer); 436852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 437ef698c633d2ecb597be58deccfa2795cc6c88e25Hans de Goedeint usbi_parse_descriptor(const unsigned char *source, const char *descriptor, 4383b41c31d3fa2c1f93649cc5fc0f59acbf3efd5a1Ludovic Rousseau void *dest, int host_endian); 4398399b52062e9aa2877ab6f61622fe9cb241fad57Nathan Hjelmint usbi_device_cache_descriptor(libusb_device *dev); 4408ebb4ccdfaf5f095a1c38787d909d280ea64405cDaniel Drakeint usbi_get_config_index_by_value(struct libusb_device *dev, 4418ebb4ccdfaf5f095a1c38787d909d280ea64405cDaniel Drake uint8_t bConfigurationValue, int *idx); 442a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake 4437801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelmvoid usbi_connect_device (struct libusb_device *dev); 4447801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelmvoid usbi_disconnect_device (struct libusb_device *dev); 4457801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm 446790ffc78b008a03c95d10899f53997b504f55c72Toby Gray/* Internal abstraction for poll (needs struct usbi_transfer on Windows) */ 447eb4e7bee4488cefcf13929d9c4fe784650fef7c7Hans de Goede#if defined(OS_LINUX) || defined(OS_DARWIN) || defined(OS_OPENBSD) || defined(OS_NETBSD) 448790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#include <unistd.h> 449790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#include "os/poll_posix.h" 450790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#elif defined(OS_WINDOWS) || defined(OS_WINCE) 4517b893cc7cee185c0bf771166ca61a05b32800556Pete Batard#include "os/poll_windows.h" 452790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#endif 453790ffc78b008a03c95d10899f53997b504f55c72Toby Gray 4547b893cc7cee185c0bf771166ca61a05b32800556Pete Batard#if (defined(OS_WINDOWS) || defined(OS_WINCE)) && !defined(__GNUC__) 4557b893cc7cee185c0bf771166ca61a05b32800556Pete Batard#define snprintf _snprintf 4567b893cc7cee185c0bf771166ca61a05b32800556Pete Batard#define vsnprintf _vsnprintf 457790ffc78b008a03c95d10899f53997b504f55c72Toby Grayint usbi_gettimeofday(struct timeval *tp, void *tzp); 458790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#define LIBUSB_GETTIMEOFDAY_WIN32 459790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#define HAVE_USBI_GETTIMEOFDAY 460790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#else 461790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#ifdef HAVE_GETTIMEOFDAY 462790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#define usbi_gettimeofday(tv, tz) gettimeofday((tv), (tz)) 463790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#define HAVE_USBI_GETTIMEOFDAY 464790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#endif 465790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#endif 466c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 467c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakestruct usbi_pollfd { 468c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake /* must come first */ 469c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake struct libusb_pollfd pollfd; 470c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 471c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake struct list_head list; 472c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake}; 473c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 4741df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakeint usbi_add_pollfd(struct libusb_context *ctx, int fd, short events); 4751df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakevoid usbi_remove_pollfd(struct libusb_context *ctx, int fd); 476a7c056c14867e1cc3ef83682f2706cdbdca7c4cePete Batardvoid usbi_fd_notification(struct libusb_context *ctx); 477c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 478c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake/* device discovery */ 479c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 480c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake/* we traverse usbfs without knowing how many devices we are going to find. 481c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake * so we create this discovered_devs model which is similar to a linked-list 482c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake * which grows when required. it can be freed once discovery has completed, 483c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake * eliminating the need for a list node in the libusb_device structure 484c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake * itself. */ 485c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakestruct discovered_devs { 486c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t len; 487c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t capacity; 4886e501b377dd0bccaefce5604616614deb2abb3fcSean McBride struct libusb_device *devices 4896e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) 4906e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [] /* valid C99 code */ 4916e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#else 4926e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [0] /* non-standard, but usually working code */ 4936e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#endif 4946e501b377dd0bccaefce5604616614deb2abb3fcSean McBride ; 495c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake}; 496c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 497c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakestruct discovered_devs *discovered_devs_append( 498c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake struct discovered_devs *discdevs, struct libusb_device *dev); 499c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 500c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake/* OS abstraction */ 501c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 5021298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake/* This is the interface that OS backends need to implement. 5031298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * All fields are mandatory, except ones explicitly noted as optional. */ 504c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakestruct usbi_os_backend { 5051298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* A human-readable name for your backend, e.g. "Linux usbfs" */ 506c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake const char *name; 5071298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 508e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard /* Binary mask for backend specific capabilities */ 509e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard uint32_t caps; 510e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard 5111298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Perform initialization of your backend. You might use this function 5121298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * to determine specific capabilities of the system, allocate required 5131298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * data structures for later, etc. 5141298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 515791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard * This function is called when a libusbx user initializes the library 5161298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * prior to use. 5171298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5181298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success, or a LIBUSB_ERROR code on failure. 5191298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 5201df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int (*init)(struct libusb_context *ctx); 5211298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 5221298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Deinitialization. Optional. This function should destroy anything 5231298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * that was set up by init. 5241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5251298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when the user deinitializes the library. 5261298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 527c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake void (*exit)(void); 528c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 5291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Enumerate all the USB devices on the system, returning them in a list 5301298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * of discovered devices. 5311298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5321298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Your implementation should enumerate all devices on the system, 5331298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * regardless of whether they have been seen before or not. 5341298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5351298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * When you have found a device, compute a session ID for it. The session 5361298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * ID should uniquely represent that particular device for that particular 5371298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * connection session since boot (i.e. if you disconnect and reconnect a 5381298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device immediately after, it should be assigned a different session ID). 5391298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If your OS cannot provide a unique session ID as described above, 5401298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * presenting a session ID of (bus_number << 8 | device_address) should 5411298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * be sufficient. Bus numbers and device addresses wrap and get reused, 5421298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * but that is an unlikely case. 5431298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5441298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * After computing a session ID for a device, call 545791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard * usbi_get_device_by_session_id(). This function checks if libusbx already 546733ffffe44ad93bd81feddb0a8072510fd7a8321Hans de Goede * knows about the device, and if so, it provides you with a reference 547733ffffe44ad93bd81feddb0a8072510fd7a8321Hans de Goede * to a libusb_device structure for it. 5481298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5491298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If usbi_get_device_by_session_id() returns NULL, it is time to allocate 5501298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * a new device structure for the device. Call usbi_alloc_device() to 5511298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * obtain a new libusb_device structure with reference count 1. Populate 5521298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * the bus_number and device_address attributes of the new device, and 5531298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * perform any other internal backend initialization you need to do. At 5541298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * this point, you should be ready to provide device descriptors and so 5551298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * on through the get_*_descriptor functions. Finally, call 5561298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * usbi_sanitize_device() to perform some final sanity checks on the 5571298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device. Assuming all of the above succeeded, we can now continue. 5581298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If any of the above failed, remember to unreference the device that 5591298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was returned by usbi_alloc_device(). 5601298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5611298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * At this stage we have a populated libusb_device structure (either one 5621298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * that was found earlier, or one that we have just allocated and 5631298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * populated). This can now be added to the discovered devices list 5641298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * using discovered_devs_append(). Note that discovered_devs_append() 5651298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * may reallocate the list, returning a new location for it, and also 5661298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * note that reallocation can fail. Your backend should handle these 5671298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * error conditions appropriately. 5681298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5691298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should not generate any bus I/O and should not block. 5701298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If I/O is required (e.g. reading the active configuration value), it is 5711298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * OK to ignore these suggestions :) 5721298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5731298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is executed when the user wishes to retrieve a list 5741298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * of USB devices connected to the system. 5751298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 576cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * If the backend has hotplug support, this function is not used! 577cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * 5781298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success, or a LIBUSB_ERROR code on failure. 5791298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 5801df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int (*get_device_list)(struct libusb_context *ctx, 5811df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct discovered_devs **discdevs); 582c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 583cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede /* Apps which were written before hotplug support, may listen for 584cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * hotplug events on their own and call libusb_get_device_list on 585cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * device addition. In this case libusb_get_device_list will likely 586cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * return a list without the new device in there, as the hotplug 587cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * event thread will still be busy enumerating the device, which may 588cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * take a while, or may not even have seen the event yet. 589cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * 590cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * To avoid this libusb_get_device_list will call this optional 591cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * function for backends with hotplug support before copying 592cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * ctx->usb_devs to the user. In this function the backend should 593cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * ensure any pending hotplug events are fully processed before 594cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * returning. 595cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * 596cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * Optional, should be implemented by backends with hotplug support. 597cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede */ 598cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede void (*hotplug_poll)(void); 599cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede 6001298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Open a device for I/O and other USB operations. The device handle 6011298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * is preallocated for you, you can retrieve the device in question 6021298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * through handle->dev. 6031298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6041298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Your backend should allocate any internal resources required for I/O 6051298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * and other operations so that those operations can happen (hopefully) 606791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard * without hiccup. This is also a good place to inform libusbx that it 6071298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * should monitor certain file descriptors related to this device - 6081298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * see the usbi_add_pollfd() function. 6091298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6101298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should not generate any bus I/O and should not block. 6111298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6121298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when the user attempts to obtain a device 6131298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * handle for a device. 6141298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6151298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 6161298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 6171298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_ACCESS if the user has insufficient permissions 6181298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since 6191298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * discovery 6201298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 6211298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6221298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Do not worry about freeing the handle on failed open, the upper layers 6231298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * do this for you. 6241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 625c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake int (*open)(struct libusb_device_handle *handle); 6261298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 6271298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Close a device such that the handle cannot be used again. Your backend 6281298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * should destroy any resources that were allocated in the open path. 6291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This may also be a good place to call usbi_remove_pollfd() to inform 630791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard * libusbx of any file descriptors associated with this device that should 6311298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * no longer be monitored. 6321298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6331298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when the user closes a device handle. 6341298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 635c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake void (*close)(struct libusb_device_handle *handle); 636c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 6371298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Retrieve the device descriptor from a device. 6381298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6391298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The descriptor should be retrieved from memory, NOT via bus I/O to the 6401298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device. This means that you may have to cache it in a private structure 6411298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * during get_device_list enumeration. Alternatively, you may be able 6421298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * to retrieve it from a kernel interface (some Linux setups can do this) 6431298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * still without generating bus I/O. 6441298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6451298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is expected to write DEVICE_DESC_LENGTH (18) bytes into 6461298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * buffer, which is guaranteed to be big enough. 6471298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6481298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when sanity-checking a device before adding 6491298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * it to the list of discovered devices, and also when the user requests 6501298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * to read the device descriptor. 6511298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6522b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * This function is expected to return the descriptor in bus-endian format 6532b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * (LE). If it returns the multi-byte values in host-endian format, 6542b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * set the host_endian output parameter to "1". 6552b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * 6561298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success or a LIBUSB_ERROR code on failure. 6571298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 658b27fff633843824744df7d334cb89ece329cafa6Daniel Drake int (*get_device_descriptor)(struct libusb_device *device, 6592b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake unsigned char *buffer, int *host_endian); 6601298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 6611298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Get the ACTIVE configuration descriptor for a device. 6621298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6631298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The descriptor should be retrieved from memory, NOT via bus I/O to the 6641298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device. This means that you may have to cache it in a private structure 6651298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * during get_device_list enumeration. You may also have to keep track 6661298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * of which configuration is active when the user changes it. 6671298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6681298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is expected to write len bytes of data into buffer, which 6691298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * is guaranteed to be big enough. If you can only do a partial write, 6701298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * return an error code. 6711298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6722b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * This function is expected to return the descriptor in bus-endian format 6732b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * (LE). If it returns the multi-byte values in host-endian format, 6742b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * set the host_endian output parameter to "1". 6752b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * 6761298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 6771298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 6781298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state 6791298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 6801298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 681fe4adcc99e30115204ab832ad3e0170c9aca7629Daniel Drake int (*get_active_config_descriptor)(struct libusb_device *device, 6822b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake unsigned char *buffer, size_t len, int *host_endian); 6831298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 6841298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Get a specific configuration descriptor for a device. 6851298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6861298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The descriptor should be retrieved from memory, NOT via bus I/O to the 6871298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device. This means that you may have to cache it in a private structure 6881298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * during get_device_list enumeration. 6891298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6901298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The requested descriptor is expressed as a zero-based index (i.e. 0 6911298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * indicates that we are requesting the first descriptor). The index does 6921298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * not (necessarily) equal the bConfigurationValue of the configuration 6931298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * being requested. 6941298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6951298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is expected to write len bytes of data into buffer, which 6961298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * is guaranteed to be big enough. If you can only do a partial write, 6971298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * return an error code. 6981298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6992b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * This function is expected to return the descriptor in bus-endian format 7002b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * (LE). If it returns the multi-byte values in host-endian format, 7012b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * set the host_endian output parameter to "1". 7022b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * 7031298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success or a LIBUSB_ERROR code on failure. 7041298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 705c3844f7aeb2176636ce6e6ef697659fdb0b30048Daniel Drake int (*get_config_descriptor)(struct libusb_device *device, 7062b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake uint8_t config_index, unsigned char *buffer, size_t len, 7072b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake int *host_endian); 708b27fff633843824744df7d334cb89ece329cafa6Daniel Drake 7096b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede /* Like get_config_descriptor but then by bConfigurationValue instead 7106b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * of by index. 7116b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * 7126b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * Optional, if not present the core will call get_config_descriptor 7136b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * for all configs until it finds the desired bConfigurationValue. 7146b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * 7156b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * Returns a pointer to the raw-descriptor in *buffer, this memory 7166b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * is valid as long as device is valid. 7176b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * 7186b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * Returns the length of the returned raw-descriptor on success, 7196b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * or a LIBUSB_ERROR code on failure. 7206b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede */ 7216b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede int (*get_config_descriptor_by_value)(struct libusb_device *device, 7226b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede uint8_t bConfigurationValue, unsigned char **buffer, 7236b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede int *host_endian); 7246b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede 725514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake /* Get the bConfigurationValue for the active configuration for a device. 726514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * Optional. This should only be implemented if you can retrieve it from 727514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * cache (don't generate I/O). 728514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * 729514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * If you cannot retrieve this from cache, either do not implement this 730514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * function, or return LIBUSB_ERROR_NOT_SUPPORTED. This will cause 731791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard * libusbx to retrieve the information through a standard control transfer. 732514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * 733514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * This function must be non-blocking. 734514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * Return: 735514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * - 0 on success 736514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 737514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * was opened 738514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * - LIBUSB_ERROR_NOT_SUPPORTED if the value cannot be retrieved without 739514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * blocking 740514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * - another LIBUSB_ERROR code on other failure. 741514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake */ 742514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake int (*get_configuration)(struct libusb_device_handle *handle, int *config); 743514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake 7441298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Set the active configuration for a device. 7451298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7461298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * A configuration value of -1 should put the device in unconfigured state. 7471298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7481298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function can block. 7491298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7501298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 7511298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 7521298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the configuration does not exist 7531298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_BUSY if interfaces are currently claimed (and hence 7541298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * configuration cannot be changed) 7551298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 7561298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 7571298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure. 7581298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 7590f463fe671455670efcf4a93e526b2a9082b0afeDaniel Drake int (*set_configuration)(struct libusb_device_handle *handle, int config); 7600f463fe671455670efcf4a93e526b2a9082b0afeDaniel Drake 7611298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Claim an interface. When claimed, the application can then perform 7621298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * I/O to an interface's endpoints. 7631298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7641298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should not generate any bus I/O and should not block. 7651298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Interface claiming is a logical operation that simply ensures that 7661298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * no other drivers/applications are using the interface, and after 7671298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * claiming, no other drivers/applicatiosn can use the interface because 7681298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * we now "own" it. 7691298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7701298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 7711298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 7721298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the interface does not exist 7731298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_BUSY if the interface is in use by another driver/app 7741298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 7751298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 7761298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 7771298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 7788aceb5c99056aaed6e6f2db1b303817e37e9fe8cPete Batard int (*claim_interface)(struct libusb_device_handle *handle, int interface_number); 7791298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 7801298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Release a previously claimed interface. 7811298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7821298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should also generate a SET_INTERFACE control request, 7831298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * resetting the alternate setting of that interface to 0. It's OK for 7841298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * this function to block as a result. 7851298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7861298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * You will only ever be asked to release an interface which was 7871298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * successfully claimed earlier. 7881298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7891298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 7901298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 7911298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 7921298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 7931298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 7941298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 7958aceb5c99056aaed6e6f2db1b303817e37e9fe8cPete Batard int (*release_interface)(struct libusb_device_handle *handle, int interface_number); 796c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 7971298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Set the alternate setting for an interface. 7981298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7991298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * You will only ever be asked to set the alternate setting for an 8001298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * interface which was successfully claimed earlier. 8011298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8021298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * It's OK for this function to block. 8031298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8041298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 8051298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 8061298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the alternate setting does not exist 8071298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 8081298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 8091298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 8101298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 81162077b7fa5b222e1bb9dea3467585aed69d596e2Daniel Drake int (*set_interface_altsetting)(struct libusb_device_handle *handle, 8128aceb5c99056aaed6e6f2db1b303817e37e9fe8cPete Batard int interface_number, int altsetting); 8131298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 8141298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Clear a halt/stall condition on an endpoint. 8151298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8161298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * It's OK for this function to block. 8171298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8181298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 8191298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 8201298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist 8211298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 8221298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 8231298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 8241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 825c01f744ce07bbeccbe353e956479f0cc5a811a6fDaniel Drake int (*clear_halt)(struct libusb_device_handle *handle, 826c01f744ce07bbeccbe353e956479f0cc5a811a6fDaniel Drake unsigned char endpoint); 8271298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 8281298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Perform a USB port reset to reinitialize a device. 8291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8301298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If possible, the handle should still be usable after the reset 8311298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * completes, assuming that the device descriptors did not change during 8321298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * reset and all previous interface state can be restored. 8331298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8341298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If something changes, or you cannot easily locate/verify the resetted 8351298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device, return LIBUSB_ERROR_NOT_FOUND. This prompts the application 8361298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * to close the old handle and re-enumerate the device. 8371298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8381298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 8391298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 8401298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if re-enumeration is required, or if the device 8411298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * has been disconnected since it was opened 8421298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 8431298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 844bfe74e9cd9c17a40fff042ea0647326f51cfecaeDaniel Drake int (*reset_device)(struct libusb_device_handle *handle); 84562077b7fa5b222e1bb9dea3467585aed69d596e2Daniel Drake 8461298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Determine if a kernel driver is active on an interface. Optional. 8471298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8481298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The presence of a kernel driver on an interface indicates that any 8491298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * calls to claim_interface would fail with the LIBUSB_ERROR_BUSY code. 8501298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8511298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 8521298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 if no driver is active 8531298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 1 if a driver is active 8541298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 8551298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 8561298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 8571298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 858470b1bc42bf53373ce678fc76bab9160a54d6881Daniel Drake int (*kernel_driver_active)(struct libusb_device_handle *handle, 8598aceb5c99056aaed6e6f2db1b303817e37e9fe8cPete Batard int interface_number); 860a636df4ca1b87ed3094a87828c022092a80ba613Pete Batard 8611298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Detach a kernel driver from an interface. Optional. 8621298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8631298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * After detaching a kernel driver, the interface should be available 8641298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * for claim. 8651298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8661298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 8671298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 8681298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if no kernel driver was active 8691298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_INVALID_PARAM if the interface does not exist 8701298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 8711298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 8721298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 8731298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 874470b1bc42bf53373ce678fc76bab9160a54d6881Daniel Drake int (*detach_kernel_driver)(struct libusb_device_handle *handle, 8758aceb5c99056aaed6e6f2db1b303817e37e9fe8cPete Batard int interface_number); 876470b1bc42bf53373ce678fc76bab9160a54d6881Daniel Drake 8771d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera /* Attach a kernel driver to an interface. Optional. 8781d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * 8791d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * Reattach a kernel driver to the device. 8801d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * 8811d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * Return: 8821d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - 0 on success 8831d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - LIBUSB_ERROR_NOT_FOUND if no kernel driver was active 8841d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - LIBUSB_ERROR_INVALID_PARAM if the interface does not exist 8851d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 8861d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * was opened 8871d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - LIBUSB_ERROR_BUSY if a program or driver has claimed the interface, 8881d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * preventing reattachment 8891d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - another LIBUSB_ERROR code on other failure 8901d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera */ 8911d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera int (*attach_kernel_driver)(struct libusb_device_handle *handle, 8928aceb5c99056aaed6e6f2db1b303817e37e9fe8cPete Batard int interface_number); 8931d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera 8941298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Destroy a device. Optional. 8951298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8961298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when the last reference to a device is 8971298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * destroyed. It should free any resources allocated in the get_device_list 8981298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * path. 8991298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 900c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake void (*destroy_device)(struct libusb_device *dev); 901c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 9021298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Submit a transfer. Your implementation should take the transfer, 9031298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * morph it into whatever form your platform requires, and submit it 9041298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * asynchronously. 9051298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 9061298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function must not block. 9071298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 908858b794cf10ff1ac76a4f453bed7645aa9709c44Hans de Goede * This function gets called with the flying_transfers_lock locked! 909858b794cf10ff1ac76a4f453bed7645aa9709c44Hans de Goede * 9101298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 9111298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 9121298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 9131298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 9141298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 915c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake int (*submit_transfer)(struct usbi_transfer *itransfer); 9161298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 9171298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Cancel a previously submitted transfer. 9181298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 9191298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function must not block. The transfer cancellation must complete 9201298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * later, resulting in a call to usbi_handle_transfer_cancellation() 9211298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * from the context of handle_events. 9221298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 923c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake int (*cancel_transfer)(struct usbi_transfer *itransfer); 9241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 9251298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Clear a transfer as if it has completed or cancelled, but do not 9261298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * report any completion/cancellation to the library. You should free 9271298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * all private data from the transfer as if you were just about to report 9281298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * completion or cancellation. 9291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 930791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard * This function might seem a bit out of place. It is used when libusbx 9311298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * detects a disconnected device - it calls this function for all pending 9321298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * transfers before reporting completion (with the disconnect code) to 9331298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * the user. Maybe we can improve upon this internal interface in future. 9341298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 935fec7c84163e25b8f811632828334d75da82bcb16Daniel Drake void (*clear_transfer_priv)(struct usbi_transfer *itransfer); 936c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 9371298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Handle any pending events. This involves monitoring any active 9381298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * transfers and processing their completion or cancellation. 9391298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 9401298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The function is passed an array of pollfd structures (size nfds) 9411298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * as a result of the poll() system call. The num_ready parameter 9421298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * indicates the number of file descriptors that have reported events 9431298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * (i.e. the poll() return value). This should be enough information 9441298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * for you to determine which actions need to be taken on the currently 9451298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * active transfers. 9461298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 9471298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * For any cancelled transfers, call usbi_handle_transfer_cancellation(). 9481298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * For completed transfers, call usbi_handle_transfer_completion(). 9491298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * For control/bulk/interrupt transfers, populate the "transferred" 9501298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * element of the appropriate usbi_transfer structure before calling the 9511298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * above functions. For isochronous transfers, populate the status and 9521298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * transferred fields of the iso packet descriptors of the transfer. 9531298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 9541298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should also be able to detect disconnection of the 9551298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device, reporting that situation with usbi_handle_disconnect(). 9561298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 95769830057547396f893f0d7b3125a05d016313b10Daniel Drake * When processing an event related to a transfer, you probably want to 95869830057547396f893f0d7b3125a05d016313b10Daniel Drake * take usbi_transfer.lock to prevent races. See the documentation for 95969830057547396f893f0d7b3125a05d016313b10Daniel Drake * the usbi_transfer structure. 96069830057547396f893f0d7b3125a05d016313b10Daniel Drake * 9611298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success, or a LIBUSB_ERROR code on failure. 9621298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 9631df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int (*handle_events)(struct libusb_context *ctx, 964a120747d561929682cd0276ea4c13fb22fad8554Peter Stuge struct pollfd *fds, POLL_NFDS_TYPE nfds, int num_ready); 965c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 9669196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm /* Get time from specified clock. At least two clocks must be implemented 9679196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm by the backend: USBI_CLOCK_REALTIME, and USBI_CLOCK_MONOTONIC. 9689196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm 9699196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm Description of clocks: 9709196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm USBI_CLOCK_REALTIME : clock returns time since system epoch. 9719196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm USBI_CLOCK_MONOTONIC: clock returns time since unspecified start 9729196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm time (usually boot). 9739196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm */ 9749196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm int (*clock_gettime)(int clkid, struct timespec *tp); 9759196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm 9764783008b7e711de9cb31631e60dda995f44068deDaniel Drake#ifdef USBI_TIMERFD_AVAILABLE 9774783008b7e711de9cb31631e60dda995f44068deDaniel Drake /* clock ID of the clock that should be used for timerfd */ 9784783008b7e711de9cb31631e60dda995f44068deDaniel Drake clockid_t (*get_timerfd_clockid)(void); 9794783008b7e711de9cb31631e60dda995f44068deDaniel Drake#endif 9804783008b7e711de9cb31631e60dda995f44068deDaniel Drake 9811298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Number of bytes to reserve for per-device private backend data. 9821298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This private data area is accessible through the "os_priv" field of 9831298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * struct libusb_device. */ 984c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t device_priv_size; 985c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 9861298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Number of bytes to reserve for per-handle private backend data. 9871298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This private data area is accessible through the "os_priv" field of 9881298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * struct libusb_device. */ 989c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t device_handle_priv_size; 990c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 9911298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Number of bytes to reserve for per-transfer private backend data. 9921298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This private data area is accessible by calling 9931298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * usbi_transfer_get_os_priv() on the appropriate usbi_transfer instance. 9941298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 995c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t transfer_priv_size; 996211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake 9971298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Mumber of additional bytes for os_priv for each iso packet. 9981298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Can your backend use this? */ 999ad6e2b712c5b54af44424e58a2776686314e26b7Daniel Drake /* FIXME: linux can't use this any more. if other OS's cannot either, 1000ad6e2b712c5b54af44424e58a2776686314e26b7Daniel Drake * then remove this */ 1001211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake size_t add_iso_packet_size; 1002c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake}; 1003c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 1004c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakeextern const struct usbi_os_backend * const usbi_backend; 1005c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 1006c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakeextern const struct usbi_os_backend linux_usbfs_backend; 1007b49f6bf5c910d0fd694ecf165d7927673707bff9Nathan Hjelmextern const struct usbi_os_backend darwin_backend; 1008c56828857eb7ba6fb4f7701693dbb3fe4e75d5f6Martin Pieuchotextern const struct usbi_os_backend openbsd_backend; 1009eb4e7bee4488cefcf13929d9c4fe784650fef7c7Hans de Goedeextern const struct usbi_os_backend netbsd_backend; 10109a4249f8a104b98a15a7e3ba7ecae9a385ed9027Pete Batardextern const struct usbi_os_backend windows_backend; 1011244271931a782028fd9bc1cdcdb12200f65cf8d9Toby Grayextern const struct usbi_os_backend wince_backend; 1012c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 1013913a233ec20bcabe7c372d423d14c71b2ddf722fNathan Hjelmextern struct list_head active_contexts_list; 1014913a233ec20bcabe7c372d423d14c71b2ddf722fNathan Hjelmextern usbi_mutex_static_t active_contexts_lock; 1015913a233ec20bcabe7c372d423d14c71b2ddf722fNathan Hjelm 1016852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#endif 1017