wiki:windows_backend

Version 198 (modified by pbatard, 20 months ago) (diff)

--

Windows backend

Windows backend

  1. About
  2. Status
  3. Supported development environments
  4. Source
  5. Creating applications using libusb
  6. USB 3.0 support
  7. .NET support
  8. Driver Installation
  9. Latest Binary Snapshots
  10. Development Considerations
  11. Known Restrictions
  12. To Do
  13. Done
  14. Development's status log
  15. Development Links
  16. Mailing list

IMPORTANT: If you are using a NEC/Renesas USB 3.0 controller, please upgrade your controller drivers to ​version 2.1.16.0 or later.
Older versions of the driver are known to prevent libusb from accessing devices.

About

The aim of this project is to bring a Windows backend to the mainline libusb 1.0 branch, so that libusb 1.0 can easily be used on Windows platforms.

Status

As is the case with newly integrated code, the Windows backend should be considered EXPERIMENTAL and will continue to remain so until a few months after official integration has been completed. Currently, it is still in pre-release stages, with only parts of it included in the official libusb v1.0 tree (MinGW and cygwin only for the time being) and hopefully more coming soon. For now, the backend itself supports ONLY WinUSB as the device driver, with libusb0 and libusbK driver support planned for a future release.

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 support WinUSB on 64bit Windows XP)

Supported development environments

The following development environments are currently supported for libusb 1.0 on Windows:

  • ​MinGW (32 bit) or ​MinGW-w64. ​TDM64 is a good MinGW-w64 distribution under Windows. It is also possible cross-build libusb-1.0 Windows backend under Linux or other OS using MinGW and MinGW-w64.
  • ​Microsoft Visual C++ (Visual Studio), either Express or full version, starting with version 6.0. You should be able to produce both win32 and x64 binaries using Visual C++. Take note that the Express version of Visual C++ can not produce 64bit binaries. Also note that Microsoft crippled the 2010 version of Visual C++ Express, so that it chokes on importing project files that have 64 bit builds. If you plan on using Express 2010, you'll have to recreate the project files from scratch.
  • ​Windows DDK build environment, which is freely available, through the use of the 'ddk_build.cmd' file. This will also produce both 32 and 64 bits binaries.
  • ​Cygwin. Cygwin currently can not produce 64bit binaries.

Source

The current development Windows backend is available in the ​libusb main git repository under ​libusb-pbatard.git.

For those not familiar with git, here are the git commands you can use retrieve and compile the Windows branch: 

git clone git://git.libusb.org/libusb-pbatard.git ; retrieve development branch (this only needs to be done once)
cd libusb-pbatard
git pull                                          ; keep in sync with the remote tree

If you want to switch to using a branch (eg. HID), you can do so by issuing the following. This only needs to be done if you want to use an alternate branch (i.e. if you know what you are doing). If you are new to libusb/Windows, you should skip this part. 

git branch -a                                     ; list all the remote branches
git checkout -b HID origin/HID                    ; switch to the HID branch

On Windows, if you don't want to use git on the commandline, you can use ​TortoiseGit to access and keep in sync with the git repository.
Note that before you can install ​TortoiseGit you need to install ​MSysGit and make sure that, during the installation of MSysGit, when prompted to adjust the PATH environment, you select "Run Git from the Windows Command Prompt" (2nd option). Also, in the general settings of ​TortoiseGit, the MSysGit path must point to the MSysGit bin directory (eg: C:Program Files (x86)Gitin")

Also note that, for MinGW and cygwin, as with the original libusb 1.0 development tree, you need to run './autogen.sh' in order to have configure and Makefile created for you.

Creating applications using libusb

To create projects relying on libusb 1.0, please refer to how the example executables (lusb, xusb) are compiled.
If you use a revision post pbr315, no additional libraries are needed besides libusb.

USB 3.0 support

libusb 1.0 should support USB 3.0 controllers and devices on Windows (from pbr339 onwards). Because of the large number of USB 3.0 controllers existing, the lack of official support of USB 3.0 support from Microsoft and limited testing, be mindful that USB 3.0 support should be considered experimental at this stage and may not work as expected. Also, if you are using a NEC/Renesas USB 3.0 controller, such as the fairly widespread uPD720200/uPD720200A, you MUST upgrade your controller drivers to ​version 2.1.16.0 or later. Older versions of the driver have a bug that prevents access to USB devices with libusb.

.NET support

A .NET version of libusb, called ​LibUsbDotNet, based on libusb 1.0 and the Windows backend has also been developed by Travis Robinson.
If you plan to use libusb in a .NET project, please make sure you check ​http://libusbdotnet.sourceforge.net or ​http://sourceforge.net/projects/libusbdotnet/

Driver Installation

To access your USB devices with the Windows backend you need to install the relevant driver. Two options are available:

  • The easiest option is to use the most recent version of our Automated Driver Installer GUI: "zadig.exe", which is part of the Windows Driver Installer library, ​libwdi.
    The current version, which is compatible with both 32 and 64 bit Windows platforms, should be able to install a WinUSB driver for any USB device for supported Windows OS versions like XP, Vista and Windows 7.
    Note that because the installer needs to run with administrative privileges, it is recommended to check the md5 checksum after download (or recompile your own version from ​the source)
  • Or you can download the ​WinUSB driver files, then customize the .inf for your device and install the driver by following the instructions that are either provided here or in the README file that comes with the driver archive.

Latest Binary Snapshots

The following pre-built binary snapshots 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

Cygwin users should be able to use the MinGW (32 bit) library with the option -mno-cygwin
Note that these archives are provided in the 7z format. If you need a decompressor, you can install ​7-zip.

Development Considerations

  • If you want to access devices outside of WinUSB ​WinUSB or libusbK, such as HID ones, you can use the ​HID branch, which is maintained separately due to an executive decision by the current libusb maintainer to remove HID support for Windows. Or you can use another library such as ​HIDAPI.
  • Windows' handling of composite devices is done with multiple drivers (VID_####&PID_####&MI_##), descendants of the usbccgp.sys driver (Composite Generic Parent), as this is Windows' default. For more info, see "2. How Windows handles a composite device" at ​http://www.cygnal.org/ubb/Forum9/HTML/001050.html. It is however possible to replace the composite parent driver with WinUSB 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 will try to provide better handling of native Windows events, but this will require a redesign of the libusb API, so is unlikely to 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 the Microsoft driver.
  • WinUSB cannot be used to set a device configuration that is different from the default one. This is a limitation of the Microsoft driver.
  • WinUSB does not support multiple concurrent applications (as per the ​WinUSB Howto whitepaper).
  • WinUSB does not support isochronous transfers.
  • Because there is no native poll on Windows, the ability to return externally pollable file descriptors on Windows (libusb_pollfd) has been disabled.

To Do

  • libusbK.sys integration
  • hotplug detection

Done

  • HID removal
  • automated driver installation (​libwdi)
  • full pthread-win32 dependency removal
  • multithreading/concurrent access
  • HID support
  • device enumeration
  • descriptors retrieval
  • composite devices & interface selection
  • poll and pipe
  • control transfers
  • bulk/interrupt transfers
  • device reset
  • transfer cancellation
  • MSVC compatibility

Development's status log

Please consult the ​git log or the raw ​Activity Log.
NB: Previous development occurred on the ​Google Code SVN Repository but this is no longer maintained.

Mailing list

The libusb-devel mailing list exists for the users of the library, plus developers interested in contributing to the library itself.

Attachments

Download all attachments as: .zip