libusb20.h revision 189110
1181834Sroberto/* $FreeBSD: head/lib/libusb20/libusb20.h 189110 2009-02-27 17:27:16Z thompsa $ */ 2181834Sroberto/*- 3181834Sroberto * Copyright (c) 2008 Hans Petter Selasky. All rights reserved. 4181834Sroberto * Copyright (c) 2007-2008 Daniel Drake. All rights reserved. 5181834Sroberto * Copyright (c) 2001 Johannes Erdfelt. All rights reserved. 6181834Sroberto * 7181834Sroberto * Redistribution and use in source and binary forms, with or without 8181834Sroberto * modification, are permitted provided that the following conditions 9181834Sroberto * are met: 10181834Sroberto * 1. Redistributions of source code must retain the above copyright 11181834Sroberto * notice, this list of conditions and the following disclaimer. 12181834Sroberto * 2. Redistributions in binary form must reproduce the above copyright 13181834Sroberto * notice, this list of conditions and the following disclaimer in the 14181834Sroberto * documentation and/or other materials provided with the distribution. 15181834Sroberto * 16181834Sroberto * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17285612Sdelphij * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18285612Sdelphij * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19285612Sdelphij * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20285612Sdelphij * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21285612Sdelphij * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22285612Sdelphij * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23285612Sdelphij * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24285612Sdelphij * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25285612Sdelphij * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26285612Sdelphij * SUCH DAMAGE. 27285612Sdelphij */ 28285612Sdelphij 29285612Sdelphij#ifndef _LIBUSB20_H_ 30285612Sdelphij#define _LIBUSB20_H_ 31181834Sroberto 32181834Sroberto#include <stdint.h> 33181834Sroberto#include <time.h> 34285612Sdelphij#include <string.h> 35181834Sroberto 36181834Sroberto#include <sys/time.h> 37285612Sdelphij#include <sys/types.h> 38330567Sgordon#include <sys/endian.h> 39285612Sdelphij 40285612Sdelphij#ifdef __cplusplus 41330567Sgordonextern "C" { 42285612Sdelphij#endif 43285612Sdelphij#if 0 44285612Sdelphij}; /* style */ 45181834Sroberto 46181834Sroberto#endif 47181834Sroberto 48285612Sdelphij/** \ingroup misc 49285612Sdelphij * Error codes. Most libusb20 functions return 0 on success or one of 50285612Sdelphij * these codes on failure. 51285612Sdelphij */ 52285612Sdelphijenum libusb20_error { 53285612Sdelphij /** Success (no error) */ 54285612Sdelphij LIBUSB20_SUCCESS = 0, 55285612Sdelphij 56285612Sdelphij /** Input/output error */ 57285612Sdelphij LIBUSB20_ERROR_IO = -1, 58330567Sgordon 59285612Sdelphij /** Invalid parameter */ 60285612Sdelphij LIBUSB20_ERROR_INVALID_PARAM = -2, 61285612Sdelphij 62285612Sdelphij /** Access denied (insufficient permissions) */ 63181834Sroberto LIBUSB20_ERROR_ACCESS = -3, 64181834Sroberto 65181834Sroberto /** No such device (it may have been disconnected) */ 66285612Sdelphij LIBUSB20_ERROR_NO_DEVICE = -4, 67181834Sroberto 68285612Sdelphij /** Entity not found */ 69285612Sdelphij LIBUSB20_ERROR_NOT_FOUND = -5, 70181834Sroberto 71330567Sgordon /** Resource busy */ 72330567Sgordon LIBUSB20_ERROR_BUSY = -6, 73330567Sgordon 74181834Sroberto /** Operation timed out */ 75181834Sroberto LIBUSB20_ERROR_TIMEOUT = -7, 76181834Sroberto 77181834Sroberto /** Overflow */ 78285612Sdelphij LIBUSB20_ERROR_OVERFLOW = -8, 79181834Sroberto 80285612Sdelphij /** Pipe error */ 81181834Sroberto LIBUSB20_ERROR_PIPE = -9, 82181834Sroberto 83285612Sdelphij /** System call interrupted (perhaps due to signal) */ 84285612Sdelphij LIBUSB20_ERROR_INTERRUPTED = -10, 85181834Sroberto 86181834Sroberto /** Insufficient memory */ 87181834Sroberto LIBUSB20_ERROR_NO_MEM = -11, 88181834Sroberto 89285612Sdelphij /** Operation not supported or unimplemented on this platform */ 90181834Sroberto LIBUSB20_ERROR_NOT_SUPPORTED = -12, 91285612Sdelphij 92181834Sroberto /** Other error */ 93181834Sroberto LIBUSB20_ERROR_OTHER = -99, 94285612Sdelphij}; 95181834Sroberto 96181834Sroberto/** \ingroup asyncio 97181834Sroberto * libusb20_tr_get_status() values */ 98181834Srobertoenum libusb20_transfer_status { 99285612Sdelphij /** Transfer completed without error. Note that this does not 100181834Sroberto * indicate that the entire amount of requested data was 101285612Sdelphij * transferred. */ 102181834Sroberto LIBUSB20_TRANSFER_COMPLETED, 103181834Sroberto 104285612Sdelphij /** Callback code to start transfer */ 105285612Sdelphij LIBUSB20_TRANSFER_START, 106181834Sroberto 107181834Sroberto /** Drain complete callback code */ 108181834Sroberto LIBUSB20_TRANSFER_DRAINED, 109181834Sroberto 110181834Sroberto /** Transfer failed */ 111285612Sdelphij LIBUSB20_TRANSFER_ERROR, 112285612Sdelphij 113285612Sdelphij /** Transfer timed out */ 114285612Sdelphij LIBUSB20_TRANSFER_TIMED_OUT, 115285612Sdelphij 116181834Sroberto /** Transfer was cancelled */ 117285612Sdelphij LIBUSB20_TRANSFER_CANCELLED, 118285612Sdelphij 119285612Sdelphij /** For bulk/interrupt endpoints: halt condition detected 120285612Sdelphij * (endpoint stalled). For control endpoints: control request 121330567Sgordon * not supported. */ 122330567Sgordon LIBUSB20_TRANSFER_STALL, 123330567Sgordon 124330567Sgordon /** Device was disconnected */ 125330567Sgordon LIBUSB20_TRANSFER_NO_DEVICE, 126181834Sroberto 127181834Sroberto /** Device sent more data than requested */ 128181834Sroberto LIBUSB20_TRANSFER_OVERFLOW, 129181834Sroberto}; 130285612Sdelphij 131285612Sdelphij/** \ingroup asyncio 132285612Sdelphij * libusb20_tr_set_flags() values */ 133285612Sdelphijenum libusb20_transfer_flags { 134285612Sdelphij /** Report a short frame as error */ 135285612Sdelphij LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK = 0x0001, 136285612Sdelphij 137285612Sdelphij /** Multiple short frames are not allowed */ 138285612Sdelphij LIBUSB20_TRANSFER_MULTI_SHORT_NOT_OK = 0x0002, 139285612Sdelphij 140285612Sdelphij /** All transmitted frames are short terminated */ 141285612Sdelphij LIBUSB20_TRANSFER_FORCE_SHORT = 0x0004, 142285612Sdelphij 143181834Sroberto /** Will do a clear-stall before xfer */ 144181834Sroberto LIBUSB20_TRANSFER_DO_CLEAR_STALL = 0x0008, 145181834Sroberto}; 146181834Sroberto 147285612Sdelphij/** \ingroup misc 148330567Sgordon * libusb20_dev_get_mode() values 149181834Sroberto */ 150285612Sdelphijenum libusb20_device_mode { 151181834Sroberto LIBUSB20_MODE_HOST, /* default */ 152181834Sroberto LIBUSB20_MODE_DEVICE, 153181834Sroberto}; 154181834Sroberto 155330567Sgordon/** \ingroup misc 156330567Sgordon * libusb20_dev_get_speed() values 157330567Sgordon */ 158330567Sgordonenum { 159330567Sgordon LIBUSB20_SPEED_UNKNOWN, /* default */ 160330567Sgordon LIBUSB20_SPEED_LOW, 161330567Sgordon LIBUSB20_SPEED_FULL, 162330567Sgordon LIBUSB20_SPEED_HIGH, 163330567Sgordon LIBUSB20_SPEED_VARIABLE, 164285612Sdelphij LIBUSB20_SPEED_SUPER, 165181834Sroberto}; 166285612Sdelphij 167181834Sroberto/** \ingroup misc 168181834Sroberto * libusb20_dev_set_power() values 169285612Sdelphij */ 170285612Sdelphijenum { 171181834Sroberto LIBUSB20_POWER_OFF, 172181834Sroberto LIBUSB20_POWER_ON, 173181834Sroberto LIBUSB20_POWER_SAVE, 174181834Sroberto LIBUSB20_POWER_SUSPEND, 175181834Sroberto LIBUSB20_POWER_RESUME, 176285612Sdelphij}; 177285612Sdelphij 178181834Srobertostruct usb2_device_info; 179181834Srobertostruct libusb20_transfer; 180285612Sdelphijstruct libusb20_backend; 181181834Srobertostruct libusb20_backend_methods; 182285612Sdelphijstruct libusb20_device; 183285612Sdelphijstruct libusb20_device_methods; 184285612Sdelphijstruct libusb20_config; 185285612Sdelphijstruct LIBUSB20_CONTROL_SETUP_DECODED; 186285612Sdelphijstruct LIBUSB20_DEVICE_DESC_DECODED; 187181834Sroberto 188181834Srobertotypedef void (libusb20_tr_callback_t)(struct libusb20_transfer *xfer); 189181834Sroberto 190181834Srobertostruct libusb20_quirk { 191181834Sroberto uint16_t vid; /* vendor ID */ 192285612Sdelphij uint16_t pid; /* product ID */ 193285612Sdelphij uint16_t bcdDeviceLow; /* low revision value, inclusive */ 194181834Sroberto uint16_t bcdDeviceHigh; /* high revision value, inclusive */ 195181834Sroberto uint16_t reserved[2]; /* for the future */ 196285612Sdelphij /* quirk name, UQ_XXX, including terminating zero */ 197181834Sroberto char quirkname[64 - 12]; 198285612Sdelphij}; 199285612Sdelphij 200285612Sdelphij/* USB transfer operations */ 201285612Sdelphij 202285612Sdelphijint libusb20_tr_close(struct libusb20_transfer *xfer); 203181834Srobertoint libusb20_tr_open(struct libusb20_transfer *xfer, uint32_t max_buf_size, uint32_t max_frame_count, uint8_t ep_no); 204181834Srobertostruct libusb20_transfer *libusb20_tr_get_pointer(struct libusb20_device *pdev, uint16_t tr_index); 205181834Srobertouint16_t libusb20_tr_get_time_complete(struct libusb20_transfer *xfer); 206181834Srobertouint32_t libusb20_tr_get_actual_frames(struct libusb20_transfer *xfer); 207285612Sdelphijuint32_t libusb20_tr_get_actual_length(struct libusb20_transfer *xfer); 208181834Srobertouint32_t libusb20_tr_get_max_frames(struct libusb20_transfer *xfer); 209181834Srobertouint32_t libusb20_tr_get_max_packet_length(struct libusb20_transfer *xfer); 210285612Sdelphijuint32_t libusb20_tr_get_max_total_length(struct libusb20_transfer *xfer); 211285612Sdelphijuint8_t libusb20_tr_get_status(struct libusb20_transfer *xfer); 212285612Sdelphijuint8_t libusb20_tr_pending(struct libusb20_transfer *xfer); 213181834Srobertovoid libusb20_tr_callback_wrapper(struct libusb20_transfer *xfer); 214285612Sdelphijvoid libusb20_tr_clear_stall_sync(struct libusb20_transfer *xfer); 215330567Sgordonvoid libusb20_tr_drain(struct libusb20_transfer *xfer); 216285612Sdelphijvoid libusb20_tr_set_buffer(struct libusb20_transfer *xfer, void *buffer, uint16_t fr_index); 217285612Sdelphijvoid libusb20_tr_set_callback(struct libusb20_transfer *xfer, libusb20_tr_callback_t *cb); 218330567Sgordonvoid libusb20_tr_set_flags(struct libusb20_transfer *xfer, uint8_t flags); 219330567Sgordonvoid libusb20_tr_set_length(struct libusb20_transfer *xfer, uint32_t length, uint16_t fr_index); 220330567Sgordonvoid libusb20_tr_set_priv_sc0(struct libusb20_transfer *xfer, void *sc0); 221285612Sdelphijvoid libusb20_tr_set_priv_sc1(struct libusb20_transfer *xfer, void *sc1); 222285612Sdelphijvoid libusb20_tr_set_timeout(struct libusb20_transfer *xfer, uint32_t timeout); 223285612Sdelphijvoid libusb20_tr_set_total_frames(struct libusb20_transfer *xfer, uint32_t nFrames); 224285612Sdelphijvoid libusb20_tr_setup_bulk(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout); 225181834Srobertovoid libusb20_tr_setup_control(struct libusb20_transfer *xfer, void *psetup, void *pbuf, uint32_t timeout); 226181834Srobertovoid libusb20_tr_setup_intr(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout); 227181834Srobertovoid libusb20_tr_setup_isoc(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint16_t fr_index); 228330567Sgordonvoid libusb20_tr_start(struct libusb20_transfer *xfer); 229330567Sgordonvoid libusb20_tr_stop(struct libusb20_transfer *xfer); 230330567Sgordonvoid libusb20_tr_submit(struct libusb20_transfer *xfer); 231330567Sgordonvoid *libusb20_tr_get_priv_sc0(struct libusb20_transfer *xfer); 232330567Sgordonvoid *libusb20_tr_get_priv_sc1(struct libusb20_transfer *xfer); 233330567Sgordon 234330567Sgordon 235330567Sgordon/* USB device operations */ 236330567Sgordon 237330567Sgordonconst char *libusb20_dev_get_backend_name(struct libusb20_device *pdev); 238330567Sgordonconst char *libusb20_dev_get_desc(struct libusb20_device *pdev); 239330567Sgordonint libusb20_dev_claim_interface(struct libusb20_device *pdev, uint8_t iface_index); 240330567Sgordonint libusb20_dev_close(struct libusb20_device *pdev); 241330567Sgordonint libusb20_dev_detach_kernel_driver(struct libusb20_device *pdev, uint8_t iface_index); 242285612Sdelphijint libusb20_dev_set_config_index(struct libusb20_device *pdev, uint8_t configIndex); 243181834Srobertoint libusb20_dev_get_debug(struct libusb20_device *pdev); 244285612Sdelphijint libusb20_dev_get_fd(struct libusb20_device *pdev); 245181834Srobertoint libusb20_dev_kernel_driver_active(struct libusb20_device *pdev, uint8_t iface_index); 246181834Srobertoint libusb20_dev_open(struct libusb20_device *pdev, uint16_t transfer_max); 247285612Sdelphijint libusb20_dev_process(struct libusb20_device *pdev); 248285612Sdelphijint libusb20_dev_release_interface(struct libusb20_device *pdev, uint8_t iface_index); 249181834Srobertoint 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); 250181834Srobertoint libusb20_dev_req_string_sync(struct libusb20_device *pdev, uint8_t index, uint16_t langid, void *ptr, uint16_t len); 251181834Srobertoint libusb20_dev_req_string_simple_sync(struct libusb20_device *pdev, uint8_t index, void *ptr, uint16_t len); 252181834Srobertoint libusb20_dev_reset(struct libusb20_device *pdev); 253285612Sdelphijint libusb20_dev_set_power_mode(struct libusb20_device *pdev, uint8_t power_mode); 254181834Srobertouint8_t libusb20_dev_get_power_mode(struct libusb20_device *pdev); 255181834Srobertoint libusb20_dev_set_alt_index(struct libusb20_device *pdev, uint8_t iface_index, uint8_t alt_index); 256181834Srobertoint libusb20_dev_get_info(struct libusb20_device *pdev, struct usb2_device_info *pinfo); 257285612Sdelphijint libusb20_dev_get_iface_desc(struct libusb20_device *pdev, uint8_t iface_index, char *buf, uint8_t len); 258181834Sroberto 259181834Srobertostruct LIBUSB20_DEVICE_DESC_DECODED *libusb20_dev_get_device_desc(struct libusb20_device *pdev); 260285612Sdelphijstruct libusb20_config *libusb20_dev_alloc_config(struct libusb20_device *pdev, uint8_t config_index); 261285612Sdelphijstruct libusb20_device *libusb20_dev_alloc(void); 262181834Srobertouint8_t libusb20_dev_get_address(struct libusb20_device *pdev); 263181834Srobertouint8_t libusb20_dev_get_bus_number(struct libusb20_device *pdev); 264181834Srobertouint8_t libusb20_dev_get_mode(struct libusb20_device *pdev); 265181834Srobertouint8_t libusb20_dev_get_speed(struct libusb20_device *pdev); 266285612Sdelphijuint8_t libusb20_dev_get_config_index(struct libusb20_device *pdev); 267181834Srobertovoid libusb20_dev_free(struct libusb20_device *pdev); 268181834Srobertovoid libusb20_dev_set_debug(struct libusb20_device *pdev, int debug); 269181834Srobertovoid libusb20_dev_wait_process(struct libusb20_device *pdev, int timeout); 270285612Sdelphij 271181834Sroberto/* USB global operations */ 272181834Sroberto 273181834Srobertoint libusb20_be_get_dev_quirk(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq); 274285612Sdelphijint libusb20_be_get_quirk_name(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq); 275285612Sdelphijint libusb20_be_add_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq); 276285612Sdelphijint libusb20_be_remove_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq); 277285612Sdelphij 278285612Sdelphij/* USB backend operations */ 279285612Sdelphij 280285612Sdelphijstruct libusb20_backend *libusb20_be_alloc(const struct libusb20_backend_methods *methods); 281285612Sdelphijstruct libusb20_backend *libusb20_be_alloc_default(void); 282285612Sdelphijstruct libusb20_backend *libusb20_be_alloc_freebsd(void); 283285612Sdelphijstruct libusb20_backend *libusb20_be_alloc_linux(void); 284330567Sgordonstruct libusb20_backend *libusb20_be_alloc_ugen20(void); 285330567Sgordonstruct libusb20_device *libusb20_be_device_foreach(struct libusb20_backend *pbe, struct libusb20_device *pdev); 286330567Sgordonvoid libusb20_be_dequeue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev); 287330567Sgordonvoid libusb20_be_enqueue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev); 288285612Sdelphijvoid libusb20_be_free(struct libusb20_backend *pbe); 289330567Sgordon 290285612Sdelphij#if 0 291285612Sdelphij{ /* style */ 292330567Sgordon#endif 293330567Sgordon#ifdef __cplusplus 294330567Sgordon} 295330567Sgordon 296285612Sdelphij#endif 297285612Sdelphij 298285612Sdelphij#endif /* _LIBUSB20_H_ */ 299330567Sgordon