libusbi.h revision c32aa662769b676ff3247778664fccc71fc427ec
1852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake/* 2e9364d72151ae1de9cce4175f330fe1529f02511Daniel Drake * Internal header for libusb 31298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Copyright (C) 2007-2008 Daniel Drake <dsd@gentoo.org> 4852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * Copyright (c) 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 21e9364d72151ae1de9cce4175f330fe1529f02511Daniel Drake#ifndef __LIBUSBI_H__ 22e9364d72151ae1de9cce4175f330fe1529f02511Daniel Drake#define __LIBUSBI_H__ 23852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 24852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#include <config.h> 25852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 26fec7c84163e25b8f811632828334d75da82bcb16Daniel Drake#include <poll.h> 270efd2efa65d5513e5754d717d522b2c5c45332e2Daniel Drake#include <pthread.h> 28852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#include <stddef.h> 29852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#include <time.h> 30852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 31e9364d72151ae1de9cce4175f330fe1529f02511Daniel Drake#include <libusb.h> 32852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 33852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define DEVICE_DESC_LENGTH 18 34852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 35a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake#define USB_MAXENDPOINTS 32 36a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake#define USB_MAXINTERFACES 32 37a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake#define USB_MAXCONFIG 8 38a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake 39852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestruct list_head { 40852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake struct list_head *prev, *next; 41852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake}; 42852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 43852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake/* Get an entry from the list 44852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * ptr - the address of this list_head element in "type" 45852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * type - the data type that contains "member" 46852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * member - the list_head element in "type" 47852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake */ 48852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define list_entry(ptr, type, member) \ 49852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake ((type *)((char *)(ptr) - (unsigned long)(&((type *)0L)->member))) 50852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 51852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake/* Get each entry from a list 52852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * pos - A structure pointer has a "member" element 53852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * head - list head 54852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake * member - the list_head element in "pos" 55852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake */ 56852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define list_for_each_entry(pos, head, member) \ 57852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake for (pos = list_entry((head)->next, typeof(*pos), member); \ 58852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake &pos->member != (head); \ 59852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake pos = list_entry(pos->member.next, typeof(*pos), member)) 60852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 61852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define list_for_each_entry_safe(pos, n, head, member) \ 62852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake for (pos = list_entry((head)->next, typeof(*pos), member), \ 63852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake n = list_entry(pos->member.next, typeof(*pos), member); \ 64852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake &pos->member != (head); \ 65852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake pos = n, n = list_entry(n->member.next, typeof(*n), member)) 66852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 67852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define list_empty(entry) ((entry)->next == (entry)) 68852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 69852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestatic inline void list_init(struct list_head *entry) 70852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake{ 71852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->prev = entry->next = entry; 72852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake} 73852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 74852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestatic inline void list_add(struct list_head *entry, struct list_head *head) 75852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake{ 76852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->next = head->next; 77852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->prev = head; 78852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 79852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake head->next->prev = entry; 80852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake head->next = entry; 81852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake} 82852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 83852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestatic inline void list_add_tail(struct list_head *entry, 84852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake struct list_head *head) 85852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake{ 86852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->next = head; 87852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->prev = head->prev; 88852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 89852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake head->prev->next = entry; 90852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake head->prev = entry; 91852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake} 92852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 93852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drakestatic inline void list_del(struct list_head *entry) 94852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake{ 95852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->next->prev = entry->prev; 96852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake entry->prev->next = entry->next; 97852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake} 98852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 99852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define container_of(ptr, type, member) ({ \ 100852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake const typeof( ((type *)0)->member ) *__mptr = (ptr); \ 101852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake (type *)( (char *)__mptr - offsetof(type,member) );}) 102852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 103852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define MIN(a, b) ((a) < (b) ? (a) : (b)) 104852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define MAX(a, b) ((a) > (b) ? (a) : (b)) 105852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 106852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#define TIMESPEC_IS_SET(ts) ((ts)->tv_sec != 0 || (ts)->tv_nsec != 0) 107852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 108dbb3fd871e3972b4e670f3161e7cd2f58f357600Daniel Drakeenum usbi_log_level { 109852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake LOG_LEVEL_DEBUG, 110852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake LOG_LEVEL_INFO, 111852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake LOG_LEVEL_WARNING, 112852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake LOG_LEVEL_ERROR, 113852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake}; 114852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 1151df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakevoid usbi_log(struct libusb_context *ctx, enum usbi_log_level, 1161df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake const char *function, const char *format, ...); 117852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 118852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#ifdef ENABLE_LOGGING 1191df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define _usbi_log(ctx, level, fmt...) usbi_log(ctx, level, __FUNCTION__, fmt) 120852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#else 1211df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define _usbi_log(ctx, level, fmt...) 122852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#endif 123852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 124852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#ifdef ENABLE_DEBUG_LOGGING 1251df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define usbi_dbg(fmt...) _usbi_log(NULL, LOG_LEVEL_DEBUG, fmt) 126852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#else 127e3a09ca0b9cb6f46d54a0130f678c6097240a2bdDaniel Drake#define usbi_dbg(fmt...) 128852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#endif 129852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 1301df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define usbi_info(ctx, fmt...) _usbi_log(ctx, LOG_LEVEL_INFO, fmt) 1311df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define usbi_warn(ctx, fmt...) _usbi_log(ctx, LOG_LEVEL_WARNING, fmt) 1321df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define usbi_err(ctx, fmt...) _usbi_log(ctx, LOG_LEVEL_ERROR, fmt) 1331df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 1341df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define USBI_GET_CONTEXT(ctx) if (!(ctx)) (ctx) = usbi_default_context 1351df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define DEVICE_CTX(dev) ((dev)->ctx) 1361df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define HANDLE_CTX(handle) (DEVICE_CTX((handle)->dev)) 1371df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define TRANSFER_CTX(transfer) (HANDLE_CTX((transfer)->dev_handle)) 1381df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake#define ITRANSFER_CTX(transfer) \ 1391df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake (TRANSFER_CTX(__USBI_TRANSFER_TO_LIBUSB_TRANSFER(transfer))) 1401df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 1411df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakeextern struct libusb_context *usbi_default_context; 1421df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 1431df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakestruct libusb_context { 1441df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int debug; 1451df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int debug_fixed; 1461df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 147c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake /* internal control pipe, used for interrupting event handling when 148c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake * something needs to modify poll fds. */ 149c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake int ctrl_pipe[2]; 150c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake 1511df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct list_head usb_devs; 1521df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake pthread_mutex_t usb_devs_lock; 1531df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 1541df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* A list of open handles. Backends are free to traverse this if required. 1551df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake */ 1561df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct list_head open_devs; 1571df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake pthread_mutex_t open_devs_lock; 1581df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 1591df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* this is a list of in-flight transfer handles, sorted by timeout 1601df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake * expiration. URBs to timeout the soonest are placed at the beginning of 1611df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake * the list, URBs that will time out later are placed after, and urbs with 1621df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake * infinite timeout are always placed at the very end. */ 1631df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct list_head flying_transfers; 1641df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake pthread_mutex_t flying_transfers_lock; 1651df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 166c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake /* list of poll fds */ 1671df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct list_head pollfds; 1681df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake pthread_mutex_t pollfds_lock; 1691df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 170c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake /* a counter that is set when we want to interrupt event handling, in order 171c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake * to modify the poll fd set. and a lock to protect it. */ 172c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake unsigned int pollfd_modify; 173c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake pthread_mutex_t pollfd_modify_lock; 174c32aa662769b676ff3247778664fccc71fc427ecDaniel Drake 1751df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* user callbacks for pollfd changes */ 1761df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake libusb_pollfd_added_cb fd_added_cb; 1771df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake libusb_pollfd_removed_cb fd_removed_cb; 178819e65f880ca43526036e56c65c415042c91f58fDaniel Drake void *fd_cb_user_data; 1791df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 1801df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* ensures that only one thread is handling events at any one time */ 1811df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake pthread_mutex_t events_lock; 1821df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 1831df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* used to see if there is an active thread doing event handling */ 1841df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int event_handler_active; 1851df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 1861df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake /* used to wait for event completion in threads other than the one that is 1871df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake * event handling */ 1881df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake pthread_mutex_t event_waiters_lock; 1891df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake pthread_cond_t event_waiters_cond; 1901df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake}; 191852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 1929cfdb494fccac53a4277da7c8b6d15f1a72a4959Daniel Drakestruct libusb_device { 1931fcdb0678b759569db7cd530457dbc0a5f86fb1dDaniel Drake /* lock protects refcnt, everything else is finalized at initialization 1941fcdb0678b759569db7cd530457dbc0a5f86fb1dDaniel Drake * time */ 1951fcdb0678b759569db7cd530457dbc0a5f86fb1dDaniel Drake pthread_mutex_t lock; 1969cfdb494fccac53a4277da7c8b6d15f1a72a4959Daniel Drake int refcnt; 1971fcdb0678b759569db7cd530457dbc0a5f86fb1dDaniel Drake 1981df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct libusb_context *ctx; 1991df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake 2003675e978fb7a1042f8601931255658bcd14a2298Daniel Drake uint8_t bus_number; 2013675e978fb7a1042f8601931255658bcd14a2298Daniel Drake uint8_t device_address; 202c3844f7aeb2176636ce6e6ef697659fdb0b30048Daniel Drake uint8_t num_configurations; 2033675e978fb7a1042f8601931255658bcd14a2298Daniel Drake 2041fcdb0678b759569db7cd530457dbc0a5f86fb1dDaniel Drake struct list_head list; 205f3fdf447916289cd92b7190377681894e8ab611aDaniel Drake unsigned long session_data; 206c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake unsigned char os_priv[0]; 207852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake}; 208852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 209ebad1c79688ba603ad017ed0fe2f3c0dc8edd1adDaniel Drakestruct libusb_device_handle { 210e20f8281fb7da32587f81b5eea5818af1eab0fe0Daniel Drake /* lock protects claimed_interfaces */ 211e20f8281fb7da32587f81b5eea5818af1eab0fe0Daniel Drake pthread_mutex_t lock; 212e20f8281fb7da32587f81b5eea5818af1eab0fe0Daniel Drake unsigned long claimed_interfaces; 213e20f8281fb7da32587f81b5eea5818af1eab0fe0Daniel Drake 214852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake struct list_head list; 2159cfdb494fccac53a4277da7c8b6d15f1a72a4959Daniel Drake struct libusb_device *dev; 216c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake unsigned char os_priv[0]; 217852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake}; 218852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 2197ac0a405b4c57db42e88cbcba5f135697f03b646Daniel Drake#define USBI_TRANSFER_TIMED_OUT (1<<0) 220852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 221211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake/* in-memory transfer layout: 222211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 223211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 1. struct usbi_transfer 224211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 2. struct libusb_transfer (which includes iso packets) [variable size] 225211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 3. os private data [variable size] 226211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * 227211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * from a libusb_transfer, you can get the usbi_transfer by rewinding the 228211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * appropriate number of bytes. 229211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * the usbi_transfer includes the number of allocated packets, so you can 230211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * determine the size of the transfer and hence the start and length of the 231211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * OS-private data. 232211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake */ 233852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 234211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drakestruct usbi_transfer { 235211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake int num_iso_packets; 236852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake struct list_head list; 237637a8d7ff8a11a23588925d9d3003a609bda8075Daniel Drake struct timeval timeout; 238852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake int transferred; 239852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake uint8_t flags; 240852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake}; 241852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 242211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake#define __USBI_TRANSFER_TO_LIBUSB_TRANSFER(transfer) \ 243211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake ((struct libusb_transfer *)(((void *)(transfer)) \ 244211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake + sizeof(struct usbi_transfer))) 245211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake#define __LIBUSB_TRANSFER_TO_USBI_TRANSFER(transfer) \ 246211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake ((struct usbi_transfer *)(((void *)(transfer)) \ 247211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake - sizeof(struct usbi_transfer))) 248211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake 249211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drakestatic inline void *usbi_transfer_get_os_priv(struct usbi_transfer *transfer) 250211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake{ 251211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake return ((void *)transfer) + sizeof(struct usbi_transfer) 252211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake + sizeof(struct libusb_transfer) 253211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake + (transfer->num_iso_packets 254211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake * sizeof(struct libusb_iso_packet_descriptor)); 255211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake} 256211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake 257852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake/* bus structures */ 258852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 259a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake/* All standard descriptors have these 2 fields in common */ 260a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drakestruct usb_descriptor_header { 261a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake uint8_t bLength; 262a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake uint8_t bDescriptorType; 263a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake}; 264a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake 265852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake/* shared data and functions */ 266852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 267c32aa662769b676ff3247778664fccc71fc427ecDaniel Drakeint usbi_io_init(struct libusb_context *ctx); 268c32aa662769b676ff3247778664fccc71fc427ecDaniel Drakevoid usbi_io_exit(struct libusb_context *ctx); 269c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 2701df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakestruct libusb_device *usbi_alloc_device(struct libusb_context *ctx, 2711df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake unsigned long session_id); 2721df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakestruct libusb_device *usbi_get_device_by_session_id(struct libusb_context *ctx, 2731df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake unsigned long session_id); 274fe4adcc99e30115204ab832ad3e0170c9aca7629Daniel Drakeint usbi_sanitize_device(struct libusb_device *dev); 275fec7c84163e25b8f811632828334d75da82bcb16Daniel Drakevoid usbi_handle_disconnect(struct libusb_device_handle *handle); 276c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 277c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakevoid usbi_handle_transfer_completion(struct usbi_transfer *itransfer, 278c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake enum libusb_transfer_status status); 279c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakevoid usbi_handle_transfer_cancellation(struct usbi_transfer *transfer); 280852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 2812b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drakeint usbi_parse_descriptor(unsigned char *source, char *descriptor, void *dest, 2822b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake int host_endian); 2838ebb4ccdfaf5f095a1c38787d909d280ea64405cDaniel Drakeint usbi_get_config_index_by_value(struct libusb_device *dev, 2848ebb4ccdfaf5f095a1c38787d909d280ea64405cDaniel Drake uint8_t bConfigurationValue, int *idx); 285a8d2881eb7c273892acf2ff6e1f3f552631d1d11Daniel Drake 286c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake/* polling */ 287c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 288c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakestruct usbi_pollfd { 289c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake /* must come first */ 290c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake struct libusb_pollfd pollfd; 291c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 292c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake struct list_head list; 293c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake}; 294c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 2951df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakeint usbi_add_pollfd(struct libusb_context *ctx, int fd, short events); 2961df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drakevoid usbi_remove_pollfd(struct libusb_context *ctx, int fd); 297c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 298c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake/* device discovery */ 299c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 300c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake/* we traverse usbfs without knowing how many devices we are going to find. 301c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake * so we create this discovered_devs model which is similar to a linked-list 302c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake * which grows when required. it can be freed once discovery has completed, 303c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake * eliminating the need for a list node in the libusb_device structure 304c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake * itself. */ 305c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakestruct discovered_devs { 306c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t len; 307c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t capacity; 308c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake struct libusb_device *devices[0]; 309c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake}; 310c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 311c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakestruct discovered_devs *discovered_devs_append( 312c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake struct discovered_devs *discdevs, struct libusb_device *dev); 313c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 314c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake/* OS abstraction */ 315c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 3161298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake/* This is the interface that OS backends need to implement. 3171298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * All fields are mandatory, except ones explicitly noted as optional. */ 318c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakestruct usbi_os_backend { 3191298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* A human-readable name for your backend, e.g. "Linux usbfs" */ 320c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake const char *name; 3211298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 3221298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Perform initialization of your backend. You might use this function 3231298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * to determine specific capabilities of the system, allocate required 3241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * data structures for later, etc. 3251298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 3261298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when a libusb user initializes the library 3271298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * prior to use. 3281298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 3291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success, or a LIBUSB_ERROR code on failure. 3301298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 3311df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int (*init)(struct libusb_context *ctx); 3321298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 3331298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Deinitialization. Optional. This function should destroy anything 3341298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * that was set up by init. 3351298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 3361298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when the user deinitializes the library. 3371298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 338c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake void (*exit)(void); 339c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 3401298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Enumerate all the USB devices on the system, returning them in a list 3411298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * of discovered devices. 3421298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 3431298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Your implementation should enumerate all devices on the system, 3441298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * regardless of whether they have been seen before or not. 3451298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 3461298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * When you have found a device, compute a session ID for it. The session 3471298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * ID should uniquely represent that particular device for that particular 3481298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * connection session since boot (i.e. if you disconnect and reconnect a 3491298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device immediately after, it should be assigned a different session ID). 3501298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If your OS cannot provide a unique session ID as described above, 3511298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * presenting a session ID of (bus_number << 8 | device_address) should 3521298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * be sufficient. Bus numbers and device addresses wrap and get reused, 3531298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * but that is an unlikely case. 3541298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 3551298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * After computing a session ID for a device, call 3561298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * usbi_get_device_by_session_id(). This function checks if libusb already 3571298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * knows about the device, and if so, it provides you with a libusb_device 3581298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * structure for it. 3591298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 3601298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If usbi_get_device_by_session_id() returns NULL, it is time to allocate 3611298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * a new device structure for the device. Call usbi_alloc_device() to 3621298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * obtain a new libusb_device structure with reference count 1. Populate 3631298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * the bus_number and device_address attributes of the new device, and 3641298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * perform any other internal backend initialization you need to do. At 3651298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * this point, you should be ready to provide device descriptors and so 3661298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * on through the get_*_descriptor functions. Finally, call 3671298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * usbi_sanitize_device() to perform some final sanity checks on the 3681298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device. Assuming all of the above succeeded, we can now continue. 3691298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If any of the above failed, remember to unreference the device that 3701298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was returned by usbi_alloc_device(). 3711298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 3721298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * At this stage we have a populated libusb_device structure (either one 3731298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * that was found earlier, or one that we have just allocated and 3741298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * populated). This can now be added to the discovered devices list 3751298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * using discovered_devs_append(). Note that discovered_devs_append() 3761298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * may reallocate the list, returning a new location for it, and also 3771298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * note that reallocation can fail. Your backend should handle these 3781298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * error conditions appropriately. 3791298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 3801298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should not generate any bus I/O and should not block. 3811298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If I/O is required (e.g. reading the active configuration value), it is 3821298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * OK to ignore these suggestions :) 3831298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 3841298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is executed when the user wishes to retrieve a list 3851298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * of USB devices connected to the system. 3861298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 3871298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success, or a LIBUSB_ERROR code on failure. 3881298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 3891df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int (*get_device_list)(struct libusb_context *ctx, 3901df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct discovered_devs **discdevs); 391c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 3921298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Open a device for I/O and other USB operations. The device handle 3931298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * is preallocated for you, you can retrieve the device in question 3941298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * through handle->dev. 3951298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 3961298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Your backend should allocate any internal resources required for I/O 3971298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * and other operations so that those operations can happen (hopefully) 3981298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * without hiccup. This is also a good place to inform libusb that it 3991298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * should monitor certain file descriptors related to this device - 4001298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * see the usbi_add_pollfd() function. 4011298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 4021298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should not generate any bus I/O and should not block. 4031298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 4041298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when the user attempts to obtain a device 4051298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * handle for a device. 4061298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 4071298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 4081298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 4091298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_ACCESS if the user has insufficient permissions 4101298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since 4111298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * discovery 4121298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 4131298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 4141298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Do not worry about freeing the handle on failed open, the upper layers 4151298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * do this for you. 4161298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 417c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake int (*open)(struct libusb_device_handle *handle); 4181298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 4191298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Close a device such that the handle cannot be used again. Your backend 4201298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * should destroy any resources that were allocated in the open path. 4211298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This may also be a good place to call usbi_remove_pollfd() to inform 4221298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * libusb of any file descriptors associated with this device that should 4231298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * no longer be monitored. 4241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 4251298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when the user closes a device handle. 4261298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 427c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake void (*close)(struct libusb_device_handle *handle); 428c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 4291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Retrieve the device descriptor from a device. 4301298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 4311298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The descriptor should be retrieved from memory, NOT via bus I/O to the 4321298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device. This means that you may have to cache it in a private structure 4331298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * during get_device_list enumeration. Alternatively, you may be able 4341298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * to retrieve it from a kernel interface (some Linux setups can do this) 4351298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * still without generating bus I/O. 4361298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 4371298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is expected to write DEVICE_DESC_LENGTH (18) bytes into 4381298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * buffer, which is guaranteed to be big enough. 4391298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 4401298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when sanity-checking a device before adding 4411298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * it to the list of discovered devices, and also when the user requests 4421298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * to read the device descriptor. 4431298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 4442b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * This function is expected to return the descriptor in bus-endian format 4452b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * (LE). If it returns the multi-byte values in host-endian format, 4462b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * set the host_endian output parameter to "1". 4472b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * 4481298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success or a LIBUSB_ERROR code on failure. 4491298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 450b27fff633843824744df7d334cb89ece329cafa6Daniel Drake int (*get_device_descriptor)(struct libusb_device *device, 4512b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake unsigned char *buffer, int *host_endian); 4521298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 4531298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Get the ACTIVE configuration descriptor for a device. 4541298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 4551298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The descriptor should be retrieved from memory, NOT via bus I/O to the 4561298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device. This means that you may have to cache it in a private structure 4571298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * during get_device_list enumeration. You may also have to keep track 4581298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * of which configuration is active when the user changes it. 4591298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 4601298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is expected to write len bytes of data into buffer, which 4611298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * is guaranteed to be big enough. If you can only do a partial write, 4621298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * return an error code. 4631298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 4642b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * This function is expected to return the descriptor in bus-endian format 4652b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * (LE). If it returns the multi-byte values in host-endian format, 4662b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * set the host_endian output parameter to "1". 4672b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * 4681298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 4691298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 4701298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state 4711298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 4721298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 473fe4adcc99e30115204ab832ad3e0170c9aca7629Daniel Drake int (*get_active_config_descriptor)(struct libusb_device *device, 4742b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake unsigned char *buffer, size_t len, int *host_endian); 4751298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 4761298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Get a specific configuration descriptor for a device. 4771298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 4781298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The descriptor should be retrieved from memory, NOT via bus I/O to the 4791298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device. This means that you may have to cache it in a private structure 4801298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * during get_device_list enumeration. 4811298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 4821298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The requested descriptor is expressed as a zero-based index (i.e. 0 4831298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * indicates that we are requesting the first descriptor). The index does 4841298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * not (necessarily) equal the bConfigurationValue of the configuration 4851298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * being requested. 4861298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 4871298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is expected to write len bytes of data into buffer, which 4881298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * is guaranteed to be big enough. If you can only do a partial write, 4891298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * return an error code. 4901298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 4912b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * This function is expected to return the descriptor in bus-endian format 4922b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * (LE). If it returns the multi-byte values in host-endian format, 4932b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * set the host_endian output parameter to "1". 4942b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake * 4951298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success or a LIBUSB_ERROR code on failure. 4961298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 497c3844f7aeb2176636ce6e6ef697659fdb0b30048Daniel Drake int (*get_config_descriptor)(struct libusb_device *device, 4982b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake uint8_t config_index, unsigned char *buffer, size_t len, 4992b2e9c40b195261b09ac52ebdb93eef25c79de90Daniel Drake int *host_endian); 500b27fff633843824744df7d334cb89ece329cafa6Daniel Drake 501514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake /* Get the bConfigurationValue for the active configuration for a device. 502514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * Optional. This should only be implemented if you can retrieve it from 503514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * cache (don't generate I/O). 504514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * 505514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * If you cannot retrieve this from cache, either do not implement this 506514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * function, or return LIBUSB_ERROR_NOT_SUPPORTED. This will cause 507514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * libusb to retrieve the information through a standard control transfer. 508514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * 509514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * This function must be non-blocking. 510514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * Return: 511514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * - 0 on success 512514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 513514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * was opened 514514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * - LIBUSB_ERROR_NOT_SUPPORTED if the value cannot be retrieved without 515514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * blocking 516514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake * - another LIBUSB_ERROR code on other failure. 517514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake */ 518514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake int (*get_configuration)(struct libusb_device_handle *handle, int *config); 519514bb8790cfe8b93ccfff82bc17081b1030acce0Daniel Drake 5201298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Set the active configuration for a device. 5211298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5221298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * A configuration value of -1 should put the device in unconfigured state. 5231298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function can block. 5251298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5261298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 5271298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 5281298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the configuration does not exist 5291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_BUSY if interfaces are currently claimed (and hence 5301298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * configuration cannot be changed) 5311298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 5321298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 5331298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure. 5341298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 5350f463fe671455670efcf4a93e526b2a9082b0afeDaniel Drake int (*set_configuration)(struct libusb_device_handle *handle, int config); 5360f463fe671455670efcf4a93e526b2a9082b0afeDaniel Drake 5371298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Claim an interface. When claimed, the application can then perform 5381298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * I/O to an interface's endpoints. 5391298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5401298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should not generate any bus I/O and should not block. 5411298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Interface claiming is a logical operation that simply ensures that 5421298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * no other drivers/applications are using the interface, and after 5431298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * claiming, no other drivers/applicatiosn can use the interface because 5441298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * we now "own" it. 5451298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5461298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 5471298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 5481298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the interface does not exist 5491298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_BUSY if the interface is in use by another driver/app 5501298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 5511298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 5521298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 5531298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 554c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake int (*claim_interface)(struct libusb_device_handle *handle, int iface); 5551298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 5561298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Release a previously claimed interface. 5571298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5581298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should also generate a SET_INTERFACE control request, 5591298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * resetting the alternate setting of that interface to 0. It's OK for 5601298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * this function to block as a result. 5611298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5621298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * You will only ever be asked to release an interface which was 5631298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * successfully claimed earlier. 5641298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5651298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 5661298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 5671298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 5681298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 5691298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 5701298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 571c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake int (*release_interface)(struct libusb_device_handle *handle, int iface); 572c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 5731298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Set the alternate setting for an interface. 5741298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5751298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * You will only ever be asked to set the alternate setting for an 5761298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * interface which was successfully claimed earlier. 5771298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5781298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * It's OK for this function to block. 5791298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5801298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 5811298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 5821298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the alternate setting does not exist 5831298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 5841298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 5851298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 5861298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 58762077b7fa5b222e1bb9dea3467585aed69d596e2Daniel Drake int (*set_interface_altsetting)(struct libusb_device_handle *handle, 58862077b7fa5b222e1bb9dea3467585aed69d596e2Daniel Drake int iface, int altsetting); 5891298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 5901298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Clear a halt/stall condition on an endpoint. 5911298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5921298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * It's OK for this function to block. 5931298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 5941298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 5951298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 5961298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist 5971298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 5981298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 5991298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 6001298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 601c01f744ce07bbeccbe353e956479f0cc5a811a6fDaniel Drake int (*clear_halt)(struct libusb_device_handle *handle, 602c01f744ce07bbeccbe353e956479f0cc5a811a6fDaniel Drake unsigned char endpoint); 6031298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 6041298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Perform a USB port reset to reinitialize a device. 6051298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6061298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If possible, the handle should still be usable after the reset 6071298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * completes, assuming that the device descriptors did not change during 6081298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * reset and all previous interface state can be restored. 6091298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6101298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * If something changes, or you cannot easily locate/verify the resetted 6111298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device, return LIBUSB_ERROR_NOT_FOUND. This prompts the application 6121298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * to close the old handle and re-enumerate the device. 6131298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6141298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 6151298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 6161298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if re-enumeration is required, or if the device 6171298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * has been disconnected since it was opened 6181298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 6191298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 620bfe74e9cd9c17a40fff042ea0647326f51cfecaeDaniel Drake int (*reset_device)(struct libusb_device_handle *handle); 62162077b7fa5b222e1bb9dea3467585aed69d596e2Daniel Drake 6221298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Determine if a kernel driver is active on an interface. Optional. 6231298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The presence of a kernel driver on an interface indicates that any 6251298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * calls to claim_interface would fail with the LIBUSB_ERROR_BUSY code. 6261298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6271298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 6281298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 if no driver is active 6291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 1 if a driver is active 6301298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 6311298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 6321298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 6331298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 634470b1bc42bf53373ce678fc76bab9160a54d6881Daniel Drake int (*kernel_driver_active)(struct libusb_device_handle *handle, 635470b1bc42bf53373ce678fc76bab9160a54d6881Daniel Drake int interface); 6361298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 6371298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Detach a kernel driver from an interface. Optional. 6381298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6391298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * After detaching a kernel driver, the interface should be available 6401298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * for claim. 6411298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6421298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 6431298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 6441298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NOT_FOUND if no kernel driver was active 6451298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_INVALID_PARAM if the interface does not exist 6461298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 6471298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * was opened 6481298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 6491298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 650470b1bc42bf53373ce678fc76bab9160a54d6881Daniel Drake int (*detach_kernel_driver)(struct libusb_device_handle *handle, 651470b1bc42bf53373ce678fc76bab9160a54d6881Daniel Drake int interface); 652470b1bc42bf53373ce678fc76bab9160a54d6881Daniel Drake 6531d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera /* Attach a kernel driver to an interface. Optional. 6541d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * 6551d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * Reattach a kernel driver to the device. 6561d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * 6571d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * Return: 6581d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - 0 on success 6591d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - LIBUSB_ERROR_NOT_FOUND if no kernel driver was active 6601d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - LIBUSB_ERROR_INVALID_PARAM if the interface does not exist 6611d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected since it 6621d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * was opened 6631d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - LIBUSB_ERROR_BUSY if a program or driver has claimed the interface, 6641d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * preventing reattachment 6651d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera * - another LIBUSB_ERROR code on other failure 6661d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera */ 6671d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera int (*attach_kernel_driver)(struct libusb_device_handle *handle, 6681d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera int interface); 6691d7cf3d0fa8698eae25097cbda1870be90ff6f5eBastien Nocera 6701298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Destroy a device. Optional. 6711298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6721298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function is called when the last reference to a device is 6731298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * destroyed. It should free any resources allocated in the get_device_list 6741298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * path. 6751298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 676c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake void (*destroy_device)(struct libusb_device *dev); 677c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 6781298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Submit a transfer. Your implementation should take the transfer, 6791298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * morph it into whatever form your platform requires, and submit it 6801298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * asynchronously. 6811298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6821298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function must not block. 6831298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6841298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return: 6851298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - 0 on success 6861298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 6871298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * - another LIBUSB_ERROR code on other failure 6881298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 689c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake int (*submit_transfer)(struct usbi_transfer *itransfer); 6901298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 6911298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Cancel a previously submitted transfer. 6921298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 6931298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function must not block. The transfer cancellation must complete 6941298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * later, resulting in a call to usbi_handle_transfer_cancellation() 6951298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * from the context of handle_events. 6961298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 697c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake int (*cancel_transfer)(struct usbi_transfer *itransfer); 6981298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake 6991298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Clear a transfer as if it has completed or cancelled, but do not 7001298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * report any completion/cancellation to the library. You should free 7011298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * all private data from the transfer as if you were just about to report 7021298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * completion or cancellation. 7031298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7041298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function might seem a bit out of place. It is used when libusb 7051298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * detects a disconnected device - it calls this function for all pending 7061298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * transfers before reporting completion (with the disconnect code) to 7071298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * the user. Maybe we can improve upon this internal interface in future. 7081298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 709fec7c84163e25b8f811632828334d75da82bcb16Daniel Drake void (*clear_transfer_priv)(struct usbi_transfer *itransfer); 710c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 7111298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Handle any pending events. This involves monitoring any active 7121298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * transfers and processing their completion or cancellation. 7131298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7141298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * The function is passed an array of pollfd structures (size nfds) 7151298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * as a result of the poll() system call. The num_ready parameter 7161298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * indicates the number of file descriptors that have reported events 7171298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * (i.e. the poll() return value). This should be enough information 7181298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * for you to determine which actions need to be taken on the currently 7191298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * active transfers. 7201298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7211298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * For any cancelled transfers, call usbi_handle_transfer_cancellation(). 7221298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * For completed transfers, call usbi_handle_transfer_completion(). 7231298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * For control/bulk/interrupt transfers, populate the "transferred" 7241298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * element of the appropriate usbi_transfer structure before calling the 7251298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * above functions. For isochronous transfers, populate the status and 7261298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * transferred fields of the iso packet descriptors of the transfer. 7271298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7281298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This function should also be able to detect disconnection of the 7291298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * device, reporting that situation with usbi_handle_disconnect(). 7301298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * 7311298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Return 0 on success, or a LIBUSB_ERROR code on failure. 7321298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 7331df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake int (*handle_events)(struct libusb_context *ctx, 7341df713d622ab4f0b03aad72d903ac7beb8fb3b90Daniel Drake struct pollfd *fds, nfds_t nfds, int num_ready); 735c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 7361298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Number of bytes to reserve for per-device private backend data. 7371298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This private data area is accessible through the "os_priv" field of 7381298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * struct libusb_device. */ 739c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t device_priv_size; 740c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 7411298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Number of bytes to reserve for per-handle private backend data. 7421298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This private data area is accessible through the "os_priv" field of 7431298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * struct libusb_device. */ 744c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t device_handle_priv_size; 745c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 7461298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Number of bytes to reserve for per-transfer private backend data. 7471298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * This private data area is accessible by calling 7481298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * usbi_transfer_get_os_priv() on the appropriate usbi_transfer instance. 7491298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake */ 750c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake size_t transfer_priv_size; 751211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake 7521298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake /* Mumber of additional bytes for os_priv for each iso packet. 7531298c51f516a7bf04ca9add1b7db14417cdc66f3Daniel Drake * Can your backend use this? */ 754ad6e2b712c5b54af44424e58a2776686314e26b7Daniel Drake /* FIXME: linux can't use this any more. if other OS's cannot either, 755ad6e2b712c5b54af44424e58a2776686314e26b7Daniel Drake * then remove this */ 756211f80c9f2a4a58cd2bbf5b7751f45089c8961e7Daniel Drake size_t add_iso_packet_size; 757c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake}; 758c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 759c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakeextern const struct usbi_os_backend * const usbi_backend; 760c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 761c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drakeextern const struct usbi_os_backend linux_usbfs_backend; 762c0c9432d38b22784070dce3a7874c62c31786a27Daniel Drake 763852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake#endif 764852bba4754ec57679c823f33e8feba6e4a564cbDaniel Drake 765