lib/libusb/libusb20.h

   1 /* $FreeBSD$ */
   2 /*-
   3  * Copyright (c) 2008-2009 Hans Petter Selasky. All rights reserved.
   4  * Copyright (c) 2007-2008 Daniel Drake.  All rights reserved.
   5  * Copyright (c) 2001 Johannes Erdfelt.  All rights reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions
   9  * are met:
  10  * 1. Redistributions of source code must retain the above copyright
  11  *    notice, this list of conditions and the following disclaimer.
  12  * 2. Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26  * SUCH DAMAGE.
  27  */
  28
  29 #ifndef _LIBUSB20_H_
  30 #define _LIBUSB20_H_
  31
  32 #include <sys/endian.h>
  33 #include <sys/time.h>
  34 #include <sys/types.h>
  35
  36 #include <stdint.h>
  37 #include <string.h>
  38 #include <time.h>
  39
  40 #ifdef __cplusplus
  41 extern  "C" {
  42 #endif
  43 #if 0
  44 };                                      /* style */
  45
  46 #endif
  47
  48 /** \ingroup misc
  49  * Error codes. Most libusb20 functions return 0 on success or one of
  50  * these codes on failure.
  51  */
  52 enum libusb20_error {
  53         /** Success (no error) */
  54         LIBUSB20_SUCCESS = 0,
  55
  56         /** Input/output error */
  57         LIBUSB20_ERROR_IO = -1,
  58
  59         /** Invalid parameter */
  60         LIBUSB20_ERROR_INVALID_PARAM = -2,
  61
  62         /** Access denied (insufficient permissions) */
  63         LIBUSB20_ERROR_ACCESS = -3,
  64
  65         /** No such device (it may have been disconnected) */
  66         LIBUSB20_ERROR_NO_DEVICE = -4,
  67
  68         /** Entity not found */
  69         LIBUSB20_ERROR_NOT_FOUND = -5,
  70
  71         /** Resource busy */
  72         LIBUSB20_ERROR_BUSY = -6,
  73
  74         /** Operation timed out */
  75         LIBUSB20_ERROR_TIMEOUT = -7,
  76
  77         /** Overflow */
  78         LIBUSB20_ERROR_OVERFLOW = -8,
  79
  80         /** Pipe error */
  81         LIBUSB20_ERROR_PIPE = -9,
  82
  83         /** System call interrupted (perhaps due to signal) */
  84         LIBUSB20_ERROR_INTERRUPTED = -10,
  85
  86         /** Insufficient memory */
  87         LIBUSB20_ERROR_NO_MEM = -11,
  88
  89         /** Operation not supported or unimplemented on this platform */
  90         LIBUSB20_ERROR_NOT_SUPPORTED = -12,
  91
  92         /** Other error */
  93         LIBUSB20_ERROR_OTHER = -99,
  94 };
  95
  96 /** \ingroup asyncio
  97  * libusb20_tr_get_status() values */
  98 enum libusb20_transfer_status {
  99         /** Transfer completed without error. Note that this does not
 100          * indicate that the entire amount of requested data was
 101          * transferred. */
 102         LIBUSB20_TRANSFER_COMPLETED,
 103
 104         /** Callback code to start transfer */
 105         LIBUSB20_TRANSFER_START,
 106
 107         /** Drain complete callback code */
 108         LIBUSB20_TRANSFER_DRAINED,
 109
 110         /** Transfer failed */
 111         LIBUSB20_TRANSFER_ERROR,
 112
 113         /** Transfer timed out */
 114         LIBUSB20_TRANSFER_TIMED_OUT,
 115
 116         /** Transfer was cancelled */
 117         LIBUSB20_TRANSFER_CANCELLED,
 118
 119         /** For bulk/interrupt endpoints: halt condition detected
 120          * (endpoint stalled). For control endpoints: control request
 121          * not supported. */
 122         LIBUSB20_TRANSFER_STALL,
 123
 124         /** Device was disconnected */
 125         LIBUSB20_TRANSFER_NO_DEVICE,
 126
 127         /** Device sent more data than requested */
 128         LIBUSB20_TRANSFER_OVERFLOW,
 129 };
 130
 131 /** \ingroup asyncio
 132  * libusb20_tr_set_flags() values */
 133 enum libusb20_transfer_flags {
 134         /** Report a short frame as error */
 135         LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK = 0x0001,
 136
 137         /** Multiple short frames are not allowed */
 138         LIBUSB20_TRANSFER_MULTI_SHORT_NOT_OK = 0x0002,
 139
 140         /** All transmitted frames are short terminated */
 141         LIBUSB20_TRANSFER_FORCE_SHORT = 0x0004,
 142
 143         /** Will do a clear-stall before xfer */
 144         LIBUSB20_TRANSFER_DO_CLEAR_STALL = 0x0008,
 145 };
 146
 147 /** \ingroup misc
 148  * libusb20_dev_get_mode() values
 149  */
 150 enum libusb20_device_mode {
 151         LIBUSB20_MODE_HOST,             /* default */
 152         LIBUSB20_MODE_DEVICE,
 153 };
 154
 155 /** \ingroup misc
 156  * libusb20_dev_get_speed() values
 157  */
 158 enum {
 159         LIBUSB20_SPEED_UNKNOWN,         /* default */
 160         LIBUSB20_SPEED_LOW,
 161         LIBUSB20_SPEED_FULL,
 162         LIBUSB20_SPEED_HIGH,
 163         LIBUSB20_SPEED_VARIABLE,
 164         LIBUSB20_SPEED_SUPER,
 165 };
 166
 167 /** \ingroup misc
 168  * libusb20_dev_set_power() values
 169  */
 170 enum {
 171         LIBUSB20_POWER_OFF,
 172         LIBUSB20_POWER_ON,
 173         LIBUSB20_POWER_SAVE,
 174         LIBUSB20_POWER_SUSPEND,
 175         LIBUSB20_POWER_RESUME,
 176 };
 177
 178 struct usb_device_info;
 179 struct libusb20_transfer;
 180 struct libusb20_backend;
 181 struct libusb20_backend_methods;
 182 struct libusb20_device;
 183 struct libusb20_device_methods;
 184 struct libusb20_config;
 185 struct LIBUSB20_CONTROL_SETUP_DECODED;
 186 struct LIBUSB20_DEVICE_DESC_DECODED;
 187
 188 typedef void (libusb20_tr_callback_t)(struct libusb20_transfer *xfer);
 189
 190 struct libusb20_quirk {
 191         uint16_t vid;                   /* vendor ID */
 192         uint16_t pid;                   /* product ID */
 193         uint16_t bcdDeviceLow;          /* low revision value, inclusive */
 194         uint16_t bcdDeviceHigh;         /* high revision value, inclusive */
 195         uint16_t reserved[2];           /* for the future */
 196         /* quirk name, UQ_XXX, including terminating zero */
 197         char    quirkname[64 - 12];
 198 };
 199
 200 #define LIBUSB20_MAX_FRAME_PRE_SCALE    (1U << 31)
 201
 202 /* USB transfer operations */
 203 int     libusb20_tr_close(struct libusb20_transfer *xfer);
 204 int     libusb20_tr_open(struct libusb20_transfer *xfer, uint32_t max_buf_size, uint32_t max_frame_count, uint8_t ep_no);
 205 struct libusb20_transfer *libusb20_tr_get_pointer(struct libusb20_device *pdev, uint16_t tr_index);
 206 uint16_t libusb20_tr_get_time_complete(struct libusb20_transfer *xfer);
 207 uint32_t libusb20_tr_get_actual_frames(struct libusb20_transfer *xfer);
 208 uint32_t libusb20_tr_get_actual_length(struct libusb20_transfer *xfer);
 209 uint32_t libusb20_tr_get_max_frames(struct libusb20_transfer *xfer);
 210 uint32_t libusb20_tr_get_max_packet_length(struct libusb20_transfer *xfer);
 211 uint32_t libusb20_tr_get_max_total_length(struct libusb20_transfer *xfer);
 212 uint8_t libusb20_tr_get_status(struct libusb20_transfer *xfer);
 213 uint8_t libusb20_tr_pending(struct libusb20_transfer *xfer);
 214 void    libusb20_tr_callback_wrapper(struct libusb20_transfer *xfer);
 215 void    libusb20_tr_clear_stall_sync(struct libusb20_transfer *xfer);
 216 void    libusb20_tr_drain(struct libusb20_transfer *xfer);
 217 void    libusb20_tr_set_buffer(struct libusb20_transfer *xfer, void *buffer, uint16_t fr_index);
 218 void    libusb20_tr_set_callback(struct libusb20_transfer *xfer, libusb20_tr_callback_t *cb);
 219 void    libusb20_tr_set_flags(struct libusb20_transfer *xfer, uint8_t flags);
 220 uint32_t libusb20_tr_get_length(struct libusb20_transfer *xfer, uint16_t fr_index);
 221 void    libusb20_tr_set_length(struct libusb20_transfer *xfer, uint32_t length, uint16_t fr_index);
 222 void    libusb20_tr_set_priv_sc0(struct libusb20_transfer *xfer, void *sc0);
 223 void    libusb20_tr_set_priv_sc1(struct libusb20_transfer *xfer, void *sc1);
 224 void    libusb20_tr_set_timeout(struct libusb20_transfer *xfer, uint32_t timeout);
 225 void    libusb20_tr_set_total_frames(struct libusb20_transfer *xfer, uint32_t nFrames);
 226 void    libusb20_tr_setup_bulk(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout);
 227 void    libusb20_tr_setup_control(struct libusb20_transfer *xfer, void *psetup, void *pbuf, uint32_t timeout);
 228 void    libusb20_tr_setup_intr(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout);
 229 void    libusb20_tr_setup_isoc(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint16_t fr_index);
 230 uint8_t libusb20_tr_bulk_intr_sync(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t *pactlen, uint32_t timeout);
 231 void    libusb20_tr_start(struct libusb20_transfer *xfer);
 232 void    libusb20_tr_stop(struct libusb20_transfer *xfer);
 233 void    libusb20_tr_submit(struct libusb20_transfer *xfer);
 234 void   *libusb20_tr_get_priv_sc0(struct libusb20_transfer *xfer);
 235 void   *libusb20_tr_get_priv_sc1(struct libusb20_transfer *xfer);
 236
 237
 238 /* USB device operations */
 239
 240 const char *libusb20_dev_get_backend_name(struct libusb20_device *pdev);
 241 const char *libusb20_dev_get_desc(struct libusb20_device *pdev);
 242 int     libusb20_dev_close(struct libusb20_device *pdev);
 243 int     libusb20_dev_detach_kernel_driver(struct libusb20_device *pdev, uint8_t iface_index);
 244 int     libusb20_dev_set_config_index(struct libusb20_device *pdev, uint8_t configIndex);
 245 int     libusb20_dev_get_debug(struct libusb20_device *pdev);
 246 int     libusb20_dev_get_fd(struct libusb20_device *pdev);
 247 int     libusb20_dev_kernel_driver_active(struct libusb20_device *pdev, uint8_t iface_index);
 248 int     libusb20_dev_open(struct libusb20_device *pdev, uint16_t transfer_max);
 249 int     libusb20_dev_process(struct libusb20_device *pdev);
 250 int     libusb20_dev_request_sync(struct libusb20_device *pdev, struct LIBUSB20_CONTROL_SETUP_DECODED *setup, void *data, uint16_t *pactlen, uint32_t timeout, uint8_t flags);
 251 int     libusb20_dev_req_string_sync(struct libusb20_device *pdev, uint8_t index, uint16_t langid, void *ptr, uint16_t len);
 252 int     libusb20_dev_req_string_simple_sync(struct libusb20_device *pdev, uint8_t index, void *ptr, uint16_t len);
 253 int     libusb20_dev_reset(struct libusb20_device *pdev);
 254 int     libusb20_dev_check_connected(struct libusb20_device *pdev);
 255 int     libusb20_dev_set_power_mode(struct libusb20_device *pdev, uint8_t power_mode);
 256 uint8_t libusb20_dev_get_power_mode(struct libusb20_device *pdev);
 257 int     libusb20_dev_set_alt_index(struct libusb20_device *pdev, uint8_t iface_index, uint8_t alt_index);
 258 int     libusb20_dev_get_info(struct libusb20_device *pdev, struct usb_device_info *pinfo);
 259 int     libusb20_dev_get_iface_desc(struct libusb20_device *pdev, uint8_t iface_index, char *buf, uint8_t len);
 260
 261 struct LIBUSB20_DEVICE_DESC_DECODED *libusb20_dev_get_device_desc(struct libusb20_device *pdev);
 262 struct libusb20_config *libusb20_dev_alloc_config(struct libusb20_device *pdev, uint8_t config_index);
 263 struct libusb20_device *libusb20_dev_alloc(void);
 264 uint8_t libusb20_dev_get_address(struct libusb20_device *pdev);
 265 uint8_t libusb20_dev_get_parent_address(struct libusb20_device *pdev);
 266 uint8_t libusb20_dev_get_parent_port(struct libusb20_device *pdev);
 267 uint8_t libusb20_dev_get_bus_number(struct libusb20_device *pdev);
 268 uint8_t libusb20_dev_get_mode(struct libusb20_device *pdev);
 269 uint8_t libusb20_dev_get_speed(struct libusb20_device *pdev);
 270 uint8_t libusb20_dev_get_config_index(struct libusb20_device *pdev);
 271 void    libusb20_dev_free(struct libusb20_device *pdev);
 272 void    libusb20_dev_set_debug(struct libusb20_device *pdev, int debug);
 273 void    libusb20_dev_wait_process(struct libusb20_device *pdev, int timeout);
 274
 275 /* USB global operations */
 276
 277 int     libusb20_be_get_dev_quirk(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq);
 278 int     libusb20_be_get_quirk_name(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq);
 279 int     libusb20_be_add_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq);
 280 int     libusb20_be_remove_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq);
 281 int     libusb20_be_get_template(struct libusb20_backend *pbe, int *ptemp);
 282 int     libusb20_be_set_template(struct libusb20_backend *pbe, int temp);
 283
 284 /* USB backend operations */
 285
 286 struct libusb20_backend *libusb20_be_alloc(const struct libusb20_backend_methods *methods);
 287 struct libusb20_backend *libusb20_be_alloc_default(void);
 288 struct libusb20_backend *libusb20_be_alloc_freebsd(void);
 289 struct libusb20_backend *libusb20_be_alloc_linux(void);
 290 struct libusb20_backend *libusb20_be_alloc_ugen20(void);
 291 struct libusb20_device *libusb20_be_device_foreach(struct libusb20_backend *pbe, struct libusb20_device *pdev);
 292 void    libusb20_be_dequeue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev);
 293 void    libusb20_be_enqueue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev);
 294 void    libusb20_be_free(struct libusb20_backend *pbe);
 295
 296 /* USB debugging */
 297
 298 const char *libusb20_strerror(int);
 299 const char *libusb20_error_name(int);
 300
 301 #if 0
 302 {                                       /* style */
 303 #endif
 304 #ifdef __cplusplus
 305 }
 306
 307 #endif
 308
 309 #endif                                  /* _LIBUSB20_H_ */