lib/libusb/libusb20.h

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