Fix typos in introductory documentation

Linux: Add libusb_open() debug and error messages with the device path

Fixes #109.

Add debug message with libusb_open() error code

References #109.

Document libusb_handle_events_completed() and _timeout_completed()

Signed-off-by: Hans de Goede <hdegoede@redhat.com>
[stuge: Note that the old racy functions should be avoided by new code]

Fix #56 race condition causing delayed completion of sync transfers

The sync API had a race where it would check a condition to know if it
needed to call a libusb_handle_events() function. However, the check
was done outside of the lock that is held while the condition is set,
so another thread could completely serve whatever was needed to make
the condition true between it being checked and the event handler being
called. This situation would be detected after a libusb-internal timeout
of 60 seconds, after which the transfer would be completed without
error, but with significant delay.

Original patch at http://marc.info/?l=libusb-devel&m=127252114815709

Changes by Hans de Goede:
- Renamed the "race-proof" functions from libusb_handle_events*_check()
  to libusb_handle_events*_completed()
- Drop r = 0 setting in libusb_handle_events_timeout_completed()
  (to make both completed checking cases identical flow wise)

Signed-off-by: Hans de Goede <hdegoede@redhat.com>
[stuge: Simplify libusb_handle_events_timeout() change with a goto]
[pbatard: Fix _handle_events_timeout() and _completed() definitions]

Darwin: Use a condition to signal async thread ready in libusb_init()

Fix #64 use of reserved identifiers throughout libusb

Darwin: fix libusb_get_device_list() and libusb_claim_interface() leaks

Darwin: use kIOMasterPortDefault instead of creating a master port

Allow devices with zero configurations to be discovered

At least in Linux, wireless USB devices have zero configurations until
they have been authorized. This device state can be set for any USB
device using:

echo 0 > /sys/bus/usb/devices/?-?/authorized

An unauthorized device would previously make usbi_sanitize_device()
return LIBUSB_ERROR_IO, although there really was no I/O error.

Reported-by: Carl-Daniel Hailfinger <c-d.hailfinger.devel.2006@gmx.net>

Linux: Continue enumeration even if one device returns an error

Linux: Handle single- and two-digit kernel versions like 3.0 and 4

The code has been tested with various version strings.

[stuge: Remove bogus string length check and optimize for newer kernels]

Windows: Provide libusb_get_device_speed() data

* use (currently superspeed unaware) USB_NODE_CONNECTION_INFORMATION_EX

Fixes #45.

[stuge: Explicitly convert OS device speeds to libusb device speeds]
[pbatard: Add breaks overlooked when adding explicit conversion]

Darwin: Provide libusb_get_device_speed() data

References #45.

Linux: Provide libusb_get_device_speed() data from sysfs

References #45.

Signed-off-by: Hans de Goede <hdegoede@redhat.com>

Add new API function libusb_get_device_speed()

Reworked version of my earlier patch, largely modelled after (if not
copy and pasted from) Trygve Laugstøl's <trygvis@inamo.no> similar
commit 5a6541e0d80fb1f21e2b960bc2337a612f9d74fb in
git://git.libusb.org/libusb-trygvis.git
http://git.libusb.org/libusb-trygvis.git
http://git.libusb.org/?p=libusb-trygvis.git;a=commitdiff;h=5a6541e0d

This patch does not add any OS specific code. The supporting code in
each backend follows in separate patches. References #45.

Signed-off-By: Hans de Goede <hdegoede@redhat.com>

Darwin: Improve device enumeration performance

The device location is saved, and later used whenever iterating over
devices. Fixes #111 and #112.

[stuge: Formatting fixes and split out libusb_get_device_speed() change]
[stuge: Combine with patch that uses the saved device location]

Linux: Use __read_sysfs_attr() to get busnum and devaddr

Remove code duplication.

Signed-off-by: Hans de Goede <hdegoede@redhat.com>

Linux: Add __read_sysfs_attr() helper function

On Linux we often need to read (postive) integers from sysfs. This patch
adds a helper function for this. This is a preparation patch for adding
a libusb_get_device_speed() function to libusb.

Signed-off-by: Hans de Goede <hdegoede@redhat.com>

Linux: Stop kernel from re-attaching in-kernel driver after reset

When an interface is bound to the usbfs driver (iow claimed), the
kernel will unbind it, and then after the reset do a device_attach
on the interface, which will bind the default in kernel driver to
the interface.

So if an app has detached the in kernel driver, and claimed the
interface and then does a libusb_reset_device. Things end up with
the interface no longer being bound to the usbfs driver (so no longer
claimed) and instead it is bound to the in kernel driver (iow the in
kernel driver is re-attached).

We can stop this from happening by releasing all claimed interfaces
before the reset, as the kernel will not do the device attach after
reset, if no driver was bound to the interface before the reset.

Signed-off-by: Hans de Goede <hdegoede@redhat.com>

Core: Use USB_MAXINTERFACES rather then sizeof(claimed_interfaces)

claimed_interfaces is a long and thus its size differs on 32
versus 64 bits, this patch uses USB_MAXINTERFACES instead of
sizeof(claimed_interfaces) on interface number range checks
for consistent behavior independent of the arch.

Signed-off-by: Hans de Goede <hdegoede@redhat.com>

Linux: Fix warnings seen when compiling with gcc-4.6

Compiling with gcc-4.6 results in the following warnings:
os/linux_usbfs.c: In function 'op_get_configuration':
os/linux_usbfs.c:1144:6: warning: variable 'r' set but not used ...
os/linux_usbfs.c: In function 'op_handle_events':
os/linux_usbfs.c:2091:40: warning: 'status' may be used uninitialized ...
os/linux_usbfs.c:2044:6: note: 'status' was declared here
dpfp.c: In function 'save_to_file':
dpfp.c:228:9: warning: variable 'ignore' set but not used ...
dpfp_threaded.c: In function 'save_to_file':
dpfp_threaded.c:257:9: warning: variable 'ignore' set but not used ...

This patch fixes these. (The second comes from handle_control_completion()
which gcc seems to inline into op_handle_events().)

Signed-off-by: Hans de Goede <hdegoede@redhat.com>
[stuge: Add fixes for dpfp examples and update source references]

Darwin: Fix #108 crash when a device is unplugged

libusb.h: Add missing LIBUSB_CLASS_ codes currently defined by usb.org

LIBUSB_CLASS_PHYSICAL
LIBUSB_CLASS_SMART_CARD
LIBUSB_CLASS_CONTENT_SECURITY
LIBUSB_CLASS_VIDEO
LIBUSB_CLASS_PERSONAL_HEALTHCARE
LIBUSB_CLASS_DIAGNOSTIC_DEVICE

Per http://www.usb.org/developers/defined_class

libusb.h: Add LIBUSB_CLASS_IMAGE in addition to LIBUSB_CLASS_PTP

The old LIBUSB_CLASS_PTP name is kept for compatibility. Fixes #106.

libusb.h: Fix LIBUSB_CLASS_PRINTER description typo

References #106.

Darwin: Fix #100 warning cast to pointer from integer of different size

configure.ac: Fix #97 clang warning about -fgnu89-inline

Remove the test that sets the flag since GNU89 inline semantics are not
required by libusb.

[stuge: Also remove reference to the test result]

Windows: Make cancel_io() in poll_windows.c static

References #97.

Windows: Make upperize() in windows_usb.h static

References #97.

descriptor.c: Fix buffer read overflow caught by valgrind

In parse_interface() an unexpected descriptor would be parsed without
validating the descriptor's length.  It is possible for size to be 0 at
this point, which means that the parsing would read past the end of the
source buffer.  Fix #83 by checking the length of the remaining buffer
before parsing.

Clean up in-flight transfers and device handle when closing a device

Any in-flight transfers should properly invalidate their references
to device handles that are being closed.  Additionally, they should be
removed from the transfer-in-flight list.  This is done with the events
lock held to protect against another thread processing the same transfer.
The events lock is initialized as a recursive mutex, because the device
close code might itself be called while an event is being handled.
Fixes #82.

[stuge: Trivial rework to reduce indenting]

Add recursive mutexes to threading abstraction

This is necessary for the device close path which needs to attain the
events lock, but which might itself be called while handling an event.
The events lock is necessary to properly clean up transfers which might
still be pointing to the device. References #82.

[stuge: Move usbi_mutex_init_recursive() into threads_posix.c]
[stuge: Must also #define _XOPEN_SOURCE 500 to be able to build]
[pbatard: Un-inline usbi_mutex_init_recursive() to make Cygwin happy]

Add USBI_TRANSFER_CANCELLING and _DEVICE_DISAPPEARED status flags

The flags are used to indicate if a cancellation has started, and if
a cancellation has failed because the device is no longer available.
References #82.

Linux: Detect and report that device has gone away while discarding URBs

Return LIBUSB_ERROR_NO_DEVICE if the device is no longer available
(ENODEV) to discard the urbs. References #82.

libusbi.h: Add comma after last value in enum usbi_transfer_flags

threads_posix.h: Whitespace fix

libusb/Makefile.am: Correct threading files in libusb_1_0_la_SOURCES

Linux: Fix #70 race condition in sysfs_get_device_list()

Change the way libusb chooses between using sysfs and usbfs for information
about the attached devies.  Using the old method, a race condition could
occur if a device was unplugged just before (or during) the call to
libusb_get_device_list(), corrupting the internal sysfs_can_relate_devices
and sysfs_has_descriptors variables and preventing libusb_get_device_list()
from working in future calls.

The old method was based on the assumption that if certain sysfs files
(eg: busnum) could not be opened, that indicated an inadequacy of sysfs
(ie: the running kernel's sysfs version did not contain those files),
when in reality those files couldn't be opened because the device had
been unplugged.

The new method checks the adequacy of sysfs during libusb_init()
(op_init()) and if a sysfs file cannot be opened, it is now assumed that
it is because the device has been unplugged, not because sysfs is
inadequate.

Signed-off-by: Alan Ott <alan@signal11.us>
[stuge: Include closedir() bugfix posted in ticket by Arne Laansoo]
[stuge: Remove dead code in sysfs_scan_device() found by Hans de Goede]

Darwin: Fix #63 error when apps use Objective-C garbage collection

Darwin: Fix #28 clang analyzer warning about unbalanced retain/release

io.c: Fix clang analyzer warning about unused variable

References #28.

.gitignore: Add m4 subdirectory created by libtool

Linux: Do not include useless pthread.h

The code does not use threads so no need to #include <pthread.h>
Fixes #74.

Windows: minor code improvements

* mostly warnings from VS2010's Intellisense

Windows: prevent set_configuration request from being sent using WinUSB

* multiple WinUSB set configuration requests can stall a device and
  WinUSB does not support setting of alt configuration in the first place
* issue reported and investigated by Xiaofan Chen

Windows: fixed default WinUSB timeout and ineffective policy settings

* default WinUSB timeout was 5 seconds, which may be to small.
  PIPE_TRANSFER_TIMEOUT policy is now set to infinite for all EPs.
* other WinUSB policy settings were called before the endpoints
  had been set. This is now fixed.

Windows: Don't leak pipe fds

use _open() and _close() rather than _open_osfhandle() and CloseHandle()

* use of CloseHandle() prevented the pipe fds from being
  relinquished on libusb_exit()
* leaked fds could lead to the OS running out of new fds
  and LIBUSB_ERROR_NO_MEM being returned as a result
* using _open() avoids _open_osfhandle() redef for cygwin
* issue reported by Stephano Antonelli

Windows: enumeration overhaul

* uses multiple passes in a single call
* uses a hash table, in anticipation for hotplug
* adds a (dummy) HUB interface for harmonization
* adds calloc on device struct creation in core
  (to detect and avoid unnecessary double initialization)

Windows: MS project files part 4 - MSVC6 project files

Fixes #57 and #1.

Windows: MS project files part 3 - VS2005 project files

References #57.

Windows: MS project files part 2 - WDK project files

References #57.

Windows: MS project files part 1 - support files & preliminaries

* adds the MSVC support files used by MSVC6, VS2005 and WDK
* also adds missing defines required by MS compilers in libusb.h
* also anticipatory sets .gitattributes for CRLF handling
* also adds manually maintained .def file for import lib generation

References #57.

Move library version number from configure.ac to libusb/version.h

This is neccessary to support native MS builds. The Windows resource
file libusb/libusb-1.0.rc must include the release version, which was
previously only available after configure had run and had substituted
the numbers into a generated libusb/libusb-1.0.rc file.

The version atoms are now stored as CPP style #defines in libusb/version.h
so that the .rc no longer needs to be generated but can simply include the
header file and access the version information directly.

The m4 macro LU_DEFINE_VERSION_ATOM() was added to configure.ac to get
version atoms from libusb/version.h for use in AC_INIT(). The macro
handles C and C++ style comments in version.h, but can easily be made
to fail by obscuring the file. Please don't do that.

Tested with MinGW using autoconf, and manual compile of libusb-1.0.rc
using RC.EXE Version 5.2.3690.0 from Visual C++ 2005 Express Edition.

Windows: Debug builds create the same .dll file name as non-debug

Thanks to Pete for pointing this out!

Windows: explicit use of ANSI or WideChar calls

* This is in anticipation of adding MSVC project files
  that use Unicode rather than MBCS

Windows: Remove SetupAPI, AdvAPI32 and OLE32 link-time dependencies

* this ensures that libusb dependent applications only need
  to explicitly link against libusb on Windows

The run-time dependency on Cfgmgr32.dll, OLE32.dll and SetupAPI.dll remains.

Add .gitattributes to avoid Windows line ending issues with autocrlf

Windows: Touch up FileDescription and ProductName resource strings

Windows: Remove emulated direct device access via HID API

Either use a library such as HIDAPI to communicate with HID class
devices, or replace the kernel driver for the device with one that
offers support for the complete libusb API.

Revert libusb_strerror() until we have i18n and l10n

dpfp_threaded: return instead of pthread_exit() to avoid Cygwin warning

Windows: Rename various variables named "index" to avoid shadow warnings

Windows: Fix logic in enumeration of driver name and port number

Windows: Allow claiming any interface in composite device using WinUSB

Issue reported by Benjamin Dobell, see #48. The call to
WinUsb_QueryInterfaceSettings() is removed since it doesn't work
on any other interface but the first (a WinUSB limitation).

This allows the use of WinUSB.sys in lieu of the usbccgp.sys
"USB Generic Parent" default driver for composite devices.

Windows: Allow arbitrary bConfigurationValue in config descriptors

Unlike bInterfaceNumber, bConfigurationValue does not have to be
either sequential or contiguous. The bConfigurationValue is now
included in debug output. Fixes #48 reported by Benjamin Dobell.

Darwin: Schedule isochronous transfers further in the future

This is required to make OpenKinect transfer data at 30 fps. This
change was originally made by Theo Watson, and Thomas improved on it.
The commit came via OpenKinect into libusb thanks to Kyle Machulis and
Hector Martin. Fixes #66.

Darwin: Fix #65 memory leak in submit_iso_transfer()

This was also independently fixed by Hoi-Ho Chan, but Thomas caught
an additional problem with his fix.

This commit came via OpenKinect into libusb thanks to Kyle Machulis
and Hector Martin.

configure.ac: Refactor Windows backend settings into one occurence

The Windows backend is used both with MinGW and Cygwin, and since most
settings are identical they can be set in one place.

configure.ac: Rename AM_LDFLAGS to LTLDFLAGS and actually use them

The new variable name tries to clarify that libtool is being used.
Linker flags must thus always be specified with -Wl.

Factor out the libtool flag -no-undefined from host specific cases.
The flag is required to build a Windows DLL, but is correct also for
the other supported systems.

Also, start actually using LTLDFLAGS in libusb/Makefile.am, so that
libtool will see the options set by configure.

configure.ac: Clean up PC_LIBS_PRIVATE and AM_LDFLAGS

Move linker options for when linking the library itself from
PC_LIBS_PRIVATE into AM_LDFLAGS. PC_LIBS_PRIVATE should only
contain flags needed to link applications statically against libusb.
Fixes #72.

configure.ac: Call AC_CONFIG_FILES() for each output file

This avoids a problem with Windows line endings.

configure.ac: Whitespace changes and trivial reordering

configure.ac: Quote AC_COMPILE_IFELSE() input

configure.ac: Define booleans to 1 when set, instead of an empty string

This makes the generated config.h look a lot nicer.

configure.ac: Clean up redundancy and fix LIBS on Linux

LIBS, AM_LDFLAGS, OS_ conditionals and THREADS_POSIX had a bit of
redundancy throughout the file, and on Linux LIBS ended up missing
the -pthread flag.

configure.ac: Touch up Darwin and Cygwin OS messages

configure.ac: Do not use -pthread on Darwin

It's not needed because Darwin has POSIX Threads in libc. Fixes #96.

configure.ac: Check for poll.h, and for nfds_t on Darwin

On Linux, assume nfds_t is always available.

On Darwin, fall back to unsigned int when poll() exists but there
is no nfds_t, such as on Mac OS X before 10.4.

On Windows (both MinGW and Cygwin), always use unsigned int instead
of nfds_t, and don't check for poll.h because we use our own poll()
implementation.

Darwin: Add support for control requests on endpoints other than 0

Signed-off-by: Nathan Hjelm <hjelmn@me.com>

Darwin: Add more error checking for libusb_open()

Now also check the CreateDeviceAsyncEventSource() return code for errors.

Signed-off-by: Nathan Hjelm <hjelmn@me.com>

Core: libusb_get_next_timeout() must consider all flying transfers

If transfer->flags indicated that a transfer had a timeout, but no
timeout was actually set, then libusb_get_next_timeout() would look
no further for a timeout, ignoring any transfers later in the list
which had a timeout set.

Since libusb has an internal 60 second timeout this bug could not
cause complete lockup, but it could cause a 60 second timeout even
when a transfer was submitted with a shorter timeout.

Linux: Correctly catch read() errors for sysfs config descriptors

read(2) returns ssize_t (signed) and not size_t (unsigned) or int.

Silence "warning: comparison of unsigned expression < 0 is always false"
and fix #75.

Linux: Refactor cancellation into one function for all transfer types

Linux: Refactor discarding of URBs into a function and return all errors

The Linux backend did not always return errors according to the
libusb_cancel_transfer() documentation.

Linux: Set private number of URBs also for control transfers

Linux: cancel URBs in reverse order

In a multi-URB transfer, URBs should be cancelled in reverse order of
submission. This prevents races that might otherwise occur (after URB N
is cancelled, data may be transferred for URB N+1 before it too can be
cancelled). Fixes #8.

Linux: report correct value for urb->actual_length

Transferred bytes are returned correctly by the kernel for every URB,
even when an error occurs.  Hence they should always be included in
the transfer statistics.  The same is true for isochronous packet
length and status.

[stuge: set itransfer->transferred so data is stored at correct offset]

Linux: improve reporting of URB error status codes

Fix the way overflow errors are handled (they can occur in any
transaction, not just the last one in a transfer) and add tests
for other commonly-occuring error statuses.

Linux: improve detection of BULK_CONTINUATION kernel support

Clarify the comments describing the BULK_CONTINATION flag, and improve
the subroutine that checks whether the flag is supported by making it
"future-proof", i.e., by working properly with kernel version numbers
higher than 2.6.

README: Update webpage URL and add Peter's email address

libusb is not just for Linux!

Remove USBI_OS_HANDLES_TIMEOUT and fix int/isoc timeouts on Darwin

Backends set USBI_TRANSFER_OS_HANDLES_TIMEOUT for transfers instead.
Darwin only handles timeouts for bulk and control transfers, so the
backend now sets that flag accordingly, making libusb core handle
timeouts for interrupt and isochronous transfers. Fixes #31.

Signed-off-by: Nathan Hjelm <hjelmn@me.com>
[stuge: rework libusb_get_next_timeout() and enum usbi_transfer_flags]
[stuge: fix typo; set USBI_TRANSFER_TIMED_OUT flag correctly]

Silence "warning: suggest braces around empty body in an 'if' statement"

Disallow libusb_get_string_descriptor_ascii() with index 0

String descriptor 0 is the list of supported language IDs in the device,
which can't have an ASCII representation. Calling the function with
index 0 is thus not really useful. Fixes #43.

Use const for the usbi_parse_descriptor() format string

Constant strings should be "const char *" instead of "char *". Silence
"discards qualifiers from pointer target type" warnings. Fixes #61.

Linux: Fix usbfs/sysfs config descriptor handling on big-endian

usbfs endian-swaps, sysfs doesn't, not the other way around. Fixes #51;
descriptor endian parsing is backwards using sysfs on big-endian hosts.
usbfs is untested.

Signed-off-by: Hector Martin <hector@marcansoft.com>
[stuge: checked against Documentation/usb/proc_usb_info.txt]

examples: #include <libusb.h> without directory name

The libusb-1.0 directory name belongs in the compile command, e.g.
via pkg-config --cflags. Fixes #58.

Add missing argument to libusb_wait_for_event() documentation, fix #55

In the libusb_wait_for_event() sample code in the section "Letting other
threads do the work for you" the call to libusb_wait_for_event() was not
updated by commit 1df713d622ab4f0b03aad72d903ac7beb8fb3b90, which added
the libusb_context *ctx parameter to the function, so the sample code
was broken until now.

examples: Silence warnings about return value of fwrite()