lib/libusb/libusb20.h

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