aboutsummaryrefslogtreecommitdiff
path: root/lib/libusb/libusb.3
blob: 1f52b9ec17ed62d377b9b027fccf27da96466ec1 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
.\"
.\" Copyright (c) 2009 Sylvestre Gallon
.\"
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd August 16, 2011
.Dt LIBUSB 3
.Os
.Sh NAME
.Nm libusb
.Nd "USB access library"
.Sh LIBRARY
USB access library
.Pq libusb, -lusb
.Sh SYNOPSIS
.In libusb.h
.Sh DESCRIPTION
The
.Nm
library contains interfaces for directly managing a usb device.
The current implementation supports v1.0 of the libusb API.
.Sh LIBRARY INITIALISATION / DEINITIALISATION
.Pp
.Ft int
.Fn libusb_init libusb_context **ctx
This function initialises libusb.
It must be called at the beginning
of the program, before other libusb routines are used.
This function returns 0 on success or LIBUSB_ERROR on
failure.
.Pp
.Ft void
.Fn libusb_exit "libusb_context *ctx"
Deinitialise libusb.
Must be called at the end of the application.
Other libusb routines may not be called after this function.
.Pp
.Ft const char *
.Fn libusb_strerror "int code"
Get the ASCII representation of the error given by the
.Fa code
argument.
.Pp
.Ft void
.Fn libusb_set_debug "libusb_context *ctx" "int level"
Set the debug level to
.Fa level .
.Pp
.Ft ssize_t
.Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list"
Populate
.Fa list
with the list of usb devices available, adding a reference to each
device in the list.
All the list entries created by this
function must have their reference counter
decremented when you are done with them,
and the list itself must be freed.
This
function returns the number of devices in the list or a LIBUSB_ERROR code.
.Pp
.Ft void
.Fn libusb_free_device_list "libusb_device **list" "int unref_devices"
Free the list of devices discovered by libusb_get_device_list.
If
.Fa unref_device
is set to 1 all devices in the list have their reference
counter decremented once.
.Pp
.Ft uint8_t
.Fn libusb_get_bus_number "libusb_device *dev"
Returns the number of the bus contained by the device
.Fa dev.
.Pp
.Ft uint8_t
.Fn libusb_get_device_address "libusb_device *dev"
Returns the device_address contained by the device
.Fa dev.
.Pp
.Ft enum libusb_speed
.Fn libusb_get_device_speed "libusb_device *dev"
Returns the wire speed at which the device is connected.
See the LIBUSB_SPEED_XXX enums for more information.
LIBUSB_SPEED_UNKNOWN is returned in case of unknown wire speed.
.Pp
.Ft int
.Fn libusb_get_max_packet_size "libusb_device *dev" "unsigned char endpoint"
Returns the wMaxPacketSize value on success, LIBUSB_ERROR_NOT_FOUND if the
endpoint does not exist and LIBUSB_ERROR_OTHERS on other failure.
.Pp
.Ft libusb_device *
.Fn libusb_ref_device "libusb_device *dev"
Increment the reference counter of the device
.Fa dev.
.Pp
.Ft void
.Fn libusb_unref_device "libusb_device *dev"
Decrement the reference counter of the device
.Fa dev.
.Pp
.Ft int
.Fn libusb_open "libusb_device *dev" "libusb_device_handle **devh"
Open a device and obtain a device_handle.
Returns 0 on success,
LIBUSB_ERROR_NO_MEM on memory allocation problems, LIBUSB_ERROR_ACCESS
on permissions problems, LIBUSB_ERROR_NO_DEVICE if the device has been
disconnected and a LIBUSB_ERROR code on other errors.
.Pp
.Ft libusb_device_handle *
.Fn libusb_open_device_with_vid_pid "libusb_context *ctx" "uint16_t vid" "uint16_t pid"
A convenience function to open a device by vendor and product IDs
.Fa vid
and
.Fa pid.
Returns NULL on error.
.Pp
.Ft void
.Fn libusb_close "libusb_device_handle *devh"
Close a device handle.
.Pp
.Ft libusb_device *
.Fn libusb_get_device "libusb_device_handle *devh"
Get the device contained by devh.
Returns NULL on error.
.Pp
.Ft int
.Fn libusb_get_configuration "libusb_device_handle *devh" "int *config"
Returns the bConfiguration value of the current configuration.
Returns 0
on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
and a LIBUSB_ERROR code on error.
.Pp
.Ft int
.Fn libusb_set_configuration "libusb_device_handle *devh" "int config"
Set the active configuration to
.Fa config
for the device contained by
.Fa devh.
This function returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the requested
configuration does not exist, LIBUSB_ERROR_BUSY if the interfaces are currently
claimed, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a
LIBUSB_ERROR code on failure.
.Pp
.Ft int
.Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number"
Claim an interface in a given libusb_handle
.Fa devh.
This is a non-blocking function.
It returns 0 on success, LIBUSB_ERROR_NOT_FOUND
if the requested interface does not exist, LIBUSB_ERROR_BUSY if a program or
driver has claimed the interface, LIBUSB_ERROR_NO_DEVICE if the device has
been disconnected and a LIBUSB_ERROR code on failure.
.Pp
.Ft int
.Fn libusb_release_interface "libusb_device_handle *devh" "int interface_number"
This function releases an interface.
All the claimed interfaces on a device must be released
before closing the device.
Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the
interface was not claimed, LIBUSB_ERROR_NO_DEVICE if the device has been
disconnected and LIBUSB_ERROR on failure.
.Pp
.Ft int
.Fn libusb_set_interface_alt_setting "libusb_device_handle *dev" "int interface_number" "int alternate_setting"
Activate an alternate setting for an interface.
Returns 0 on success,
LIBUSB_ERROR_NOT_FOUND if the interface was not claimed or the requested
setting does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been
disconnected and a LIBUSB_ERROR code on failure.
.Pp
.Ft int
.Fn libusb_clear_halt "libusb_device_handle *devh" "unsigned char endpoint"
Clear an halt/stall for a endpoint.
Returns 0 on success, LIBUSB_ERROR_NOT_FOUND
if the endpoint does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been
disconnected and a LIBUSB_ERROR code on failure.
.Pp
.Ft int
.Fn libusb_reset_device "libusb_device_handle *devh"
Perform an USB port reset for an usb device.
Returns 0 on success,
LIBUSB_ERROR_NOT_FOUND if re-enumeration is required or if the device has
been disconnected and a LIBUSB_ERROR code on failure.
.Pp
.Ft int
.Fn libusb_check_connected "libusb_device_handle *devh"
Test if the USB device is still connected.
Returns 0 on success,
LIBUSB_ERROR_NO_DEVICE if it has been disconnected and a LIBUSB_ERROR
code on failure.
.Pp
.Ft int
.Fn libusb_kernel_driver_active "libusb_device_handle *devh" "int interface"
Determine if a driver is active on a interface.
Returns 0 if no kernel driver
is active, 1 if a kernel driver is active, LIBUSB_ERROR_NO_DEVICE
if the device has been disconnected and a LIBUSB_ERROR code on failure.
.Pp
.Ft int
.Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
or
.Ft int
.Fn libusb_get_driver_np "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
Copy the name of the driver attached to the given
.Fa device
and
.Fa interface
into the buffer
.Fa name
of length
.Fa namelen .
Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver is attached
to the given interface and LIBUSB_ERROR_INVALID_PARAM if the interface does
not exist.
This function is non-portable.
The buffer pointed to by
.Fa name
is only zero terminated on success.
.Pp
.Ft int
.Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface"
or
.Ft int
.Fn libusb_detach_kernel_driver_np "libusb_device_handle *devh" "int interface"
Detach a kernel driver from an interface.
This is needed to claim an interface already claimed by a kernel driver.
Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver was active,
LIBUSB_ERROR_INVALID_PARAM if the interface does not exist,
LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
and a LIBUSB_ERROR code on failure.
This function is non-portable.
.Pp
.Ft int
.Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface"
Re-attach an interface kernel driver that was previously detached.
Returns 0 on success,
LIBUSB_ERROR_INVALID_PARAM if the interface does not exist,
LIBUSB_ERROR_NO_DEVICE
if the device has been disconnected, LIBUSB_ERROR_BUSY if the driver cannot be
attached because the interface is claimed by a program or driver and a
LIBUSB_ERROR code on failure.
.Pp
.Sh USB DESCRIPTORS
.Pp
.Ft int
.Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc"
Get the USB device descriptor for the device
.Fa dev.
This is a non-blocking function.
Returns 0 on success and a LIBUSB_ERROR code on
failure.
.Pp
.Ft int
.Fn libsub_get_active_config_descriptor "libusb_device *dev" "struct libusb_config_descriptor **config"
Get the USB configuration descriptor for the active configuration.
Returns 0 on
success, LIBUSB_ERROR_NOT_FOUND if the device is in
an unconfigured state
and a LIBUSB_ERROR code on error.
.Pp
.Ft int
.Fn libusb_get_config_descriptor "libusb_device *dev" "uint8_t config_index" "libusb_config_descriptor **config"
Get a USB configuration descriptor based on its index
.Fa idx.
Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist
and a LIBUSB_ERROR code on error.
.Pp
.Ft int
.Fn libusb_get_config_descriptor_by_value "libusb_device *dev" "uint8 bConfigurationValue" "libusb_config_descriptor **config"
Get a USB configuration descriptor with a specific bConfigurationValue.
This is
a non-blocking function which does not send a request through the device.
Returns 0
on success, LIBUSB_ERROR_NOT_FOUND if the configuration
does not exist and a
LIBUSB_ERROR code on failure.
.Pp
.Ft void
.Fn libusb_free_config_descriptor "libusb_config_descriptor *config"
Free a configuration descriptor.
.Pp
.Ft int
.Fn libusb_get_string_descriptor_ascii "libusb_device_handle *devh" "uint8_t desc_idx" "unsigned char *data" "int length"
Retrieve a string descriptor in C style ASCII.
Returns the positive number of bytes in the resulting ASCII string
on success and a LIBUSB_ERROR code on failure.
.Pp
.Sh USB ASYNCHRONOUS I/O
.Pp
.Ft struct libusb_transfer *
.Fn libusb_alloc_transfer "int iso_packets"
Allocate a transfer with the number of isochronous packet descriptors
specified by
.Fa iso_packets .
Returns NULL on error.
.Pp
.Ft void
.Fn libusb_free_transfer "struct libusb_transfer *tr"
Free a transfer.
.Pp
.Ft int
.Fn libusb_submit_transfer "struct libusb_transfer *tr"
This function will submit a transfer and returns immediately.
Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if
the device has been disconnected and a
LIBUSB_ERROR code on other failure.
.Pp
.Ft int
.Fn libusb_cancel_transfer "struct libusb_transfer *tr"
This function asynchronously cancels a transfer.
Returns 0 on success and a LIBUSB_ERROR code on failure.
.Pp
.Sh USB SYNCHRONOUS I/O
.Pp
.Ft int
.Fn libusb_control_transfer "libusb_device_handle *devh" "uint8_t bmRequestType" "uint8_t bRequest" "uint16_t wValue" "uint16_t wIndex" "unsigned char *data" "uint16_t wLength" "unsigned int timeout"
Perform a USB control transfer.
Returns the actual number of bytes
transferred on success, in the range from and including zero up to and
including
.Fa wLength .
On error a LIBUSB_ERROR code is returned, for example
LIBUSB_ERROR_TIMEOUT if the transfer timed out, LIBUSB_ERROR_PIPE if the
control request was not supported, LIBUSB_ERROR_NO_DEVICE if the
device has been disconnected and another LIBUSB_ERROR code on other failures.
The LIBUSB_ERROR codes are all negative.
.Pp
.Ft int
.Fn libusb_bulk_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout"
Perform an USB bulk transfer.
A timeout value of zero means no timeout.
The timeout value is given in milliseconds.
Returns 0 on success, LIBUSB_ERROR_TIMEOUT
if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not
supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
a LIBUSB_ERROR code on other failure.
.Pp
.Ft int
.Fn libusb_interrupt_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout"
Perform an USB Interrupt transfer.
A timeout value of zero means no timeout.
The timeout value is given in milliseconds.
Returns 0 on success, LIBUSB_ERROR_TIMEOUT
if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not
supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
a LIBUSB_ERROR code on other failure.
.Pp
.Sh USB EVENTS
.Pp
.Ft int
.Fn libusb_try_lock_events "libusb_context *ctx"
Try to acquire the event handling lock.
Returns 0 if the lock was obtained and 1 if not.
.Pp
.Ft void
.Fn libusb_lock_events "libusb_context *ctx"
Acquire the event handling lock.
This function is blocking.
.Pp
.Ft void
.Fn libusb_unlock_events "libusb_context *ctx"
Release the event handling lock.
This will wake up any thread blocked
on
.B libusb_wait_for_event() .
.Pp
.Ft int
.Fn libusb_event_handling_ok "libusb_context *ctx"
Determine if it still OK for this thread to be doing event handling.
Returns 1
if event handling can start or continue.
Returns 0 if this thread must give up
the events lock.
.Pp
.Ft int
.Fn libusb_event_handler_active "libusb_context *ctx"
Determine if an active thread is handling events.
Returns 1 if there is a thread handling events and 0 if there
are no threads currently handling events.
.Pp
.Ft void
.Fn libusb_lock_event_waiters "libusb_context *ctx"
Acquire the event_waiters lock.
This lock is designed to be obtained in the
situation where you want to be aware when events are completed, but some other
thread is event handling so calling libusb_handle_events() is not allowed.
.Pp
.Ft void
.Fn libusb_unlock_event_waiters "libusb_context *ctx"
Release the event_waiters lock.
.Pp
.Ft int
.Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv"
Wait for another thread to signal completion of an event.
Must be called
with the event waiters lock held, see libusb_lock_event_waiters().
This will
block until the timeout expires or a transfer completes or a thread releases
the event handling lock through libusb_unlock_events().
Returns 0 after a
transfer completes or another thread stops event handling, and 1 if the
timeout expired.
.Pp
.Ft int
.Fn libusb_handle_events_timeout "libusb_context *ctx" "struct timeval *tv"
Handle any pending events by checking if timeouts have expired and by
checking the set of file descriptors for activity.
Returns 0 on success, or a
LIBUSB_ERROR code on failure.
.Pp
.Ft int
.Fn libusb_handle_events "libusb_context *ctx"
Handle any pending events in blocking mode with a sensible timeout.
Returns 0
on success and a LIBUSB_ERROR code on failure.
.Pp
.Ft int
.Fn libusb_handle_events_locked "libusb_context *ctx" "struct timeval *tv"
Handle any pending events by polling file desciptors, without checking if
another thread is already doing so.
Must be called with the event lock held.
.Pp
.Ft int
.Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv"
Determine the next internal timeout that libusb needs to handle.
Returns 0
if there are no pending timeouts, 1 if a timeout was returned, or a LIBUSB_ERROR
code on failure.
.Pp
.Ft void
.Fn libusb_set_pollfd_notifiers "libusb_context *ctx" "libusb_pollfd_added_cb added_cb" "libusb_pollfd_removed_cb remove_cb" "void *user_data"
Register notification functions for file descriptor additions/removals.
These functions will be invoked for every new or removed file descriptor
that libusb uses as an event source.
.Pp
.Ft const struct libusb_pollfd **
.Fn libusb_get_pollfds "libusb_context *ctx"
Retrive a list of file descriptors that should be polled by your main loop as
libusb event sources.
Returns a NULL-terminated list on success or NULL on failure.
.Sh LIBUSB VERSION 0.1 COMPATIBILITY
.Pp
The library is also compliant with LibUSB version 0.1.12.
.Pp
.Fn usb_open
.Fn usb_close
.Fn usb_get_string
.Fn usb_get_string_simple
.Fn usb_get_descriptor_by_endpoint
.Fn usb_get_descriptor
.Fn usb_parse_descriptor
.Fn usb_parse_configuration
.Fn usb_destroy_configuration
.Fn usb_fetch_and_parse_descriptors
.Fn usb_bulk_write
.Fn usb_bulk_read
.Fn usb_interrupt_write
.Fn usb_interrupt_read
.Fn usb_control_msg
.Fn usb_set_configuration
.Fn usb_claim_interface
.Fn usb_release_interface
.Fn usb_set_altinterface
.Fn usb_resetep
.Fn usb_clear_halt
.Fn usb_reset
.Fn usb_strerror
.Fn usb_init
.Fn usb_set_debug
.Fn usb_find_busses
.Fn usb_find_devices
.Fn usb_device
.Fn usb_get_busses
.Fn usb_check_connected
.Fn usb_get_driver_np
.Fn usb_detach_kernel_driver_np
.Sh SEE ALSO
.Xr libusb20 3 ,
.Xr usb 4 ,
.Xr usbconfig 8
.Pp
.Pa http://libusb.sourceforge.net/
.Sh HISTORY
.Nm
support first appeared in
.Fx 8.0 .