libusbi.h revision ef698c633d2ecb597be58deccfa2795cc6c88e25
1852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake/* 2791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard * Internal header for libusbx 3a544e5972bf2b0ac9e006439576f681a8439d311Pete Batard * Copyright © 2007-2009 Daniel Drake <dsd@gentoo.org> 4a544e5972bf2b0ac9e006439576f681a8439d311Pete Batard * Copyright © 2001 Johannes Erdfelt <johannes@erdfelt.com> 5852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * 6852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * This library is free software; you can redistribute it and/or 7852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * modify it under the terms of the GNU Lesser General Public 8852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * License as published by the Free Software Foundation; either 9852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * version 2.1 of the License, or (at your option) any later version. 10852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * 11852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * This library is distributed in the hope that it will be useful, 12852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * but WITHOUT ANY WARRANTY; without even the implied warranty of 13852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * Lesser General Public License for more details. 15852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * 16852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * You should have received a copy of the GNU Lesser General Public 17852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * License along with this library; if not, write to the Free Software 18852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 19852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake */ 20852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 21d1bd234f7e1b1ff4168b8f605e2038e87a0e361fNathan Hjelm#ifndef LIBUSBI_H 22d1bd234f7e1b1ff4168b8f605e2038e87a0e361fNathan Hjelm#define LIBUSBI_H 23852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 24e39b24ae5a6069b1571ecef3eb510c9e90db4956Sean McBride#include "config.h" 25852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 26852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#include <stddef.h> 27f6d60a9a8fcf06629812da886e3a5de592624b61Pete Batard#include <stdint.h> 28852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#include <time.h> 29a8e2e7cab278fbfcba91909eaf762cf66da9eda5Ludovic Rousseau#include <stdarg.h> 30a120747d561929682cd0276ea4c13fb22fad8554Peter Stuge#ifdef HAVE_POLL_H 31a120747d561929682cd0276ea4c13fb22fad8554Peter Stuge#include <poll.h> 32a120747d561929682cd0276ea4c13fb22fad8554Peter Stuge#endif 33852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 34baf714f5e0f22b968cea0e747c23eeced44f602ePete Batard#ifdef HAVE_MISSING_H 35baf714f5e0f22b968cea0e747c23eeced44f602ePete Batard#include "missing.h" 36baf714f5e0f22b968cea0e747c23eeced44f602ePete Batard#endif 37e39b24ae5a6069b1571ecef3eb510c9e90db4956Sean McBride#include "libusb.h" 3837dfd16c8c2f36c81c86de303072def0dc405e32Pete Batard#include "version.h" 39852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 40791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard/* Inside the libusbx code, mark all public functions as follows: 4129f9f9e3af3340df6a955881a93caf9d2a6d08d6Pete Batard * return_type API_EXPORTED function_name(params) { ... } 4229f9f9e3af3340df6a955881a93caf9d2a6d08d6Pete Batard * But if the function returns a pointer, mark it as follows: 4329f9f9e3af3340df6a955881a93caf9d2a6d08d6Pete Batard * DEFAULT_VISIBILITY return_type * LIBUSB_CALL function_name(params) { ... } 44791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard * In the libusbx public header, mark all declarations as: 4529f9f9e3af3340df6a955881a93caf9d2a6d08d6Pete Batard * return_type LIBUSB_CALL function_name(params); 4629f9f9e3af3340df6a955881a93caf9d2a6d08d6Pete Batard */ 4729f9f9e3af3340df6a955881a93caf9d2a6d08d6Pete Batard#define API_EXPORTED LIBUSB_CALL DEFAULT_VISIBILITY 4829f9f9e3af3340df6a955881a93caf9d2a6d08d6Pete Batard 49852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define DEVICE_DESC_LENGTH 18 50852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 51a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake#define USB_MAXENDPOINTS 32 52a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake#define USB_MAXINTERFACES 32 53a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake#define USB_MAXCONFIG 8 54a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake 55e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard/* Backend specific capabilities */ 56e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard#define USBI_CAP_HAS_HID_ACCESS 0x00010000 57e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard#define USBI_CAP_SUPPORTS_DETACH_KERNEL_DRIVER 0x00020000 58e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard 590e0cbb6c27efa5a2ae58c30267a4be9486c766ccPete Batard/* The following is used to silence warnings for unused variables */ 60e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard#define UNUSED(var) do { (void)(var); } while(0) 610e0cbb6c27efa5a2ae58c30267a4be9486c766ccPete Batard 62852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestruct list_head { 63852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake struct list_head *prev, *next; 64852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake}; 65852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 66a636df4ca1b87ed3094a87828c022092a80ba613Pete Batard/* Get an entry from the list 67a636df4ca1b87ed3094a87828c022092a80ba613Pete Batard * ptr - the address of this list_head element in "type" 68852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * type - the data type that contains "member" 69a636df4ca1b87ed3094a87828c022092a80ba613Pete Batard * member - the list_head element in "type" 70852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake */ 71852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define list_entry(ptr, type, member) \ 7279cf539b2a05da5e76841bf51dfa15a5c35e656eSean McBride ((type *)((uintptr_t)(ptr) - (uintptr_t)offsetof(type, member))) 73852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 74852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake/* Get each entry from a list 75852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * pos - A structure pointer has a "member" element 76852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * head - list head 77852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * member - the list_head element in "pos" 78aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard * type - the type of the first parameter 79852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake */ 80aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard#define list_for_each_entry(pos, head, member, type) \ 81aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard for (pos = list_entry((head)->next, type, member); \ 82aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard &pos->member != (head); \ 83aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard pos = list_entry(pos->member.next, type, member)) 84aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard 85aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard#define list_for_each_entry_safe(pos, n, head, member, type) \ 86aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard for (pos = list_entry((head)->next, type, member), \ 87aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard n = list_entry(pos->member.next, type, member); \ 88aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard &pos->member != (head); \ 89aa77b02da65afb0332b9e6853dae9e4dcda00bfaPete Batard pos = n, n = list_entry(n->member.next, type, member)) 90852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 91852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define list_empty(entry) ((entry)->next == (entry)) 92852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 93852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestatic inline void list_init(struct list_head *entry) 94852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake{ 95852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->prev = entry->next = entry; 96852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake} 97852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 98852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestatic inline void list_add(struct list_head *entry, struct list_head *head) 99852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake{ 100852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->next = head->next; 101852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->prev = head; 102852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 103852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake head->next->prev = entry; 104852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake head->next = entry; 105852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake} 106852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 107852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestatic inline void list_add_tail(struct list_head *entry, 108852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake struct list_head *head) 109852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake{ 110852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->next = head; 111852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->prev = head->prev; 112852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 113852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake head->prev->next = entry; 114852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake head->prev = entry; 115852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake} 116852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 117852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestatic inline void list_del(struct list_head *entry) 118852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake{ 119852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->next->prev = entry->prev; 120852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->prev->next = entry->next; 121d2e8b37a68b06b8d75e9bd947b8a90d570a77778Orin Eman entry->next = entry->prev = NULL; 122852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake} 123852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 124a983fad006fe39a48517e061bf9f66501ff900bePete Batardstatic inline void *usbi_reallocf(void *ptr, size_t size) 125a983fad006fe39a48517e061bf9f66501ff900bePete Batard{ 126a983fad006fe39a48517e061bf9f66501ff900bePete Batard void *ret = realloc(ptr, size); 127a983fad006fe39a48517e061bf9f66501ff900bePete Batard if (!ret) 128a983fad006fe39a48517e061bf9f66501ff900bePete Batard free(ptr); 129a983fad006fe39a48517e061bf9f66501ff900bePete Batard return ret; 130a983fad006fe39a48517e061bf9f66501ff900bePete Batard} 131a983fad006fe39a48517e061bf9f66501ff900bePete Batard 132852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define container_of(ptr, type, member) ({ \ 133d1bd234f7e1b1ff4168b8f605e2038e87a0e361fNathan Hjelm const typeof( ((type *)0)->member ) *mptr = (ptr); \ 134d1bd234f7e1b1ff4168b8f605e2038e87a0e361fNathan Hjelm (type *)( (char *)mptr - offsetof(type,member) );}) 135852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 136852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define MIN(a, b) ((a) < (b) ? (a) : (b)) 137852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define MAX(a, b) ((a) > (b) ? (a) : (b)) 138852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 139852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define TIMESPEC_IS_SET(ts) ((ts)->tv_sec != 0 || (ts)->tv_nsec != 0) 140852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 1417ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batardvoid usbi_log(struct libusb_context *ctx, enum libusb_log_level level, 1421df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake const char *function, const char *format, ...); 143852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 1447ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batardvoid usbi_log_v(struct libusb_context *ctx, enum libusb_log_level level, 145a8e2e7cab278fbfcba91909eaf762cf66da9eda5Ludovic Rousseau const char *function, const char *format, va_list args); 146a8e2e7cab278fbfcba91909eaf762cf66da9eda5Ludovic Rousseau 147974251ba94861d03dbe9837a902d84e83d301cdaPete Batard#if !defined(_MSC_VER) || _MSC_VER >= 1400 148b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante 149852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#ifdef ENABLE_LOGGING 150b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante#define _usbi_log(ctx, level, ...) usbi_log(ctx, level, __FUNCTION__, __VA_ARGS__) 1517ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard#define usbi_dbg(...) _usbi_log(NULL, LIBUSB_LOG_LEVEL_DEBUG, __VA_ARGS__) 152b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante#else 153cf6e68acb116c63f4a8c9d30ee4f2757e8c2e12aPete Batard#define _usbi_log(ctx, level, ...) do { (void)(ctx); } while(0) 154370922dfbe0964c0b8a0c1974bb1d7b85ac10607Peter Stuge#define usbi_dbg(...) do {} while(0) 155b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante#endif 156b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante 1577ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard#define usbi_info(ctx, ...) _usbi_log(ctx, LIBUSB_LOG_LEVEL_INFO, __VA_ARGS__) 1587ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard#define usbi_warn(ctx, ...) _usbi_log(ctx, LIBUSB_LOG_LEVEL_WARNING, __VA_ARGS__) 1597ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard#define usbi_err(ctx, ...) _usbi_log(ctx, LIBUSB_LOG_LEVEL_ERROR, __VA_ARGS__) 160b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante 161974251ba94861d03dbe9837a902d84e83d301cdaPete Batard#else /* !defined(_MSC_VER) || _MSC_VER >= 1400 */ 162b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante 163b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante#ifdef ENABLE_LOGGING 164b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante#define LOG_BODY(ctxt, level) \ 165b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante{ \ 166b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante va_list args; \ 167b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante va_start (args, format); \ 168b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante usbi_log_v(ctxt, level, "", format, args); \ 169b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante va_end(args); \ 170b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante} 171852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#else 172abc3143ba1989a48f62246c2afb0eb4c3c5f7917Peter Stuge#define LOG_BODY(ctxt, level) do { (void)(ctxt); } while(0) 173852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#endif 174852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 175b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plantestatic inline void usbi_info(struct libusb_context *ctx, const char *format, 176b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante ...) 1777ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard LOG_BODY(ctx,LIBUSB_LOG_LEVEL_INFO) 178b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plantestatic inline void usbi_warn(struct libusb_context *ctx, const char *format, 179b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante ...) 1807ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard LOG_BODY(ctx,LIBUSB_LOG_LEVEL_WARNING) 181b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plantestatic inline void usbi_err( struct libusb_context *ctx, const char *format, 182b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante ...) 1837ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard LOG_BODY(ctx,LIBUSB_LOG_LEVEL_ERROR) 184b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plante 185b03de9d07bf9a6b0c4e6cba9ec06b5271a22e621Michael Plantestatic inline void usbi_dbg(const char *format, ...) 1867ec94a45ed8155e7a1d4d5d75575099b09c78834Pete Batard LOG_BODY(NULL,LIBUSB_LOG_LEVEL_DEBUG) 187852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 188974251ba94861d03dbe9837a902d84e83d301cdaPete Batard#endif /* !defined(_MSC_VER) || _MSC_VER >= 1400 */ 1891df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 1901df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define USBI_GET_CONTEXT(ctx) if (!(ctx)) (ctx) = usbi_default_context 1911df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define DEVICE_CTX(dev) ((dev)->ctx) 1921df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define HANDLE_CTX(handle) (DEVICE_CTX((handle)->dev)) 1931df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define TRANSFER_CTX(transfer) (HANDLE_CTX((transfer)->dev_handle)) 1941df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define ITRANSFER_CTX(transfer) \ 195d1bd234f7e1b1ff4168b8f605e2038e87a0e361fNathan Hjelm (TRANSFER_CTX(USBI_TRANSFER_TO_LIBUSB_TRANSFER(transfer))) 1961df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 19776af4c99bd6122c1dd7b58858b669c919d8c8806Peter Stuge#define IS_EPIN(ep) (0 != ((ep) & LIBUSB_ENDPOINT_IN)) 19876af4c99bd6122c1dd7b58858b669c919d8c8806Peter Stuge#define IS_EPOUT(ep) (!IS_EPIN(ep)) 19976af4c99bd6122c1dd7b58858b669c919d8c8806Peter Stuge#define IS_XFERIN(xfer) (0 != ((xfer)->endpoint & LIBUSB_ENDPOINT_IN)) 20076af4c99bd6122c1dd7b58858b669c919d8c8806Peter Stuge#define IS_XFEROUT(xfer) (!IS_XFERIN(xfer)) 20176af4c99bd6122c1dd7b58858b669c919d8c8806Peter Stuge 202790ffc78b008a03c95d10899f53997b504f55c72Toby Gray/* Internal abstraction for thread synchronization */ 2039a4249f8a104b98a15a7e3ba7ecae9a385ed9027Pete Batard#if defined(THREADS_POSIX) 20438e6eb86b2ceb301d67fd4754c5a1493f7911eceLudovic Rousseau#include "os/threads_posix.h" 205244271931a782028fd9bc1cdcdb12200f65cf8d9Toby Gray#elif defined(OS_WINDOWS) || defined(OS_WINCE) 2069a4249f8a104b98a15a7e3ba7ecae9a385ed9027Pete Batard#include <os/threads_windows.h> 2079a4249f8a104b98a15a7e3ba7ecae9a385ed9027Pete Batard#endif 2089a4249f8a104b98a15a7e3ba7ecae9a385ed9027Pete Batard 2091df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakeextern struct libusb_context *usbi_default_context; 2101df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2111df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakestruct libusb_context { 2121df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int debug; 2131df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int debug_fixed; 2141df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 215c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake /* internal control pipe, used for interrupting event handling when 216c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake * something needs to modify poll fds. */ 217c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake int ctrl_pipe[2]; 218c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake 2191df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct list_head usb_devs; 22023b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t usb_devs_lock; 2211df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2221df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* A list of open handles. Backends are free to traverse this if required. 2231df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake */ 2241df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct list_head open_devs; 22523b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t open_devs_lock; 2261df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2277801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm /* A list of registered hotplug callbacks */ 2287801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm struct list_head hotplug_cbs; 2297801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm usbi_mutex_t hotplug_cbs_lock; 2307801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm int hotplug_pipe[2]; 2317801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm 232a636df4ca1b87ed3094a87828c022092a80ba613Pete Batard /* this is a list of in-flight transfer handles, sorted by timeout 2331df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake * expiration. URBs to timeout the soonest are placed at the beginning of 2341df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake * the list, URBs that will time out later are placed after, and urbs with 2351df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake * infinite timeout are always placed at the very end. */ 2361df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct list_head flying_transfers; 23723b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t flying_transfers_lock; 2381df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 239c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake /* list of poll fds */ 2401df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct list_head pollfds; 24123b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t pollfds_lock; 2421df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 243c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake /* a counter that is set when we want to interrupt event handling, in order 244c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake * to modify the poll fd set. and a lock to protect it. */ 245c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake unsigned int pollfd_modify; 24623b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t pollfd_modify_lock; 247c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake 2481df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* user callbacks for pollfd changes */ 2491df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake libusb_pollfd_added_cb fd_added_cb; 2501df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake libusb_pollfd_removed_cb fd_removed_cb; 251819e65f880ca43526036e56c65c415042c91f58fDaniel Drake void *fd_cb_user_data; 2521df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2531df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* ensures that only one thread is handling events at any one time */ 25423b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t events_lock; 2551df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2561df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* used to see if there is an active thread doing event handling */ 2571df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int event_handler_active; 2581df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2591df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* used to wait for event completion in threads other than the one that is 2601df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake * event handling */ 26123b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t event_waiters_lock; 26223b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_cond_t event_waiters_cond; 2634783008b7e711de9cb31631e60dda995f44068deDaniel Drake 2644783008b7e711de9cb31631e60dda995f44068deDaniel Drake#ifdef USBI_TIMERFD_AVAILABLE 2654783008b7e711de9cb31631e60dda995f44068deDaniel Drake /* used for timeout handling, if supported by OS. 2664783008b7e711de9cb31631e60dda995f44068deDaniel Drake * this timerfd is maintained to trigger on the next pending timeout */ 2674783008b7e711de9cb31631e60dda995f44068deDaniel Drake int timerfd; 2684783008b7e711de9cb31631e60dda995f44068deDaniel Drake#endif 269913a233ec20bcabe7c372d423d14c71b2ddf722fNathan Hjelm 270913a233ec20bcabe7c372d423d14c71b2ddf722fNathan Hjelm struct list_head list; 2711df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake}; 272852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 2734783008b7e711de9cb31631e60dda995f44068deDaniel Drake#ifdef USBI_TIMERFD_AVAILABLE 2744783008b7e711de9cb31631e60dda995f44068deDaniel Drake#define usbi_using_timerfd(ctx) ((ctx)->timerfd >= 0) 2754783008b7e711de9cb31631e60dda995f44068deDaniel Drake#else 2764783008b7e711de9cb31631e60dda995f44068deDaniel Drake#define usbi_using_timerfd(ctx) (0) 2774783008b7e711de9cb31631e60dda995f44068deDaniel Drake#endif 2784783008b7e711de9cb31631e60dda995f44068deDaniel Drake 2799cfdb494fccac53a4277da7c8b6d15f1a72a4959Daniel Drakestruct libusb_device { 2801fcdb0678b759569db7cd530457dbc0a5f86fb1dDaniel Drake /* lock protects refcnt, everything else is finalized at initialization 2811fcdb0678b759569db7cd530457dbc0a5f86fb1dDaniel Drake * time */ 28223b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t lock; 2839cfdb494fccac53a4277da7c8b6d15f1a72a4959Daniel Drake int refcnt; 2841fcdb0678b759569db7cd530457dbc0a5f86fb1dDaniel Drake 2851df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct libusb_context *ctx; 2861df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2873675e978fb7a1042f8601931255658bcd14a2298Daniel Drake uint8_t bus_number; 288cfb8610242394d532778a483570089c2bed52c84Pete Batard uint8_t port_number; 289cfb8610242394d532778a483570089c2bed52c84Pete Batard struct libusb_device* parent_dev; 2903675e978fb7a1042f8601931255658bcd14a2298Daniel Drake uint8_t device_address; 291c3844f7aeb2176636ce6e6ef697659fdb0b30048Daniel Drake uint8_t num_configurations; 292c8c40bcbd22abca922ff31c4ed6a75fd7af78b59Hans de Goede enum libusb_speed speed; 2933675e978fb7a1042f8601931255658bcd14a2298Daniel Drake 2941fcdb0678b759569db7cd530457dbc0a5f86fb1dDaniel Drake struct list_head list; 295f3fdf447916289cd92b7190377681894e8ab611aDaniel Drake unsigned long session_data; 2968399b52062e9aa2877ab6f61622fe9cb241fad57Nathan Hjelm 2978399b52062e9aa2877ab6f61622fe9cb241fad57Nathan Hjelm struct libusb_device_descriptor device_descriptor; 2987801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm int attached; 2998399b52062e9aa2877ab6f61622fe9cb241fad57Nathan Hjelm 3006e501b377dd0bccaefce5604616614deb2abb3fcSean McBride unsigned char os_priv 3016e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) 3026e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [] /* valid C99 code */ 3036e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#else 3046e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [0] /* non-standard, but usually working code */ 3056e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#endif 3066e501b377dd0bccaefce5604616614deb2abb3fcSean McBride ; 307852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake}; 308852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 309ebad1c79688ba603ad017ed0fe2f3c0dc8edd1adDaniel Drakestruct libusb_device_handle { 310e20f8281fb7da32587f81b5eea5818af1eab0fe0Daniel Drake /* lock protects claimed_interfaces */ 31123b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t lock; 312e20f8281fb7da32587f81b5eea5818af1eab0fe0Daniel Drake unsigned long claimed_interfaces; 313e20f8281fb7da32587f81b5eea5818af1eab0fe0Daniel Drake 314852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake struct list_head list; 3159cfdb494fccac53a4277da7c8b6d15f1a72a4959Daniel Drake struct libusb_device *dev; 3166e501b377dd0bccaefce5604616614deb2abb3fcSean McBride unsigned char os_priv 3176e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) 3186e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [] /* valid C99 code */ 3196e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#else 3206e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [0] /* non-standard, but usually working code */ 3216e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#endif 3226e501b377dd0bccaefce5604616614deb2abb3fcSean McBride ; 323852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake}; 324852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 3259196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelmenum { 3269196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm USBI_CLOCK_MONOTONIC, 3279196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm USBI_CLOCK_REALTIME 3289196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm}; 3299196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm 330211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake/* in-memory transfer layout: 331211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 332211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 1. struct usbi_transfer 333211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 2. struct libusb_transfer (which includes iso packets) [variable size] 334211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 3. os private data [variable size] 335211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 336211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * from a libusb_transfer, you can get the usbi_transfer by rewinding the 337211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * appropriate number of bytes. 338211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * the usbi_transfer includes the number of allocated packets, so you can 339211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * determine the size of the transfer and hence the start and length of the 340211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * OS-private data. 341211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake */ 342852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 343211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drakestruct usbi_transfer { 344211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake int num_iso_packets; 345852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake struct list_head list; 346637a8d7ff8a11a23588925d9d3003a609bda8075Daniel Drake struct timeval timeout; 347852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake int transferred; 348852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake uint8_t flags; 34969830057547396f893f0d7b3125a05d016313b10Daniel Drake 35069830057547396f893f0d7b3125a05d016313b10Daniel Drake /* this lock is held during libusb_submit_transfer() and 35169830057547396f893f0d7b3125a05d016313b10Daniel Drake * libusb_cancel_transfer() (allowing the OS backend to prevent duplicate 35269830057547396f893f0d7b3125a05d016313b10Daniel Drake * cancellation, submission-during-cancellation, etc). the OS backend 35369830057547396f893f0d7b3125a05d016313b10Daniel Drake * should also take this lock in the handle_events path, to prevent the user 35469830057547396f893f0d7b3125a05d016313b10Daniel Drake * cancelling the transfer from another thread while you are processing 35569830057547396f893f0d7b3125a05d016313b10Daniel Drake * its completion (presumably there would be races within your OS backend 35669830057547396f893f0d7b3125a05d016313b10Daniel Drake * if this were possible). */ 35723b5db8b3e353176dfa0635bfb6f0e2658f6e3dePeter Stuge usbi_mutex_t lock; 358852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake}; 359852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 36067d9ef7b6877e17f2deec81cd41dc0948f6bed4bNathan Hjelmenum usbi_transfer_flags { 36167d9ef7b6877e17f2deec81cd41dc0948f6bed4bNathan Hjelm /* The transfer has timed out */ 36267d9ef7b6877e17f2deec81cd41dc0948f6bed4bNathan Hjelm USBI_TRANSFER_TIMED_OUT = 1 << 0, 36367d9ef7b6877e17f2deec81cd41dc0948f6bed4bNathan Hjelm 36467d9ef7b6877e17f2deec81cd41dc0948f6bed4bNathan Hjelm /* Set by backend submit_transfer() if the OS handles timeout */ 3652c85c363cddd72b9ab425f05e2ee03e0b1df24f1Peter Stuge USBI_TRANSFER_OS_HANDLES_TIMEOUT = 1 << 1, 3668f1bc0659136faf312dabe8fe67380a798299d33Vitali Lovich 3678f1bc0659136faf312dabe8fe67380a798299d33Vitali Lovich /* Cancellation was requested via libusb_cancel_transfer() */ 3688f1bc0659136faf312dabe8fe67380a798299d33Vitali Lovich USBI_TRANSFER_CANCELLING = 1 << 2, 3698f1bc0659136faf312dabe8fe67380a798299d33Vitali Lovich 3708f1bc0659136faf312dabe8fe67380a798299d33Vitali Lovich /* Operation on the transfer failed because the device disappeared */ 3718f1bc0659136faf312dabe8fe67380a798299d33Vitali Lovich USBI_TRANSFER_DEVICE_DISAPPEARED = 1 << 3, 3721ed09c7b2a5fc27c3cfea21740584879781bff67Toby Gray 3731ed09c7b2a5fc27c3cfea21740584879781bff67Toby Gray /* Set by backend submit_transfer() if the fds in use have been updated */ 3741ed09c7b2a5fc27c3cfea21740584879781bff67Toby Gray USBI_TRANSFER_UPDATED_FDS = 1 << 4, 37567d9ef7b6877e17f2deec81cd41dc0948f6bed4bNathan Hjelm}; 37667d9ef7b6877e17f2deec81cd41dc0948f6bed4bNathan Hjelm 377d1bd234f7e1b1ff4168b8f605e2038e87a0e361fNathan Hjelm#define USBI_TRANSFER_TO_LIBUSB_TRANSFER(transfer) \ 378d7031ee8e1c449af23b2674fe18d9fc652c9bd80Pete Batard ((struct libusb_transfer *)(((unsigned char *)(transfer)) \ 379211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake + sizeof(struct usbi_transfer))) 380d1bd234f7e1b1ff4168b8f605e2038e87a0e361fNathan Hjelm#define LIBUSB_TRANSFER_TO_USBI_TRANSFER(transfer) \ 381d7031ee8e1c449af23b2674fe18d9fc652c9bd80Pete Batard ((struct usbi_transfer *)(((unsigned char *)(transfer)) \ 382211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake - sizeof(struct usbi_transfer))) 383211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake 384211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drakestatic inline void *usbi_transfer_get_os_priv(struct usbi_transfer *transfer) 385211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake{ 386d7031ee8e1c449af23b2674fe18d9fc652c9bd80Pete Batard return ((unsigned char *)transfer) + sizeof(struct usbi_transfer) 387211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake + sizeof(struct libusb_transfer) 388211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake + (transfer->num_iso_packets 389211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * sizeof(struct libusb_iso_packet_descriptor)); 390211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake} 391211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake 392852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake/* bus structures */ 393852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 394a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake/* All standard descriptors have these 2 fields in common */ 395a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drakestruct usb_descriptor_header { 396a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake uint8_t bLength; 397a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake uint8_t bDescriptorType; 398a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake}; 399a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake 400852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake/* shared data and functions */ 401852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 402c32aa662769b676ff3247778664fccc71fc427ecDaniel Drakeint usbi_io_init(struct libusb_context *ctx); 403c32aa662769b676ff3247778664fccc71fc427ecDaniel Drakevoid usbi_io_exit(struct libusb_context *ctx); 404c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 4051df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakestruct libusb_device *usbi_alloc_device(struct libusb_context *ctx, 4061df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake unsigned long session_id); 4071df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakestruct libusb_device *usbi_get_device_by_session_id(struct libusb_context *ctx, 4081df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake unsigned long session_id); 409fe4adcc99e30115204ab832ad3e0170c9aca7629Daniel Drakeint usbi_sanitize_device(struct libusb_device *dev); 410fec7c84163e25b8f811632828334d75da82bcb16Daniel Drakevoid usbi_handle_disconnect(struct libusb_device_handle *handle); 411c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 4124783008b7e711de9cb31631e60dda995f44068deDaniel Drakeint usbi_handle_transfer_completion(struct usbi_transfer *itransfer, 413c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake enum libusb_transfer_status status); 4144783008b7e711de9cb31631e60dda995f44068deDaniel Drakeint usbi_handle_transfer_cancellation(struct usbi_transfer *transfer); 415852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 416ef698c633d2ecb597be58deccfa2795cc6c88e25Hans de Goedeint usbi_parse_descriptor(const unsigned char *source, const char *descriptor, 4173b41c31d3fa2c1f93649cc5fc0f59acbf3efd5a1Ludovic Rousseau void *dest, int host_endian); 4188399b52062e9aa2877ab6f61622fe9cb241fad57Nathan Hjelmint usbi_device_cache_descriptor(libusb_device *dev); 4198ebb4ccdfaf5f095a1c38787d909d280ea64405cDaniel Drakeint usbi_get_config_index_by_value(struct libusb_device *dev, 4208ebb4ccdfaf5f095a1c38787d909d280ea64405cDaniel Drake uint8_t bConfigurationValue, int *idx); 421a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake 4227801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelmvoid usbi_connect_device (struct libusb_device *dev); 4237801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelmvoid usbi_disconnect_device (struct libusb_device *dev); 4247801ff94fa6e49fe98433eccc7f2e461590a6f7cNathan Hjelm 425790ffc78b008a03c95d10899f53997b504f55c72Toby Gray/* Internal abstraction for poll (needs struct usbi_transfer on Windows) */ 426790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#if defined(OS_LINUX) || defined(OS_DARWIN) || defined(OS_OPENBSD) 427790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#include <unistd.h> 428790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#include "os/poll_posix.h" 429790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#elif defined(OS_WINDOWS) || defined(OS_WINCE) 430790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#include <os/poll_windows.h> 431790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#endif 432790ffc78b008a03c95d10899f53997b504f55c72Toby Gray 433244271931a782028fd9bc1cdcdb12200f65cf8d9Toby Gray#if (defined(OS_WINDOWS) || defined(OS_WINCE)) && !defined(__GCC__) 434790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#undef HAVE_GETTIMEOFDAY 435790ffc78b008a03c95d10899f53997b504f55c72Toby Grayint usbi_gettimeofday(struct timeval *tp, void *tzp); 436790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#define LIBUSB_GETTIMEOFDAY_WIN32 437790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#define HAVE_USBI_GETTIMEOFDAY 438790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#else 439790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#ifdef HAVE_GETTIMEOFDAY 440790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#define usbi_gettimeofday(tv, tz) gettimeofday((tv), (tz)) 441790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#define HAVE_USBI_GETTIMEOFDAY 442790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#endif 443790ffc78b008a03c95d10899f53997b504f55c72Toby Gray#endif 444c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 445c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakestruct usbi_pollfd { 446c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake /* must come first */ 447c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake struct libusb_pollfd pollfd; 448c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 449c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake struct list_head list; 450c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake}; 451c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 4521df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakeint usbi_add_pollfd(struct libusb_context *ctx, int fd, short events); 4531df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakevoid usbi_remove_pollfd(struct libusb_context *ctx, int fd); 454a7c056c14867e1cc3ef83682f2706cdbdca7c4cePete Batardvoid usbi_fd_notification(struct libusb_context *ctx); 455c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 456c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake/* device discovery */ 457c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 458c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake/* we traverse usbfs without knowing how many devices we are going to find. 459c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake * so we create this discovered_devs model which is similar to a linked-list 460c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake * which grows when required. it can be freed once discovery has completed, 461c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake * eliminating the need for a list node in the libusb_device structure 462c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake * itself. */ 463c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakestruct discovered_devs { 464c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t len; 465c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t capacity; 4666e501b377dd0bccaefce5604616614deb2abb3fcSean McBride struct libusb_device *devices 4676e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) 4686e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [] /* valid C99 code */ 4696e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#else 4706e501b377dd0bccaefce5604616614deb2abb3fcSean McBride [0] /* non-standard, but usually working code */ 4716e501b377dd0bccaefce5604616614deb2abb3fcSean McBride#endif 4726e501b377dd0bccaefce5604616614deb2abb3fcSean McBride ; 473c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake}; 474c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 475c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakestruct discovered_devs *discovered_devs_append( 476c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake struct discovered_devs *discdevs, struct libusb_device *dev); 477c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 478c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake/* OS abstraction */ 479c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 4801298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake/* This is the interface that OS backends need to implement. 4811298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * All fields are mandatory, except ones explicitly noted as optional. */ 482c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakestruct usbi_os_backend { 4831298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* A human-readable name for your backend, e.g. "Linux usbfs" */ 484c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake const char *name; 4851298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 486e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard /* Binary mask for backend specific capabilities */ 487e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard uint32_t caps; 488e0628c566a3fb928baab9e4359760cdc5afe5e95Pete Batard 4891298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Perform initialization of your backend. You might use this function 4901298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * to determine specific capabilities of the system, allocate required 4911298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * data structures for later, etc. 4921298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 493791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard * This function is called when a libusbx user initializes the library 4941298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * prior to use. 4951298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 4961298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success, or a LIBUSB_ERROR code on failure. 4971298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 4981df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int (*init)(struct libusb_context *ctx); 4991298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 5001298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Deinitialization. Optional. This function should destroy anything 5011298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * that was set up by init. 5021298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5031298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when the user deinitializes the library. 5041298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 505c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake void (*exit)(void); 506c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 5071298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Enumerate all the USB devices on the system, returning them in a list 5081298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * of discovered devices. 5091298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5101298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Your implementation should enumerate all devices on the system, 5111298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * regardless of whether they have been seen before or not. 5121298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5131298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * When you have found a device, compute a session ID for it. The session 5141298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * ID should uniquely represent that particular device for that particular 5151298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * connection session since boot (i.e. if you disconnect and reconnect a 5161298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device immediately after, it should be assigned a different session ID). 5171298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If your OS cannot provide a unique session ID as described above, 5181298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * presenting a session ID of (bus_number << 8 | device_address) should 5191298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * be sufficient. Bus numbers and device addresses wrap and get reused, 5201298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * but that is an unlikely case. 5211298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5221298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * After computing a session ID for a device, call 523791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard * usbi_get_device_by_session_id(). This function checks if libusbx already 5241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * knows about the device, and if so, it provides you with a libusb_device 5251298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * structure for it. 5261298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5271298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If usbi_get_device_by_session_id() returns NULL, it is time to allocate 5281298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * a new device structure for the device. Call usbi_alloc_device() to 5291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * obtain a new libusb_device structure with reference count 1. Populate 5301298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * the bus_number and device_address attributes of the new device, and 5311298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * perform any other internal backend initialization you need to do. At 5321298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * this point, you should be ready to provide device descriptors and so 5331298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * on through the get_*_descriptor functions. Finally, call 5341298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * usbi_sanitize_device() to perform some final sanity checks on the 5351298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device. Assuming all of the above succeeded, we can now continue. 5361298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If any of the above failed, remember to unreference the device that 5371298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was returned by usbi_alloc_device(). 5381298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5391298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * At this stage we have a populated libusb_device structure (either one 5401298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * that was found earlier, or one that we have just allocated and 5411298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * populated). This can now be added to the discovered devices list 5421298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * using discovered_devs_append(). Note that discovered_devs_append() 5431298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * may reallocate the list, returning a new location for it, and also 5441298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * note that reallocation can fail. Your backend should handle these 5451298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * error conditions appropriately. 5461298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5471298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should not generate any bus I/O and should not block. 5481298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If I/O is required (e.g. reading the active configuration value), it is 5491298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * OK to ignore these suggestions :) 5501298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5511298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is executed when the user wishes to retrieve a list 5521298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * of USB devices connected to the system. 5531298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 554cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * If the backend has hotplug support, this function is not used! 555cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * 5561298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success, or a LIBUSB_ERROR code on failure. 5571298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 5581df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int (*get_device_list)(struct libusb_context *ctx, 5591df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct discovered_devs **discdevs); 560c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 561cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede /* Apps which were written before hotplug support, may listen for 562cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * hotplug events on their own and call libusb_get_device_list on 563cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * device addition. In this case libusb_get_device_list will likely 564cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * return a list without the new device in there, as the hotplug 565cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * event thread will still be busy enumerating the device, which may 566cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * take a while, or may not even have seen the event yet. 567cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * 568cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * To avoid this libusb_get_device_list will call this optional 569cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * function for backends with hotplug support before copying 570cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * ctx->usb_devs to the user. In this function the backend should 571cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * ensure any pending hotplug events are fully processed before 572cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * returning. 573cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * 574cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede * Optional, should be implemented by backends with hotplug support. 575cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede */ 576cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede void (*hotplug_poll)(void); 577cedc7f6e289c427c84a9175045b06614be56ec5aHans de Goede 5781298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Open a device for I/O and other USB operations. The device handle 5791298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * is preallocated for you, you can retrieve the device in question 5801298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * through handle->dev. 5811298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5821298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Your backend should allocate any internal resources required for I/O 5831298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * and other operations so that those operations can happen (hopefully) 584791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard * without hiccup. This is also a good place to inform libusbx that it 5851298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * should monitor certain file descriptors related to this device - 5861298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * see the usbi_add_pollfd() function. 5871298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5881298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should not generate any bus I/O and should not block. 5891298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5901298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when the user attempts to obtain a device 5911298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * handle for a device. 5921298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5931298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 5941298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 5951298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_ACCESS if the user has insufficient permissions 5961298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since 5971298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * discovery 5981298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 5991298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6001298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Do not worry about freeing the handle on failed open, the upper layers 6011298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * do this for you. 6021298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 603c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake int (*open)(struct libusb_device_handle *handle); 6041298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 6051298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Close a device such that the handle cannot be used again. Your backend 6061298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * should destroy any resources that were allocated in the open path. 6071298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This may also be a good place to call usbi_remove_pollfd() to inform 608791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard * libusbx of any file descriptors associated with this device that should 6091298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * no longer be monitored. 6101298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6111298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when the user closes a device handle. 6121298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 613c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake void (*close)(struct libusb_device_handle *handle); 614c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 6151298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Retrieve the device descriptor from a device. 6161298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6171298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The descriptor should be retrieved from memory, NOT via bus I/O to the 6181298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device. This means that you may have to cache it in a private structure 6191298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * during get_device_list enumeration. Alternatively, you may be able 6201298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * to retrieve it from a kernel interface (some Linux setups can do this) 6211298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * still without generating bus I/O. 6221298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6231298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is expected to write DEVICE_DESC_LENGTH (18) bytes into 6241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * buffer, which is guaranteed to be big enough. 6251298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6261298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when sanity-checking a device before adding 6271298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * it to the list of discovered devices, and also when the user requests 6281298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * to read the device descriptor. 6291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6302b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * This function is expected to return the descriptor in bus-endian format 6312b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * (LE). If it returns the multi-byte values in host-endian format, 6322b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * set the host_endian output parameter to "1". 6332b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * 6341298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success or a LIBUSB_ERROR code on failure. 6351298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 636b27fff633843824744df7d334cb89ece329cafa6Daniel Drake int (*get_device_descriptor)(struct libusb_device *device, 6372b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake unsigned char *buffer, int *host_endian); 6381298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 6391298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Get the ACTIVE configuration descriptor for a device. 6401298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6411298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The descriptor should be retrieved from memory, NOT via bus I/O to the 6421298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device. This means that you may have to cache it in a private structure 6431298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * during get_device_list enumeration. You may also have to keep track 6441298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * of which configuration is active when the user changes it. 6451298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6461298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is expected to write len bytes of data into buffer, which 6471298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * is guaranteed to be big enough. If you can only do a partial write, 6481298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * return an error code. 6491298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6502b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * This function is expected to return the descriptor in bus-endian format 6512b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * (LE). If it returns the multi-byte values in host-endian format, 6522b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * set the host_endian output parameter to "1". 6532b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * 6541298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 6551298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 6561298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state 6571298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 6581298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 659fe4adcc99e30115204ab832ad3e0170c9aca7629Daniel Drake int (*get_active_config_descriptor)(struct libusb_device *device, 6602b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake unsigned char *buffer, size_t len, int *host_endian); 6611298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 6621298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Get a specific configuration descriptor for a device. 6631298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6641298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The descriptor should be retrieved from memory, NOT via bus I/O to the 6651298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device. This means that you may have to cache it in a private structure 6661298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * during get_device_list enumeration. 6671298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6681298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The requested descriptor is expressed as a zero-based index (i.e. 0 6691298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * indicates that we are requesting the first descriptor). The index does 6701298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * not (necessarily) equal the bConfigurationValue of the configuration 6711298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * being requested. 6721298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6731298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is expected to write len bytes of data into buffer, which 6741298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * is guaranteed to be big enough. If you can only do a partial write, 6751298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * return an error code. 6761298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6772b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * This function is expected to return the descriptor in bus-endian format 6782b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * (LE). If it returns the multi-byte values in host-endian format, 6792b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * set the host_endian output parameter to "1". 6802b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * 6811298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success or a LIBUSB_ERROR code on failure. 6821298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 683c3844f7aeb2176636ce6e6ef697659fdb0b30048Daniel Drake int (*get_config_descriptor)(struct libusb_device *device, 6842b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake uint8_t config_index, unsigned char *buffer, size_t len, 6852b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake int *host_endian); 686b27fff633843824744df7d334cb89ece329cafa6Daniel Drake 6876b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede /* Like get_config_descriptor but then by bConfigurationValue instead 6886b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * of by index. 6896b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * 6906b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * Optional, if not present the core will call get_config_descriptor 6916b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * for all configs until it finds the desired bConfigurationValue. 6926b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * 6936b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * Returns a pointer to the raw-descriptor in *buffer, this memory 6946b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * is valid as long as device is valid. 6956b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * 6966b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * Returns the length of the returned raw-descriptor on success, 6976b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede * or a LIBUSB_ERROR code on failure. 6986b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede */ 6996b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede int (*get_config_descriptor_by_value)(struct libusb_device *device, 7006b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede uint8_t bConfigurationValue, unsigned char **buffer, 7016b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede int *host_endian); 7026b41074352bec3e8fe132fc74768da8e930a2ab5Hans de Goede 703514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake /* Get the bConfigurationValue for the active configuration for a device. 704514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * Optional. This should only be implemented if you can retrieve it from 705514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * cache (don't generate I/O). 706514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * 707514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * If you cannot retrieve this from cache, either do not implement this 708514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * function, or return LIBUSB_ERROR_NOT_SUPPORTED. This will cause 709791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard * libusbx to retrieve the information through a standard control transfer. 710514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * 711514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * This function must be non-blocking. 712514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * Return: 713514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * - 0 on success 714514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 715514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * was opened 716514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * - LIBUSB_ERROR_NOT_SUPPORTED if the value cannot be retrieved without 717514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * blocking 718514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * - another LIBUSB_ERROR code on other failure. 719514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake */ 720514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake int (*get_configuration)(struct libusb_device_handle *handle, int *config); 721514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake 7221298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Set the active configuration for a device. 7231298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * A configuration value of -1 should put the device in unconfigured state. 7251298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7261298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function can block. 7271298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7281298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 7291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 7301298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the configuration does not exist 7311298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_BUSY if interfaces are currently claimed (and hence 7321298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * configuration cannot be changed) 7331298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 7341298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 7351298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure. 7361298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 7370f463fe671455670efcf4a93e526b2a9082b0afeDaniel Drake int (*set_configuration)(struct libusb_device_handle *handle, int config); 7380f463fe671455670efcf4a93e526b2a9082b0afeDaniel Drake 7391298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Claim an interface. When claimed, the application can then perform 7401298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * I/O to an interface's endpoints. 7411298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7421298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should not generate any bus I/O and should not block. 7431298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Interface claiming is a logical operation that simply ensures that 7441298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * no other drivers/applications are using the interface, and after 7451298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * claiming, no other drivers/applicatiosn can use the interface because 7461298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * we now "own" it. 7471298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7481298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 7491298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 7501298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the interface does not exist 7511298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_BUSY if the interface is in use by another driver/app 7521298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 7531298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 7541298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 7551298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 7568aceb5c99056aaed6e6f2db1b303817e37e9fe8cPete Batard int (*claim_interface)(struct libusb_device_handle *handle, int interface_number); 7571298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 7581298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Release a previously claimed interface. 7591298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7601298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should also generate a SET_INTERFACE control request, 7611298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * resetting the alternate setting of that interface to 0. It's OK for 7621298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * this function to block as a result. 7631298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7641298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * You will only ever be asked to release an interface which was 7651298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * successfully claimed earlier. 7661298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7671298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 7681298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 7691298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 7701298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 7711298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 7721298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 7738aceb5c99056aaed6e6f2db1b303817e37e9fe8cPete Batard int (*release_interface)(struct libusb_device_handle *handle, int interface_number); 774c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 7751298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Set the alternate setting for an interface. 7761298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7771298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * You will only ever be asked to set the alternate setting for an 7781298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * interface which was successfully claimed earlier. 7791298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7801298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * It's OK for this function to block. 7811298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7821298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 7831298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 7841298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the alternate setting does not exist 7851298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 7861298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 7871298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 7881298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 78962077b7fa5b222e1bb9dea3467585aed69d596e2Daniel Drake int (*set_interface_altsetting)(struct libusb_device_handle *handle, 7908aceb5c99056aaed6e6f2db1b303817e37e9fe8cPete Batard int interface_number, int altsetting); 7911298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 7921298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Clear a halt/stall condition on an endpoint. 7931298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7941298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * It's OK for this function to block. 7951298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7961298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 7971298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 7981298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist 7991298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 8001298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 8011298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 8021298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 803c01f744ce07bbeccbe353e956479f0cc5a811a6fDaniel Drake int (*clear_halt)(struct libusb_device_handle *handle, 804c01f744ce07bbeccbe353e956479f0cc5a811a6fDaniel Drake unsigned char endpoint); 8051298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 8061298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Perform a USB port reset to reinitialize a device. 8071298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8081298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If possible, the handle should still be usable after the reset 8091298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * completes, assuming that the device descriptors did not change during 8101298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * reset and all previous interface state can be restored. 8111298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8121298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If something changes, or you cannot easily locate/verify the resetted 8131298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device, return LIBUSB_ERROR_NOT_FOUND. This prompts the application 8141298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * to close the old handle and re-enumerate the device. 8151298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8161298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 8171298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 8181298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if re-enumeration is required, or if the device 8191298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * has been disconnected since it was opened 8201298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 8211298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 822bfe74e9cd9c17a40fff042ea0647326f51cfecaeDaniel Drake int (*reset_device)(struct libusb_device_handle *handle); 82362077b7fa5b222e1bb9dea3467585aed69d596e2Daniel Drake 8241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Determine if a kernel driver is active on an interface. Optional. 8251298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8261298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The presence of a kernel driver on an interface indicates that any 8271298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * calls to claim_interface would fail with the LIBUSB_ERROR_BUSY code. 8281298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 8301298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 if no driver is active 8311298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 1 if a driver is active 8321298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 8331298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 8341298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 8351298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 836470b1bc42bf53373ce678fc76bab9160a54d6881Daniel Drake int (*kernel_driver_active)(struct libusb_device_handle *handle, 8378aceb5c99056aaed6e6f2db1b303817e37e9fe8cPete Batard int interface_number); 838a636df4ca1b87ed3094a87828c022092a80ba613Pete Batard 8391298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Detach a kernel driver from an interface. Optional. 8401298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8411298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * After detaching a kernel driver, the interface should be available 8421298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * for claim. 8431298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8441298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 8451298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 8461298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if no kernel driver was active 8471298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_INVALID_PARAM if the interface does not exist 8481298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 8491298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 8501298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 8511298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 852470b1bc42bf53373ce678fc76bab9160a54d6881Daniel Drake int (*detach_kernel_driver)(struct libusb_device_handle *handle, 8538aceb5c99056aaed6e6f2db1b303817e37e9fe8cPete Batard int interface_number); 854470b1bc42bf53373ce678fc76bab9160a54d6881Daniel Drake 8551d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera /* Attach a kernel driver to an interface. Optional. 8561d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * 8571d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * Reattach a kernel driver to the device. 8581d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * 8591d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * Return: 8601d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - 0 on success 8611d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - LIBUSB_ERROR_NOT_FOUND if no kernel driver was active 8621d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - LIBUSB_ERROR_INVALID_PARAM if the interface does not exist 8631d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 8641d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * was opened 8651d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - LIBUSB_ERROR_BUSY if a program or driver has claimed the interface, 8661d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * preventing reattachment 8671d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - another LIBUSB_ERROR code on other failure 8681d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera */ 8691d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera int (*attach_kernel_driver)(struct libusb_device_handle *handle, 8708aceb5c99056aaed6e6f2db1b303817e37e9fe8cPete Batard int interface_number); 8711d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera 8721298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Destroy a device. Optional. 8731298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8741298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when the last reference to a device is 8751298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * destroyed. It should free any resources allocated in the get_device_list 8761298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * path. 8771298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 878c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake void (*destroy_device)(struct libusb_device *dev); 879c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 8801298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Submit a transfer. Your implementation should take the transfer, 8811298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * morph it into whatever form your platform requires, and submit it 8821298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * asynchronously. 8831298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8841298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function must not block. 8851298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 886858b794cf10ff1ac76a4f453bed7645aa9709c44Hans de Goede * This function gets called with the flying_transfers_lock locked! 887858b794cf10ff1ac76a4f453bed7645aa9709c44Hans de Goede * 8881298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 8891298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 8901298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 8911298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 8921298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 893c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake int (*submit_transfer)(struct usbi_transfer *itransfer); 8941298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 8951298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Cancel a previously submitted transfer. 8961298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 8971298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function must not block. The transfer cancellation must complete 8981298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * later, resulting in a call to usbi_handle_transfer_cancellation() 8991298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * from the context of handle_events. 9001298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 901c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake int (*cancel_transfer)(struct usbi_transfer *itransfer); 9021298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 9031298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Clear a transfer as if it has completed or cancelled, but do not 9041298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * report any completion/cancellation to the library. You should free 9051298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * all private data from the transfer as if you were just about to report 9061298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * completion or cancellation. 9071298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 908791b7473ec38155ee3d1d9889f3d0f1b4c8f33f0Pete Batard * This function might seem a bit out of place. It is used when libusbx 9091298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * detects a disconnected device - it calls this function for all pending 9101298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * transfers before reporting completion (with the disconnect code) to 9111298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * the user. Maybe we can improve upon this internal interface in future. 9121298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 913fec7c84163e25b8f811632828334d75da82bcb16Daniel Drake void (*clear_transfer_priv)(struct usbi_transfer *itransfer); 914c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 9151298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Handle any pending events. This involves monitoring any active 9161298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * transfers and processing their completion or cancellation. 9171298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 9181298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The function is passed an array of pollfd structures (size nfds) 9191298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * as a result of the poll() system call. The num_ready parameter 9201298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * indicates the number of file descriptors that have reported events 9211298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * (i.e. the poll() return value). This should be enough information 9221298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * for you to determine which actions need to be taken on the currently 9231298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * active transfers. 9241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 9251298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * For any cancelled transfers, call usbi_handle_transfer_cancellation(). 9261298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * For completed transfers, call usbi_handle_transfer_completion(). 9271298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * For control/bulk/interrupt transfers, populate the "transferred" 9281298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * element of the appropriate usbi_transfer structure before calling the 9291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * above functions. For isochronous transfers, populate the status and 9301298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * transferred fields of the iso packet descriptors of the transfer. 9311298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 9321298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should also be able to detect disconnection of the 9331298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device, reporting that situation with usbi_handle_disconnect(). 9341298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 93569830057547396f893f0d7b3125a05d016313b10Daniel Drake * When processing an event related to a transfer, you probably want to 93669830057547396f893f0d7b3125a05d016313b10Daniel Drake * take usbi_transfer.lock to prevent races. See the documentation for 93769830057547396f893f0d7b3125a05d016313b10Daniel Drake * the usbi_transfer structure. 93869830057547396f893f0d7b3125a05d016313b10Daniel Drake * 9391298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success, or a LIBUSB_ERROR code on failure. 9401298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 9411df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int (*handle_events)(struct libusb_context *ctx, 942a120747d561929682cd0276ea4c13fb22fad8554Peter Stuge struct pollfd *fds, POLL_NFDS_TYPE nfds, int num_ready); 943c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 9449196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm /* Get time from specified clock. At least two clocks must be implemented 9459196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm by the backend: USBI_CLOCK_REALTIME, and USBI_CLOCK_MONOTONIC. 9469196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm 9479196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm Description of clocks: 9489196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm USBI_CLOCK_REALTIME : clock returns time since system epoch. 9499196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm USBI_CLOCK_MONOTONIC: clock returns time since unspecified start 9509196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm time (usually boot). 9519196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm */ 9529196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm int (*clock_gettime)(int clkid, struct timespec *tp); 9539196f58bdc8b9e967261df39865215faa5d39cfaNathan Hjelm 9544783008b7e711de9cb31631e60dda995f44068deDaniel Drake#ifdef USBI_TIMERFD_AVAILABLE 9554783008b7e711de9cb31631e60dda995f44068deDaniel Drake /* clock ID of the clock that should be used for timerfd */ 9564783008b7e711de9cb31631e60dda995f44068deDaniel Drake clockid_t (*get_timerfd_clockid)(void); 9574783008b7e711de9cb31631e60dda995f44068deDaniel Drake#endif 9584783008b7e711de9cb31631e60dda995f44068deDaniel Drake 9591298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Number of bytes to reserve for per-device private backend data. 9601298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This private data area is accessible through the "os_priv" field of 9611298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * struct libusb_device. */ 962c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t device_priv_size; 963c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 9641298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Number of bytes to reserve for per-handle private backend data. 9651298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This private data area is accessible through the "os_priv" field of 9661298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * struct libusb_device. */ 967c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t device_handle_priv_size; 968c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 9691298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Number of bytes to reserve for per-transfer private backend data. 9701298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This private data area is accessible by calling 9711298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * usbi_transfer_get_os_priv() on the appropriate usbi_transfer instance. 9721298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 973c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t transfer_priv_size; 974211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake 9751298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Mumber of additional bytes for os_priv for each iso packet. 9761298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Can your backend use this? */ 977ad6e2b712c5b54af44424e58a2776686314e26b7Daniel Drake /* FIXME: linux can't use this any more. if other OS's cannot either, 978ad6e2b712c5b54af44424e58a2776686314e26b7Daniel Drake * then remove this */ 979211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake size_t add_iso_packet_size; 980c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake}; 981c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 982c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakeextern const struct usbi_os_backend * const usbi_backend; 983c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 984c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakeextern const struct usbi_os_backend linux_usbfs_backend; 985b49f6bf5c910d0fd694ecf165d7927673707bff9Nathan Hjelmextern const struct usbi_os_backend darwin_backend; 986c56828857eb7ba6fb4f7701693dbb3fe4e75d5f6Martin Pieuchotextern const struct usbi_os_backend openbsd_backend; 9879a4249f8a104b98a15a7e3ba7ecae9a385ed9027Pete Batardextern const struct usbi_os_backend windows_backend; 988244271931a782028fd9bc1cdcdb12200f65cf8d9Toby Grayextern const struct usbi_os_backend wince_backend; 989c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 990913a233ec20bcabe7c372d423d14c71b2ddf722fNathan Hjelmextern struct list_head active_contexts_list; 991913a233ec20bcabe7c372d423d14c71b2ddf722fNathan Hjelmextern usbi_mutex_static_t active_contexts_lock; 992913a233ec20bcabe7c372d423d14c71b2ddf722fNathan Hjelm 993852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#endif 994