libusb20.h revision 184610
11541Srgrimes/* $FreeBSD: head/lib/libusb20/libusb20.h 184610 2008-11-04 02:31:03Z alfred $ */ 21541Srgrimes/*- 31541Srgrimes * Copyright (c) 2008 Hans Petter Selasky. All rights reserved. 41541Srgrimes * Copyright (c) 2007-2008 Daniel Drake. All rights reserved. 51541Srgrimes * Copyright (c) 2001 Johannes Erdfelt. All rights reserved. 61541Srgrimes * 71541Srgrimes * Redistribution and use in source and binary forms, with or without 81541Srgrimes * modification, are permitted provided that the following conditions 91541Srgrimes * are met: 101541Srgrimes * 1. Redistributions of source code must retain the above copyright 111541Srgrimes * notice, this list of conditions and the following disclaimer. 121541Srgrimes * 2. Redistributions in binary form must reproduce the above copyright 131541Srgrimes * notice, this list of conditions and the following disclaimer in the 141541Srgrimes * documentation and/or other materials provided with the distribution. 151541Srgrimes * 161541Srgrimes * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 171541Srgrimes * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 181541Srgrimes * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 191541Srgrimes * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 201541Srgrimes * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 211541Srgrimes * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 221541Srgrimes * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 231541Srgrimes * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 241541Srgrimes * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 251541Srgrimes * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 261541Srgrimes * SUCH DAMAGE. 271541Srgrimes */ 281541Srgrimes 291541Srgrimes#ifndef _LIBUSB20_H_ 301541Srgrimes#define _LIBUSB20_H_ 311541Srgrimes 321541Srgrimes#include <stdint.h> 3314501Shsu#include <time.h> 3450477Speter#include <string.h> 351541Srgrimes 361541Srgrimes#include <sys/time.h> 371541Srgrimes#include <sys/types.h> 381541Srgrimes#include <sys/endian.h> 391541Srgrimes 4034924Sbde#ifdef __cplusplus 4165495Struckmanextern "C" { 4234924Sbde#endif 431541Srgrimes#if 0 441541Srgrimes}; /* style */ 451541Srgrimes 461541Srgrimes#endif 471541Srgrimes 481541Srgrimes/** \ingroup misc 491541Srgrimes * Error codes. Most libusb20 functions return 0 on success or one of 501541Srgrimes * these codes on failure. 511541Srgrimes */ 521541Srgrimesenum libusb20_error { 531541Srgrimes /** Success (no error) */ 541541Srgrimes LIBUSB20_SUCCESS = 0, 551541Srgrimes 561541Srgrimes /** Input/output error */ 571541Srgrimes LIBUSB20_ERROR_IO = -1, 581541Srgrimes 591541Srgrimes /** Invalid parameter */ 601541Srgrimes LIBUSB20_ERROR_INVALID_PARAM = -2, 611541Srgrimes 621541Srgrimes /** Access denied (insufficient permissions) */ 631541Srgrimes LIBUSB20_ERROR_ACCESS = -3, 641541Srgrimes 651541Srgrimes /** No such device (it may have been disconnected) */ 661541Srgrimes LIBUSB20_ERROR_NO_DEVICE = -4, 671541Srgrimes 681541Srgrimes /** Entity not found */ 691541Srgrimes LIBUSB20_ERROR_NOT_FOUND = -5, 701541Srgrimes 711541Srgrimes /** Resource busy */ 721541Srgrimes LIBUSB20_ERROR_BUSY = -6, 731541Srgrimes 741541Srgrimes /** Operation timed out */ 751541Srgrimes LIBUSB20_ERROR_TIMEOUT = -7, 761541Srgrimes 771541Srgrimes /** Overflow */ 781541Srgrimes LIBUSB20_ERROR_OVERFLOW = -8, 791541Srgrimes 801541Srgrimes /** Pipe error */ 8136441Sphk LIBUSB20_ERROR_PIPE = -9, 821541Srgrimes 831541Srgrimes /** System call interrupted (perhaps due to signal) */ 8465495Struckman LIBUSB20_ERROR_INTERRUPTED = -10, 8565495Struckman 8665495Struckman /** Insufficient memory */ 8765495Struckman LIBUSB20_ERROR_NO_MEM = -11, 8865495Struckman 8965495Struckman /** Operation not supported or unimplemented on this platform */ 9065495Struckman LIBUSB20_ERROR_NOT_SUPPORTED = -12, 9165495Struckman 9265495Struckman /** Other error */ 9365495Struckman LIBUSB20_ERROR_OTHER = -99, 9465495Struckman}; 9555205Speter 9665495Struckman/** \ingroup asyncio 9734924Sbde * libusb20_tr_get_status() values */ 9834924Sbdeenum libusb20_transfer_status { 991541Srgrimes /** Transfer completed without error. Note that this does not 1001541Srgrimes * indicate that the entire amount of requested data was 1014470Sbde * transferred. */ 10214501Shsu LIBUSB20_TRANSFER_COMPLETED, 10365495Struckman 10465495Struckman /** Callback code to start transfer */ 10565495Struckman LIBUSB20_TRANSFER_START, 1064470Sbde 1071541Srgrimes /** Drain complete callback code */ 1081541Srgrimes LIBUSB20_TRANSFER_DRAINED, 1094470Sbde 1104470Sbde /** Transfer failed */ 11165495Struckman LIBUSB20_TRANSFER_ERROR, 11265495Struckman 11365495Struckman /** Transfer timed out */ 11465495Struckman LIBUSB20_TRANSFER_TIMED_OUT, 1151541Srgrimes 1164470Sbde /** Transfer was cancelled */ 1171541Srgrimes 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 */ 133enum 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 */ 150enum libusb20_device_mode { 151 LIBUSB20_MODE_HOST, /* default */ 152 LIBUSB20_MODE_DEVICE, 153}; 154 155/** \ingroup misc 156 * libusb20_dev_get_speed() values 157 */ 158enum { 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 */ 170enum { 171 LIBUSB20_POWER_OFF, 172 LIBUSB20_POWER_ON, 173 LIBUSB20_POWER_SAVE, 174 LIBUSB20_POWER_SUSPEND, 175 LIBUSB20_POWER_RESUME, 176}; 177 178struct libusb20_transfer; 179struct libusb20_backend; 180struct libusb20_backend_methods; 181struct libusb20_device; 182struct libusb20_device_methods; 183struct libusb20_config; 184struct LIBUSB20_CONTROL_SETUP_DECODED; 185struct LIBUSB20_DEVICE_DESC_DECODED; 186 187typedef void (libusb20_tr_callback_t)(struct libusb20_transfer *xfer); 188 189struct libusb20_quirk { 190 uint16_t vid; /* vendor ID */ 191 uint16_t pid; /* product ID */ 192 uint16_t bcdDeviceLow; /* low revision value, inclusive */ 193 uint16_t bcdDeviceHigh; /* high revision value, inclusive */ 194 uint16_t reserved[2]; /* for the future */ 195 /* quirk name, UQ_XXX, including terminating zero */ 196 char quirkname[64 - 12]; 197}; 198 199/* USB transfer operations */ 200 201int libusb20_tr_close(struct libusb20_transfer *xfer); 202int libusb20_tr_open(struct libusb20_transfer *xfer, uint32_t pMaxBufSize, uint32_t MaxFrameCount, uint8_t ep_no); 203struct libusb20_transfer *libusb20_tr_get_pointer(struct libusb20_device *pdev, uint16_t tr_index); 204uint16_t libusb20_tr_get_time_complete(struct libusb20_transfer *xfer); 205uint32_t libusb20_tr_get_actual_frames(struct libusb20_transfer *xfer); 206uint32_t libusb20_tr_get_actual_length(struct libusb20_transfer *xfer); 207uint32_t libusb20_tr_get_max_frames(struct libusb20_transfer *xfer); 208uint32_t libusb20_tr_get_max_packet_length(struct libusb20_transfer *xfer); 209uint32_t libusb20_tr_get_max_total_length(struct libusb20_transfer *xfer); 210uint8_t libusb20_tr_get_status(struct libusb20_transfer *xfer); 211uint8_t libusb20_tr_pending(struct libusb20_transfer *xfer); 212void libusb20_tr_callback_wrapper(struct libusb20_transfer *xfer); 213void libusb20_tr_clear_stall_sync(struct libusb20_transfer *xfer); 214void libusb20_tr_drain(struct libusb20_transfer *xfer); 215void libusb20_tr_set_buffer(struct libusb20_transfer *xfer, void *buffer, uint16_t fr_index); 216void libusb20_tr_set_callback(struct libusb20_transfer *xfer, libusb20_tr_callback_t *cb); 217void libusb20_tr_set_flags(struct libusb20_transfer *xfer, uint8_t flags); 218void libusb20_tr_set_length(struct libusb20_transfer *xfer, uint32_t length, uint16_t fr_index); 219void libusb20_tr_set_priv_sc0(struct libusb20_transfer *xfer, void *sc0); 220void libusb20_tr_set_priv_sc1(struct libusb20_transfer *xfer, void *sc1); 221void libusb20_tr_set_timeout(struct libusb20_transfer *xfer, uint32_t timeout); 222void libusb20_tr_set_total_frames(struct libusb20_transfer *xfer, uint32_t nFrames); 223void libusb20_tr_setup_bulk(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout); 224void libusb20_tr_setup_control(struct libusb20_transfer *xfer, void *psetup, void *pbuf, uint32_t timeout); 225void libusb20_tr_setup_intr(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout); 226void libusb20_tr_setup_isoc(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint16_t fr_index); 227void libusb20_tr_start(struct libusb20_transfer *xfer); 228void libusb20_tr_stop(struct libusb20_transfer *xfer); 229void libusb20_tr_submit(struct libusb20_transfer *xfer); 230void *libusb20_tr_get_priv_sc0(struct libusb20_transfer *xfer); 231void *libusb20_tr_get_priv_sc1(struct libusb20_transfer *xfer); 232 233 234/* USB device operations */ 235 236const char *libusb20_dev_get_backend_name(struct libusb20_device *pdev); 237const char *libusb20_dev_get_desc(struct libusb20_device *pdev); 238int libusb20_dev_claim_interface(struct libusb20_device *pdev, uint8_t iface_index); 239int libusb20_dev_close(struct libusb20_device *pdev); 240int libusb20_dev_detach_kernel_driver(struct libusb20_device *pdev, uint8_t iface_index); 241int libusb20_dev_set_config_index(struct libusb20_device *pdev, uint8_t configIndex); 242int libusb20_dev_get_debug(struct libusb20_device *pdev); 243int libusb20_dev_get_fd(struct libusb20_device *pdev); 244int libusb20_dev_kernel_driver_active(struct libusb20_device *pdev, uint8_t iface_index); 245int libusb20_dev_open(struct libusb20_device *pdev, uint16_t transfer_max); 246int libusb20_dev_process(struct libusb20_device *pdev); 247int libusb20_dev_release_interface(struct libusb20_device *pdev, uint8_t iface_index); 248int 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); 249int libusb20_dev_req_string_sync(struct libusb20_device *pdev, uint8_t index, uint16_t langid, void *ptr, uint16_t len); 250int libusb20_dev_req_string_simple_sync(struct libusb20_device *pdev, uint8_t index, void *ptr, uint16_t len); 251int libusb20_dev_reset(struct libusb20_device *pdev); 252int libusb20_dev_set_power_mode(struct libusb20_device *pdev, uint8_t power_mode); 253uint8_t libusb20_dev_get_power_mode(struct libusb20_device *pdev); 254int libusb20_dev_set_alt_index(struct libusb20_device *pdev, uint8_t iface_index, uint8_t alt_index); 255int libusb20_dev_set_owner(struct libusb20_device *pdev, uid_t user, gid_t group); 256int libusb20_dev_set_perm(struct libusb20_device *pdev, mode_t mode); 257int libusb20_dev_set_iface_owner(struct libusb20_device *pdev, uint8_t iface_index, uid_t user, gid_t group); 258int libusb20_dev_set_iface_perm(struct libusb20_device *pdev, uint8_t iface_index, mode_t mode); 259int libusb20_dev_get_owner(struct libusb20_device *pdev, uid_t *user, gid_t *group); 260int libusb20_dev_get_perm(struct libusb20_device *pdev, mode_t *mode); 261int libusb20_dev_get_iface_owner(struct libusb20_device *pdev, uint8_t iface_index, uid_t *user, gid_t *group); 262int libusb20_dev_get_iface_perm(struct libusb20_device *pdev, uint8_t iface_index, mode_t *mode); 263 264struct LIBUSB20_DEVICE_DESC_DECODED *libusb20_dev_get_device_desc(struct libusb20_device *pdev); 265struct libusb20_config *libusb20_dev_alloc_config(struct libusb20_device *pdev, uint8_t config_index); 266struct libusb20_device *libusb20_dev_alloc(void); 267uint8_t libusb20_dev_get_address(struct libusb20_device *pdev); 268uint8_t libusb20_dev_get_bus_number(struct libusb20_device *pdev); 269uint8_t libusb20_dev_get_mode(struct libusb20_device *pdev); 270uint8_t libusb20_dev_get_speed(struct libusb20_device *pdev); 271uint8_t libusb20_dev_get_config_index(struct libusb20_device *pdev); 272void libusb20_dev_free(struct libusb20_device *pdev); 273void libusb20_dev_set_debug(struct libusb20_device *pdev, int debug); 274void libusb20_dev_wait_process(struct libusb20_device *pdev, int timeout); 275 276/* USB bus operations */ 277 278int libusb20_bus_set_owner(struct libusb20_backend *pbe, uint8_t bus, uid_t user, gid_t group); 279int libusb20_bus_set_perm(struct libusb20_backend *pbe, uint8_t bus, mode_t mode); 280int libusb20_bus_get_owner(struct libusb20_backend *pbe, uint8_t bus, uid_t *user, gid_t *group); 281int libusb20_bus_get_perm(struct libusb20_backend *pbe, uint8_t bus, mode_t *mode); 282 283/* USB global operations */ 284 285int libusb20_be_get_dev_quirk(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq); 286int libusb20_be_get_quirk_name(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq); 287int libusb20_be_add_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq); 288int libusb20_be_remove_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq); 289int libusb20_be_set_owner(struct libusb20_backend *be, uid_t user, gid_t group); 290int libusb20_be_set_perm(struct libusb20_backend *be, mode_t mode); 291int libusb20_be_get_owner(struct libusb20_backend *be, uid_t *user, gid_t *group); 292int libusb20_be_get_perm(struct libusb20_backend *be, mode_t *mode); 293 294/* USB backend operations */ 295 296struct libusb20_backend *libusb20_be_alloc(const struct libusb20_backend_methods *methods); 297struct libusb20_backend *libusb20_be_alloc_default(void); 298struct libusb20_backend *libusb20_be_alloc_freebsd(void); 299struct libusb20_backend *libusb20_be_alloc_linux(void); 300struct libusb20_device *libusb20_be_device_foreach(struct libusb20_backend *pbe, struct libusb20_device *pdev); 301void libusb20_be_dequeue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev); 302void libusb20_be_enqueue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev); 303void libusb20_be_free(struct libusb20_backend *pbe); 304 305#if 0 306{ /* style */ 307#endif 308#ifdef __cplusplus 309} 310 311#endif 312 313#endif /* _LIBUSB20_H_ */ 314