libusb/libusbi.h

   1 /*
   2  * Internal header for libusb
   3  * Copyright (C) 2007 Daniel Drake <dsd@gentoo.org>
   4  * Copyright (c) 2001 Johannes Erdfelt <johannes@erdfelt.com>
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  19  */
  20
  21 #ifndef __LIBUSBI_H__
  22 #define __LIBUSBI_H__
  23
  24 #include <config.h>
  25
  26 #include <endian.h>
  27 #include <pthread.h>
  28 #include <stddef.h>
  29 #include <sys/select.h>
  30 #include <time.h>
  31
  32 #include <libusb.h>
  33
  34 #define DEVICE_DESC_LENGTH              18
  35
  36 #define USB_MAXENDPOINTS        32
  37 #define USB_MAXINTERFACES       32
  38 #define USB_MAXCONFIG           8
  39
  40 struct list_head {
  41         struct list_head *prev, *next;
  42 };
  43
  44 /* Get an entry from the list
  45  *      ptr - the address of this list_head element in "type"
  46  *      type - the data type that contains "member"
  47  *      member - the list_head element in "type"
  48  */
  49 #define list_entry(ptr, type, member) \
  50         ((type *)((char *)(ptr) - (unsigned long)(&((type *)0L)->member)))
  51
  52 /* Get each entry from a list
  53  *      pos - A structure pointer has a "member" element
  54  *      head - list head
  55  *      member - the list_head element in "pos"
  56  */
  57 #define list_for_each_entry(pos, head, member)                          \
  58         for (pos = list_entry((head)->next, typeof(*pos), member);      \
  59              &pos->member != (head);                                    \
  60              pos = list_entry(pos->member.next, typeof(*pos), member))
  61
  62 #define list_for_each_entry_safe(pos, n, head, member)                  \
  63         for (pos = list_entry((head)->next, typeof(*pos), member),      \
  64                 n = list_entry(pos->member.next, typeof(*pos), member); \
  65              &pos->member != (head);                                    \
  66              pos = n, n = list_entry(n->member.next, typeof(*n), member))
  67
  68 #define list_empty(entry) ((entry)->next == (entry))
  69
  70 static inline void list_init(struct list_head *entry)
  71 {
  72         entry->prev = entry->next = entry;
  73 }
  74
  75 static inline void list_add(struct list_head *entry, struct list_head *head)
  76 {
  77         entry->next = head->next;
  78         entry->prev = head;
  79
  80         head->next->prev = entry;
  81         head->next = entry;
  82 }
  83
  84 static inline void list_add_tail(struct list_head *entry,
  85         struct list_head *head)
  86 {
  87         entry->next = head;
  88         entry->prev = head->prev;
  89
  90         head->prev->next = entry;
  91         head->prev = entry;
  92 }
  93
  94 static inline void list_del(struct list_head *entry)
  95 {
  96         entry->next->prev = entry->prev;
  97         entry->prev->next = entry->next;
  98 }
  99
 100 #define container_of(ptr, type, member) ({                      \
 101         const typeof( ((type *)0)->member ) *__mptr = (ptr);    \
 102         (type *)( (char *)__mptr - offsetof(type,member) );})
 103
 104 #define bswap16(x) (((x & 0xff) << 8) | (x >> 8))
 105 #if __BYTE_ORDER == __LITTLE_ENDIAN
 106 #define cpu_to_le16(x) (x)
 107 #define le16_to_cpu(x) (x)
 108 #elif __BYTE_ORDER == __BIG_ENDIAN
 109 #define le16_to_cpu(x) bswap16(x)
 110 #define cpu_to_le16(x) bswap16(x)
 111 #else
 112 #error "Unrecognized endianness"
 113 #endif
 114
 115 #define MIN(a, b)       ((a) < (b) ? (a) : (b))
 116 #define MAX(a, b)       ((a) > (b) ? (a) : (b))
 117
 118 #define TIMESPEC_IS_SET(ts) ((ts)->tv_sec != 0 || (ts)->tv_nsec != 0)
 119
 120 enum usbi_log_level {
 121         LOG_LEVEL_DEBUG,
 122         LOG_LEVEL_INFO,
 123         LOG_LEVEL_WARNING,
 124         LOG_LEVEL_ERROR,
 125 };
 126
 127 void usbi_log(enum usbi_log_level, const char *function, const char *format, ...);
 128
 129 #ifdef ENABLE_LOGGING
 130 #define _usbi_log(level, fmt...) usbi_log(level, __FUNCTION__, fmt)
 131 #else
 132 #define _usbi_log(level, fmt...)
 133 #endif
 134
 135 #ifdef ENABLE_DEBUG_LOGGING
 136 #define usbi_dbg(fmt...) _usbi_log(LOG_LEVEL_DEBUG, fmt)
 137 #else
 138 #define usbi_dbg(fmt...)
 139 #endif
 140
 141 #define usbi_info(fmt...) _usbi_log(LOG_LEVEL_INFO, fmt)
 142 #define usbi_warn(fmt...) _usbi_log(LOG_LEVEL_WARNING, fmt)
 143 #define usbi_err(fmt...) _usbi_log(LOG_LEVEL_ERROR, fmt)
 144
 145 struct libusb_device {
 146         /* lock protects refcnt, everything else is finalized at initialization
 147          * time */
 148         pthread_mutex_t lock;
 149         int refcnt;
 150
 151         uint8_t bus_number;
 152         uint8_t device_address;
 153         uint8_t num_configurations;
 154
 155         struct list_head list;
 156         unsigned long session_data;
 157         unsigned char os_priv[0];
 158 };
 159
 160 struct libusb_device_handle {
 161         /* lock protects claimed_interfaces */
 162         pthread_mutex_t lock;
 163         unsigned long claimed_interfaces;
 164
 165         struct list_head list;
 166         struct libusb_device *dev;
 167         unsigned char os_priv[0];
 168 };
 169
 170 #define USBI_TRANSFER_TIMED_OUT                         (1<<0)
 171
 172 /* in-memory transfer layout:
 173  *
 174  * 1. struct usbi_transfer
 175  * 2. struct libusb_transfer (which includes iso packets) [variable size]
 176  * 3. os private data [variable size]
 177  *
 178  * from a libusb_transfer, you can get the usbi_transfer by rewinding the
 179  * appropriate number of bytes.
 180  * the usbi_transfer includes the number of allocated packets, so you can
 181  * determine the size of the transfer and hence the start and length of the
 182  * OS-private data.
 183  */
 184
 185 struct usbi_transfer {
 186         int num_iso_packets;
 187         struct list_head list;
 188         struct timeval timeout;
 189         int transferred;
 190         uint8_t flags;
 191 };
 192
 193 #define __USBI_TRANSFER_TO_LIBUSB_TRANSFER(transfer) \
 194         ((struct libusb_transfer *)(((void *)(transfer)) \
 195                 + sizeof(struct usbi_transfer)))
 196 #define __LIBUSB_TRANSFER_TO_USBI_TRANSFER(transfer) \
 197         ((struct usbi_transfer *)(((void *)(transfer)) \
 198                 - sizeof(struct usbi_transfer)))
 199
 200 static inline void *usbi_transfer_get_os_priv(struct usbi_transfer *transfer)
 201 {
 202         return ((void *)transfer) + sizeof(struct usbi_transfer)
 203                 + sizeof(struct libusb_transfer)
 204                 + (transfer->num_iso_packets
 205                         * sizeof(struct libusb_iso_packet_descriptor));
 206 }
 207
 208 /* bus structures */
 209
 210 /* All standard descriptors have these 2 fields in common */
 211 struct usb_descriptor_header {
 212         uint8_t  bLength;
 213         uint8_t  bDescriptorType;
 214 };
 215
 216 /* shared data and functions */
 217
 218 extern struct list_head usbi_open_devs;
 219 extern pthread_mutex_t usbi_open_devs_lock;
 220
 221 void usbi_io_init(void);
 222
 223 struct libusb_device *usbi_alloc_device(unsigned long session_id);
 224 struct libusb_device *usbi_get_device_by_session_id(unsigned long session_id);
 225 int usbi_sanitize_device(struct libusb_device *dev);
 226
 227 void usbi_handle_transfer_completion(struct usbi_transfer *itransfer,
 228         enum libusb_transfer_status status);
 229 void usbi_handle_transfer_cancellation(struct usbi_transfer *transfer);
 230
 231 int usbi_parse_descriptor(unsigned char *source, char *descriptor, void *dest);
 232
 233 /* polling */
 234
 235 struct usbi_pollfd {
 236         /* must come first */
 237         struct libusb_pollfd pollfd;
 238
 239         struct list_head list;
 240 };
 241
 242 int usbi_add_pollfd(int fd, short events);
 243 void usbi_remove_pollfd(int fd);
 244
 245 /* device discovery */
 246
 247 /* we traverse usbfs without knowing how many devices we are going to find.
 248  * so we create this discovered_devs model which is similar to a linked-list
 249  * which grows when required. it can be freed once discovery has completed,
 250  * eliminating the need for a list node in the libusb_device structure
 251  * itself. */
 252 struct discovered_devs {
 253         size_t len;
 254         size_t capacity;
 255         struct libusb_device *devices[0];
 256 };
 257
 258 struct discovered_devs *discovered_devs_append(
 259         struct discovered_devs *discdevs, struct libusb_device *dev);
 260
 261 /* OS abstraction */
 262
 263 struct usbi_os_backend {
 264         const char *name;
 265         int (*init)(void);
 266         void (*exit)(void);
 267
 268         int (*get_device_list)(struct discovered_devs **discdevs);
 269
 270         int (*open)(struct libusb_device_handle *handle);
 271         void (*close)(struct libusb_device_handle *handle);
 272
 273         int (*get_device_descriptor)(struct libusb_device *device,
 274                 unsigned char *buffer);
 275         int (*get_active_config_descriptor)(struct libusb_device *device,
 276                 unsigned char *buffer, size_t len);
 277         int (*get_config_descriptor)(struct libusb_device *device,
 278                 uint8_t config_index, unsigned char *buffer, size_t len);
 279
 280         int (*set_configuration)(struct libusb_device_handle *handle, int config);
 281
 282         int (*claim_interface)(struct libusb_device_handle *handle, int iface);
 283         int (*release_interface)(struct libusb_device_handle *handle, int iface);
 284
 285         int (*set_interface_altsetting)(struct libusb_device_handle *handle,
 286                 int iface, int altsetting);
 287         int (*clear_halt)(struct libusb_device_handle *handle,
 288                 unsigned char endpoint);
 289         int (*reset_device)(struct libusb_device_handle *handle);
 290
 291         /* optional */
 292         int (*kernel_driver_active)(struct libusb_device_handle *handle,
 293                 int interface);
 294         int (*detach_kernel_driver)(struct libusb_device_handle *handle,
 295                 int interface);
 296
 297         void (*destroy_device)(struct libusb_device *dev);
 298
 299         int (*submit_transfer)(struct usbi_transfer *itransfer);
 300         int (*cancel_transfer)(struct usbi_transfer *itransfer);
 301
 302         int (*handle_events)(fd_set *readfds, fd_set *writefds);
 303
 304         /* number of bytes to reserve for libusb_device.os_priv */
 305         size_t device_priv_size;
 306
 307         /* number of bytes to reserve for libusb_device_handle.os_priv */
 308         size_t device_handle_priv_size;
 309
 310         /* number of bytes to reserve for usbi_transfer.os_priv */
 311         size_t transfer_priv_size;
 312
 313         /* number of additional bytes for os_priv for each iso packet */
 314         /* FIXME: linux can't use this any more. if other OS's cannot either,
 315          * then remove this */
 316         size_t add_iso_packet_size;
 317 };
 318
 319 extern const struct usbi_os_backend * const usbi_backend;
 320
 321 extern const struct usbi_os_backend linux_usbfs_backend;
 322
 323 #endif
 324