3 * SPDX-License-Identifier: BSD-2-Clause
5 * Copyright (c) 2008-2009 Hans Petter Selasky. All rights reserved.
6 * Copyright (c) 2007-2008 Daniel Drake. All rights reserved.
7 * Copyright (c) 2001 Johannes Erdfelt. All rights reserved.
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions
12 * 1. Redistributions of source code must retain the above copyright
13 * notice, this list of conditions and the following disclaimer.
14 * 2. Redistributions in binary form must reproduce the above copyright
15 * notice, this list of conditions and the following disclaimer in the
16 * documentation and/or other materials provided with the distribution.
18 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
22 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 #ifndef LIBUSB_GLOBAL_INCLUDE_FILE
47 * Error codes. Most libusb20 functions return 0 on success or one of
48 * these codes on failure.
51 /** Success (no error) */
54 /** Input/output error */
55 LIBUSB20_ERROR_IO = -1,
57 /** Invalid parameter */
58 LIBUSB20_ERROR_INVALID_PARAM = -2,
60 /** Access denied (insufficient permissions) */
61 LIBUSB20_ERROR_ACCESS = -3,
63 /** No such device (it may have been disconnected) */
64 LIBUSB20_ERROR_NO_DEVICE = -4,
66 /** Entity not found */
67 LIBUSB20_ERROR_NOT_FOUND = -5,
70 LIBUSB20_ERROR_BUSY = -6,
72 /** Operation timed out */
73 LIBUSB20_ERROR_TIMEOUT = -7,
76 LIBUSB20_ERROR_OVERFLOW = -8,
79 LIBUSB20_ERROR_PIPE = -9,
81 /** System call interrupted (perhaps due to signal) */
82 LIBUSB20_ERROR_INTERRUPTED = -10,
84 /** Insufficient memory */
85 LIBUSB20_ERROR_NO_MEM = -11,
87 /** Operation not supported or unimplemented on this platform */
88 LIBUSB20_ERROR_NOT_SUPPORTED = -12,
91 LIBUSB20_ERROR_OTHER = -99,
95 * libusb20_tr_get_status() values */
96 enum libusb20_transfer_status {
97 /** Transfer completed without error. Note that this does not
98 * indicate that the entire amount of requested data was
100 LIBUSB20_TRANSFER_COMPLETED,
102 /** Callback code to start transfer */
103 LIBUSB20_TRANSFER_START,
105 /** Drain complete callback code */
106 LIBUSB20_TRANSFER_DRAINED,
108 /** Transfer failed */
109 LIBUSB20_TRANSFER_ERROR,
111 /** Transfer timed out */
112 LIBUSB20_TRANSFER_TIMED_OUT,
114 /** Transfer was cancelled */
115 LIBUSB20_TRANSFER_CANCELLED,
117 /** For bulk/interrupt endpoints: halt condition detected
118 * (endpoint stalled). For control endpoints: control request
120 LIBUSB20_TRANSFER_STALL,
122 /** Device was disconnected */
123 LIBUSB20_TRANSFER_NO_DEVICE,
125 /** Device sent more data than requested */
126 LIBUSB20_TRANSFER_OVERFLOW,
130 * libusb20_tr_set_flags() values */
131 enum libusb20_transfer_flags {
132 /** Report a short frame as error */
133 LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK = 0x0001,
135 /** Multiple short frames are not allowed */
136 LIBUSB20_TRANSFER_MULTI_SHORT_NOT_OK = 0x0002,
138 /** All transmitted frames are short terminated */
139 LIBUSB20_TRANSFER_FORCE_SHORT = 0x0004,
141 /** Will do a clear-stall before xfer */
142 LIBUSB20_TRANSFER_DO_CLEAR_STALL = 0x0008,
146 * libusb20_dev_get_mode() values
148 enum libusb20_device_mode {
149 LIBUSB20_MODE_HOST, /* default */
150 LIBUSB20_MODE_DEVICE,
154 * libusb20_dev_get_speed() values
157 LIBUSB20_SPEED_UNKNOWN, /* default */
161 LIBUSB20_SPEED_VARIABLE,
162 LIBUSB20_SPEED_SUPER,
166 * libusb20_dev_set_power() values
172 LIBUSB20_POWER_SUSPEND,
173 LIBUSB20_POWER_RESUME,
176 struct usb_device_info;
177 struct libusb20_transfer;
178 struct libusb20_backend;
179 struct libusb20_backend_methods;
180 struct libusb20_device;
181 struct libusb20_device_methods;
182 struct libusb20_config;
183 struct LIBUSB20_CONTROL_SETUP_DECODED;
184 struct LIBUSB20_DEVICE_DESC_DECODED;
186 typedef void (libusb20_tr_callback_t)(struct libusb20_transfer *xfer);
188 struct libusb20_quirk {
189 uint16_t vid; /* vendor ID */
190 uint16_t pid; /* product ID */
191 uint16_t bcdDeviceLow; /* low revision value, inclusive */
192 uint16_t bcdDeviceHigh; /* high revision value, inclusive */
193 uint16_t reserved[2]; /* for the future */
194 /* quirk name, UQ_XXX, including terminating zero */
195 char quirkname[64 - 12];
198 struct libusb20_device_stats {
199 uint64_t xfer_ok[4]; /* sorted by USB transfer type, UE_XXX */
200 uint64_t xfer_fail[4]; /* sorted by USB transfer type, UE_XXX */
201 uint64_t xfer_reserved[24]; /* reserved */
204 #define LIBUSB20_MAX_FRAME_PRE_SCALE (1U << 31)
206 /* USB transfer operations */
207 int libusb20_tr_close(struct libusb20_transfer *xfer);
208 int libusb20_tr_open(struct libusb20_transfer *xfer, uint32_t max_buf_size, uint32_t max_frame_count, uint8_t ep_no);
209 int 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);
210 struct libusb20_transfer *libusb20_tr_get_pointer(struct libusb20_device *pdev, uint16_t tr_index);
211 uint16_t libusb20_tr_get_time_complete(struct libusb20_transfer *xfer);
212 uint32_t libusb20_tr_get_actual_frames(struct libusb20_transfer *xfer);
213 uint32_t libusb20_tr_get_actual_length(struct libusb20_transfer *xfer);
214 uint32_t libusb20_tr_get_max_frames(struct libusb20_transfer *xfer);
215 uint32_t libusb20_tr_get_max_packet_length(struct libusb20_transfer *xfer);
216 uint32_t libusb20_tr_get_max_total_length(struct libusb20_transfer *xfer);
217 uint8_t libusb20_tr_get_status(struct libusb20_transfer *xfer);
218 uint8_t libusb20_tr_pending(struct libusb20_transfer *xfer);
219 void libusb20_tr_callback_wrapper(struct libusb20_transfer *xfer);
220 void libusb20_tr_clear_stall_sync(struct libusb20_transfer *xfer);
221 void libusb20_tr_drain(struct libusb20_transfer *xfer);
222 void libusb20_tr_set_buffer(struct libusb20_transfer *xfer, void *buffer, uint16_t fr_index);
223 void libusb20_tr_set_callback(struct libusb20_transfer *xfer, libusb20_tr_callback_t *cb);
224 void libusb20_tr_set_flags(struct libusb20_transfer *xfer, uint8_t flags);
225 uint32_t libusb20_tr_get_length(struct libusb20_transfer *xfer, uint16_t fr_index);
226 void libusb20_tr_set_length(struct libusb20_transfer *xfer, uint32_t length, uint16_t fr_index);
227 void libusb20_tr_set_priv_sc0(struct libusb20_transfer *xfer, void *sc0);
228 void libusb20_tr_set_priv_sc1(struct libusb20_transfer *xfer, void *sc1);
229 void libusb20_tr_set_timeout(struct libusb20_transfer *xfer, uint32_t timeout);
230 void libusb20_tr_set_total_frames(struct libusb20_transfer *xfer, uint32_t nFrames);
231 void libusb20_tr_setup_bulk(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout);
232 void libusb20_tr_setup_control(struct libusb20_transfer *xfer, void *psetup, void *pbuf, uint32_t timeout);
233 void libusb20_tr_setup_intr(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout);
234 void libusb20_tr_setup_isoc(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint16_t fr_index);
235 uint8_t libusb20_tr_bulk_intr_sync(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t *pactlen, uint32_t timeout);
236 void libusb20_tr_start(struct libusb20_transfer *xfer);
237 void libusb20_tr_stop(struct libusb20_transfer *xfer);
238 void libusb20_tr_submit(struct libusb20_transfer *xfer);
239 void *libusb20_tr_get_priv_sc0(struct libusb20_transfer *xfer);
240 void *libusb20_tr_get_priv_sc1(struct libusb20_transfer *xfer);
243 /* USB device operations */
245 const char *libusb20_dev_get_backend_name(struct libusb20_device *pdev);
246 const char *libusb20_dev_get_desc(struct libusb20_device *pdev);
247 int libusb20_dev_close(struct libusb20_device *pdev);
248 int libusb20_dev_detach_kernel_driver(struct libusb20_device *pdev, uint8_t iface_index);
249 int libusb20_dev_set_config_index(struct libusb20_device *pdev, uint8_t configIndex);
250 int libusb20_dev_get_debug(struct libusb20_device *pdev);
251 int libusb20_dev_get_fd(struct libusb20_device *pdev);
252 int libusb20_dev_get_stats(struct libusb20_device *pdev, struct libusb20_device_stats *pstat);
253 int libusb20_dev_kernel_driver_active(struct libusb20_device *pdev, uint8_t iface_index);
254 int libusb20_dev_open(struct libusb20_device *pdev, uint16_t transfer_max);
255 int libusb20_dev_process(struct libusb20_device *pdev);
256 int 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);
257 int libusb20_dev_req_string_sync(struct libusb20_device *pdev, uint8_t index, uint16_t langid, void *ptr, uint16_t len);
258 int libusb20_dev_req_string_simple_sync(struct libusb20_device *pdev, uint8_t index, void *ptr, uint16_t len);
259 int libusb20_dev_reset(struct libusb20_device *pdev);
260 int libusb20_dev_check_connected(struct libusb20_device *pdev);
261 int libusb20_dev_set_power_mode(struct libusb20_device *pdev, uint8_t power_mode);
262 uint8_t libusb20_dev_get_power_mode(struct libusb20_device *pdev);
263 int libusb20_dev_get_port_path(struct libusb20_device *pdev, uint8_t *buf, uint8_t bufsize);
264 uint16_t libusb20_dev_get_power_usage(struct libusb20_device *pdev);
265 int libusb20_dev_set_alt_index(struct libusb20_device *pdev, uint8_t iface_index, uint8_t alt_index);
266 int libusb20_dev_get_info(struct libusb20_device *pdev, struct usb_device_info *pinfo);
267 int libusb20_dev_get_iface_desc(struct libusb20_device *pdev, uint8_t iface_index, char *buf, uint8_t len);
269 struct LIBUSB20_DEVICE_DESC_DECODED *libusb20_dev_get_device_desc(struct libusb20_device *pdev);
270 struct libusb20_config *libusb20_dev_alloc_config(struct libusb20_device *pdev, uint8_t config_index);
271 struct libusb20_device *libusb20_dev_alloc(void);
272 uint8_t libusb20_dev_get_address(struct libusb20_device *pdev);
273 uint8_t libusb20_dev_get_parent_address(struct libusb20_device *pdev);
274 uint8_t libusb20_dev_get_parent_port(struct libusb20_device *pdev);
275 uint8_t libusb20_dev_get_bus_number(struct libusb20_device *pdev);
276 uint8_t libusb20_dev_get_mode(struct libusb20_device *pdev);
277 uint8_t libusb20_dev_get_speed(struct libusb20_device *pdev);
278 uint8_t libusb20_dev_get_config_index(struct libusb20_device *pdev);
279 void libusb20_dev_free(struct libusb20_device *pdev);
280 void libusb20_dev_set_debug(struct libusb20_device *pdev, int debug);
281 void libusb20_dev_wait_process(struct libusb20_device *pdev, int timeout);
283 /* USB global operations */
285 int libusb20_be_get_dev_quirk(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq);
286 int libusb20_be_get_quirk_name(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq);
287 int libusb20_be_add_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq);
288 int libusb20_be_remove_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq);
289 int libusb20_be_get_template(struct libusb20_backend *pbe, int *ptemp);
290 int libusb20_be_set_template(struct libusb20_backend *pbe, int temp);
292 /* USB backend operations */
294 struct libusb20_backend *libusb20_be_alloc(const struct libusb20_backend_methods *methods);
295 struct libusb20_backend *libusb20_be_alloc_default(void);
296 struct libusb20_backend *libusb20_be_alloc_freebsd(void);
297 struct libusb20_backend *libusb20_be_alloc_linux(void);
298 struct libusb20_backend *libusb20_be_alloc_ugen20(void);
299 struct libusb20_device *libusb20_be_device_foreach(struct libusb20_backend *pbe, struct libusb20_device *pdev);
300 void libusb20_be_dequeue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev);
301 void libusb20_be_enqueue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev);
302 void libusb20_be_free(struct libusb20_backend *pbe);
306 const char *libusb20_strerror(int);
307 const char *libusb20_error_name(int);
317 #endif /* _LIBUSB20_H_ */