Skip to content

Windows Backend

Jump to bottom Edit New page
pbatard edited this page Jul 5, 2012 · 22 revisions

IMPORTANT: NEC/Renesas USB 3.0 users, please upgrade your drivers to version 2.1.16.0 or later. Older versions of the driver have a bug that prevents libusbx from accessing devices.

Table of Contents

Overview

About

This project adds Windows platform support to the libusbx 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 (with HID keyboards and mice not accessible, as they are reserved by the OS). libusb0.sys and libusbK.sys driver support will also be added soon.

Current Status

The Windows backend is part of the libusbx official release. While it has been tested for a couple of years and is assumed stable, because it's official inclusion in a release is still recent, it should be considered EXPERIMENTAL over the next few releases.

Binary Snapshots

Pre-built binary snapshots are provided in the release directory under /<current-version>/Windows/.
These 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
Note that these archives are provided in the 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

libusbx supports USB 3.0 controllers and devices on Windows. Because of the large number of USB 3.0 controllers, the lack of official USB 3.0 support from Microsoft in Windows 7 and earlier as well as limited testing, be mindful that USB 3.0 support should still be considered experimental at this stage.

Also, if you are using a NEC/Renesas USB 3.0 controller, such as the fairly widespread uPD720200/uPD720200A, please 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.0 Support

libusbx has been tested under the various Windows 8 Previews (Developer, Consumer, Release) for both 32 and 64 bit and no issues were found.

.NET support

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

How to use libusbx on Windows

Driver Installation

If your target device is not HID, you install a driver before you can communicate with it using libusbx. Currentlty, this means installing Microsoft's WinUSB driver. Two options are available:

  • Easiest: Use the most recent version of Zadig, an Automated Driver Installer GUI application for WinUSB.
    • Note: Zadig also allows the selection and installation of the latest libusb-win32 and libusbK drivers.
  • Or you can download the WinUSB driver files and customize the inf file for your device.

Development Considerations

The handling of composite devices under Windows is done with multiple drivers, descendants 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://www.cygnal.org/ubb/Forum9/HTML/001050.html. If needed, it is also 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 libusbx file descriptors with poll() on cygwin is NOT supported. In a future version of libusbx, we should provide better handling of native Windows events, but this will require a redesign of the libusbx API, so is won't occur before libusbx 2.0.

Known Restrictions

  • WinUSB cannot be used to send an actual reset command to an USB device.
  • WinUSB cannot be used to set a device configuration that is different from the first one.
  • WinUSB does not support multiple concurrent applications (as per the MSDN documentation).
  • WinUSB does not support isochronous transfers.
  • HID keyboards and mice cannot be accessed using the native HID driver as Windows reserves exclusive access to them.
  • The HID Report Descriptors provided by libusbx 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 Windows libusb_get_pollfd() returns an error.

Development Information

To Do

  • libusb0.sys & libusbk.sys driver support
  • Hotplug detection

Links

Add a custom footer
Add a custom sidebar

Clone this wiki locally