From 82294fed9dcec3bf6687a4c58b52939ef7d5fb80 Mon Sep 17 00:00:00 2001 From: hselasky Date: Tue, 23 Aug 2011 07:35:21 +0000 Subject: [PATCH] MFC r224903, r224917, r225035, r225090, r225091: - Add missing API function to the LibUSB v1.0 API. - Update LibUSB v1.0 manual page. PR: docs/159898 git-svn-id: svn://svn.freebsd.org/base/stable/8@225102 ccf9f872-aa2e-dd11-9fc8-001c23d0bc1f --- lib/libusb/Makefile | 1 + lib/libusb/libusb.3 | 408 +++++++++++++++++++----------------------- lib/libusb/libusb.h | 9 + lib/libusb/libusb10.c | 21 +++ 4 files changed, 211 insertions(+), 228 deletions(-) diff --git a/lib/libusb/Makefile b/lib/libusb/Makefile index ece52d124..dad00f082 100644 --- a/lib/libusb/Makefile +++ b/lib/libusb/Makefile @@ -43,6 +43,7 @@ MLINKS += libusb.3 libusb_get_device_list.3 MLINKS += libusb.3 libusb_free_device_list.3 MLINKS += libusb.3 libusb_get_bus_number.3 MLINKS += libusb.3 libusb_get_device_address.3 +MLINKS += libusb.3 libusb_get_device_speed.3 MLINKS += libusb.3 libusb_get_max_packet_size.3 MLINKS += libusb.3 libusb_ref_device.3 MLINKS += libusb.3 libusb_unref_device.3 diff --git a/lib/libusb/libusb.3 b/lib/libusb/libusb.3 index 33d807dbf..1f52b9ec1 100644 --- a/lib/libusb/libusb.3 +++ b/lib/libusb/libusb.3 @@ -26,247 +26,211 @@ .\" .\" $FreeBSD$ .\" -.Dd November 18, 2010 +.Dd August 16, 2011 .Dt LIBUSB 3 .Os .Sh NAME .Nm libusb -. .Nd "USB access library" -. -. .Sh LIBRARY -. -. -USB access library (libusb -lusb) -. -. +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. Must be called at the beginning -of the program. This function returns 0 on success or LIBUSB_ERROR on +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. -. +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 ASCII representation of the error given by the +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 debug to the -.Fa level -level. -. +Set the debug level to +.Fa 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 -. +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 +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. -. +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" -Return the device_address contained by the device +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" -Return the wMaxPacketSize value on success, LIBUSB_ERROR_NOT_FOUND if the +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. 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. -. +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" -Convenience function to open a device with is -.Fa vid -and +A convenience function to open a device by vendor and product IDs +.Fa vid +and .Fa pid. -Return NULL on error. -. +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. Return NULL on error. -. +.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" -Return the bConfiguration value of the current configuration. return 0 -on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected +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 +Set the active configuration to .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 +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 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 +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 release an interface. All the claimed interface must be released -before closing a device. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the -interface was not claimed, LIBUSB_ERROR_NO_DEVICE if the device has been +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 LIBUSB_ERROR code on failure. -. +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 +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, +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 USB device is still connected. Returns 0 on success, -LIBUSB_ERROR_NO_DEVICE if has been disconnected and a LIBUSB_ERROR +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, 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. -. +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" -Gets the name of the driver attached to the given +Copy the name of the driver attached to the given .Fa device and .Fa interface -into the buffer given by +into the buffer .Fa name -and +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 @@ -275,239 +239,230 @@ 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 required by a kernel driver. +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. -. +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 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 +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 +This is a non-blocking function. +Returns 0 on success and a LIBUSB_ERROR code on failure. -. .Pp -.Ft int +.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, returns LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state -and return another LIBUSB_ERROR code on error. -. +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 +.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 +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 returns another LIBUSB_ERROR code on error. -. +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 request through the device. Returns 0 -on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist and another +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 a number of byte on success -and a LIBUSB_ERROR code on failure. -. +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 -.Fa iso_packets -numbers of isochronous packet descriptors. Returns NULL on error. -. +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 +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 cancel a transfer. Returns 0 on success and -LIBUSB_ERROR code on failure. -. +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 until and +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 timeout, LIBUSB_ERROR_PIPE if the +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 or another LIBUSB_ERROR code on other failures. -The libusb error codes are always negative. -. +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 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. -. +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 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. -. +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. -. +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. -. +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(). -. +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 +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 +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 under the +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 +.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 +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 +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 +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. -. +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 threads are already doing so. Must be called with the event lock held. -. +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 LIBUSB_ERROR +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. -. +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. @@ -544,16 +499,13 @@ The library is also compliant with LibUSB version 0.1.12. .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 . diff --git a/lib/libusb/libusb.h b/lib/libusb/libusb.h index 0c9e50f93..bbde47584 100644 --- a/lib/libusb/libusb.h +++ b/lib/libusb/libusb.h @@ -151,6 +151,14 @@ enum libusb_error { LIBUSB_ERROR_OTHER = -99, }; +enum libusb_speed { + LIBUSB_SPEED_UNKNOWN = 0, + LIBUSB_SPEED_LOW = 1, + LIBUSB_SPEED_FULL = 2, + LIBUSB_SPEED_HIGH = 3, + LIBUSB_SPEED_SUPER = 4, +}; + enum libusb_transfer_status { LIBUSB_TRANSFER_COMPLETED, LIBUSB_TRANSFER_ERROR, @@ -304,6 +312,7 @@ ssize_t libusb_get_device_list(libusb_context * ctx, libusb_device *** list); void libusb_free_device_list(libusb_device ** list, int unref_devices); uint8_t libusb_get_bus_number(libusb_device * dev); uint8_t libusb_get_device_address(libusb_device * dev); +enum libusb_speed libusb_get_device_speed(libusb_device * dev); int libusb_clear_halt(libusb_device_handle *devh, uint8_t endpoint); int libusb_get_max_packet_size(libusb_device * dev, uint8_t endpoint); libusb_device *libusb_ref_device(libusb_device * dev); diff --git a/lib/libusb/libusb10.c b/lib/libusb/libusb10.c index 3ecba58eb..b66ccb6ee 100644 --- a/lib/libusb/libusb10.c +++ b/lib/libusb/libusb10.c @@ -272,6 +272,27 @@ libusb_get_device_address(libusb_device *dev) return (libusb20_dev_get_address(dev->os_priv)); } +enum libusb_speed +libusb_get_device_speed(libusb_device *dev) +{ + if (dev == NULL) + return (LIBUSB_SPEED_UNKNOWN); /* should not happen */ + + switch (libusb20_dev_get_speed(dev->os_priv)) { + case LIBUSB20_SPEED_LOW: + return (LIBUSB_SPEED_LOW); + case LIBUSB20_SPEED_FULL: + return (LIBUSB_SPEED_FULL); + case LIBUSB20_SPEED_HIGH: + return (LIBUSB_SPEED_HIGH); + case LIBUSB20_SPEED_SUPER: + return (LIBUSB_SPEED_SUPER); + default: + break; + } + return (LIBUSB_SPEED_UNKNOWN); +} + int libusb_get_max_packet_size(libusb_device *dev, uint8_t endpoint) { -- 2.45.0