Jul 02, 2018 libusb-win32 is a port of libusb-0.1 under Windows Brought to you by: donpedro2, ste_meyer, trobinso, xiaofanc.
I have a custom composite USB device with usbser, winusb, usbstor interfaces.
We have a few hundred devices running for three ish years now, with billions of libusb operations. (Thanks folks!) on win7,8,10.
We have a few hundred devices running for three ish years now, with billions of libusb operations. (Thanks folks!) on win7,8,10.
The unit has a feature in which I send a command to the winusb interface to reconfigure it's usb serial#.
The device soft disconnects from the USB bus, changes part of it's descriptor (the serial number), waits 500ms (or 2seconds, doesn't help the issue) and then reconnects.
Under windows 7, and the virus known as windows 8, this works fine.
Under windows 10, I get a duplicate entry of the old device in my libusb_get_device_list structure.
The device soft disconnects from the USB bus, changes part of it's descriptor (the serial number), waits 500ms (or 2seconds, doesn't help the issue) and then reconnects.
Under windows 7, and the virus known as windows 8, this works fine.
Under windows 10, I get a duplicate entry of the old device in my libusb_get_device_list structure.
Below is a data dump. I have libusb debugging turned on (hence the first 3 lines)
The first line (VID 046D) is a USB flash drive that was unplugged during a PRIOR power cycle of the box. Where or why libusb is complaining about this device is a mystery to me. At the same time it may likely be a clue to the what is going on.
Using usbdview, all 3 errant devices are not present.
The first line (VID 046D) is a USB flash drive that was unplugged during a PRIOR power cycle of the box. Where or why libusb is complaining about this device is a mystery to me. At the same time it may likely be a clue to the what is going on.
Using usbdview, all 3 errant devices are not present.
The second 2 lines (VID 2B2A) refer to the winusb and msc interfaces on my composite device, and the parent id of 17AD5DBB is the old parent from the previous enumeration of my device. (with the old serial number). 2B2A is a private USB VID.
Finally, the 0), 1), 2), is a simple crawl of the libusb_get_device_list with libusb_get_devicedescriptor
There should be only one VID 2B2A in this list (as there is on win7/8); there is only 1 device attached to the PC.
There should be only one VID 2B2A in this list (as there is on win7/8); there is only 1 device attached to the PC.
If I reboot, there is in fact only 1 device present, and things work. However, rebooting isn't really an option for the actual use case of the product. (but I still get the gripe about the USB flash drive)
libusb: error [init_device] device '.USB#VID_046D&PID_C080&MI_01#6&33F61665&0&0001' is no longer connected!
libusb: error [init_device] device '.USB#VID_2B2A&PID_0156&MI_02#6&17AD5DBB&1&0002' is no longer connected!
libusb: error [init_device] device '.USB#VID_2B2A&PID_0156&MI_03#6&17AD5DBB&1&0003' is no longer connected!
libusb: error [init_device] device '.USB#VID_2B2A&PID_0156&MI_02#6&17AD5DBB&1&0002' is no longer connected!
libusb: error [init_device] device '.USB#VID_2B2A&PID_0156&MI_03#6&17AD5DBB&1&0003' is no longer connected!
- VID 1B21 PID 1242 CLS 0000 PROT 00
- VID 1B1C PID 1B15 CLS 0000 PROT 00
- VID 1B1C PID 1B15 CLS 0000 PROT 00
- VID 046D PID C080 CLS 0000 PROT 00
- VID 2B2A PID 0156 CLS 00EF PROT 01
- VID 2B2A PID 0156 CLS 00EF PROT 01
- VID 8086 PID A12F CLS 0000 PROT 00
Any suggestions are welcome. I unload libusb as soon as possible after firing off the call that causes the disconnect/modification of the serial number/reconnect. I am confident that I have unloaded the libusb default context, closed libusb, and exited my program before the USB endpoint device performs the soft-disconnect.
The errant behavior happens on 3 different windows 10 Pro boxes. In all cases, the device is connected to the root hub embedded in the Intel chipset. (USB xHCI )
The errant behavior happens on 3 different windows 10 Pro boxes. In all cases, the device is connected to the root hub embedded in the Intel chipset. (USB xHCI )
-Steve
IMPORTANT: NEC/Renesas uPD720200/uPD720200A USB 3.0 users, please upgrade your drivers to version 2.1.16.0 or later.uPD720201/uPD720202 users should use version 3.x (3.0.23 or later preferred). Older versions of the driver have a bug that prevents libusb from accessing devices.
|
Overview
About
This project adds Windows platform support to the libusb Open Source library, in order to help developers easily communicate with USB devices on Windows.Currently it supports the WinUSB and HID drivers for generic USB device access as well as the libusb-win32 and libusbK drivers.
Take note libusb-win32 and libusbK are separated projects. libusb-win32 is a Windows only project which provide libusb-0.1 API compatible library for Windows and the kernel driver libusb0.sys. libusbK is a Windows only project which provides a new set of API for Windows and kernel driver libusbK.sys.
Binary Snapshots
Pre-built binary snapshots are provided in the Sourceforge files directory along with the source code archive. For later versions like 1.0.21 release, they are also in github release page
The pre-built Windows binaries are provided AS IS for your convenience, generated for the following environments:
The pre-built Windows binaries are provided AS IS for your convenience, generated for the following environments:
- Microsoft Visual Studio and DDK/WDK → MS32(32 bit) and MS64 (64 bit) directories
- MinGW -> MinGW32 (32 bit) and MinGW64 (64 bit) directories
7z
format so you may have to install 7-zip.Supported Environments
Supported systems are all Windows platforms, starting with Windows XP, and including 64 bit versions, with the following exceptions:
- Windows 2003 (Microsoft does not support WinUSB on 32bit/64bit Windows 2003)
- Windows XP 64 bit (Microsoft does not officially support WinUSB on 64bit Windows XP)
USB 3.0 Support
libusb supports USB 3.0 controllers and devices on Windows. Proprietary vendor controller drivers for Windows 7 and earlier as well as the Microsoft controller xHCI driver for Windows 8 are supported. If you are not using Windows 8 or later, you will be using vendor driver. Make sure you upgrade to the latest version of the driver if you encounter problems.
If you are using a NEC/Renesas USB 3.0 controller, such as the fairly widespread
uPD720200
/uPD720200A
, remember to make sure that your controller drivers are version 2.1.16.0 or later. Older versions of the drivers are known to have a bug that prevents access to USB devices.Windows 8.x/10 Support
libusb was tested under Windows 8 and Windows 8.1, for both 32 and 64 bit, and no issues were found.
.NET support
A
.NET
version of libusb, called LibUsbDotNet, based on libusb 1.0, has been developed by Travis Lee Robinson. If you plan to use libusb in a .NET
project, make sure you check http://libusbdotnet.sourceforge.net or http://sourceforge.net/projects/libusbdotnet/, but be aware that LibUsbDotNet's most recent version is v2.2.8, which was released on 2010-10-29. Travis Lee Robinson also created the libusbK project, which has C# wrappers for its 'libusbK.dll'. The latest (v3.0.7, 2014-04-27) binaries, source code and wrapper classes can be downloaded from its SourceForge directory.
How to use libusb on Windows
Driver Installation
If your target device is not HID, you must install a driver before you can communicate with it using libusb. Currently, this means installing one of Microsoft's
WinUSB
, libusb-win32 or libusbK drivers. Two options are available:- Recommended: Use the most recent version of Zadig, an Automated Driver Installer GUI application for
WinUSB
,libusb-win32
andlibusbK
... - Alternatively, if you are only interested in
WinUSB
, you can download the WinUSB driver files and customize theinf
file for your device. - For version 1.0.21 or later, you can also use usbdk backend. usbdk provides another driver option for libusb Windows backend. For 1.0.21, usbdk is a compile-time option, but it becomes a runtime option from version 1.0.22 onwards, so you need to specify the usbdk backend using something like the following.
Development Considerations
The handling of composite devices under Windows is done with multiple drivers, that are children of the
usbccgp.sys
driver (Composite Generic Parent), as this is the default for the OS. For more info, see '2. How Windows handles a composite device' at http://forum.silabs.com/ubbthreads.php?ubb=showflat&Number=39797. If needed, it is also possible to replace the composite parent driver to access the device.Because Windows does not provide a native
poll()
function, and cygwin is the only development environment that provides such a call, the use of libusb file descriptors with poll()
on cygwin is NOT supported. In a future version of libusb, we should provide better handling of native Windows events, but this will require a redesign of the libusb API, so it probably won't occur before libusb 2.0.Known Restrictions
WinUSB
cannot be used to send an actual reset command to an USB device. This is a limitation of WinUSB.WinUSB
andlibusbK
cannot be used to set a device configuration that is different from the first one. This is a limitation of KMDF USB I/O Target.WinUSB
does not support multiple concurrent applications (as per the MSDN documentation).WinUSB
does not support isochronous transfers under Windows XP/Vista/7/8. WinUSB under Windows 8.1 or later supports isochronous transfer. Take note as of now libusb Windows only supports isochronous transfer using the usbdk backend (version 1.0.21 and later). libusb-1.0.22 adds isochronous support using libsubK driver. Future version will add isochronous transfer for WinUSB (Windows 8.1/10 or later).- With
WinUSB
, whenLIBUSB_RECIPIENT_INTERFACE
is used for the transfer, theWinUSB
DLL forces the low byte ofwIndex
to the interface number, regardless of what you set it to.- This is not a real limitation though, please refer to the OSR threads. From Tim Roberts answer in that thread:
- One can also argue that this is a security measure. The USB spec requires that the low byte of wIndex be set to the interface number when the recipient is set to 'interface'. Devices that use that field for other purposes are broken.
- HID keyboards and mice cannot be accessed using the native HID driver as Windows reserves exclusive access to them.
- Multiple HID top level collections are currently not supported (only the first top level collection will be used).
- The HID Report Descriptors provided by libusb are recomposed and may present minor differences from the actual ones, as the Windows HID API does not allow to read them directly from the device.
- Because there is no native
poll()
on Windows, the ability to return externally pollable file descriptors on Windowslibusb_get_pollfd()
returns an error. - If you use a composite device, and plan to install a libusb compatible driver for any of the interfaces, you should ensure that your driver package adds a Device Interface GUID in the registry, as proper enumeration of composite devices in libusb depends on it. This is typically achieved by adding something like the following in your inf:
HKR,DeviceInterfaceGUIDs,0x00010000,{12345678-1234-1234-1234-123456789ABC}
This is in particular a problem with libusb-win32's inf-wizard which will be deprecated by libusb-win32 project. Please use Zadig instead. libusb0.sys and libusbk.sys
access is done through the libusbK DLL, therefore, if you plan to use the libusb-win32/libusb0.sys or libusbK/libusbk.sys driver in libusb, you must have that library installed. If using a recent version of Zadig, you should not have to do anything, at it will install the library for you. However the support of libusb0.sys is not ready, therefore you should not use libusb-win32/libusb0.sys for now.
Development Links
- How to Use WinUSB to Communicate with a USB Device & WinUSB (Winusb.sys) Installation.
Note that the inf file given in the howto has a typo. If you don't changeSourceDisksFiles.NTamd64
toSourceDisksFiles.amd64
, the driver installation will fail to copy the required DLLs on 64 bit systems... - Microsoft's USB Core Team Blog (including resources on instrumenting the USB stack in Windows 7)
- additionalinformation about Windows Co-Installers