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