1184610Salfred/* $FreeBSD: stable/11/lib/libusb/libusb20.h 356398 2020-01-06 09:21:15Z hselasky $ */ 2184610Salfred/*- 3199575Sthompsa * Copyright (c) 2008-2009 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 32248236Shselasky#ifndef LIBUSB_GLOBAL_INCLUDE_FILE 33184610Salfred#include <stdint.h> 34248236Shselasky#endif 35184610Salfred 36184610Salfred#ifdef __cplusplus 37184610Salfredextern "C" { 38184610Salfred#endif 39184610Salfred#if 0 40184610Salfred}; /* style */ 41184610Salfred 42184610Salfred#endif 43184610Salfred 44184610Salfred/** \ingroup misc 45184610Salfred * Error codes. Most libusb20 functions return 0 on success or one of 46184610Salfred * these codes on failure. 47184610Salfred */ 48184610Salfredenum libusb20_error { 49184610Salfred /** Success (no error) */ 50184610Salfred LIBUSB20_SUCCESS = 0, 51184610Salfred 52184610Salfred /** Input/output error */ 53184610Salfred LIBUSB20_ERROR_IO = -1, 54184610Salfred 55184610Salfred /** Invalid parameter */ 56184610Salfred LIBUSB20_ERROR_INVALID_PARAM = -2, 57184610Salfred 58184610Salfred /** Access denied (insufficient permissions) */ 59184610Salfred LIBUSB20_ERROR_ACCESS = -3, 60184610Salfred 61184610Salfred /** No such device (it may have been disconnected) */ 62184610Salfred LIBUSB20_ERROR_NO_DEVICE = -4, 63184610Salfred 64184610Salfred /** Entity not found */ 65184610Salfred LIBUSB20_ERROR_NOT_FOUND = -5, 66184610Salfred 67184610Salfred /** Resource busy */ 68184610Salfred LIBUSB20_ERROR_BUSY = -6, 69184610Salfred 70184610Salfred /** Operation timed out */ 71184610Salfred LIBUSB20_ERROR_TIMEOUT = -7, 72184610Salfred 73184610Salfred /** Overflow */ 74184610Salfred LIBUSB20_ERROR_OVERFLOW = -8, 75184610Salfred 76184610Salfred /** Pipe error */ 77184610Salfred LIBUSB20_ERROR_PIPE = -9, 78184610Salfred 79184610Salfred /** System call interrupted (perhaps due to signal) */ 80184610Salfred LIBUSB20_ERROR_INTERRUPTED = -10, 81184610Salfred 82184610Salfred /** Insufficient memory */ 83184610Salfred LIBUSB20_ERROR_NO_MEM = -11, 84184610Salfred 85184610Salfred /** Operation not supported or unimplemented on this platform */ 86184610Salfred LIBUSB20_ERROR_NOT_SUPPORTED = -12, 87184610Salfred 88184610Salfred /** Other error */ 89184610Salfred LIBUSB20_ERROR_OTHER = -99, 90184610Salfred}; 91184610Salfred 92184610Salfred/** \ingroup asyncio 93184610Salfred * libusb20_tr_get_status() values */ 94184610Salfredenum libusb20_transfer_status { 95184610Salfred /** Transfer completed without error. Note that this does not 96184610Salfred * indicate that the entire amount of requested data was 97184610Salfred * transferred. */ 98184610Salfred LIBUSB20_TRANSFER_COMPLETED, 99184610Salfred 100184610Salfred /** Callback code to start transfer */ 101184610Salfred LIBUSB20_TRANSFER_START, 102184610Salfred 103184610Salfred /** Drain complete callback code */ 104184610Salfred LIBUSB20_TRANSFER_DRAINED, 105184610Salfred 106184610Salfred /** Transfer failed */ 107184610Salfred LIBUSB20_TRANSFER_ERROR, 108184610Salfred 109184610Salfred /** Transfer timed out */ 110184610Salfred LIBUSB20_TRANSFER_TIMED_OUT, 111184610Salfred 112184610Salfred /** Transfer was cancelled */ 113184610Salfred LIBUSB20_TRANSFER_CANCELLED, 114184610Salfred 115184610Salfred /** For bulk/interrupt endpoints: halt condition detected 116184610Salfred * (endpoint stalled). For control endpoints: control request 117184610Salfred * not supported. */ 118184610Salfred LIBUSB20_TRANSFER_STALL, 119184610Salfred 120184610Salfred /** Device was disconnected */ 121184610Salfred LIBUSB20_TRANSFER_NO_DEVICE, 122184610Salfred 123184610Salfred /** Device sent more data than requested */ 124184610Salfred LIBUSB20_TRANSFER_OVERFLOW, 125184610Salfred}; 126184610Salfred 127184610Salfred/** \ingroup asyncio 128184610Salfred * libusb20_tr_set_flags() values */ 129184610Salfredenum libusb20_transfer_flags { 130184610Salfred /** Report a short frame as error */ 131184610Salfred LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK = 0x0001, 132184610Salfred 133184610Salfred /** Multiple short frames are not allowed */ 134184610Salfred LIBUSB20_TRANSFER_MULTI_SHORT_NOT_OK = 0x0002, 135184610Salfred 136184610Salfred /** All transmitted frames are short terminated */ 137184610Salfred LIBUSB20_TRANSFER_FORCE_SHORT = 0x0004, 138184610Salfred 139184610Salfred /** Will do a clear-stall before xfer */ 140184610Salfred LIBUSB20_TRANSFER_DO_CLEAR_STALL = 0x0008, 141184610Salfred}; 142184610Salfred 143184610Salfred/** \ingroup misc 144184610Salfred * libusb20_dev_get_mode() values 145184610Salfred */ 146184610Salfredenum libusb20_device_mode { 147184610Salfred LIBUSB20_MODE_HOST, /* default */ 148184610Salfred LIBUSB20_MODE_DEVICE, 149184610Salfred}; 150184610Salfred 151184610Salfred/** \ingroup misc 152184610Salfred * libusb20_dev_get_speed() values 153184610Salfred */ 154184610Salfredenum { 155184610Salfred LIBUSB20_SPEED_UNKNOWN, /* default */ 156184610Salfred LIBUSB20_SPEED_LOW, 157184610Salfred LIBUSB20_SPEED_FULL, 158184610Salfred LIBUSB20_SPEED_HIGH, 159184610Salfred LIBUSB20_SPEED_VARIABLE, 160184610Salfred LIBUSB20_SPEED_SUPER, 161184610Salfred}; 162184610Salfred 163184610Salfred/** \ingroup misc 164184610Salfred * libusb20_dev_set_power() values 165184610Salfred */ 166184610Salfredenum { 167184610Salfred LIBUSB20_POWER_OFF, 168184610Salfred LIBUSB20_POWER_ON, 169184610Salfred LIBUSB20_POWER_SAVE, 170184610Salfred LIBUSB20_POWER_SUSPEND, 171184610Salfred LIBUSB20_POWER_RESUME, 172184610Salfred}; 173184610Salfred 174192984Sthompsastruct usb_device_info; 175184610Salfredstruct libusb20_transfer; 176184610Salfredstruct libusb20_backend; 177184610Salfredstruct libusb20_backend_methods; 178184610Salfredstruct libusb20_device; 179184610Salfredstruct libusb20_device_methods; 180184610Salfredstruct libusb20_config; 181184610Salfredstruct LIBUSB20_CONTROL_SETUP_DECODED; 182184610Salfredstruct LIBUSB20_DEVICE_DESC_DECODED; 183184610Salfred 184184610Salfredtypedef void (libusb20_tr_callback_t)(struct libusb20_transfer *xfer); 185184610Salfred 186184610Salfredstruct libusb20_quirk { 187184610Salfred uint16_t vid; /* vendor ID */ 188184610Salfred uint16_t pid; /* product ID */ 189184610Salfred uint16_t bcdDeviceLow; /* low revision value, inclusive */ 190184610Salfred uint16_t bcdDeviceHigh; /* high revision value, inclusive */ 191184610Salfred uint16_t reserved[2]; /* for the future */ 192184610Salfred /* quirk name, UQ_XXX, including terminating zero */ 193184610Salfred char quirkname[64 - 12]; 194184610Salfred}; 195184610Salfred 196356398Shselaskystruct libusb20_device_stats { 197356398Shselasky uint64_t xfer_ok[4]; /* sorted by USB transfer type, UE_XXX */ 198356398Shselasky uint64_t xfer_fail[4]; /* sorted by USB transfer type, UE_XXX */ 199356398Shselasky uint64_t xfer_reserved[24]; /* reserved */ 200356398Shselasky}; 201356398Shselasky 202219100Shselasky#define LIBUSB20_MAX_FRAME_PRE_SCALE (1U << 31) 203219100Shselasky 204184610Salfred/* USB transfer operations */ 205184610Salfredint libusb20_tr_close(struct libusb20_transfer *xfer); 206185087Salfredint libusb20_tr_open(struct libusb20_transfer *xfer, uint32_t max_buf_size, uint32_t max_frame_count, uint8_t ep_no); 207239239Shselaskyint 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); 208184610Salfredstruct libusb20_transfer *libusb20_tr_get_pointer(struct libusb20_device *pdev, uint16_t tr_index); 209184610Salfreduint16_t libusb20_tr_get_time_complete(struct libusb20_transfer *xfer); 210184610Salfreduint32_t libusb20_tr_get_actual_frames(struct libusb20_transfer *xfer); 211184610Salfreduint32_t libusb20_tr_get_actual_length(struct libusb20_transfer *xfer); 212184610Salfreduint32_t libusb20_tr_get_max_frames(struct libusb20_transfer *xfer); 213184610Salfreduint32_t libusb20_tr_get_max_packet_length(struct libusb20_transfer *xfer); 214184610Salfreduint32_t libusb20_tr_get_max_total_length(struct libusb20_transfer *xfer); 215184610Salfreduint8_t libusb20_tr_get_status(struct libusb20_transfer *xfer); 216184610Salfreduint8_t libusb20_tr_pending(struct libusb20_transfer *xfer); 217184610Salfredvoid libusb20_tr_callback_wrapper(struct libusb20_transfer *xfer); 218184610Salfredvoid libusb20_tr_clear_stall_sync(struct libusb20_transfer *xfer); 219184610Salfredvoid libusb20_tr_drain(struct libusb20_transfer *xfer); 220184610Salfredvoid libusb20_tr_set_buffer(struct libusb20_transfer *xfer, void *buffer, uint16_t fr_index); 221184610Salfredvoid libusb20_tr_set_callback(struct libusb20_transfer *xfer, libusb20_tr_callback_t *cb); 222184610Salfredvoid libusb20_tr_set_flags(struct libusb20_transfer *xfer, uint8_t flags); 223193313Sthompsauint32_t libusb20_tr_get_length(struct libusb20_transfer *xfer, uint16_t fr_index); 224184610Salfredvoid libusb20_tr_set_length(struct libusb20_transfer *xfer, uint32_t length, uint16_t fr_index); 225184610Salfredvoid libusb20_tr_set_priv_sc0(struct libusb20_transfer *xfer, void *sc0); 226184610Salfredvoid libusb20_tr_set_priv_sc1(struct libusb20_transfer *xfer, void *sc1); 227184610Salfredvoid libusb20_tr_set_timeout(struct libusb20_transfer *xfer, uint32_t timeout); 228184610Salfredvoid libusb20_tr_set_total_frames(struct libusb20_transfer *xfer, uint32_t nFrames); 229184610Salfredvoid libusb20_tr_setup_bulk(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout); 230184610Salfredvoid libusb20_tr_setup_control(struct libusb20_transfer *xfer, void *psetup, void *pbuf, uint32_t timeout); 231184610Salfredvoid libusb20_tr_setup_intr(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout); 232184610Salfredvoid libusb20_tr_setup_isoc(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint16_t fr_index); 233199575Sthompsauint8_t libusb20_tr_bulk_intr_sync(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t *pactlen, uint32_t timeout); 234184610Salfredvoid libusb20_tr_start(struct libusb20_transfer *xfer); 235184610Salfredvoid libusb20_tr_stop(struct libusb20_transfer *xfer); 236184610Salfredvoid libusb20_tr_submit(struct libusb20_transfer *xfer); 237184610Salfredvoid *libusb20_tr_get_priv_sc0(struct libusb20_transfer *xfer); 238184610Salfredvoid *libusb20_tr_get_priv_sc1(struct libusb20_transfer *xfer); 239184610Salfred 240184610Salfred 241184610Salfred/* USB device operations */ 242184610Salfred 243184610Salfredconst char *libusb20_dev_get_backend_name(struct libusb20_device *pdev); 244184610Salfredconst char *libusb20_dev_get_desc(struct libusb20_device *pdev); 245184610Salfredint libusb20_dev_close(struct libusb20_device *pdev); 246184610Salfredint libusb20_dev_detach_kernel_driver(struct libusb20_device *pdev, uint8_t iface_index); 247184610Salfredint libusb20_dev_set_config_index(struct libusb20_device *pdev, uint8_t configIndex); 248184610Salfredint libusb20_dev_get_debug(struct libusb20_device *pdev); 249184610Salfredint libusb20_dev_get_fd(struct libusb20_device *pdev); 250356398Shselaskyint libusb20_dev_get_stats(struct libusb20_device *pdev, struct libusb20_device_stats *pstat); 251184610Salfredint libusb20_dev_kernel_driver_active(struct libusb20_device *pdev, uint8_t iface_index); 252184610Salfredint libusb20_dev_open(struct libusb20_device *pdev, uint16_t transfer_max); 253184610Salfredint libusb20_dev_process(struct libusb20_device *pdev); 254184610Salfredint 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); 255184610Salfredint libusb20_dev_req_string_sync(struct libusb20_device *pdev, uint8_t index, uint16_t langid, void *ptr, uint16_t len); 256184610Salfredint libusb20_dev_req_string_simple_sync(struct libusb20_device *pdev, uint8_t index, void *ptr, uint16_t len); 257184610Salfredint libusb20_dev_reset(struct libusb20_device *pdev); 258203147Sthompsaint libusb20_dev_check_connected(struct libusb20_device *pdev); 259184610Salfredint libusb20_dev_set_power_mode(struct libusb20_device *pdev, uint8_t power_mode); 260184610Salfreduint8_t libusb20_dev_get_power_mode(struct libusb20_device *pdev); 261250201Shselaskyint libusb20_dev_get_port_path(struct libusb20_device *pdev, uint8_t *buf, uint8_t bufsize); 262246789Shselaskyuint16_t libusb20_dev_get_power_usage(struct libusb20_device *pdev); 263184610Salfredint libusb20_dev_set_alt_index(struct libusb20_device *pdev, uint8_t iface_index, uint8_t alt_index); 264192984Sthompsaint libusb20_dev_get_info(struct libusb20_device *pdev, struct usb_device_info *pinfo); 265188622Sthompsaint libusb20_dev_get_iface_desc(struct libusb20_device *pdev, uint8_t iface_index, char *buf, uint8_t len); 266184610Salfred 267184610Salfredstruct LIBUSB20_DEVICE_DESC_DECODED *libusb20_dev_get_device_desc(struct libusb20_device *pdev); 268184610Salfredstruct libusb20_config *libusb20_dev_alloc_config(struct libusb20_device *pdev, uint8_t config_index); 269184610Salfredstruct libusb20_device *libusb20_dev_alloc(void); 270184610Salfreduint8_t libusb20_dev_get_address(struct libusb20_device *pdev); 271223495Shselaskyuint8_t libusb20_dev_get_parent_address(struct libusb20_device *pdev); 272223495Shselaskyuint8_t libusb20_dev_get_parent_port(struct libusb20_device *pdev); 273184610Salfreduint8_t libusb20_dev_get_bus_number(struct libusb20_device *pdev); 274184610Salfreduint8_t libusb20_dev_get_mode(struct libusb20_device *pdev); 275184610Salfreduint8_t libusb20_dev_get_speed(struct libusb20_device *pdev); 276184610Salfreduint8_t libusb20_dev_get_config_index(struct libusb20_device *pdev); 277184610Salfredvoid libusb20_dev_free(struct libusb20_device *pdev); 278184610Salfredvoid libusb20_dev_set_debug(struct libusb20_device *pdev, int debug); 279184610Salfredvoid libusb20_dev_wait_process(struct libusb20_device *pdev, int timeout); 280184610Salfred 281184610Salfred/* USB global operations */ 282184610Salfred 283184610Salfredint libusb20_be_get_dev_quirk(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq); 284184610Salfredint libusb20_be_get_quirk_name(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq); 285184610Salfredint libusb20_be_add_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq); 286184610Salfredint libusb20_be_remove_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq); 287189939Sdelphijint libusb20_be_get_template(struct libusb20_backend *pbe, int *ptemp); 288189939Sdelphijint libusb20_be_set_template(struct libusb20_backend *pbe, int temp); 289184610Salfred 290184610Salfred/* USB backend operations */ 291184610Salfred 292184610Salfredstruct libusb20_backend *libusb20_be_alloc(const struct libusb20_backend_methods *methods); 293184610Salfredstruct libusb20_backend *libusb20_be_alloc_default(void); 294184610Salfredstruct libusb20_backend *libusb20_be_alloc_freebsd(void); 295184610Salfredstruct libusb20_backend *libusb20_be_alloc_linux(void); 296185087Salfredstruct libusb20_backend *libusb20_be_alloc_ugen20(void); 297184610Salfredstruct libusb20_device *libusb20_be_device_foreach(struct libusb20_backend *pbe, struct libusb20_device *pdev); 298184610Salfredvoid libusb20_be_dequeue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev); 299184610Salfredvoid libusb20_be_enqueue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev); 300184610Salfredvoid libusb20_be_free(struct libusb20_backend *pbe); 301184610Salfred 302225659Shselasky/* USB debugging */ 303225659Shselasky 304225659Shselaskyconst char *libusb20_strerror(int); 305225659Shselaskyconst char *libusb20_error_name(int); 306225659Shselasky 307184610Salfred#if 0 308184610Salfred{ /* style */ 309184610Salfred#endif 310184610Salfred#ifdef __cplusplus 311184610Salfred} 312184610Salfred 313184610Salfred#endif 314184610Salfred 315184610Salfred#endif /* _LIBUSB20_H_ */ 316