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 #ifndef LIBUSB_GLOBAL_INCLUDE_FILE
  33 #include <stdint.h>
  34 #endif
  35
  36 #ifdef __cplusplus
  37 extern  "C" {
  38 #endif
  39 #if 0
  40 };                                      /* style */
  41
  42 #endif
  43
  44 /** \ingroup misc
  45  * Error codes. Most libusb20 functions return 0 on success or one of
  46  * these codes on failure.
  47  */
  48 enum libusb20_error {
  49         /** Success (no error) */
  50         LIBUSB20_SUCCESS = 0,
  51
  52         /** Input/output error */
  53         LIBUSB20_ERROR_IO = -1,
  54
  55         /** Invalid parameter */
  56         LIBUSB20_ERROR_INVALID_PARAM = -2,
  57
  58         /** Access denied (insufficient permissions) */
  59         LIBUSB20_ERROR_ACCESS = -3,
  60
  61         /** No such device (it may have been disconnected) */
  62         LIBUSB20_ERROR_NO_DEVICE = -4,
  63
  64         /** Entity not found */
  65         LIBUSB20_ERROR_NOT_FOUND = -5,
  66
  67         /** Resource busy */
  68         LIBUSB20_ERROR_BUSY = -6,
  69
  70         /** Operation timed out */
  71         LIBUSB20_ERROR_TIMEOUT = -7,
  72
  73         /** Overflow */
  74         LIBUSB20_ERROR_OVERFLOW = -8,
  75
  76         /** Pipe error */
  77         LIBUSB20_ERROR_PIPE = -9,
  78
  79         /** System call interrupted (perhaps due to signal) */
  80         LIBUSB20_ERROR_INTERRUPTED = -10,
  81
  82         /** Insufficient memory */
  83         LIBUSB20_ERROR_NO_MEM = -11,
  84
  85         /** Operation not supported or unimplemented on this platform */
  86         LIBUSB20_ERROR_NOT_SUPPORTED = -12,
  87
  88         /** Other error */
  89         LIBUSB20_ERROR_OTHER = -99,
  90 };
  91
  92 /** \ingroup asyncio
  93  * libusb20_tr_get_status() values */
  94 enum libusb20_transfer_status {
  95         /** Transfer completed without error. Note that this does not
  96          * indicate that the entire amount of requested data was
  97          * transferred. */
  98         LIBUSB20_TRANSFER_COMPLETED,
  99
 100         /** Callback code to start transfer */
 101         LIBUSB20_TRANSFER_START,
 102
 103         /** Drain complete callback code */
 104         LIBUSB20_TRANSFER_DRAINED,
 105
 106         /** Transfer failed */
 107         LIBUSB20_TRANSFER_ERROR,
 108
 109         /** Transfer timed out */
 110         LIBUSB20_TRANSFER_TIMED_OUT,
 111
 112         /** Transfer was cancelled */
 113         LIBUSB20_TRANSFER_CANCELLED,
 114
 115         /** For bulk/interrupt endpoints: halt condition detected
 116          * (endpoint stalled). For control endpoints: control request
 117          * not supported. */
 118         LIBUSB20_TRANSFER_STALL,
 119
 120         /** Device was disconnected */
 121         LIBUSB20_TRANSFER_NO_DEVICE,
 122
 123         /** Device sent more data than requested */
 124         LIBUSB20_TRANSFER_OVERFLOW,
 125 };
 126
 127 /** \ingroup asyncio
 128  * libusb20_tr_set_flags() values */
 129 enum libusb20_transfer_flags {
 130         /** Report a short frame as error */
 131         LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK = 0x0001,
 132
 133         /** Multiple short frames are not allowed */
 134         LIBUSB20_TRANSFER_MULTI_SHORT_NOT_OK = 0x0002,
 135
 136         /** All transmitted frames are short terminated */
 137         LIBUSB20_TRANSFER_FORCE_SHORT = 0x0004,
 138
 139         /** Will do a clear-stall before xfer */
 140         LIBUSB20_TRANSFER_DO_CLEAR_STALL = 0x0008,
 141 };
 142
 143 /** \ingroup misc
 144  * libusb20_dev_get_mode() values
 145  */
 146 enum libusb20_device_mode {
 147         LIBUSB20_MODE_HOST,             /* default */
 148         LIBUSB20_MODE_DEVICE,
 149 };
 150
 151 /** \ingroup misc
 152  * libusb20_dev_get_speed() values
 153  */
 154 enum {
 155         LIBUSB20_SPEED_UNKNOWN,         /* default */
 156         LIBUSB20_SPEED_LOW,
 157         LIBUSB20_SPEED_FULL,
 158         LIBUSB20_SPEED_HIGH,
 159         LIBUSB20_SPEED_VARIABLE,
 160         LIBUSB20_SPEED_SUPER,
 161 };
 162
 163 /** \ingroup misc
 164  * libusb20_dev_set_power() values
 165  */
 166 enum {
 167         LIBUSB20_POWER_OFF,
 168         LIBUSB20_POWER_ON,
 169         LIBUSB20_POWER_SAVE,
 170         LIBUSB20_POWER_SUSPEND,
 171         LIBUSB20_POWER_RESUME,
 172 };
 173
 174 struct usb_device_info;
 175 struct libusb20_transfer;
 176 struct libusb20_backend;
 177 struct libusb20_backend_methods;
 178 struct libusb20_device;
 179 struct libusb20_device_methods;
 180 struct libusb20_config;
 181 struct LIBUSB20_CONTROL_SETUP_DECODED;
 182 struct LIBUSB20_DEVICE_DESC_DECODED;
 183
 184 typedef void (libusb20_tr_callback_t)(struct libusb20_transfer *xfer);
 185
 186 struct libusb20_quirk {
 187         uint16_t vid;                   /* vendor ID */
 188         uint16_t pid;                   /* product ID */
 189         uint16_t bcdDeviceLow;          /* low revision value, inclusive */
 190         uint16_t bcdDeviceHigh;         /* high revision value, inclusive */
 191         uint16_t reserved[2];           /* for the future */
 192         /* quirk name, UQ_XXX, including terminating zero */
 193         char    quirkname[64 - 12];
 194 };
 195
 196 struct libusb20_device_stats {
 197         uint64_t xfer_ok[4];            /* sorted by USB transfer type, UE_XXX */
 198         uint64_t xfer_fail[4];          /* sorted by USB transfer type, UE_XXX */
 199         uint64_t xfer_reserved[24];     /* reserved */
 200 };
 201
 202 #define LIBUSB20_MAX_FRAME_PRE_SCALE    (1U << 31)
 203
 204 /* USB transfer operations */
 205 int     libusb20_tr_close(struct libusb20_transfer *xfer);
 206 int     libusb20_tr_open(struct libusb20_transfer *xfer, uint32_t max_buf_size, uint32_t max_frame_count, uint8_t ep_no);
 207 int     libusb20_tr_open_stream(struct libusb20_transfer *xfer, uint32_t max_buf_size, uint32_t max_frame_count, uint8_t ep_no, uint16_t stream_id);
 208 struct libusb20_transfer *libusb20_tr_get_pointer(struct libusb20_device *pdev, uint16_t tr_index);
 209 uint16_t libusb20_tr_get_time_complete(struct libusb20_transfer *xfer);
 210 uint32_t libusb20_tr_get_actual_frames(struct libusb20_transfer *xfer);
 211 uint32_t libusb20_tr_get_actual_length(struct libusb20_transfer *xfer);
 212 uint32_t libusb20_tr_get_max_frames(struct libusb20_transfer *xfer);
 213 uint32_t libusb20_tr_get_max_packet_length(struct libusb20_transfer *xfer);
 214 uint32_t libusb20_tr_get_max_total_length(struct libusb20_transfer *xfer);
 215 uint8_t libusb20_tr_get_status(struct libusb20_transfer *xfer);
 216 uint8_t libusb20_tr_pending(struct libusb20_transfer *xfer);
 217 void    libusb20_tr_callback_wrapper(struct libusb20_transfer *xfer);
 218 void    libusb20_tr_clear_stall_sync(struct libusb20_transfer *xfer);
 219 void    libusb20_tr_drain(struct libusb20_transfer *xfer);
 220 void    libusb20_tr_set_buffer(struct libusb20_transfer *xfer, void *buffer, uint16_t fr_index);
 221 void    libusb20_tr_set_callback(struct libusb20_transfer *xfer, libusb20_tr_callback_t *cb);
 222 void    libusb20_tr_set_flags(struct libusb20_transfer *xfer, uint8_t flags);
 223 uint32_t libusb20_tr_get_length(struct libusb20_transfer *xfer, uint16_t fr_index);
 224 void    libusb20_tr_set_length(struct libusb20_transfer *xfer, uint32_t length, uint16_t fr_index);
 225 void    libusb20_tr_set_priv_sc0(struct libusb20_transfer *xfer, void *sc0);
 226 void    libusb20_tr_set_priv_sc1(struct libusb20_transfer *xfer, void *sc1);
 227 void    libusb20_tr_set_timeout(struct libusb20_transfer *xfer, uint32_t timeout);
 228 void    libusb20_tr_set_total_frames(struct libusb20_transfer *xfer, uint32_t nFrames);
 229 void    libusb20_tr_setup_bulk(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout);
 230 void    libusb20_tr_setup_control(struct libusb20_transfer *xfer, void *psetup, void *pbuf, uint32_t timeout);
 231 void    libusb20_tr_setup_intr(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout);
 232 void    libusb20_tr_setup_isoc(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint16_t fr_index);
 233 uint8_t libusb20_tr_bulk_intr_sync(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t *pactlen, uint32_t timeout);
 234 void    libusb20_tr_start(struct libusb20_transfer *xfer);
 235 void    libusb20_tr_stop(struct libusb20_transfer *xfer);
 236 void    libusb20_tr_submit(struct libusb20_transfer *xfer);
 237 void   *libusb20_tr_get_priv_sc0(struct libusb20_transfer *xfer);
 238 void   *libusb20_tr_get_priv_sc1(struct libusb20_transfer *xfer);
 239
 240
 241 /* USB device operations */
 242
 243 const char *libusb20_dev_get_backend_name(struct libusb20_device *pdev);
 244 const char *libusb20_dev_get_desc(struct libusb20_device *pdev);
 245 int     libusb20_dev_close(struct libusb20_device *pdev);
 246 int     libusb20_dev_detach_kernel_driver(struct libusb20_device *pdev, uint8_t iface_index);
 247 int     libusb20_dev_set_config_index(struct libusb20_device *pdev, uint8_t configIndex);
 248 int     libusb20_dev_get_debug(struct libusb20_device *pdev);
 249 int     libusb20_dev_get_fd(struct libusb20_device *pdev);
 250 int     libusb20_dev_get_stats(struct libusb20_device *pdev, struct libusb20_device_stats *pstat);
 251 int     libusb20_dev_kernel_driver_active(struct libusb20_device *pdev, uint8_t iface_index);
 252 int     libusb20_dev_open(struct libusb20_device *pdev, uint16_t transfer_max);
 253 int     libusb20_dev_process(struct libusb20_device *pdev);
 254 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);
 255 int     libusb20_dev_req_string_sync(struct libusb20_device *pdev, uint8_t index, uint16_t langid, void *ptr, uint16_t len);
 256 int     libusb20_dev_req_string_simple_sync(struct libusb20_device *pdev, uint8_t index, void *ptr, uint16_t len);
 257 int     libusb20_dev_reset(struct libusb20_device *pdev);
 258 int     libusb20_dev_check_connected(struct libusb20_device *pdev);
 259 int     libusb20_dev_set_power_mode(struct libusb20_device *pdev, uint8_t power_mode);
 260 uint8_t libusb20_dev_get_power_mode(struct libusb20_device *pdev);
 261 int     libusb20_dev_get_port_path(struct libusb20_device *pdev, uint8_t *buf, uint8_t bufsize);
 262 uint16_t        libusb20_dev_get_power_usage(struct libusb20_device *pdev);
 263 int     libusb20_dev_set_alt_index(struct libusb20_device *pdev, uint8_t iface_index, uint8_t alt_index);
 264 int     libusb20_dev_get_info(struct libusb20_device *pdev, struct usb_device_info *pinfo);
 265 int     libusb20_dev_get_iface_desc(struct libusb20_device *pdev, uint8_t iface_index, char *buf, uint8_t len);
 266
 267 struct LIBUSB20_DEVICE_DESC_DECODED *libusb20_dev_get_device_desc(struct libusb20_device *pdev);
 268 struct libusb20_config *libusb20_dev_alloc_config(struct libusb20_device *pdev, uint8_t config_index);
 269 struct libusb20_device *libusb20_dev_alloc(void);
 270 uint8_t libusb20_dev_get_address(struct libusb20_device *pdev);
 271 uint8_t libusb20_dev_get_parent_address(struct libusb20_device *pdev);
 272 uint8_t libusb20_dev_get_parent_port(struct libusb20_device *pdev);
 273 uint8_t libusb20_dev_get_bus_number(struct libusb20_device *pdev);
 274 uint8_t libusb20_dev_get_mode(struct libusb20_device *pdev);
 275 uint8_t libusb20_dev_get_speed(struct libusb20_device *pdev);
 276 uint8_t libusb20_dev_get_config_index(struct libusb20_device *pdev);
 277 void    libusb20_dev_free(struct libusb20_device *pdev);
 278 void    libusb20_dev_set_debug(struct libusb20_device *pdev, int debug);
 279 void    libusb20_dev_wait_process(struct libusb20_device *pdev, int timeout);
 280
 281 /* USB global operations */
 282
 283 int     libusb20_be_get_dev_quirk(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq);
 284 int     libusb20_be_get_quirk_name(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq);
 285 int     libusb20_be_add_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq);
 286 int     libusb20_be_remove_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq);
 287 int     libusb20_be_get_template(struct libusb20_backend *pbe, int *ptemp);
 288 int     libusb20_be_set_template(struct libusb20_backend *pbe, int temp);
 289
 290 /* USB backend operations */
 291
 292 struct libusb20_backend *libusb20_be_alloc(const struct libusb20_backend_methods *methods);
 293 struct libusb20_backend *libusb20_be_alloc_default(void);
 294 struct libusb20_backend *libusb20_be_alloc_freebsd(void);
 295 struct libusb20_backend *libusb20_be_alloc_linux(void);
 296 struct libusb20_backend *libusb20_be_alloc_ugen20(void);
 297 struct libusb20_device *libusb20_be_device_foreach(struct libusb20_backend *pbe, struct libusb20_device *pdev);
 298 void    libusb20_be_dequeue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev);
 299 void    libusb20_be_enqueue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev);
 300 void    libusb20_be_free(struct libusb20_backend *pbe);
 301
 302 /* USB debugging */
 303
 304 const char *libusb20_strerror(int);
 305 const char *libusb20_error_name(int);
 306
 307 #if 0
 308 {                                       /* style */
 309 #endif
 310 #ifdef __cplusplus
 311 }
 312
 313 #endif
 314
 315 #endif                                  /* _LIBUSB20_H_ */