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_ */ 318