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 38extern "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 */ 49enum 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 */ 95enum 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 */ 130enum 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 */ 147enum libusb20_device_mode { 148 LIBUSB20_MODE_HOST, /* default */ 149 LIBUSB20_MODE_DEVICE, 150}; 151 152/** \ingroup misc 153 * libusb20_dev_get_speed() values 154 */ 155enum { 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 */ 167enum { 168 LIBUSB20_POWER_OFF, 169 LIBUSB20_POWER_ON, 170 LIBUSB20_POWER_SAVE, 171 LIBUSB20_POWER_SUSPEND, 172 LIBUSB20_POWER_RESUME, 173}; 174 175struct usb_device_info; 176struct libusb20_transfer; 177struct libusb20_backend; 178struct libusb20_backend_methods; 179struct libusb20_device; 180struct libusb20_device_methods; 181struct libusb20_config; 182struct LIBUSB20_CONTROL_SETUP_DECODED; 183struct LIBUSB20_DEVICE_DESC_DECODED; 184 185typedef void (libusb20_tr_callback_t)(struct libusb20_transfer *xfer); 186 187struct 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 197struct 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 */ 206int libusb20_tr_close(struct libusb20_transfer *xfer); 207int libusb20_tr_open(struct libusb20_transfer *xfer, uint32_t max_buf_size, uint32_t max_frame_count, uint8_t ep_no); 208int 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); 209struct libusb20_transfer *libusb20_tr_get_pointer(struct libusb20_device *pdev, uint16_t tr_index); 210uint16_t libusb20_tr_get_time_complete(struct libusb20_transfer *xfer); 211uint32_t libusb20_tr_get_actual_frames(struct libusb20_transfer *xfer); 212uint32_t libusb20_tr_get_actual_length(struct libusb20_transfer *xfer); 213uint32_t libusb20_tr_get_max_frames(struct libusb20_transfer *xfer); 214uint32_t libusb20_tr_get_max_packet_length(struct libusb20_transfer *xfer); 215uint32_t libusb20_tr_get_max_total_length(struct libusb20_transfer *xfer); 216uint8_t libusb20_tr_get_status(struct libusb20_transfer *xfer); 217uint8_t libusb20_tr_pending(struct libusb20_transfer *xfer); 218void libusb20_tr_callback_wrapper(struct libusb20_transfer *xfer); 219void libusb20_tr_clear_stall_sync(struct libusb20_transfer *xfer); 220void libusb20_tr_drain(struct libusb20_transfer *xfer); 221void libusb20_tr_set_buffer(struct libusb20_transfer *xfer, void *buffer, uint16_t fr_index); 222void libusb20_tr_set_callback(struct libusb20_transfer *xfer, libusb20_tr_callback_t *cb); 223void libusb20_tr_set_flags(struct libusb20_transfer *xfer, uint8_t flags); 224uint32_t libusb20_tr_get_length(struct libusb20_transfer *xfer, uint16_t fr_index); 225void libusb20_tr_set_length(struct libusb20_transfer *xfer, uint32_t length, uint16_t fr_index); 226void libusb20_tr_set_priv_sc0(struct libusb20_transfer *xfer, void *sc0); 227void libusb20_tr_set_priv_sc1(struct libusb20_transfer *xfer, void *sc1); 228void libusb20_tr_set_timeout(struct libusb20_transfer *xfer, uint32_t timeout); 229void libusb20_tr_set_total_frames(struct libusb20_transfer *xfer, uint32_t nFrames); 230void libusb20_tr_setup_bulk(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout); 231void libusb20_tr_setup_control(struct libusb20_transfer *xfer, void *psetup, void *pbuf, uint32_t timeout); 232void libusb20_tr_setup_intr(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout); 233void libusb20_tr_setup_isoc(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint16_t fr_index); 234uint8_t libusb20_tr_bulk_intr_sync(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t *pactlen, uint32_t timeout); 235void libusb20_tr_start(struct libusb20_transfer *xfer); 236void libusb20_tr_stop(struct libusb20_transfer *xfer); 237void libusb20_tr_submit(struct libusb20_transfer *xfer); 238void *libusb20_tr_get_priv_sc0(struct libusb20_transfer *xfer); 239void *libusb20_tr_get_priv_sc1(struct libusb20_transfer *xfer); 240 241 242/* USB device operations */ 243 244const char *libusb20_dev_get_backend_name(struct libusb20_device *pdev); 245const char *libusb20_dev_get_desc(struct libusb20_device *pdev); 246int libusb20_dev_close(struct libusb20_device *pdev); 247int libusb20_dev_detach_kernel_driver(struct libusb20_device *pdev, uint8_t iface_index); 248int libusb20_dev_set_config_index(struct libusb20_device *pdev, uint8_t configIndex); 249int libusb20_dev_get_debug(struct libusb20_device *pdev); 250int libusb20_dev_get_fd(struct libusb20_device *pdev); 251int libusb20_dev_get_stats(struct libusb20_device *pdev, struct libusb20_device_stats *pstat); 252int libusb20_dev_kernel_driver_active(struct libusb20_device *pdev, uint8_t iface_index); 253int libusb20_dev_open(struct libusb20_device *pdev, uint16_t transfer_max); 254int libusb20_dev_process(struct libusb20_device *pdev); 255int 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); 256int libusb20_dev_req_string_sync(struct libusb20_device *pdev, uint8_t index, uint16_t langid, void *ptr, uint16_t len); 257int libusb20_dev_req_string_simple_sync(struct libusb20_device *pdev, uint8_t index, void *ptr, uint16_t len); 258int libusb20_dev_reset(struct libusb20_device *pdev); 259int libusb20_dev_check_connected(struct libusb20_device *pdev); 260int libusb20_dev_set_power_mode(struct libusb20_device *pdev, uint8_t power_mode); 261uint8_t libusb20_dev_get_power_mode(struct libusb20_device *pdev); 262int libusb20_dev_get_port_path(struct libusb20_device *pdev, uint8_t *buf, uint8_t bufsize); 263uint16_t libusb20_dev_get_power_usage(struct libusb20_device *pdev); 264int libusb20_dev_set_alt_index(struct libusb20_device *pdev, uint8_t iface_index, uint8_t alt_index); 265int libusb20_dev_get_info(struct libusb20_device *pdev, struct usb_device_info *pinfo); 266int libusb20_dev_get_iface_desc(struct libusb20_device *pdev, uint8_t iface_index, char *buf, uint8_t len); 267 268struct LIBUSB20_DEVICE_DESC_DECODED *libusb20_dev_get_device_desc(struct libusb20_device *pdev); 269struct libusb20_config *libusb20_dev_alloc_config(struct libusb20_device *pdev, uint8_t config_index); 270struct libusb20_device *libusb20_dev_alloc(void); 271uint8_t libusb20_dev_get_address(struct libusb20_device *pdev); 272uint8_t libusb20_dev_get_parent_address(struct libusb20_device *pdev); 273uint8_t libusb20_dev_get_parent_port(struct libusb20_device *pdev); 274uint8_t libusb20_dev_get_bus_number(struct libusb20_device *pdev); 275uint8_t libusb20_dev_get_mode(struct libusb20_device *pdev); 276uint8_t libusb20_dev_get_speed(struct libusb20_device *pdev); 277uint8_t libusb20_dev_get_config_index(struct libusb20_device *pdev); 278void libusb20_dev_free(struct libusb20_device *pdev); 279void libusb20_dev_set_debug(struct libusb20_device *pdev, int debug); 280void libusb20_dev_wait_process(struct libusb20_device *pdev, int timeout); 281 282/* USB global operations */ 283 284int libusb20_be_get_dev_quirk(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq); 285int libusb20_be_get_quirk_name(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq); 286int libusb20_be_add_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq); 287int libusb20_be_remove_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq); 288int libusb20_be_get_template(struct libusb20_backend *pbe, int *ptemp); 289int libusb20_be_set_template(struct libusb20_backend *pbe, int temp); 290 291/* USB backend operations */ 292 293struct libusb20_backend *libusb20_be_alloc(const struct libusb20_backend_methods *methods); 294struct libusb20_backend *libusb20_be_alloc_default(void); 295struct libusb20_backend *libusb20_be_alloc_freebsd(void); 296struct libusb20_backend *libusb20_be_alloc_linux(void); 297struct libusb20_backend *libusb20_be_alloc_ugen20(void); 298struct libusb20_device *libusb20_be_device_foreach(struct libusb20_backend *pbe, struct libusb20_device *pdev); 299void libusb20_be_dequeue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev); 300void libusb20_be_enqueue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev); 301void libusb20_be_free(struct libusb20_backend *pbe); 302 303/* USB debugging */ 304 305const char *libusb20_strerror(int); 306const 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_ */ 317