1852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake/* 21eff220474f63d7ea7f8f99bef2a3da9da5324ebhjelmn@cs.unm.edu * Internal header for libusb 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 24d8a2950f5409ee399c386b56301d49c61ee71fdfChris Dickens#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 35baf714f5e0f22b968cea0e747c23eeced44f602ePete Batard#ifdef HAVE_MISSING_H 36d8a2950f5409ee399c386b56301d49c61ee71fdfChris Dickens#include <missing.h> 37baf714f5e0f22b968cea0e747c23eeced44f602ePete Batard#endif 38d8a2950f5409ee399c386b56301d49c61ee71fdfChris Dickens 39e39b24ae5a6069b1571ecef3eb510c9e90db4956Sean McBride#include "libusb.h" 4037dfd16c8c2f36c81c86de303072def0dc405e32Pete Batard#include "version.h" 41852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 421eff220474f63d7ea7f8f99bef2a3da9da5324ebhjelmn@cs.unm.edu/* Inside the libusb 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) { ... } 461eff220474f63d7ea7f8f99bef2a3da9da5324ebhjelmn@cs.unm.edu * In the libusb 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 51dc97425bb415422423b8876af0e34111e566d56dAkshay Jaggi#ifdef __cplusplus 52dc97425bb415422423b8876af0e34111e566d56dAkshay Jaggiextern "C" { 53dc97425bb415422423b8876af0e34111e566d56dAkshay Jaggi#endif 54dc97425bb415422423b8876af0e34111e566d56dAkshay Jaggi 55c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define DEVICE_DESC_LENGTH 18 56852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 57a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake#define USB_MAXENDPOINTS 32 58a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake#define USB_MAXINTERFACES 32 59a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake#define USB_MAXCONFIG 8 60a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake 61e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard/* Backend specific capabilities */ 62c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define USBI_CAP_HAS_HID_ACCESS 0x00010000 63e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard#define USBI_CAP_SUPPORTS_DETACH_KERNEL_DRIVER 0x00020000 64e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard 65fb4c208c33788068bbca67bdd6d11127b5be5a26Toby Gray/* Maximum number of bytes in a log line */ 667b893cc7cee185c0bf771166ca61a05b32800556Pete Batard#define USBI_MAX_LOG_LEN 1024 67fb4c208c33788068bbca67bdd6d11127b5be5a26Toby Gray/* Terminator for log lines */ 687b893cc7cee185c0bf771166ca61a05b32800556Pete Batard#define USBI_LOG_LINE_END "\n" 69fb4c208c33788068bbca67bdd6d11127b5be5a26Toby Gray 700e0cbb6c27efa5a2ae58c30267a4be9486c766ccPete Batard/* The following is used to silence warnings for unused variables */ 71c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define UNUSED(var) do { (void)(var); } while(0) 720e0cbb6c27efa5a2ae58c30267a4be9486c766ccPete Batard 73511ed18228dd097dfe6d5c6fd926eaea24435f64Hans de Goede#if !defined(ARRAYSIZE) 74c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define ARRAYSIZE(array) (sizeof(array) / sizeof(array[0])) 75511ed18228dd097dfe6d5c6fd926eaea24435f64Hans de Goede#endif 76511ed18228dd097dfe6d5c6fd926eaea24435f64Hans de Goede 77852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestruct list_head { 78852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake struct list_head *prev, *next; 79852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake}; 80852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 81a636df4ca1b87ed3094a87828c022092a80ba613Pete Batard/* Get an entry from the list 827b893cc7cee185c0bf771166ca61a05b32800556Pete Batard * ptr - the address of this list_head element in "type" 837b893cc7cee185c0bf771166ca61a05b32800556Pete Batard * type - the data type that contains "member" 847b893cc7cee185c0bf771166ca61a05b32800556Pete Batard * member - the list_head element in "type" 85852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake */ 86852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define list_entry(ptr, type, member) \ 8779cf539b2a05da5e76841bf51dfa15a5c35e656eSean McBride ((type *)((uintptr_t)(ptr) - (uintptr_t)offsetof(type, member))) 88852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 893b371f1a6ab30bdebdadfcde1b96a9b98fb806caChris Dickens#define list_first_entry(ptr, type, member) \ 903b371f1a6ab30bdebdadfcde1b96a9b98fb806caChris Dickens list_entry((ptr)->next, type, member) 913b371f1a6ab30bdebdadfcde1b96a9b98fb806caChris Dickens 92852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake/* Get each entry from a list 937b893cc7cee185c0bf771166ca61a05b32800556Pete Batard * pos - A structure pointer has a "member" element 947b893cc7cee185c0bf771166ca61a05b32800556Pete Batard * head - list head 957b893cc7cee185c0bf771166ca61a05b32800556Pete Batard * member - the list_head element in "pos" 967b893cc7cee185c0bf771166ca61a05b32800556Pete Batard * type - the type of the first parameter 97852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake */ 98aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard#define list_for_each_entry(pos, head, member, type) \ 99c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens for (pos = list_entry((head)->next, type, member); \ 100c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens &pos->member != (head); \ 101aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard pos = list_entry(pos->member.next, type, member)) 102aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard 103c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define list_for_each_entry_safe(pos, n, head, member, type) \ 104c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens for (pos = list_entry((head)->next, type, member), \ 105c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens n = list_entry(pos->member.next, type, member); \ 106c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens &pos->member != (head); \ 107aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard pos = n, n = list_entry(n->member.next, type, member)) 108852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 109852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define list_empty(entry) ((entry)->next == (entry)) 110852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 111852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestatic inline void list_init(struct list_head *entry) 112852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake{ 113852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->prev = entry->next = entry; 114852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake} 115852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 116852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestatic inline void list_add(struct list_head *entry, struct list_head *head) 117852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake{ 118852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->next = head->next; 119852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->prev = head; 120852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 121852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake head->next->prev = entry; 122852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake head->next = entry; 123852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake} 124852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 125852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestatic inline void list_add_tail(struct list_head *entry, 126852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake struct list_head *head) 127852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake{ 128852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->next = head; 129852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->prev = head->prev; 130852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 131852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake head->prev->next = entry; 132852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake head->prev = entry; 133852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake} 134852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 135852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestatic inline void list_del(struct list_head *entry) 136852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake{ 137852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->next->prev = entry->prev; 138852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->prev->next = entry->next; 139d2e8b37a68b06b8d75e9bd947b8a90d570a77778Orin Eman entry->next = entry->prev = NULL; 140852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake} 141852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 142a983fad006fe39a48517e061bf9f66501ff900bePete Batardstatic inline void *usbi_reallocf(void *ptr, size_t size) 143a983fad006fe39a48517e061bf9f66501ff900bePete Batard{ 144a983fad006fe39a48517e061bf9f66501ff900bePete Batard void *ret = realloc(ptr, size); 145a983fad006fe39a48517e061bf9f66501ff900bePete Batard if (!ret) 146a983fad006fe39a48517e061bf9f66501ff900bePete Batard free(ptr); 147a983fad006fe39a48517e061bf9f66501ff900bePete Batard return ret; 148a983fad006fe39a48517e061bf9f66501ff900bePete Batard} 149a983fad006fe39a48517e061bf9f66501ff900bePete Batard 150c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define container_of(ptr, type, member) ({ \ 151c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens const typeof( ((type *)0)->member ) *mptr = (ptr); \ 152c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens (type *)( (char *)mptr - offsetof(type,member) );}) 153852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 154dc97425bb415422423b8876af0e34111e566d56dAkshay Jaggi#ifndef MIN 155852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define MIN(a, b) ((a) < (b) ? (a) : (b)) 156dc97425bb415422423b8876af0e34111e566d56dAkshay Jaggi#endif 157dc97425bb415422423b8876af0e34111e566d56dAkshay Jaggi#ifndef MAX 158852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define MAX(a, b) ((a) > (b) ? (a) : (b)) 159dc97425bb415422423b8876af0e34111e566d56dAkshay Jaggi#endif 160852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 161852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define TIMESPEC_IS_SET(ts) ((ts)->tv_sec != 0 || (ts)->tv_nsec != 0) 162852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 163a34ba28b40d901afeeca084e6b7043fcf95cd935Brent Rector#if defined(_WIN32) || defined(__CYGWIN__) || defined(_WIN32_WCE) 164a34ba28b40d901afeeca084e6b7043fcf95cd935Brent Rector#define TIMEVAL_TV_SEC_TYPE long 165a34ba28b40d901afeeca084e6b7043fcf95cd935Brent Rector#else 166a34ba28b40d901afeeca084e6b7043fcf95cd935Brent Rector#define TIMEVAL_TV_SEC_TYPE time_t 167a34ba28b40d901afeeca084e6b7043fcf95cd935Brent Rector#endif 168a34ba28b40d901afeeca084e6b7043fcf95cd935Brent Rector 1697e3de5de095a493accc77081fb384be8e9144250Kuangye Guo/* Some platforms don't have this define */ 1707e3de5de095a493accc77081fb384be8e9144250Kuangye Guo#ifndef TIMESPEC_TO_TIMEVAL 171c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define TIMESPEC_TO_TIMEVAL(tv, ts) \ 172c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens do { \ 173c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens (tv)->tv_sec = (TIMEVAL_TV_SEC_TYPE) (ts)->tv_sec; \ 174c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens (tv)->tv_usec = (ts)->tv_nsec / 1000; \ 175c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens } while (0) 1767e3de5de095a493accc77081fb384be8e9144250Kuangye Guo#endif 1777e3de5de095a493accc77081fb384be8e9144250Kuangye Guo 1787ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batardvoid usbi_log(struct libusb_context *ctx, enum libusb_log_level level, 1791df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake const char *function, const char *format, ...); 180852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 1817ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batardvoid usbi_log_v(struct libusb_context *ctx, enum libusb_log_level level, 182a8e2e7cab278fbfcba91909eaf762cf66da9eda5Ludovic Rousseau const char *function, const char *format, va_list args); 183a8e2e7cab278fbfcba91909eaf762cf66da9eda5Ludovic Rousseau 184974251ba94861d03dbe9837a902d84e83d301cdaPete Batard#if !defined(_MSC_VER) || _MSC_VER >= 1400 185b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante 186852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#ifdef ENABLE_LOGGING 187b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante#define _usbi_log(ctx, level, ...) usbi_log(ctx, level, __FUNCTION__, __VA_ARGS__) 1887ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard#define usbi_dbg(...) _usbi_log(NULL, LIBUSB_LOG_LEVEL_DEBUG, __VA_ARGS__) 189b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante#else 190cf6e68acb116c63f4a8c9d30ee4f2757e8c2e12aPete Batard#define _usbi_log(ctx, level, ...) do { (void)(ctx); } while(0) 191370922dfbe0964c0b8a0c1974bb1d7b85ac10607Peter Stuge#define usbi_dbg(...) do {} while(0) 192b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante#endif 193b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante 1947ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard#define usbi_info(ctx, ...) _usbi_log(ctx, LIBUSB_LOG_LEVEL_INFO, __VA_ARGS__) 1957ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard#define usbi_warn(ctx, ...) _usbi_log(ctx, LIBUSB_LOG_LEVEL_WARNING, __VA_ARGS__) 1967ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard#define usbi_err(ctx, ...) _usbi_log(ctx, LIBUSB_LOG_LEVEL_ERROR, __VA_ARGS__) 197b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante 198974251ba94861d03dbe9837a902d84e83d301cdaPete Batard#else /* !defined(_MSC_VER) || _MSC_VER >= 1400 */ 199b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante 200b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante#ifdef ENABLE_LOGGING 201c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define LOG_BODY(ctxt, level) \ 202c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens{ \ 203c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens va_list args; \ 204c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens va_start(args, format); \ 205c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens usbi_log_v(ctxt, level, "", format, args); \ 206c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens va_end(args); \ 207b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante} 208852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#else 209c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define LOG_BODY(ctxt, level) \ 210c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens{ \ 211c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens (void)(ctxt); \ 212c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens} 213852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#endif 214852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 215c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickensstatic inline void usbi_info(struct libusb_context *ctx, const char *format, ...) 216c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens LOG_BODY(ctx, LIBUSB_LOG_LEVEL_INFO) 217c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickensstatic inline void usbi_warn(struct libusb_context *ctx, const char *format, ...) 218c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens LOG_BODY(ctx, LIBUSB_LOG_LEVEL_WARNING) 219c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickensstatic inline void usbi_err(struct libusb_context *ctx, const char *format, ...) 220c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens LOG_BODY(ctx, LIBUSB_LOG_LEVEL_ERROR) 221b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante 222b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plantestatic inline void usbi_dbg(const char *format, ...) 223c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens LOG_BODY(NULL, LIBUSB_LOG_LEVEL_DEBUG) 224852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 225974251ba94861d03dbe9837a902d84e83d301cdaPete Batard#endif /* !defined(_MSC_VER) || _MSC_VER >= 1400 */ 2261df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 227c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define USBI_GET_CONTEXT(ctx) \ 228c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens do { \ 229c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens if (!(ctx)) \ 230c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens (ctx) = usbi_default_context; \ 231c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens } while(0) 232c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens 233c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define DEVICE_CTX(dev) ((dev)->ctx) 234c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define HANDLE_CTX(handle) (DEVICE_CTX((handle)->dev)) 235c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define TRANSFER_CTX(transfer) (HANDLE_CTX((transfer)->dev_handle)) 2361df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define ITRANSFER_CTX(transfer) \ 237d1bd234f7e1b1ff4168b8f605e2038e87a0e361fNathan Hjelm (TRANSFER_CTX(USBI_TRANSFER_TO_LIBUSB_TRANSFER(transfer))) 2381df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 239c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define IS_EPIN(ep) (0 != ((ep) & LIBUSB_ENDPOINT_IN)) 240c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define IS_EPOUT(ep) (!IS_EPIN(ep)) 241c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define IS_XFERIN(xfer) (0 != ((xfer)->endpoint & LIBUSB_ENDPOINT_IN)) 242c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define IS_XFEROUT(xfer) (!IS_XFERIN(xfer)) 24376af4c99bd6122c1dd7b58858b669c919d8c8806Peter Stuge 244790ffc78b008a03c95d10899f53997b504f55c72Toby Gray/* Internal abstraction for thread synchronization */ 2459a4249f8a104b98a15a7e3ba7ecae9a385ed9027Pete Batard#if defined(THREADS_POSIX) 24638e6eb86b2ceb301d67fd4754c5a1493f7911eceLudovic Rousseau#include "os/threads_posix.h" 247244271931a782028fd9bc1cdcdb12200f65cf8d9Toby Gray#elif defined(OS_WINDOWS) || defined(OS_WINCE) 248c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#include "os/threads_windows.h" 2499a4249f8a104b98a15a7e3ba7ecae9a385ed9027Pete Batard#endif 2509a4249f8a104b98a15a7e3ba7ecae9a385ed9027Pete Batard 2511df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakeextern struct libusb_context *usbi_default_context; 2521df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2538035a7748980704c439b5d729bed8a0d75d47046Chris Dickens/* Forward declaration for use in context (fully defined inside poll abstraction) */ 2548035a7748980704c439b5d729bed8a0d75d47046Chris Dickensstruct pollfd; 2558035a7748980704c439b5d729bed8a0d75d47046Chris Dickens 2561df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakestruct libusb_context { 2571df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int debug; 2581df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int debug_fixed; 2591df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2605b2f2e11852edf81be401736e5ece7c9debe047eChris Dickens /* internal event pipe, used for signalling occurrence of an internal event. */ 2615b2f2e11852edf81be401736e5ece7c9debe047eChris Dickens int event_pipe[2]; 262c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake 2631df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct list_head usb_devs; 26423b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t usb_devs_lock; 2651df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2661df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* A list of open handles. Backends are free to traverse this if required. 2671df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake */ 2681df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct list_head open_devs; 26923b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t open_devs_lock; 2701df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2717801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm /* A list of registered hotplug callbacks */ 2727801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm struct list_head hotplug_cbs; 2737801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm usbi_mutex_t hotplug_cbs_lock; 2747801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm 275a636df4ca1b87ed3094a87828c022092a80ba613Pete Batard /* this is a list of in-flight transfer handles, sorted by timeout 2761df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake * expiration. URBs to timeout the soonest are placed at the beginning of 2771df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake * the list, URBs that will time out later are placed after, and urbs with 2781df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake * infinite timeout are always placed at the very end. */ 2791df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct list_head flying_transfers; 280138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens /* Note paths taking both this and usbi_transfer->lock must always 281138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens * take this lock first */ 28223b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t flying_transfers_lock; 2831df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2841df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* user callbacks for pollfd changes */ 2851df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake libusb_pollfd_added_cb fd_added_cb; 2861df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake libusb_pollfd_removed_cb fd_removed_cb; 287819e65f880ca43526036e56c65c415042c91f58fDaniel Drake void *fd_cb_user_data; 2881df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2891df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* ensures that only one thread is handling events at any one time */ 29023b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t events_lock; 2911df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2921df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* used to see if there is an active thread doing event handling */ 2931df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int event_handler_active; 2941df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 295960a6e7506c4d0d59052056ae2ebfffbe8587175Chris Dickens /* A thread-local storage key to track which thread is performing event 296960a6e7506c4d0d59052056ae2ebfffbe8587175Chris Dickens * handling */ 297960a6e7506c4d0d59052056ae2ebfffbe8587175Chris Dickens usbi_tls_key_t event_handling_key; 298960a6e7506c4d0d59052056ae2ebfffbe8587175Chris Dickens 2994c28cd8593cbbca234a1fa0b9b84f4356fd00796Chris Dickens /* used to wait for event completion in threads other than the one that is 3004c28cd8593cbbca234a1fa0b9b84f4356fd00796Chris Dickens * event handling */ 3014c28cd8593cbbca234a1fa0b9b84f4356fd00796Chris Dickens usbi_mutex_t event_waiters_lock; 3024c28cd8593cbbca234a1fa0b9b84f4356fd00796Chris Dickens usbi_cond_t event_waiters_cond; 3034c28cd8593cbbca234a1fa0b9b84f4356fd00796Chris Dickens 3040e62e5cf34cd02e811157ecb4c6725f2b940a136Chris Dickens /* A lock to protect internal context event data. */ 3050e62e5cf34cd02e811157ecb4c6725f2b940a136Chris Dickens usbi_mutex_t event_data_lock; 3060e62e5cf34cd02e811157ecb4c6725f2b940a136Chris Dickens 30787a97e4f2065cc7190b0098b4d0df5a68e10a547Chris Dickens /* A bitmask of flags that are set to indicate specific events that need to 30887a97e4f2065cc7190b0098b4d0df5a68e10a547Chris Dickens * be handled. Protected by event_data_lock. */ 30987a97e4f2065cc7190b0098b4d0df5a68e10a547Chris Dickens unsigned int event_flags; 31087a97e4f2065cc7190b0098b4d0df5a68e10a547Chris Dickens 3111b4b7f8b15fb98688a15c1125ede1e018a4451d6Chris Dickens /* A counter that is set when we want to interrupt and prevent event handling, 3121b4b7f8b15fb98688a15c1125ede1e018a4451d6Chris Dickens * in order to safely close a device. Protected by event_data_lock. */ 3131b4b7f8b15fb98688a15c1125ede1e018a4451d6Chris Dickens unsigned int device_close; 3141b4b7f8b15fb98688a15c1125ede1e018a4451d6Chris Dickens 3154c28cd8593cbbca234a1fa0b9b84f4356fd00796Chris Dickens /* list and count of poll fds and an array of poll fd structures that is 31687a97e4f2065cc7190b0098b4d0df5a68e10a547Chris Dickens * (re)allocated as necessary prior to polling. Protected by event_data_lock. */ 3174c28cd8593cbbca234a1fa0b9b84f4356fd00796Chris Dickens struct list_head ipollfds; 3184c28cd8593cbbca234a1fa0b9b84f4356fd00796Chris Dickens struct pollfd *pollfds; 3194c28cd8593cbbca234a1fa0b9b84f4356fd00796Chris Dickens POLL_NFDS_TYPE pollfds_cnt; 320f5795bfa0e5d9e2ccd1e031d02269f041101aca7Chris Dickens 3213b371f1a6ab30bdebdadfcde1b96a9b98fb806caChris Dickens /* A list of pending hotplug messages. Protected by event_data_lock. */ 3223b371f1a6ab30bdebdadfcde1b96a9b98fb806caChris Dickens struct list_head hotplug_msgs; 3233b371f1a6ab30bdebdadfcde1b96a9b98fb806caChris Dickens 324fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens /* A list of pending completed transfers. Protected by event_data_lock. */ 325fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens struct list_head completed_transfers; 326fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens 3274783008b7e711de9cb31631e60dda995f44068deDaniel Drake#ifdef USBI_TIMERFD_AVAILABLE 3284783008b7e711de9cb31631e60dda995f44068deDaniel Drake /* used for timeout handling, if supported by OS. 3294783008b7e711de9cb31631e60dda995f44068deDaniel Drake * this timerfd is maintained to trigger on the next pending timeout */ 3304783008b7e711de9cb31631e60dda995f44068deDaniel Drake int timerfd; 3314783008b7e711de9cb31631e60dda995f44068deDaniel Drake#endif 332913a233ec20bcabe7c372d423d14c71b2ddf722fNathan Hjelm 333913a233ec20bcabe7c372d423d14c71b2ddf722fNathan Hjelm struct list_head list; 3341df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake}; 335852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 33687a97e4f2065cc7190b0098b4d0df5a68e10a547Chris Dickensenum usbi_event_flags { 33787a97e4f2065cc7190b0098b4d0df5a68e10a547Chris Dickens /* The list of pollfds has been modified */ 33887a97e4f2065cc7190b0098b4d0df5a68e10a547Chris Dickens USBI_EVENT_POLLFDS_MODIFIED = 1 << 0, 339a6db382ad11f7662b550338e0570d5a2dfd8ce5aChris Dickens 340a6db382ad11f7662b550338e0570d5a2dfd8ce5aChris Dickens /* The user has interrupted the event handler */ 341a6db382ad11f7662b550338e0570d5a2dfd8ce5aChris Dickens USBI_EVENT_USER_INTERRUPT = 1 << 1, 34287a97e4f2065cc7190b0098b4d0df5a68e10a547Chris Dickens}; 34387a97e4f2065cc7190b0098b4d0df5a68e10a547Chris Dickens 344960a6e7506c4d0d59052056ae2ebfffbe8587175Chris Dickens/* Macros for managing event handling state */ 345960a6e7506c4d0d59052056ae2ebfffbe8587175Chris Dickens#define usbi_handling_events(ctx) \ 346960a6e7506c4d0d59052056ae2ebfffbe8587175Chris Dickens (usbi_tls_key_get((ctx)->event_handling_key) != NULL) 347960a6e7506c4d0d59052056ae2ebfffbe8587175Chris Dickens 348960a6e7506c4d0d59052056ae2ebfffbe8587175Chris Dickens#define usbi_start_event_handling(ctx) \ 349960a6e7506c4d0d59052056ae2ebfffbe8587175Chris Dickens usbi_tls_key_set((ctx)->event_handling_key, ctx) 350960a6e7506c4d0d59052056ae2ebfffbe8587175Chris Dickens 351960a6e7506c4d0d59052056ae2ebfffbe8587175Chris Dickens#define usbi_end_event_handling(ctx) \ 352960a6e7506c4d0d59052056ae2ebfffbe8587175Chris Dickens usbi_tls_key_set((ctx)->event_handling_key, NULL) 353960a6e7506c4d0d59052056ae2ebfffbe8587175Chris Dickens 35489b5407b9aa74790a64b6f32a5b14a96242ba128Chris Dickens/* Update the following macro if new event sources are added */ 35589b5407b9aa74790a64b6f32a5b14a96242ba128Chris Dickens#define usbi_pending_events(ctx) \ 35687a97e4f2065cc7190b0098b4d0df5a68e10a547Chris Dickens ((ctx)->event_flags || (ctx)->device_close \ 357fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens || !list_empty(&(ctx)->hotplug_msgs) || !list_empty(&(ctx)->completed_transfers)) 35889b5407b9aa74790a64b6f32a5b14a96242ba128Chris Dickens 3594783008b7e711de9cb31631e60dda995f44068deDaniel Drake#ifdef USBI_TIMERFD_AVAILABLE 3604783008b7e711de9cb31631e60dda995f44068deDaniel Drake#define usbi_using_timerfd(ctx) ((ctx)->timerfd >= 0) 3614783008b7e711de9cb31631e60dda995f44068deDaniel Drake#else 3624783008b7e711de9cb31631e60dda995f44068deDaniel Drake#define usbi_using_timerfd(ctx) (0) 3634783008b7e711de9cb31631e60dda995f44068deDaniel Drake#endif 3644783008b7e711de9cb31631e60dda995f44068deDaniel Drake 3659cfdb494fccac53a4277da7c8b6d15f1a72a4959Daniel Drakestruct libusb_device { 3661fcdb0678b759569db7cd530457dbc0a5f86fb1dDaniel Drake /* lock protects refcnt, everything else is finalized at initialization 3671fcdb0678b759569db7cd530457dbc0a5f86fb1dDaniel Drake * time */ 36823b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t lock; 3699cfdb494fccac53a4277da7c8b6d15f1a72a4959Daniel Drake int refcnt; 3701fcdb0678b759569db7cd530457dbc0a5f86fb1dDaniel Drake 3711df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct libusb_context *ctx; 3721df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 3733675e978fb7a1042f8601931255658bcd14a2298Daniel Drake uint8_t bus_number; 374cfb8610242394d532778a483570089c2bed52c84Pete Batard uint8_t port_number; 375cfb8610242394d532778a483570089c2bed52c84Pete Batard struct libusb_device* parent_dev; 3763675e978fb7a1042f8601931255658bcd14a2298Daniel Drake uint8_t device_address; 377c3844f7aeb2176636ce6e6ef697659fdb0b30048Daniel Drake uint8_t num_configurations; 378c8c40bcbd22abca922ff31c4ed6a75fd7af78b59Hans de Goede enum libusb_speed speed; 3793675e978fb7a1042f8601931255658bcd14a2298Daniel Drake 3801fcdb0678b759569db7cd530457dbc0a5f86fb1dDaniel Drake struct list_head list; 381f3fdf447916289cd92b7190377681894e8ab611aDaniel Drake unsigned long session_data; 3828399b52062e9aa2877ab6f61622fe9cb241fad57Nathan Hjelm 3838399b52062e9aa2877ab6f61622fe9cb241fad57Nathan Hjelm struct libusb_device_descriptor device_descriptor; 3847801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm int attached; 3858399b52062e9aa2877ab6f61622fe9cb241fad57Nathan Hjelm 3866e501b377dd0bccaefce5604616614deb2abb3fcSean McBride unsigned char os_priv 3876e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) 3886e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [] /* valid C99 code */ 3896e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#else 3906e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [0] /* non-standard, but usually working code */ 3916e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#endif 392eefd32213ec191967acc3b40b5c7c61064bc1273Lei Chen#if defined(OS_SUNOS) 393eefd32213ec191967acc3b40b5c7c61064bc1273Lei Chen __attribute__ ((aligned (8))); 394eefd32213ec191967acc3b40b5c7c61064bc1273Lei Chen#else 3956e501b377dd0bccaefce5604616614deb2abb3fcSean McBride ; 396eefd32213ec191967acc3b40b5c7c61064bc1273Lei Chen#endif 397852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake}; 398852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 399ebad1c79688ba603ad017ed0fe2f3c0dc8edd1adDaniel Drakestruct libusb_device_handle { 400e20f8281fb7da32587f81b5eea5818af1eab0fe0Daniel Drake /* lock protects claimed_interfaces */ 40123b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t lock; 402e20f8281fb7da32587f81b5eea5818af1eab0fe0Daniel Drake unsigned long claimed_interfaces; 403e20f8281fb7da32587f81b5eea5818af1eab0fe0Daniel Drake 404852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake struct list_head list; 4059cfdb494fccac53a4277da7c8b6d15f1a72a4959Daniel Drake struct libusb_device *dev; 406fc51f19341af70508b94c06ff763842b396ea72eHans de Goede int auto_detach_kernel_driver; 4076e501b377dd0bccaefce5604616614deb2abb3fcSean McBride unsigned char os_priv 4086e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) 4096e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [] /* valid C99 code */ 4106e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#else 4116e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [0] /* non-standard, but usually working code */ 4126e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#endif 413eefd32213ec191967acc3b40b5c7c61064bc1273Lei Chen#if defined(OS_SUNOS) 414eefd32213ec191967acc3b40b5c7c61064bc1273Lei Chen __attribute__ ((aligned (8))); 415eefd32213ec191967acc3b40b5c7c61064bc1273Lei Chen#else 4166e501b377dd0bccaefce5604616614deb2abb3fcSean McBride ; 417eefd32213ec191967acc3b40b5c7c61064bc1273Lei Chen#endif 418852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake}; 419852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 4209196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelmenum { 421c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens USBI_CLOCK_MONOTONIC, 422c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens USBI_CLOCK_REALTIME 4239196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm}; 4249196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm 425211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake/* in-memory transfer layout: 426211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 427211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 1. struct usbi_transfer 428211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 2. struct libusb_transfer (which includes iso packets) [variable size] 429211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 3. os private data [variable size] 430211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 431211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * from a libusb_transfer, you can get the usbi_transfer by rewinding the 432211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * appropriate number of bytes. 433211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * the usbi_transfer includes the number of allocated packets, so you can 434211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * determine the size of the transfer and hence the start and length of the 435211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * OS-private data. 436211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake */ 437852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 438211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drakestruct usbi_transfer { 439211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake int num_iso_packets; 440852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake struct list_head list; 441e8dad7c37e0cdd7087be32073fb0a237cc18bd7bChris Dickens struct list_head completed_list; 442637a8d7ff8a11a23588925d9d3003a609bda8075Daniel Drake struct timeval timeout; 443852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake int transferred; 4446d8dfe0aee41a3c7dd862c3de488df3ce452d86eHans de Goede uint32_t stream_id; 445138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens uint8_t state_flags; /* Protected by usbi_transfer->lock */ 446138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens uint8_t timeout_flags; /* Protected by the flying_stransfers_lock */ 44769830057547396f893f0d7b3125a05d016313b10Daniel Drake 44869830057547396f893f0d7b3125a05d016313b10Daniel Drake /* this lock is held during libusb_submit_transfer() and 44969830057547396f893f0d7b3125a05d016313b10Daniel Drake * libusb_cancel_transfer() (allowing the OS backend to prevent duplicate 45069830057547396f893f0d7b3125a05d016313b10Daniel Drake * cancellation, submission-during-cancellation, etc). the OS backend 45169830057547396f893f0d7b3125a05d016313b10Daniel Drake * should also take this lock in the handle_events path, to prevent the user 45269830057547396f893f0d7b3125a05d016313b10Daniel Drake * cancelling the transfer from another thread while you are processing 45369830057547396f893f0d7b3125a05d016313b10Daniel Drake * its completion (presumably there would be races within your OS backend 454138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens * if this were possible). 455138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens * Note paths taking both this and the flying_transfers_lock must 456138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens * always take the flying_transfers_lock first */ 45723b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t lock; 458852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake}; 459852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 460138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickensenum usbi_transfer_state_flags { 461138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens /* Transfer successfully submitted by backend */ 462138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens USBI_TRANSFER_IN_FLIGHT = 1 << 0, 4638f1bc0659136faf312dabe8fe67380a798299d33Vitali Lovich 4648f1bc0659136faf312dabe8fe67380a798299d33Vitali Lovich /* Cancellation was requested via libusb_cancel_transfer() */ 465138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens USBI_TRANSFER_CANCELLING = 1 << 1, 4668f1bc0659136faf312dabe8fe67380a798299d33Vitali Lovich 4678f1bc0659136faf312dabe8fe67380a798299d33Vitali Lovich /* Operation on the transfer failed because the device disappeared */ 468138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens USBI_TRANSFER_DEVICE_DISAPPEARED = 1 << 2, 469138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens}; 470a886bb02c87dd5faf271fad595e4622f7027d347Chris Dickens 471138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickensenum usbi_transfer_timeout_flags { 472138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens /* Set by backend submit_transfer() if the OS handles timeout */ 473138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens USBI_TRANSFER_OS_HANDLES_TIMEOUT = 1 << 0, 4742e1781e7c57384166e04d7728c42e45665d07b09Chris Dickens 4752e1781e7c57384166e04d7728c42e45665d07b09Chris Dickens /* The transfer timeout has been handled */ 476138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens USBI_TRANSFER_TIMEOUT_HANDLED = 1 << 1, 477138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens 478138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens /* The transfer timeout was successfully processed */ 479138b661f4214e9fc10e836f3a8abebeb166da896Chris Dickens USBI_TRANSFER_TIMED_OUT = 1 << 2, 48067d9ef7b6877e17f2deec81cd41dc0948f6bed4bNathan Hjelm}; 48167d9ef7b6877e17f2deec81cd41dc0948f6bed4bNathan Hjelm 482c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define USBI_TRANSFER_TO_LIBUSB_TRANSFER(transfer) \ 483c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens ((struct libusb_transfer *)(((unsigned char *)(transfer)) \ 484211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake + sizeof(struct usbi_transfer))) 485c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens#define LIBUSB_TRANSFER_TO_USBI_TRANSFER(transfer) \ 486c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens ((struct usbi_transfer *)(((unsigned char *)(transfer)) \ 487211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake - sizeof(struct usbi_transfer))) 488211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake 489211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drakestatic inline void *usbi_transfer_get_os_priv(struct usbi_transfer *transfer) 490211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake{ 491d7031ee8e1c449af23b2674fe18d9fc652c9bd80Pete Batard return ((unsigned char *)transfer) + sizeof(struct usbi_transfer) 492211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake + sizeof(struct libusb_transfer) 493211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake + (transfer->num_iso_packets 494211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * sizeof(struct libusb_iso_packet_descriptor)); 495211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake} 496211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake 497852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake/* bus structures */ 498852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 499a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake/* All standard descriptors have these 2 fields in common */ 500a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drakestruct usb_descriptor_header { 501c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens uint8_t bLength; 502c37f8f4b143a41cf16302b7cdba2dbfbb01b9eefChris Dickens uint8_t bDescriptorType; 503a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake}; 504a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake 505852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake/* shared data and functions */ 506852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 507c32aa662769b676ff3247778664fccc71fc427ecDaniel Drakeint usbi_io_init(struct libusb_context *ctx); 508c32aa662769b676ff3247778664fccc71fc427ecDaniel Drakevoid usbi_io_exit(struct libusb_context *ctx); 509c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 5101df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakestruct libusb_device *usbi_alloc_device(struct libusb_context *ctx, 5111df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake unsigned long session_id); 5121df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakestruct libusb_device *usbi_get_device_by_session_id(struct libusb_context *ctx, 5131df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake unsigned long session_id); 514fe4adcc99e30115204ab832ad3e0170c9aca7629Daniel Drakeint usbi_sanitize_device(struct libusb_device *dev); 5158a0c14372f98d56529556f18126a42fda2ab0137Chris Dickensvoid usbi_handle_disconnect(struct libusb_device_handle *dev_handle); 516c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 5174783008b7e711de9cb31631e60dda995f44068deDaniel Drakeint usbi_handle_transfer_completion(struct usbi_transfer *itransfer, 518c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake enum libusb_transfer_status status); 5194783008b7e711de9cb31631e60dda995f44068deDaniel Drakeint usbi_handle_transfer_cancellation(struct usbi_transfer *transfer); 520fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickensvoid usbi_signal_transfer_completion(struct usbi_transfer *transfer); 521852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 522ef698c633d2ecb597be58deccfa2795cc6c88e25Hans de Goedeint usbi_parse_descriptor(const unsigned char *source, const char *descriptor, 5233b41c31d3fa2c1f93649cc5fc0f59acbf3efd5a1Ludovic Rousseau void *dest, int host_endian); 5248399b52062e9aa2877ab6f61622fe9cb241fad57Nathan Hjelmint usbi_device_cache_descriptor(libusb_device *dev); 5258ebb4ccdfaf5f095a1c38787d909d280ea64405cDaniel Drakeint usbi_get_config_index_by_value(struct libusb_device *dev, 5268ebb4ccdfaf5f095a1c38787d909d280ea64405cDaniel Drake uint8_t bConfigurationValue, int *idx); 527a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake 5287801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelmvoid usbi_connect_device (struct libusb_device *dev); 5297801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelmvoid usbi_disconnect_device (struct libusb_device *dev); 5307801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm 531192adf437baec398bec36de50737a570e6c2f29cChris Dickensint usbi_signal_event(struct libusb_context *ctx); 532192adf437baec398bec36de50737a570e6c2f29cChris Dickensint usbi_clear_event(struct libusb_context *ctx); 533192adf437baec398bec36de50737a570e6c2f29cChris Dickens 5348035a7748980704c439b5d729bed8a0d75d47046Chris Dickens/* Internal abstraction for poll (needs struct usbi_transfer on Windows) */ 535eefd32213ec191967acc3b40b5c7c61064bc1273Lei Chen#if defined(OS_LINUX) || defined(OS_DARWIN) || defined(OS_OPENBSD) || defined(OS_NETBSD) ||\ 536eefd32213ec191967acc3b40b5c7c61064bc1273Lei Chen defined(OS_HAIKU) || defined(OS_SUNOS) 5378035a7748980704c439b5d729bed8a0d75d47046Chris Dickens#include <unistd.h> 5388035a7748980704c439b5d729bed8a0d75d47046Chris Dickens#include "os/poll_posix.h" 5398035a7748980704c439b5d729bed8a0d75d47046Chris Dickens#elif defined(OS_WINDOWS) || defined(OS_WINCE) 5408035a7748980704c439b5d729bed8a0d75d47046Chris Dickens#include "os/poll_windows.h" 5418035a7748980704c439b5d729bed8a0d75d47046Chris Dickens#endif 5428035a7748980704c439b5d729bed8a0d75d47046Chris Dickens 5437b893cc7cee185c0bf771166ca61a05b32800556Pete Batard#if (defined(OS_WINDOWS) || defined(OS_WINCE)) && !defined(__GNUC__) 5447b893cc7cee185c0bf771166ca61a05b32800556Pete Batard#define snprintf _snprintf 5457b893cc7cee185c0bf771166ca61a05b32800556Pete Batard#define vsnprintf _vsnprintf 546790ffc78b008a03c95d10899f53997b504f55c72Toby Grayint usbi_gettimeofday(struct timeval *tp, void *tzp); 547790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#define LIBUSB_GETTIMEOFDAY_WIN32 548790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#define HAVE_USBI_GETTIMEOFDAY 549790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#else 550790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#ifdef HAVE_GETTIMEOFDAY 551790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#define usbi_gettimeofday(tv, tz) gettimeofday((tv), (tz)) 552790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#define HAVE_USBI_GETTIMEOFDAY 553790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#endif 554790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#endif 555c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 556c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakestruct usbi_pollfd { 557c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake /* must come first */ 558c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake struct libusb_pollfd pollfd; 559c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 560c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake struct list_head list; 561c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake}; 562c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 5631df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakeint usbi_add_pollfd(struct libusb_context *ctx, int fd, short events); 5641df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakevoid usbi_remove_pollfd(struct libusb_context *ctx, int fd); 565c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 566c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake/* device discovery */ 567c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 568c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake/* we traverse usbfs without knowing how many devices we are going to find. 569c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake * so we create this discovered_devs model which is similar to a linked-list 570c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake * which grows when required. it can be freed once discovery has completed, 571c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake * eliminating the need for a list node in the libusb_device structure 572c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake * itself. */ 573c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakestruct discovered_devs { 574c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t len; 575c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t capacity; 5766e501b377dd0bccaefce5604616614deb2abb3fcSean McBride struct libusb_device *devices 5776e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) 5786e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [] /* valid C99 code */ 5796e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#else 5806e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [0] /* non-standard, but usually working code */ 5816e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#endif 5826e501b377dd0bccaefce5604616614deb2abb3fcSean McBride ; 583c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake}; 584c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 585c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakestruct discovered_devs *discovered_devs_append( 586c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake struct discovered_devs *discdevs, struct libusb_device *dev); 587c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 588c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake/* OS abstraction */ 589c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 5901298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake/* This is the interface that OS backends need to implement. 5911298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * All fields are mandatory, except ones explicitly noted as optional. */ 592c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakestruct usbi_os_backend { 5931298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* A human-readable name for your backend, e.g. "Linux usbfs" */ 594c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake const char *name; 5951298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 596e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard /* Binary mask for backend specific capabilities */ 597e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard uint32_t caps; 598e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard 5991298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Perform initialization of your backend. You might use this function 6001298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * to determine specific capabilities of the system, allocate required 6011298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * data structures for later, etc. 6021298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6031eff220474f63d7ea7f8f99bef2a3da9da5324ebhjelmn@cs.unm.edu * This function is called when a libusb user initializes the library 6041298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * prior to use. 6051298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6061298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success, or a LIBUSB_ERROR code on failure. 6071298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 6081df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int (*init)(struct libusb_context *ctx); 6091298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 6101298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Deinitialization. Optional. This function should destroy anything 6111298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * that was set up by init. 6121298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6131298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when the user deinitializes the library. 6141298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 615c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake void (*exit)(void); 616c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 6171298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Enumerate all the USB devices on the system, returning them in a list 6181298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * of discovered devices. 6191298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6201298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Your implementation should enumerate all devices on the system, 6211298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * regardless of whether they have been seen before or not. 6221298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6231298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * When you have found a device, compute a session ID for it. The session 6241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * ID should uniquely represent that particular device for that particular 6251298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * connection session since boot (i.e. if you disconnect and reconnect a 6261298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device immediately after, it should be assigned a different session ID). 6271298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If your OS cannot provide a unique session ID as described above, 6281298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * presenting a session ID of (bus_number << 8 | device_address) should 6291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * be sufficient. Bus numbers and device addresses wrap and get reused, 6301298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * but that is an unlikely case. 6311298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6321298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * After computing a session ID for a device, call 6331eff220474f63d7ea7f8f99bef2a3da9da5324ebhjelmn@cs.unm.edu * usbi_get_device_by_session_id(). This function checks if libusb already 634733ffffe44ad93bd81feddb0a8072510fd7a8321Hans de Goede * knows about the device, and if so, it provides you with a reference 635733ffffe44ad93bd81feddb0a8072510fd7a8321Hans de Goede * to a libusb_device structure for it. 6361298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6371298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If usbi_get_device_by_session_id() returns NULL, it is time to allocate 6381298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * a new device structure for the device. Call usbi_alloc_device() to 6391298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * obtain a new libusb_device structure with reference count 1. Populate 6401298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * the bus_number and device_address attributes of the new device, and 6411298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * perform any other internal backend initialization you need to do. At 6421298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * this point, you should be ready to provide device descriptors and so 6431298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * on through the get_*_descriptor functions. Finally, call 6441298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * usbi_sanitize_device() to perform some final sanity checks on the 6451298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device. Assuming all of the above succeeded, we can now continue. 6461298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If any of the above failed, remember to unreference the device that 6471298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was returned by usbi_alloc_device(). 6481298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6491298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * At this stage we have a populated libusb_device structure (either one 6501298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * that was found earlier, or one that we have just allocated and 6511298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * populated). This can now be added to the discovered devices list 6521298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * using discovered_devs_append(). Note that discovered_devs_append() 6531298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * may reallocate the list, returning a new location for it, and also 6541298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * note that reallocation can fail. Your backend should handle these 6551298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * error conditions appropriately. 6561298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6571298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should not generate any bus I/O and should not block. 6581298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If I/O is required (e.g. reading the active configuration value), it is 6591298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * OK to ignore these suggestions :) 6601298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6611298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is executed when the user wishes to retrieve a list 6621298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * of USB devices connected to the system. 6631298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 664cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * If the backend has hotplug support, this function is not used! 665cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * 6661298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success, or a LIBUSB_ERROR code on failure. 6671298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 6681df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int (*get_device_list)(struct libusb_context *ctx, 6691df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct discovered_devs **discdevs); 670c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 671cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede /* Apps which were written before hotplug support, may listen for 672cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * hotplug events on their own and call libusb_get_device_list on 673cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * device addition. In this case libusb_get_device_list will likely 674cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * return a list without the new device in there, as the hotplug 675cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * event thread will still be busy enumerating the device, which may 676cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * take a while, or may not even have seen the event yet. 677cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * 678cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * To avoid this libusb_get_device_list will call this optional 679cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * function for backends with hotplug support before copying 680cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * ctx->usb_devs to the user. In this function the backend should 681cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * ensure any pending hotplug events are fully processed before 682cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * returning. 683cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * 684cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * Optional, should be implemented by backends with hotplug support. 685cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede */ 686cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede void (*hotplug_poll)(void); 687cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede 6881298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Open a device for I/O and other USB operations. The device handle 6891298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * is preallocated for you, you can retrieve the device in question 6901298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * through handle->dev. 6911298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6921298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Your backend should allocate any internal resources required for I/O 6931298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * and other operations so that those operations can happen (hopefully) 6941eff220474f63d7ea7f8f99bef2a3da9da5324ebhjelmn@cs.unm.edu * without hiccup. This is also a good place to inform libusb that it 6951298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * should monitor certain file descriptors related to this device - 6961298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * see the usbi_add_pollfd() function. 6971298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6981298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should not generate any bus I/O and should not block. 6991298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7001298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when the user attempts to obtain a device 7011298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * handle for a device. 7021298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7031298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 7041298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 7051298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_ACCESS if the user has insufficient permissions 7061298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since 7071298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * discovery 7081298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 7091298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7101298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Do not worry about freeing the handle on failed open, the upper layers 7111298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * do this for you. 7121298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 7138a0c14372f98d56529556f18126a42fda2ab0137Chris Dickens int (*open)(struct libusb_device_handle *dev_handle); 7141298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 7151298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Close a device such that the handle cannot be used again. Your backend 7161298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * should destroy any resources that were allocated in the open path. 7171298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This may also be a good place to call usbi_remove_pollfd() to inform 7181eff220474f63d7ea7f8f99bef2a3da9da5324ebhjelmn@cs.unm.edu * libusb of any file descriptors associated with this device that should 7191298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * no longer be monitored. 7201298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7211298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when the user closes a device handle. 7221298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 7238a0c14372f98d56529556f18126a42fda2ab0137Chris Dickens void (*close)(struct libusb_device_handle *dev_handle); 724c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 7251298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Retrieve the device descriptor from a device. 7261298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7271298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The descriptor should be retrieved from memory, NOT via bus I/O to the 7281298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device. This means that you may have to cache it in a private structure 7291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * during get_device_list enumeration. Alternatively, you may be able 7301298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * to retrieve it from a kernel interface (some Linux setups can do this) 7311298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * still without generating bus I/O. 7321298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7331298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is expected to write DEVICE_DESC_LENGTH (18) bytes into 7341298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * buffer, which is guaranteed to be big enough. 7351298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7361298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when sanity-checking a device before adding 7371298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * it to the list of discovered devices, and also when the user requests 7381298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * to read the device descriptor. 7391298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7402b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * This function is expected to return the descriptor in bus-endian format 7412b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * (LE). If it returns the multi-byte values in host-endian format, 7422b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * set the host_endian output parameter to "1". 7432b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * 7441298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success or a LIBUSB_ERROR code on failure. 7451298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 746b27fff633843824744df7d334cb89ece329cafa6Daniel Drake int (*get_device_descriptor)(struct libusb_device *device, 7472b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake unsigned char *buffer, int *host_endian); 7481298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 7491298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Get the ACTIVE configuration descriptor for a device. 7501298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7511298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The descriptor should be retrieved from memory, NOT via bus I/O to the 7521298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device. This means that you may have to cache it in a private structure 7531298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * during get_device_list enumeration. You may also have to keep track 7541298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * of which configuration is active when the user changes it. 7551298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7561298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is expected to write len bytes of data into buffer, which 7571298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * is guaranteed to be big enough. If you can only do a partial write, 7581298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * return an error code. 7591298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7602b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * This function is expected to return the descriptor in bus-endian format 7612b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * (LE). If it returns the multi-byte values in host-endian format, 7622b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * set the host_endian output parameter to "1". 7632b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * 7641298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 7651298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 7661298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state 7671298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 7681298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 769fe4adcc99e30115204ab832ad3e0170c9aca7629Daniel Drake int (*get_active_config_descriptor)(struct libusb_device *device, 7702b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake unsigned char *buffer, size_t len, int *host_endian); 7711298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 7721298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Get a specific configuration descriptor for a device. 7731298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7741298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The descriptor should be retrieved from memory, NOT via bus I/O to the 7751298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device. This means that you may have to cache it in a private structure 7761298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * during get_device_list enumeration. 7771298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7781298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The requested descriptor is expressed as a zero-based index (i.e. 0 7791298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * indicates that we are requesting the first descriptor). The index does 7801298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * not (necessarily) equal the bConfigurationValue of the configuration 7811298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * being requested. 7821298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7831298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is expected to write len bytes of data into buffer, which 7841298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * is guaranteed to be big enough. If you can only do a partial write, 7851298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * return an error code. 7861298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7872b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * This function is expected to return the descriptor in bus-endian format 7882b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * (LE). If it returns the multi-byte values in host-endian format, 7892b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * set the host_endian output parameter to "1". 7902b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * 79119e88a6a588c51c0b3284e2b71385b12b0a37029Nathan Hjelm * Return the length read on success or a LIBUSB_ERROR code on failure. 7921298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 793c3844f7aeb2176636ce6e6ef697659fdb0b30048Daniel Drake int (*get_config_descriptor)(struct libusb_device *device, 7942b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake uint8_t config_index, unsigned char *buffer, size_t len, 7952b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake int *host_endian); 796b27fff633843824744df7d334cb89ece329cafa6Daniel Drake 7976b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede /* Like get_config_descriptor but then by bConfigurationValue instead 7986b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * of by index. 7996b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * 8006b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * Optional, if not present the core will call get_config_descriptor 8016b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * for all configs until it finds the desired bConfigurationValue. 8026b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * 8036b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * Returns a pointer to the raw-descriptor in *buffer, this memory 8046b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * is valid as long as device is valid. 8056b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * 8066b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * Returns the length of the returned raw-descriptor on success, 8076b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * or a LIBUSB_ERROR code on failure. 8086b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede */ 8096b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede int (*get_config_descriptor_by_value)(struct libusb_device *device, 8106b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede uint8_t bConfigurationValue, unsigned char **buffer, 8116b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede int *host_endian); 8126b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede 813514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake /* Get the bConfigurationValue for the active configuration for a device. 814514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * Optional. This should only be implemented if you can retrieve it from 815514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * cache (don't generate I/O). 816514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * 817514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * If you cannot retrieve this from cache, either do not implement this 818514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * function, or return LIBUSB_ERROR_NOT_SUPPORTED. This will cause 8191eff220474f63d7ea7f8f99bef2a3da9da5324ebhjelmn@cs.unm.edu * libusb to retrieve the information through a standard control transfer. 820514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * 821514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * This function must be non-blocking. 822514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * Return: 823514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * - 0 on success 824514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 825514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * was opened 826514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * - LIBUSB_ERROR_NOT_SUPPORTED if the value cannot be retrieved without 827514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * blocking 828514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * - another LIBUSB_ERROR code on other failure. 829514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake */ 8308a0c14372f98d56529556f18126a42fda2ab0137Chris Dickens int (*get_configuration)(struct libusb_device_handle *dev_handle, int *config); 831514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake 8321298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Set the active configuration for a device. 8331298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8341298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * A configuration value of -1 should put the device in unconfigured state. 8351298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8361298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function can block. 8371298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8381298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 8391298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 8401298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the configuration does not exist 8411298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_BUSY if interfaces are currently claimed (and hence 8421298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * configuration cannot be changed) 8431298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 8441298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 8451298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure. 8461298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 8478a0c14372f98d56529556f18126a42fda2ab0137Chris Dickens int (*set_configuration)(struct libusb_device_handle *dev_handle, int config); 8480f463fe671455670efcf4a93e526b2a9082b0afeDaniel Drake 8491298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Claim an interface. When claimed, the application can then perform 8501298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * I/O to an interface's endpoints. 8511298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8521298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should not generate any bus I/O and should not block. 8531298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Interface claiming is a logical operation that simply ensures that 8541298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * no other drivers/applications are using the interface, and after 855b000fe1821dceb5e19fc811a6ee2b977205d4034orbitcowboy * claiming, no other drivers/applications can use the interface because 8561298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * we now "own" it. 8571298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8581298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 8591298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 8601298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the interface does not exist 8611298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_BUSY if the interface is in use by another driver/app 8621298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 8631298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 8641298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 8651298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 8668a0c14372f98d56529556f18126a42fda2ab0137Chris Dickens int (*claim_interface)(struct libusb_device_handle *dev_handle, int interface_number); 8671298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 8681298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Release a previously claimed interface. 8691298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8701298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should also generate a SET_INTERFACE control request, 8711298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * resetting the alternate setting of that interface to 0. It's OK for 8721298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * this function to block as a result. 8731298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8741298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * You will only ever be asked to release an interface which was 8751298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * successfully claimed earlier. 8761298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8771298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 8781298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 8791298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 8801298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 8811298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 8821298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 8838a0c14372f98d56529556f18126a42fda2ab0137Chris Dickens int (*release_interface)(struct libusb_device_handle *dev_handle, int interface_number); 884c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 8851298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Set the alternate setting for an interface. 8861298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8871298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * You will only ever be asked to set the alternate setting for an 8881298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * interface which was successfully claimed earlier. 8891298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8901298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * It's OK for this function to block. 8911298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8921298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 8931298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 8941298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the alternate setting does not exist 8951298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 8961298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 8971298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 8981298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 8998a0c14372f98d56529556f18126a42fda2ab0137Chris Dickens int (*set_interface_altsetting)(struct libusb_device_handle *dev_handle, 9008aceb5c99056aaed6e6f2db1b303817e37e9fe8cPete Batard int interface_number, int altsetting); 9011298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 9021298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Clear a halt/stall condition on an endpoint. 9031298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 9041298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * It's OK for this function to block. 9051298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 9061298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 9071298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 9081298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist 9091298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 9101298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 9111298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 9121298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 9138a0c14372f98d56529556f18126a42fda2ab0137Chris Dickens int (*clear_halt)(struct libusb_device_handle *dev_handle, 914c01f744ce07bbeccbe353e956479f0cc5a811a6fDaniel Drake unsigned char endpoint); 9151298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 9161298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Perform a USB port reset to reinitialize a device. 9171298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 9188a0c14372f98d56529556f18126a42fda2ab0137Chris Dickens * If possible, the device handle should still be usable after the reset 9191298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * completes, assuming that the device descriptors did not change during 9201298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * reset and all previous interface state can be restored. 9211298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 9221298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If something changes, or you cannot easily locate/verify the resetted 9231298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device, return LIBUSB_ERROR_NOT_FOUND. This prompts the application 9241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * to close the old handle and re-enumerate the device. 9251298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 9261298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 9271298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 9281298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if re-enumeration is required, or if the device 9291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * has been disconnected since it was opened 9301298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 9311298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 9328a0c14372f98d56529556f18126a42fda2ab0137Chris Dickens int (*reset_device)(struct libusb_device_handle *dev_handle); 93362077b7fa5b222e1bb9dea3467585aed69d596e2Daniel Drake 9340504375ea965dd25f00d4828a19c329b7e7525d4Hans de Goede /* Alloc num_streams usb3 bulk streams on the passed in endpoints */ 9358a0c14372f98d56529556f18126a42fda2ab0137Chris Dickens int (*alloc_streams)(struct libusb_device_handle *dev_handle, 9360504375ea965dd25f00d4828a19c329b7e7525d4Hans de Goede uint32_t num_streams, unsigned char *endpoints, int num_endpoints); 9370504375ea965dd25f00d4828a19c329b7e7525d4Hans de Goede 9380504375ea965dd25f00d4828a19c329b7e7525d4Hans de Goede /* Free usb3 bulk streams allocated with alloc_streams */ 9398a0c14372f98d56529556f18126a42fda2ab0137Chris Dickens int (*free_streams)(struct libusb_device_handle *dev_handle, 9400504375ea965dd25f00d4828a19c329b7e7525d4Hans de Goede unsigned char *endpoints, int num_endpoints); 9410504375ea965dd25f00d4828a19c329b7e7525d4Hans de Goede 942a283c3b5a3dce8f6f33331b9aa1d95d41c8f241cSteinar H. Gunderson /* Allocate persistent DMA memory for the given device, suitable for 943a283c3b5a3dce8f6f33331b9aa1d95d41c8f241cSteinar H. Gunderson * zerocopy. May return NULL on failure. Optional to implement. 944a283c3b5a3dce8f6f33331b9aa1d95d41c8f241cSteinar H. Gunderson */ 945a283c3b5a3dce8f6f33331b9aa1d95d41c8f241cSteinar H. Gunderson unsigned char *(*dev_mem_alloc)(struct libusb_device_handle *handle, 946a283c3b5a3dce8f6f33331b9aa1d95d41c8f241cSteinar H. Gunderson size_t len); 947a283c3b5a3dce8f6f33331b9aa1d95d41c8f241cSteinar H. Gunderson 948a283c3b5a3dce8f6f33331b9aa1d95d41c8f241cSteinar H. Gunderson /* Free memory allocated by dev_mem_alloc. */ 949a283c3b5a3dce8f6f33331b9aa1d95d41c8f241cSteinar H. Gunderson int (*dev_mem_free)(struct libusb_device_handle *handle, 950a283c3b5a3dce8f6f33331b9aa1d95d41c8f241cSteinar H. Gunderson unsigned char *buffer, size_t len); 951a283c3b5a3dce8f6f33331b9aa1d95d41c8f241cSteinar H. Gunderson 9521298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Determine if a kernel driver is active on an interface. Optional. 9531298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 9541298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The presence of a kernel driver on an interface indicates that any 9551298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * calls to claim_interface would fail with the LIBUSB_ERROR_BUSY code. 9561298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 9571298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 9581298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 if no driver is active 9591298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 1 if a driver is active 9601298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 9611298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 9621298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 9631298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 9648a0c14372f98d56529556f18126a42fda2ab0137Chris Dickens int (*kernel_driver_active)(struct libusb_device_handle *dev_handle, 9658aceb5c99056aaed6e6f2db1b303817e37e9fe8cPete Batard int interface_number); 966a636df4ca1b87ed3094a87828c022092a80ba613Pete Batard 9671298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Detach a kernel driver from an interface. Optional. 9681298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 9691298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * After detaching a kernel driver, the interface should be available 9701298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * for claim. 9711298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 9721298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 9731298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 9741298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if no kernel driver was active 9751298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_INVALID_PARAM if the interface does not exist 9761298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 9771298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 9781298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 9791298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 9808a0c14372f98d56529556f18126a42fda2ab0137Chris Dickens int (*detach_kernel_driver)(struct libusb_device_handle *dev_handle, 9818aceb5c99056aaed6e6f2db1b303817e37e9fe8cPete Batard int interface_number); 982470b1bc42bf53373ce678fc76bab9160a54d6881Daniel Drake 9831d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera /* Attach a kernel driver to an interface. Optional. 9841d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * 9851d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * Reattach a kernel driver to the device. 9861d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * 9871d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * Return: 9881d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - 0 on success 9891d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - LIBUSB_ERROR_NOT_FOUND if no kernel driver was active 9901d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - LIBUSB_ERROR_INVALID_PARAM if the interface does not exist 9911d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 9921d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * was opened 9931d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - LIBUSB_ERROR_BUSY if a program or driver has claimed the interface, 9941d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * preventing reattachment 9951d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - another LIBUSB_ERROR code on other failure 9961d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera */ 9978a0c14372f98d56529556f18126a42fda2ab0137Chris Dickens int (*attach_kernel_driver)(struct libusb_device_handle *dev_handle, 9988aceb5c99056aaed6e6f2db1b303817e37e9fe8cPete Batard int interface_number); 9991d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera 10001298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Destroy a device. Optional. 10011298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 10021298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when the last reference to a device is 10031298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * destroyed. It should free any resources allocated in the get_device_list 10041298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * path. 10051298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 1006c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake void (*destroy_device)(struct libusb_device *dev); 1007c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 10081298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Submit a transfer. Your implementation should take the transfer, 10091298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * morph it into whatever form your platform requires, and submit it 10101298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * asynchronously. 10111298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 10121298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function must not block. 10131298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 1014858b794cf10ff1ac76a4f453bed7645aa9709c44Hans de Goede * This function gets called with the flying_transfers_lock locked! 1015858b794cf10ff1ac76a4f453bed7645aa9709c44Hans de Goede * 10161298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 10171298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 10181298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 10191298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 10201298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 1021c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake int (*submit_transfer)(struct usbi_transfer *itransfer); 10221298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 10231298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Cancel a previously submitted transfer. 10241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 10251298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function must not block. The transfer cancellation must complete 10261298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * later, resulting in a call to usbi_handle_transfer_cancellation() 10271298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * from the context of handle_events. 10281298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 1029c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake int (*cancel_transfer)(struct usbi_transfer *itransfer); 10301298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 10311298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Clear a transfer as if it has completed or cancelled, but do not 10321298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * report any completion/cancellation to the library. You should free 10331298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * all private data from the transfer as if you were just about to report 10341298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * completion or cancellation. 10351298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 10361eff220474f63d7ea7f8f99bef2a3da9da5324ebhjelmn@cs.unm.edu * This function might seem a bit out of place. It is used when libusb 10371298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * detects a disconnected device - it calls this function for all pending 10381298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * transfers before reporting completion (with the disconnect code) to 10391298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * the user. Maybe we can improve upon this internal interface in future. 10401298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 1041fec7c84163e25b8f811632828334d75da82bcb16Daniel Drake void (*clear_transfer_priv)(struct usbi_transfer *itransfer); 1042c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 1043fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens /* Handle any pending events on file descriptors. Optional. 1044fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * 1045fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * Provide this function when file descriptors directly indicate device 1046fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * or transfer activity. If your backend does not have such file descriptors, 1047fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * implement the handle_transfer_completion function below. 1048fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * 1049fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * This involves monitoring any active transfers and processing their 1050fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * completion or cancellation. 10511298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 10521298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The function is passed an array of pollfd structures (size nfds) 10531298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * as a result of the poll() system call. The num_ready parameter 10541298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * indicates the number of file descriptors that have reported events 10551298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * (i.e. the poll() return value). This should be enough information 10561298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * for you to determine which actions need to be taken on the currently 10571298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * active transfers. 10581298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 10591298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * For any cancelled transfers, call usbi_handle_transfer_cancellation(). 10601298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * For completed transfers, call usbi_handle_transfer_completion(). 10611298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * For control/bulk/interrupt transfers, populate the "transferred" 10621298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * element of the appropriate usbi_transfer structure before calling the 10631298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * above functions. For isochronous transfers, populate the status and 10641298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * transferred fields of the iso packet descriptors of the transfer. 10651298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 10661298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should also be able to detect disconnection of the 10671298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device, reporting that situation with usbi_handle_disconnect(). 10681298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 106969830057547396f893f0d7b3125a05d016313b10Daniel Drake * When processing an event related to a transfer, you probably want to 107069830057547396f893f0d7b3125a05d016313b10Daniel Drake * take usbi_transfer.lock to prevent races. See the documentation for 107169830057547396f893f0d7b3125a05d016313b10Daniel Drake * the usbi_transfer structure. 107269830057547396f893f0d7b3125a05d016313b10Daniel Drake * 10731298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success, or a LIBUSB_ERROR code on failure. 10741298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 10751df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int (*handle_events)(struct libusb_context *ctx, 1076a120747d561929682cd0276ea4c13fb22fad8554Peter Stuge struct pollfd *fds, POLL_NFDS_TYPE nfds, int num_ready); 1077c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 1078fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens /* Handle transfer completion. Optional. 1079fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * 1080fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * Provide this function when there are no file descriptors available 1081fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * that directly indicate device or transfer activity. If your backend does 1082fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * have such file descriptors, implement the handle_events function above. 1083fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * 1084fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * Your backend must tell the library when a transfer has completed by 1085fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * calling usbi_signal_transfer_completion(). You should store any private 1086fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * information about the transfer and its completion status in the transfer's 1087fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * private backend data. 1088fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * 1089fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * During event handling, this function will be called on each transfer for 1090fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * which usbi_signal_transfer_completion() was called. 1091fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * 1092fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * For any cancelled transfers, call usbi_handle_transfer_cancellation(). 1093fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * For completed transfers, call usbi_handle_transfer_completion(). 1094fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * For control/bulk/interrupt transfers, populate the "transferred" 1095fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * element of the appropriate usbi_transfer structure before calling the 1096fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * above functions. For isochronous transfers, populate the status and 1097fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * transferred fields of the iso packet descriptors of the transfer. 1098fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * 1099fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens * Return 0 on success, or a LIBUSB_ERROR code on failure. 1100fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens */ 1101fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens int (*handle_transfer_completion)(struct usbi_transfer *itransfer); 1102fec3f8c6de4683f7107d5b68dd887c7c192ab0c0Chris Dickens 11039196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm /* Get time from specified clock. At least two clocks must be implemented 11049196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm by the backend: USBI_CLOCK_REALTIME, and USBI_CLOCK_MONOTONIC. 11059196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm 11069196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm Description of clocks: 11079196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm USBI_CLOCK_REALTIME : clock returns time since system epoch. 11089196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm USBI_CLOCK_MONOTONIC: clock returns time since unspecified start 11099196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm time (usually boot). 11109196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm */ 11119196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm int (*clock_gettime)(int clkid, struct timespec *tp); 11129196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm 11134783008b7e711de9cb31631e60dda995f44068deDaniel Drake#ifdef USBI_TIMERFD_AVAILABLE 11144783008b7e711de9cb31631e60dda995f44068deDaniel Drake /* clock ID of the clock that should be used for timerfd */ 11154783008b7e711de9cb31631e60dda995f44068deDaniel Drake clockid_t (*get_timerfd_clockid)(void); 11164783008b7e711de9cb31631e60dda995f44068deDaniel Drake#endif 11174783008b7e711de9cb31631e60dda995f44068deDaniel Drake 11181298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Number of bytes to reserve for per-device private backend data. 11191298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This private data area is accessible through the "os_priv" field of 11201298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * struct libusb_device. */ 1121c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t device_priv_size; 1122c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 11231298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Number of bytes to reserve for per-handle private backend data. 11241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This private data area is accessible through the "os_priv" field of 11251298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * struct libusb_device. */ 1126c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t device_handle_priv_size; 1127c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 11281298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Number of bytes to reserve for per-transfer private backend data. 11291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This private data area is accessible by calling 11301298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * usbi_transfer_get_os_priv() on the appropriate usbi_transfer instance. 11311298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 1132c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t transfer_priv_size; 1133c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake}; 1134c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 1135c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakeextern const struct usbi_os_backend * const usbi_backend; 1136c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 1137c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakeextern const struct usbi_os_backend linux_usbfs_backend; 1138b49f6bf5c910d0fd694ecf165d7927673707bff9Nathan Hjelmextern const struct usbi_os_backend darwin_backend; 1139c56828857eb7ba6fb4f7701693dbb3fe4e75d5f6Martin Pieuchotextern const struct usbi_os_backend openbsd_backend; 1140eb4e7bee4488cefcf13929d9c4fe784650fef7c7Hans de Goedeextern const struct usbi_os_backend netbsd_backend; 11419a4249f8a104b98a15a7e3ba7ecae9a385ed9027Pete Batardextern const struct usbi_os_backend windows_backend; 11428823c17024c59984c2dcf5870e27ab3a023428b9Dmitry Fleytmanextern const struct usbi_os_backend usbdk_backend; 1143244271931a782028fd9bc1cdcdb12200f65cf8d9Toby Grayextern const struct usbi_os_backend wince_backend; 1144dc97425bb415422423b8876af0e34111e566d56dAkshay Jaggiextern const struct usbi_os_backend haiku_usb_raw_backend; 1145eefd32213ec191967acc3b40b5c7c61064bc1273Lei Chenextern const struct usbi_os_backend sunos_backend; 1146c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 1147913a233ec20bcabe7c372d423d14c71b2ddf722fNathan Hjelmextern struct list_head active_contexts_list; 1148913a233ec20bcabe7c372d423d14c71b2ddf722fNathan Hjelmextern usbi_mutex_static_t active_contexts_lock; 1149913a233ec20bcabe7c372d423d14c71b2ddf722fNathan Hjelm 1150dc97425bb415422423b8876af0e34111e566d56dAkshay Jaggi#ifdef __cplusplus 1151dc97425bb415422423b8876af0e34111e566d56dAkshay Jaggi} 1152dc97425bb415422423b8876af0e34111e566d56dAkshay Jaggi#endif 1153dc97425bb415422423b8876af0e34111e566d56dAkshay Jaggi 1154852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#endif 1155