1a82c9d313
Sourceforge. Libusb 1.0 is a portable usb api released December 2008 and supersedes the original libusb released 10 years ago, it supports isochronous endpoints and asynchronous I/O. Many applications have already started using the interfaces. This has been developed as part of Google Summer of Code this year by Sylvestre Gallon and has been cribbed early due to it being desirable in FreeBSD 8.0 Submitted by: Sylvestre Gallon Sponsored by: Google Summer of Code 2009 Reviewed by: Hans Petter Selasky
504 lines
16 KiB
Groff
504 lines
16 KiB
Groff
.\"
|
|
.\" 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 June 22, 2009
|
|
.Dt LIBUSB 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm libusb
|
|
.
|
|
.Nd "USB access library"
|
|
.
|
|
.
|
|
.Sh LIBRARY
|
|
.
|
|
.
|
|
USB access library (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. Must be called at the beginning
|
|
of the program. 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.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft void
|
|
.Fn libusb_set_debug "libusb_context *ctx" "int level"
|
|
Set debug to the
|
|
.Fa level
|
|
level.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft ssize_t
|
|
.Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list"
|
|
Fill into
|
|
.Fa list
|
|
the list of usb device available. All the device created by this
|
|
function must be unref and free when you are done with them. This
|
|
function returns the number of devices in 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 are unref one time.
|
|
.
|
|
.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"
|
|
Return the device_address contained by the device
|
|
.Fa dev.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft int
|
|
.Fn libusb_get_max_packet_size "libusb_device *dev" "unsigned char endpoint"
|
|
Return 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. Return 0 on success,
|
|
LIBUSB_ERROR_NO_MEM on memory allocation problem, LIBUSB_ERROR_ACCESS
|
|
on permission problem, LIBUSB_ERROR_NO_DEVICE if the device has been
|
|
disconnected and a LIBUSB_ERROR code on error.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft libusb_device_handle *
|
|
.Fn libusb_open_device_with_vid_pid "libusb_context *ctx" "uint16_t vid" "uint16_t pid"
|
|
Conveniance function to open a device with is
|
|
.Fa vid
|
|
and
|
|
.Fa pid.
|
|
Return 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. Return NULL on error.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft int
|
|
.Fn libusb_get_configuration "libusb_device_handle *devh" "int *config"
|
|
Return the bConfiguration value of the current configuration. return 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
|
|
.Fa config
|
|
for the device contained by
|
|
.Fa devh.
|
|
This function return 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 return 0 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 release an interface. All the claimed interface must be released
|
|
before closing a device. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the
|
|
interafce 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 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_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, returns 1 if a kernel driver is active, returns LIBUSB_ERROR_NO_DEVICE
|
|
if the device has been disconnected and return a LIBUSB_ERROR code on failure.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft int
|
|
.Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface"
|
|
Detach a kernel driver from an interface. This is needed to claim an interface
|
|
required 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.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft int
|
|
.Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface"
|
|
Re-attach an interface kernel driver 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 disconnect, 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" "libusb_device_descriptor **config"
|
|
Get the USB configuration descriptor for the active configuration. Returns 0 on
|
|
success, returns LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state
|
|
and return another 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 USB configuration descriptor based on its index
|
|
.Fa idx.
|
|
Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist
|
|
and returns another 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 request through the device. Returns 0
|
|
on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist and another
|
|
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 a number of byte 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
|
|
.Fa iso_packets
|
|
numbers of isochronous packet descriptors. 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
|
|
LIBUSB_ERROR code on other failure.
|
|
.
|
|
.Pp
|
|
.Ft int
|
|
.Fn libusb_cancel_transfer "struct libusb_transfer *tr"
|
|
This function asynchronously cancel a transfer. Returns 0 on success and
|
|
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" "uint16_t wIndex" "unsigned char *data" "uint16_t wLength" "unsigned int timeout"
|
|
Perform a USB control transfer. Returns 0 on success, LIBUSB_ERROR_TIMEOUT
|
|
if the transfer timeout, LIBUSB_ERROR_PIPE if the control request was not
|
|
supported, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
|
|
LIBUSB_ERROR code on other failure.
|
|
.
|
|
.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. Returns 0 on success, LIBUSB_ERROR_TIMEOUT
|
|
if the transfer timeout, 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
|
|
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. Returns 0 on success, LIBUSB_ERROR_TIMEOUT
|
|
if the transfer timeout, 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
|
|
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 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 yes 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 under 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, returns 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, returns 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 threads are 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 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
|
|
.
|
|
.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 .
|