libusb20.h revision 285830
133965Sjdp/* $FreeBSD: releng/10.2/lib/libusb/libusb20.h 250201 2013-05-03 07:44:58Z hselasky $ */ 233965Sjdp/*- 333965Sjdp * Copyright (c) 2008-2009 Hans Petter Selasky. All rights reserved. 433965Sjdp * Copyright (c) 2007-2008 Daniel Drake. All rights reserved. 533965Sjdp * Copyright (c) 2001 Johannes Erdfelt. All rights reserved. 633965Sjdp * 789857Sobrien * Redistribution and use in source and binary forms, with or without 877298Sobrien * modification, are permitted provided that the following conditions 933965Sjdp * are met: 1033965Sjdp * 1. Redistributions of source code must retain the above copyright 1133965Sjdp * notice, this list of conditions and the following disclaimer. 1233965Sjdp * 2. Redistributions in binary form must reproduce the above copyright 1333965Sjdp * notice, this list of conditions and the following disclaimer in the 1433965Sjdp * documentation and/or other materials provided with the distribution. 1533965Sjdp * 1633965Sjdp * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 1733965Sjdp * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 1833965Sjdp * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 1933965Sjdp * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 2033965Sjdp * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 2133965Sjdp * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 2233965Sjdp * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 2333965Sjdp * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 2433965Sjdp * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 2533965Sjdp * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 2633965Sjdp * SUCH DAMAGE. 2733965Sjdp */ 2833965Sjdp 2933965Sjdp#ifndef _LIBUSB20_H_ 3033965Sjdp#define _LIBUSB20_H_ 3133965Sjdp 3233965Sjdp#ifndef LIBUSB_GLOBAL_INCLUDE_FILE 3333965Sjdp#include <stdint.h> 3433965Sjdp#endif 3533965Sjdp 3633965Sjdp#ifdef __cplusplus 3777298Sobrienextern "C" { 3877298Sobrien#endif 3977298Sobrien#if 0 4077298Sobrien}; /* style */ 4177298Sobrien 4233965Sjdp#endif 4333965Sjdp 4433965Sjdp/** \ingroup misc 4589857Sobrien * Error codes. Most libusb20 functions return 0 on success or one of 4689857Sobrien * these codes on failure. 4789857Sobrien */ 4889857Sobrienenum libusb20_error { 4989857Sobrien /** Success (no error) */ 5089857Sobrien LIBUSB20_SUCCESS = 0, 5189857Sobrien 5289857Sobrien /** Input/output error */ 5389857Sobrien LIBUSB20_ERROR_IO = -1, 5489857Sobrien 5589857Sobrien /** Invalid parameter */ 5633965Sjdp LIBUSB20_ERROR_INVALID_PARAM = -2, 5733965Sjdp 5833965Sjdp /** Access denied (insufficient permissions) */ 5933965Sjdp LIBUSB20_ERROR_ACCESS = -3, 6033965Sjdp 6133965Sjdp /** No such device (it may have been disconnected) */ 6233965Sjdp LIBUSB20_ERROR_NO_DEVICE = -4, 6333965Sjdp 6489857Sobrien /** Entity not found */ 6589857Sobrien LIBUSB20_ERROR_NOT_FOUND = -5, 6689857Sobrien 6789857Sobrien /** Resource busy */ 6889857Sobrien LIBUSB20_ERROR_BUSY = -6, 6989857Sobrien 7033965Sjdp /** Operation timed out */ 7133965Sjdp LIBUSB20_ERROR_TIMEOUT = -7, 7233965Sjdp 7333965Sjdp /** Overflow */ 7433965Sjdp LIBUSB20_ERROR_OVERFLOW = -8, 7533965Sjdp 7633965Sjdp /** Pipe error */ 7733965Sjdp LIBUSB20_ERROR_PIPE = -9, 7833965Sjdp 7933965Sjdp /** System call interrupted (perhaps due to signal) */ 8060484Sobrien LIBUSB20_ERROR_INTERRUPTED = -10, 8133965Sjdp 8233965Sjdp /** Insufficient memory */ 8333965Sjdp LIBUSB20_ERROR_NO_MEM = -11, 8433965Sjdp 8533965Sjdp /** Operation not supported or unimplemented on this platform */ 8633965Sjdp LIBUSB20_ERROR_NOT_SUPPORTED = -12, 8733965Sjdp 8833965Sjdp /** Other error */ 8933965Sjdp LIBUSB20_ERROR_OTHER = -99, 9033965Sjdp}; 9133965Sjdp 9233965Sjdp/** \ingroup asyncio 9333965Sjdp * libusb20_tr_get_status() values */ 9433965Sjdpenum libusb20_transfer_status { 9533965Sjdp /** Transfer completed without error. Note that this does not 9633965Sjdp * indicate that the entire amount of requested data was 9733965Sjdp * transferred. */ 9833965Sjdp LIBUSB20_TRANSFER_COMPLETED, 9933965Sjdp 10033965Sjdp /** Callback code to start transfer */ 10133965Sjdp LIBUSB20_TRANSFER_START, 10233965Sjdp 10333965Sjdp /** Drain complete callback code */ 10433965Sjdp LIBUSB20_TRANSFER_DRAINED, 10533965Sjdp 10633965Sjdp /** Transfer failed */ 10733965Sjdp LIBUSB20_TRANSFER_ERROR, 10833965Sjdp 10933965Sjdp /** Transfer timed out */ 11033965Sjdp LIBUSB20_TRANSFER_TIMED_OUT, 11133965Sjdp 11233965Sjdp /** Transfer was cancelled */ 11333965Sjdp LIBUSB20_TRANSFER_CANCELLED, 11433965Sjdp 11533965Sjdp /** For bulk/interrupt endpoints: halt condition detected 11633965Sjdp * (endpoint stalled). For control endpoints: control request 11733965Sjdp * not supported. */ 11833965Sjdp LIBUSB20_TRANSFER_STALL, 11933965Sjdp 12089857Sobrien /** Device was disconnected */ 12133965Sjdp LIBUSB20_TRANSFER_NO_DEVICE, 12233965Sjdp 12333965Sjdp /** Device sent more data than requested */ 12433965Sjdp LIBUSB20_TRANSFER_OVERFLOW, 12533965Sjdp}; 12689857Sobrien 12789857Sobrien/** \ingroup asyncio 12889857Sobrien * libusb20_tr_set_flags() values */ 12989857Sobrienenum libusb20_transfer_flags { 13089857Sobrien /** Report a short frame as error */ 13189857Sobrien LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK = 0x0001, 13289857Sobrien 13389857Sobrien /** Multiple short frames are not allowed */ 13489857Sobrien LIBUSB20_TRANSFER_MULTI_SHORT_NOT_OK = 0x0002, 13589857Sobrien 13633965Sjdp /** All transmitted frames are short terminated */ 13760484Sobrien LIBUSB20_TRANSFER_FORCE_SHORT = 0x0004, 13889857Sobrien 13989857Sobrien /** Will do a clear-stall before xfer */ 14089857Sobrien LIBUSB20_TRANSFER_DO_CLEAR_STALL = 0x0008, 14189857Sobrien}; 14289857Sobrien 14389857Sobrien/** \ingroup misc 14489857Sobrien * libusb20_dev_get_mode() values 14589857Sobrien */ 14689857Sobrienenum libusb20_device_mode { 147104834Sobrien LIBUSB20_MODE_HOST, /* default */ 148104834Sobrien LIBUSB20_MODE_DEVICE, 14933965Sjdp}; 15033965Sjdp 151/** \ingroup misc 152 * libusb20_dev_get_speed() values 153 */ 154enum { 155 LIBUSB20_SPEED_UNKNOWN, /* default */ 156 LIBUSB20_SPEED_LOW, 157 LIBUSB20_SPEED_FULL, 158 LIBUSB20_SPEED_HIGH, 159 LIBUSB20_SPEED_VARIABLE, 160 LIBUSB20_SPEED_SUPER, 161}; 162 163/** \ingroup misc 164 * libusb20_dev_set_power() values 165 */ 166enum { 167 LIBUSB20_POWER_OFF, 168 LIBUSB20_POWER_ON, 169 LIBUSB20_POWER_SAVE, 170 LIBUSB20_POWER_SUSPEND, 171 LIBUSB20_POWER_RESUME, 172}; 173 174struct usb_device_info; 175struct libusb20_transfer; 176struct libusb20_backend; 177struct libusb20_backend_methods; 178struct libusb20_device; 179struct libusb20_device_methods; 180struct libusb20_config; 181struct LIBUSB20_CONTROL_SETUP_DECODED; 182struct LIBUSB20_DEVICE_DESC_DECODED; 183 184typedef void (libusb20_tr_callback_t)(struct libusb20_transfer *xfer); 185 186struct libusb20_quirk { 187 uint16_t vid; /* vendor ID */ 188 uint16_t pid; /* product ID */ 189 uint16_t bcdDeviceLow; /* low revision value, inclusive */ 190 uint16_t bcdDeviceHigh; /* high revision value, inclusive */ 191 uint16_t reserved[2]; /* for the future */ 192 /* quirk name, UQ_XXX, including terminating zero */ 193 char quirkname[64 - 12]; 194}; 195 196#define LIBUSB20_MAX_FRAME_PRE_SCALE (1U << 31) 197 198/* USB transfer operations */ 199int libusb20_tr_close(struct libusb20_transfer *xfer); 200int libusb20_tr_open(struct libusb20_transfer *xfer, uint32_t max_buf_size, uint32_t max_frame_count, uint8_t ep_no); 201int 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); 202struct libusb20_transfer *libusb20_tr_get_pointer(struct libusb20_device *pdev, uint16_t tr_index); 203uint16_t libusb20_tr_get_time_complete(struct libusb20_transfer *xfer); 204uint32_t libusb20_tr_get_actual_frames(struct libusb20_transfer *xfer); 205uint32_t libusb20_tr_get_actual_length(struct libusb20_transfer *xfer); 206uint32_t libusb20_tr_get_max_frames(struct libusb20_transfer *xfer); 207uint32_t libusb20_tr_get_max_packet_length(struct libusb20_transfer *xfer); 208uint32_t libusb20_tr_get_max_total_length(struct libusb20_transfer *xfer); 209uint8_t libusb20_tr_get_status(struct libusb20_transfer *xfer); 210uint8_t libusb20_tr_pending(struct libusb20_transfer *xfer); 211void libusb20_tr_callback_wrapper(struct libusb20_transfer *xfer); 212void libusb20_tr_clear_stall_sync(struct libusb20_transfer *xfer); 213void libusb20_tr_drain(struct libusb20_transfer *xfer); 214void libusb20_tr_set_buffer(struct libusb20_transfer *xfer, void *buffer, uint16_t fr_index); 215void libusb20_tr_set_callback(struct libusb20_transfer *xfer, libusb20_tr_callback_t *cb); 216void libusb20_tr_set_flags(struct libusb20_transfer *xfer, uint8_t flags); 217uint32_t libusb20_tr_get_length(struct libusb20_transfer *xfer, uint16_t fr_index); 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); 227uint8_t libusb20_tr_bulk_intr_sync(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t *pactlen, uint32_t timeout); 228void libusb20_tr_start(struct libusb20_transfer *xfer); 229void libusb20_tr_stop(struct libusb20_transfer *xfer); 230void libusb20_tr_submit(struct libusb20_transfer *xfer); 231void *libusb20_tr_get_priv_sc0(struct libusb20_transfer *xfer); 232void *libusb20_tr_get_priv_sc1(struct libusb20_transfer *xfer); 233 234 235/* USB device operations */ 236 237const char *libusb20_dev_get_backend_name(struct libusb20_device *pdev); 238const char *libusb20_dev_get_desc(struct libusb20_device *pdev); 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_request_sync(struct libusb20_device *pdev, struct LIBUSB20_CONTROL_SETUP_DECODED *setup, void *data, uint16_t *pactlen, uint32_t timeout, uint8_t flags); 248int libusb20_dev_req_string_sync(struct libusb20_device *pdev, uint8_t index, uint16_t langid, void *ptr, uint16_t len); 249int libusb20_dev_req_string_simple_sync(struct libusb20_device *pdev, uint8_t index, void *ptr, uint16_t len); 250int libusb20_dev_reset(struct libusb20_device *pdev); 251int libusb20_dev_check_connected(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_get_port_path(struct libusb20_device *pdev, uint8_t *buf, uint8_t bufsize); 255uint16_t libusb20_dev_get_power_usage(struct libusb20_device *pdev); 256int libusb20_dev_set_alt_index(struct libusb20_device *pdev, uint8_t iface_index, uint8_t alt_index); 257int libusb20_dev_get_info(struct libusb20_device *pdev, struct usb_device_info *pinfo); 258int libusb20_dev_get_iface_desc(struct libusb20_device *pdev, uint8_t iface_index, char *buf, uint8_t len); 259 260struct LIBUSB20_DEVICE_DESC_DECODED *libusb20_dev_get_device_desc(struct libusb20_device *pdev); 261struct libusb20_config *libusb20_dev_alloc_config(struct libusb20_device *pdev, uint8_t config_index); 262struct libusb20_device *libusb20_dev_alloc(void); 263uint8_t libusb20_dev_get_address(struct libusb20_device *pdev); 264uint8_t libusb20_dev_get_parent_address(struct libusb20_device *pdev); 265uint8_t libusb20_dev_get_parent_port(struct libusb20_device *pdev); 266uint8_t libusb20_dev_get_bus_number(struct libusb20_device *pdev); 267uint8_t libusb20_dev_get_mode(struct libusb20_device *pdev); 268uint8_t libusb20_dev_get_speed(struct libusb20_device *pdev); 269uint8_t libusb20_dev_get_config_index(struct libusb20_device *pdev); 270void libusb20_dev_free(struct libusb20_device *pdev); 271void libusb20_dev_set_debug(struct libusb20_device *pdev, int debug); 272void libusb20_dev_wait_process(struct libusb20_device *pdev, int timeout); 273 274/* USB global operations */ 275 276int libusb20_be_get_dev_quirk(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq); 277int libusb20_be_get_quirk_name(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq); 278int libusb20_be_add_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq); 279int libusb20_be_remove_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq); 280int libusb20_be_get_template(struct libusb20_backend *pbe, int *ptemp); 281int libusb20_be_set_template(struct libusb20_backend *pbe, int temp); 282 283/* USB backend operations */ 284 285struct libusb20_backend *libusb20_be_alloc(const struct libusb20_backend_methods *methods); 286struct libusb20_backend *libusb20_be_alloc_default(void); 287struct libusb20_backend *libusb20_be_alloc_freebsd(void); 288struct libusb20_backend *libusb20_be_alloc_linux(void); 289struct libusb20_backend *libusb20_be_alloc_ugen20(void); 290struct libusb20_device *libusb20_be_device_foreach(struct libusb20_backend *pbe, struct libusb20_device *pdev); 291void libusb20_be_dequeue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev); 292void libusb20_be_enqueue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev); 293void libusb20_be_free(struct libusb20_backend *pbe); 294 295/* USB debugging */ 296 297const char *libusb20_strerror(int); 298const char *libusb20_error_name(int); 299 300#if 0 301{ /* style */ 302#endif 303#ifdef __cplusplus 304} 305 306#endif 307 308#endif /* _LIBUSB20_H_ */ 309