libusb20.h revision 185087
1184610Salfred/* $FreeBSD: head/lib/libusb20/libusb20.h 185087 2008-11-19 08:56:35Z alfred $ */ 2184610Salfred/*- 3184610Salfred * Copyright (c) 2008 Hans Petter Selasky. All rights reserved. 4184610Salfred * Copyright (c) 2007-2008 Daniel Drake. All rights reserved. 5184610Salfred * Copyright (c) 2001 Johannes Erdfelt. All rights reserved. 6184610Salfred * 7184610Salfred * Redistribution and use in source and binary forms, with or without 8184610Salfred * modification, are permitted provided that the following conditions 9184610Salfred * are met: 10184610Salfred * 1. Redistributions of source code must retain the above copyright 11184610Salfred * notice, this list of conditions and the following disclaimer. 12184610Salfred * 2. Redistributions in binary form must reproduce the above copyright 13184610Salfred * notice, this list of conditions and the following disclaimer in the 14184610Salfred * documentation and/or other materials provided with the distribution. 15184610Salfred * 16184610Salfred * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17184610Salfred * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18184610Salfred * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19184610Salfred * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20184610Salfred * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21184610Salfred * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22184610Salfred * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23184610Salfred * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24184610Salfred * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25184610Salfred * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26184610Salfred * SUCH DAMAGE. 27184610Salfred */ 28184610Salfred 29184610Salfred#ifndef _LIBUSB20_H_ 30184610Salfred#define _LIBUSB20_H_ 31184610Salfred 32184610Salfred#include <stdint.h> 33184610Salfred#include <time.h> 34184610Salfred#include <string.h> 35184610Salfred 36184610Salfred#include <sys/time.h> 37184610Salfred#include <sys/types.h> 38184610Salfred#include <sys/endian.h> 39184610Salfred 40184610Salfred#ifdef __cplusplus 41184610Salfredextern "C" { 42184610Salfred#endif 43184610Salfred#if 0 44184610Salfred}; /* style */ 45184610Salfred 46184610Salfred#endif 47184610Salfred 48184610Salfred/** \ingroup misc 49184610Salfred * Error codes. Most libusb20 functions return 0 on success or one of 50184610Salfred * these codes on failure. 51184610Salfred */ 52184610Salfredenum libusb20_error { 53184610Salfred /** Success (no error) */ 54184610Salfred LIBUSB20_SUCCESS = 0, 55184610Salfred 56184610Salfred /** Input/output error */ 57184610Salfred LIBUSB20_ERROR_IO = -1, 58184610Salfred 59184610Salfred /** Invalid parameter */ 60184610Salfred LIBUSB20_ERROR_INVALID_PARAM = -2, 61184610Salfred 62184610Salfred /** Access denied (insufficient permissions) */ 63184610Salfred LIBUSB20_ERROR_ACCESS = -3, 64184610Salfred 65184610Salfred /** No such device (it may have been disconnected) */ 66184610Salfred LIBUSB20_ERROR_NO_DEVICE = -4, 67184610Salfred 68184610Salfred /** Entity not found */ 69184610Salfred LIBUSB20_ERROR_NOT_FOUND = -5, 70184610Salfred 71184610Salfred /** Resource busy */ 72184610Salfred LIBUSB20_ERROR_BUSY = -6, 73184610Salfred 74184610Salfred /** Operation timed out */ 75184610Salfred LIBUSB20_ERROR_TIMEOUT = -7, 76184610Salfred 77184610Salfred /** Overflow */ 78184610Salfred LIBUSB20_ERROR_OVERFLOW = -8, 79184610Salfred 80184610Salfred /** Pipe error */ 81184610Salfred LIBUSB20_ERROR_PIPE = -9, 82184610Salfred 83184610Salfred /** System call interrupted (perhaps due to signal) */ 84184610Salfred LIBUSB20_ERROR_INTERRUPTED = -10, 85184610Salfred 86184610Salfred /** Insufficient memory */ 87184610Salfred LIBUSB20_ERROR_NO_MEM = -11, 88184610Salfred 89184610Salfred /** Operation not supported or unimplemented on this platform */ 90184610Salfred LIBUSB20_ERROR_NOT_SUPPORTED = -12, 91184610Salfred 92184610Salfred /** Other error */ 93184610Salfred LIBUSB20_ERROR_OTHER = -99, 94184610Salfred}; 95184610Salfred 96184610Salfred/** \ingroup asyncio 97184610Salfred * libusb20_tr_get_status() values */ 98184610Salfredenum libusb20_transfer_status { 99184610Salfred /** Transfer completed without error. Note that this does not 100184610Salfred * indicate that the entire amount of requested data was 101184610Salfred * transferred. */ 102184610Salfred LIBUSB20_TRANSFER_COMPLETED, 103184610Salfred 104184610Salfred /** Callback code to start transfer */ 105184610Salfred LIBUSB20_TRANSFER_START, 106184610Salfred 107184610Salfred /** Drain complete callback code */ 108184610Salfred LIBUSB20_TRANSFER_DRAINED, 109184610Salfred 110184610Salfred /** Transfer failed */ 111184610Salfred LIBUSB20_TRANSFER_ERROR, 112184610Salfred 113184610Salfred /** Transfer timed out */ 114184610Salfred LIBUSB20_TRANSFER_TIMED_OUT, 115184610Salfred 116184610Salfred /** Transfer was cancelled */ 117184610Salfred LIBUSB20_TRANSFER_CANCELLED, 118184610Salfred 119184610Salfred /** For bulk/interrupt endpoints: halt condition detected 120184610Salfred * (endpoint stalled). For control endpoints: control request 121184610Salfred * not supported. */ 122184610Salfred LIBUSB20_TRANSFER_STALL, 123184610Salfred 124184610Salfred /** Device was disconnected */ 125184610Salfred LIBUSB20_TRANSFER_NO_DEVICE, 126184610Salfred 127184610Salfred /** Device sent more data than requested */ 128184610Salfred LIBUSB20_TRANSFER_OVERFLOW, 129184610Salfred}; 130184610Salfred 131184610Salfred/** \ingroup asyncio 132184610Salfred * libusb20_tr_set_flags() values */ 133184610Salfredenum libusb20_transfer_flags { 134184610Salfred /** Report a short frame as error */ 135184610Salfred LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK = 0x0001, 136184610Salfred 137184610Salfred /** Multiple short frames are not allowed */ 138184610Salfred LIBUSB20_TRANSFER_MULTI_SHORT_NOT_OK = 0x0002, 139184610Salfred 140184610Salfred /** All transmitted frames are short terminated */ 141184610Salfred LIBUSB20_TRANSFER_FORCE_SHORT = 0x0004, 142184610Salfred 143184610Salfred /** Will do a clear-stall before xfer */ 144184610Salfred LIBUSB20_TRANSFER_DO_CLEAR_STALL = 0x0008, 145184610Salfred}; 146184610Salfred 147184610Salfred/** \ingroup misc 148184610Salfred * libusb20_dev_get_mode() values 149184610Salfred */ 150184610Salfredenum libusb20_device_mode { 151184610Salfred LIBUSB20_MODE_HOST, /* default */ 152184610Salfred LIBUSB20_MODE_DEVICE, 153184610Salfred}; 154184610Salfred 155184610Salfred/** \ingroup misc 156184610Salfred * libusb20_dev_get_speed() values 157184610Salfred */ 158184610Salfredenum { 159184610Salfred LIBUSB20_SPEED_UNKNOWN, /* default */ 160184610Salfred LIBUSB20_SPEED_LOW, 161184610Salfred LIBUSB20_SPEED_FULL, 162184610Salfred LIBUSB20_SPEED_HIGH, 163184610Salfred LIBUSB20_SPEED_VARIABLE, 164184610Salfred LIBUSB20_SPEED_SUPER, 165184610Salfred}; 166184610Salfred 167184610Salfred/** \ingroup misc 168184610Salfred * libusb20_dev_set_power() values 169184610Salfred */ 170184610Salfredenum { 171184610Salfred LIBUSB20_POWER_OFF, 172184610Salfred LIBUSB20_POWER_ON, 173184610Salfred LIBUSB20_POWER_SAVE, 174184610Salfred LIBUSB20_POWER_SUSPEND, 175184610Salfred LIBUSB20_POWER_RESUME, 176184610Salfred}; 177184610Salfred 178184610Salfredstruct libusb20_transfer; 179184610Salfredstruct libusb20_backend; 180184610Salfredstruct libusb20_backend_methods; 181184610Salfredstruct libusb20_device; 182184610Salfredstruct libusb20_device_methods; 183184610Salfredstruct libusb20_config; 184184610Salfredstruct LIBUSB20_CONTROL_SETUP_DECODED; 185184610Salfredstruct LIBUSB20_DEVICE_DESC_DECODED; 186184610Salfred 187184610Salfredtypedef void (libusb20_tr_callback_t)(struct libusb20_transfer *xfer); 188184610Salfred 189184610Salfredstruct libusb20_quirk { 190184610Salfred uint16_t vid; /* vendor ID */ 191184610Salfred uint16_t pid; /* product ID */ 192184610Salfred uint16_t bcdDeviceLow; /* low revision value, inclusive */ 193184610Salfred uint16_t bcdDeviceHigh; /* high revision value, inclusive */ 194184610Salfred uint16_t reserved[2]; /* for the future */ 195184610Salfred /* quirk name, UQ_XXX, including terminating zero */ 196184610Salfred char quirkname[64 - 12]; 197184610Salfred}; 198184610Salfred 199184610Salfred/* USB transfer operations */ 200184610Salfred 201184610Salfredint libusb20_tr_close(struct libusb20_transfer *xfer); 202185087Salfredint libusb20_tr_open(struct libusb20_transfer *xfer, uint32_t max_buf_size, uint32_t max_frame_count, uint8_t ep_no); 203184610Salfredstruct libusb20_transfer *libusb20_tr_get_pointer(struct libusb20_device *pdev, uint16_t tr_index); 204184610Salfreduint16_t libusb20_tr_get_time_complete(struct libusb20_transfer *xfer); 205184610Salfreduint32_t libusb20_tr_get_actual_frames(struct libusb20_transfer *xfer); 206184610Salfreduint32_t libusb20_tr_get_actual_length(struct libusb20_transfer *xfer); 207184610Salfreduint32_t libusb20_tr_get_max_frames(struct libusb20_transfer *xfer); 208184610Salfreduint32_t libusb20_tr_get_max_packet_length(struct libusb20_transfer *xfer); 209184610Salfreduint32_t libusb20_tr_get_max_total_length(struct libusb20_transfer *xfer); 210184610Salfreduint8_t libusb20_tr_get_status(struct libusb20_transfer *xfer); 211184610Salfreduint8_t libusb20_tr_pending(struct libusb20_transfer *xfer); 212184610Salfredvoid libusb20_tr_callback_wrapper(struct libusb20_transfer *xfer); 213184610Salfredvoid libusb20_tr_clear_stall_sync(struct libusb20_transfer *xfer); 214184610Salfredvoid libusb20_tr_drain(struct libusb20_transfer *xfer); 215184610Salfredvoid libusb20_tr_set_buffer(struct libusb20_transfer *xfer, void *buffer, uint16_t fr_index); 216184610Salfredvoid libusb20_tr_set_callback(struct libusb20_transfer *xfer, libusb20_tr_callback_t *cb); 217184610Salfredvoid libusb20_tr_set_flags(struct libusb20_transfer *xfer, uint8_t flags); 218184610Salfredvoid libusb20_tr_set_length(struct libusb20_transfer *xfer, uint32_t length, uint16_t fr_index); 219184610Salfredvoid libusb20_tr_set_priv_sc0(struct libusb20_transfer *xfer, void *sc0); 220184610Salfredvoid libusb20_tr_set_priv_sc1(struct libusb20_transfer *xfer, void *sc1); 221184610Salfredvoid libusb20_tr_set_timeout(struct libusb20_transfer *xfer, uint32_t timeout); 222184610Salfredvoid libusb20_tr_set_total_frames(struct libusb20_transfer *xfer, uint32_t nFrames); 223184610Salfredvoid libusb20_tr_setup_bulk(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout); 224184610Salfredvoid libusb20_tr_setup_control(struct libusb20_transfer *xfer, void *psetup, void *pbuf, uint32_t timeout); 225184610Salfredvoid libusb20_tr_setup_intr(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout); 226184610Salfredvoid libusb20_tr_setup_isoc(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint16_t fr_index); 227184610Salfredvoid libusb20_tr_start(struct libusb20_transfer *xfer); 228184610Salfredvoid libusb20_tr_stop(struct libusb20_transfer *xfer); 229184610Salfredvoid libusb20_tr_submit(struct libusb20_transfer *xfer); 230184610Salfredvoid *libusb20_tr_get_priv_sc0(struct libusb20_transfer *xfer); 231184610Salfredvoid *libusb20_tr_get_priv_sc1(struct libusb20_transfer *xfer); 232184610Salfred 233184610Salfred 234184610Salfred/* USB device operations */ 235184610Salfred 236184610Salfredconst char *libusb20_dev_get_backend_name(struct libusb20_device *pdev); 237184610Salfredconst char *libusb20_dev_get_desc(struct libusb20_device *pdev); 238184610Salfredint libusb20_dev_claim_interface(struct libusb20_device *pdev, uint8_t iface_index); 239184610Salfredint libusb20_dev_close(struct libusb20_device *pdev); 240184610Salfredint libusb20_dev_detach_kernel_driver(struct libusb20_device *pdev, uint8_t iface_index); 241184610Salfredint libusb20_dev_set_config_index(struct libusb20_device *pdev, uint8_t configIndex); 242184610Salfredint libusb20_dev_get_debug(struct libusb20_device *pdev); 243184610Salfredint libusb20_dev_get_fd(struct libusb20_device *pdev); 244184610Salfredint libusb20_dev_kernel_driver_active(struct libusb20_device *pdev, uint8_t iface_index); 245184610Salfredint libusb20_dev_open(struct libusb20_device *pdev, uint16_t transfer_max); 246184610Salfredint libusb20_dev_process(struct libusb20_device *pdev); 247184610Salfredint libusb20_dev_release_interface(struct libusb20_device *pdev, uint8_t iface_index); 248184610Salfredint 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); 249184610Salfredint libusb20_dev_req_string_sync(struct libusb20_device *pdev, uint8_t index, uint16_t langid, void *ptr, uint16_t len); 250184610Salfredint libusb20_dev_req_string_simple_sync(struct libusb20_device *pdev, uint8_t index, void *ptr, uint16_t len); 251184610Salfredint libusb20_dev_reset(struct libusb20_device *pdev); 252184610Salfredint libusb20_dev_set_power_mode(struct libusb20_device *pdev, uint8_t power_mode); 253184610Salfreduint8_t libusb20_dev_get_power_mode(struct libusb20_device *pdev); 254184610Salfredint libusb20_dev_set_alt_index(struct libusb20_device *pdev, uint8_t iface_index, uint8_t alt_index); 255184610Salfredint libusb20_dev_set_owner(struct libusb20_device *pdev, uid_t user, gid_t group); 256184610Salfredint libusb20_dev_set_perm(struct libusb20_device *pdev, mode_t mode); 257184610Salfredint libusb20_dev_set_iface_owner(struct libusb20_device *pdev, uint8_t iface_index, uid_t user, gid_t group); 258184610Salfredint libusb20_dev_set_iface_perm(struct libusb20_device *pdev, uint8_t iface_index, mode_t mode); 259184610Salfredint libusb20_dev_get_owner(struct libusb20_device *pdev, uid_t *user, gid_t *group); 260184610Salfredint libusb20_dev_get_perm(struct libusb20_device *pdev, mode_t *mode); 261184610Salfredint libusb20_dev_get_iface_owner(struct libusb20_device *pdev, uint8_t iface_index, uid_t *user, gid_t *group); 262184610Salfredint libusb20_dev_get_iface_perm(struct libusb20_device *pdev, uint8_t iface_index, mode_t *mode); 263184610Salfred 264184610Salfredstruct LIBUSB20_DEVICE_DESC_DECODED *libusb20_dev_get_device_desc(struct libusb20_device *pdev); 265184610Salfredstruct libusb20_config *libusb20_dev_alloc_config(struct libusb20_device *pdev, uint8_t config_index); 266184610Salfredstruct libusb20_device *libusb20_dev_alloc(void); 267184610Salfreduint8_t libusb20_dev_get_address(struct libusb20_device *pdev); 268184610Salfreduint8_t libusb20_dev_get_bus_number(struct libusb20_device *pdev); 269184610Salfreduint8_t libusb20_dev_get_mode(struct libusb20_device *pdev); 270184610Salfreduint8_t libusb20_dev_get_speed(struct libusb20_device *pdev); 271184610Salfreduint8_t libusb20_dev_get_config_index(struct libusb20_device *pdev); 272184610Salfredvoid libusb20_dev_free(struct libusb20_device *pdev); 273184610Salfredvoid libusb20_dev_set_debug(struct libusb20_device *pdev, int debug); 274184610Salfredvoid libusb20_dev_wait_process(struct libusb20_device *pdev, int timeout); 275184610Salfred 276184610Salfred/* USB bus operations */ 277184610Salfred 278184610Salfredint libusb20_bus_set_owner(struct libusb20_backend *pbe, uint8_t bus, uid_t user, gid_t group); 279184610Salfredint libusb20_bus_set_perm(struct libusb20_backend *pbe, uint8_t bus, mode_t mode); 280184610Salfredint libusb20_bus_get_owner(struct libusb20_backend *pbe, uint8_t bus, uid_t *user, gid_t *group); 281184610Salfredint libusb20_bus_get_perm(struct libusb20_backend *pbe, uint8_t bus, mode_t *mode); 282184610Salfred 283184610Salfred/* USB global operations */ 284184610Salfred 285184610Salfredint libusb20_be_get_dev_quirk(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq); 286184610Salfredint libusb20_be_get_quirk_name(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq); 287184610Salfredint libusb20_be_add_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq); 288184610Salfredint libusb20_be_remove_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq); 289184610Salfredint libusb20_be_set_owner(struct libusb20_backend *be, uid_t user, gid_t group); 290184610Salfredint libusb20_be_set_perm(struct libusb20_backend *be, mode_t mode); 291184610Salfredint libusb20_be_get_owner(struct libusb20_backend *be, uid_t *user, gid_t *group); 292184610Salfredint libusb20_be_get_perm(struct libusb20_backend *be, mode_t *mode); 293184610Salfred 294184610Salfred/* USB backend operations */ 295184610Salfred 296184610Salfredstruct libusb20_backend *libusb20_be_alloc(const struct libusb20_backend_methods *methods); 297184610Salfredstruct libusb20_backend *libusb20_be_alloc_default(void); 298184610Salfredstruct libusb20_backend *libusb20_be_alloc_freebsd(void); 299184610Salfredstruct libusb20_backend *libusb20_be_alloc_linux(void); 300185087Salfredstruct libusb20_backend *libusb20_be_alloc_ugen20(void); 301184610Salfredstruct libusb20_device *libusb20_be_device_foreach(struct libusb20_backend *pbe, struct libusb20_device *pdev); 302184610Salfredvoid libusb20_be_dequeue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev); 303184610Salfredvoid libusb20_be_enqueue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev); 304184610Salfredvoid libusb20_be_free(struct libusb20_backend *pbe); 305184610Salfred 306184610Salfred#if 0 307184610Salfred{ /* style */ 308184610Salfred#endif 309184610Salfred#ifdef __cplusplus 310184610Salfred} 311184610Salfred 312184610Salfred#endif 313184610Salfred 314184610Salfred#endif /* _LIBUSB20_H_ */ 315