wiki:windows_backend

Version 57 (modified by pbatard, 3 years ago) (diff)

--

Windows backend

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

The Windows backend is now in pre-release stages. As of 2010.02.17, it include all of the main libusb v1.0 features, for both HID and WinUSB devices, apart from isochronous transfers (which is a limitation from the WinUSB Microsoft API).
It currently supports all Windows platforms from Windows XP, including 64 bit versions of Windows (Windows 2003 is untested).

Supported development environments

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

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)
git pull                                          ; keep in sync with the remote tree

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.

To create projects relying on libusb 1.0, please refer to how the example executables (lusb, xusb) are compiled.

.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, if the device is not HID compliant, you will need to install the relevant driver. Two options are available:

  • The easiest option is to use the the setdrv executable (BETA - part of the Windows Driver Installer library, libwdi). The current version, which is compatible with both 32 and 64 bit Windows platforms, can be downloaded below and will install a WinUSB driver for any USB device that is currently plugged, and that doesn't have a driver.
    Note that because parts of the installer need to run with administrative privileges, it is recommended to check the md5sum after download (or recompile your own version from ​the source)
    • ​setdrv_20100330.exe (4.9 MB, md5sum:6ff24004db57c1ad4789888fe1216594) Compiled with DDK 7600.16385.0 from w23.
  • 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.

Latest binary snapshots

The following binary snapshots are provided for your convenience, generated for the following environments:

  • Microsoft Visual Studio and DDK/SDK: DLL, static lib and examples -> MS32 and MS64 directories
  • MinGW: DLL and static lib -> MinGW32 directory

cygwin users should be able to use the MinGW 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

  • For the first release, only ​WinUSB and HID access will be supported, with provisions for other access modes to be included later. This should cover most devices however.
  • Windows' handling of composite devices is done with multiple drivers (VID_####&PID_####&MI_##), descendants of the usbccgp.sys driver (Composite Generic Parent). For more info, see "2. How Windows handles a composite device" at ​http://www.cygnal.org/ubb/Forum9/HTML/001050.html.
  • 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. We should provide native Windows events, to use with WaitForSingleObject/WaitForMultipleObjects?, in a future version of libusb.

Known Restrictions

  • WinUSB does not support multiple concurrent applications (as per the ​WinUSB Howto whitepaper).
  • WinUSB does not support isochronous transfers.
  • Windows does not allow read or write access to HID keyboards and mice
  • Windows does not allow generic USB access to HID devices or interfaces for which the OS has a specific, non generic driver (eg. HID audio devices)
  • 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

  • automated driver installation
  • multithreaded sample application
  • libusb0.sys integration
  • hotplug detection

Done

  • full pthread-win32 dependency removal
  • multithreading/concurrent access
  • HID
  • 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

  • [2010.01.14 and later] Please consult the ​git log or the raw Activity Log.
  • [2009.12.13 to 2010.01.13] Tracked on the the ​Work-In-Progress SVN Repository (no longer maintained).
  • [2009.12.12]
    • Back on track after resubmission of git patches and timer related fixes.
  • [2009.12.04]
  • [2009.12.03]
    • matching of libusb enumerated devices with WinUSB GUID devices (WIP)
    • ​WinUSB driver cleanup & documentation.
  • [2009.12.02]
    • WinUSB generic device installation (x86 & x64)
    • retrieval of device handles for use with WinUSB
    • WinUSB init
  • [2009.12.01]
    • configuration descriptors retrieval
    • initial possible API breakdown & more code cleanup
  • [2009.11.30]
    • Added clock_gettime() with hires timer detection for monotonic and GetSystemTimeAsFileTime?() (100 ns resolution) for realtime.
    • Moved the USB 2.0 root hub caps detection into set_hcd_device_descriptor()
  • [2009.11.29]
    • First release with working lsusb enumeration

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