Changes between Version 203 and Version 204 of windows_backend


Ignore:
Timestamp:
10/19/11 19:15:22 (19 months ago)
Author:
pbatard
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • windows_backend

    v203 v204  
    99 
    1010This project adds Windows platform support to the [[WikiStart|libusb-1.0]] Open Source library, in order to help developers easily communicate with USB devices on Windows.[[BR]] 
    11 Currently it supports the [http://msdn.microsoft.com/en-us/library/windows/hardware/ff540174.aspx WinUSB] driver for generic USB device access, with more drivers to be added later. 
     11Currently it supports the [msdn.microsoft.com/en-us/library/windows/hardware/ff540207.aspx WinUSB] driver for generic USB device access, with more drivers to be added later. 
    1212 
    1313== Status == 
    … …  
    2323The following development environments are currently supported for libusb 1.0 on Windows: 
    2424  * [http://www.mingw.org MinGW] (32 bit) or [http://mingw-w64.sourceforge.net/ MinGW-w64]. [http://tdm-gcc.tdragon.net/download 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. 
    25   * [http://msdn.microsoft.com/en-us/visualc/default.aspx 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. 
     25  * [http://msdn.microsoft.com/en-us/visualc/default.aspx 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 you may have to install the Windows SDK if trying to compile for 64 bit with Visual C++ Express. 
    2626  * [http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=36a2630f-5d56-43b5-b996-7633f2ec14ff 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. 
    2727  * [http://www.cygwin.com/ Cygwin]. Cygwin currently can not produce 64bit binaries. 
    … …  
    4444 
    4545On Windows, if you don't want to use git on the commandline, you can use [http://code.google.com/p/tortoisegit/ TortoiseGit] to access and keep in sync with the git repository.[[BR]] 
    46 Note that before you can install [http://code.google.com/p/tortoisegit/ TortoiseGit] you need to install [http://code.google.com/p/msysgit/ 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 [http://code.google.com/p/tortoisegit/ TortoiseGit], the MSysGit path must point to the MSysGit bin directory (eg: C:Program Files (x86)Gitin") 
     46Note that before you can install [http://code.google.com/p/tortoisegit/ TortoiseGit] you need to install [http://code.google.com/p/msysgit/ MSysGit]. 
    4747 
    48 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'''. 
     48Also 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'''. 
    4949 
    5050== Creating applications using libusb == 
    5151 
    52 To create projects relying on libusb 1.0, please refer to how the example executables (lusb, xusb) are compiled.[[BR]] 
    53 If you use a revision post '''pbr315''', no additional libraries are needed besides libusb. 
     52To create projects relying on libusb 1.0, please refer to how the example executables ({{{lsusb}}}, {{{xusb}}}) are compiled.[[BR]] 
     53If you use a recent version (post [http://git.libusb.org/?p=libusb-pbatard.git;a=shortlog;js=1 pbr315]), no additional libraries should be needed besides libusb. 
    5454 
    5555== USB 3.0 support == 
    5656 
    57 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. 
     57libusb 1.0 supports USB 3.0 controllers and devices on Windows, from [http://git.libusb.org/?p=libusb-pbatard.git;a=shortlog;js=1 pbr339] onwards. Because of the large number of USB 3.0 controllers existing, the lack of official 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. 
    5858  
    59 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 [http://www.station-drivers.com/page/nec.htm version 2.1.16.0 or later]. Older versions of the driver have a bug that prevents access to USB devices with libusb. 
     59Also, if you are using a NEC/Renesas USB 3.0 controller, such as the fairly widespread uPD720200/uPD720200A, you please make sure that your controller drivers are [http://www.station-drivers.com/page/nec.htm version 2.1.16.0 or later]. Older versions of the drivers have a bug that prevents access to USB devices when using libusb. 
    6060 
    6161== .NET support == 
    6262 
    6363A .NET version of libusb, called [http://libusbdotnet.sourceforge.net/V2/Index.html LibUsbDotNet], based on libusb 1.0 and the Windows backend has also been developed by Travis Robinson.[[BR]] 
    64 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/] 
     64If you plan to use libusb in a .NET project, make sure you check [http://libusbdotnet.sourceforge.net] or [http://sourceforge.net/projects/libusbdotnet/] 
    6565 
    6666== Driver Installation == 
    6767 
    6868To access your USB devices with the Windows backend you need to install the relevant driver. Two options are available: 
    69   * 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, '''[http://libwdi.sf.net libwdi]'''.[[BR]] 
    70   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. [[BR]] 
    71   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 [http://git.libusb.org/?p=libwdi.git;a=shortlog the source])[[BR]] 
    72    * [https://sourceforge.net/projects/libwdi/files/zadig/ zadig.exe] (You may have to install [http://www.7-zip.org/download.html 7-zip] to uncompress the .7z file)[[BR]] 
     69  * The easiest option is to use the most recent version of the Automated Driver Installer GUI application '''[https://sourceforge.net/projects/libwdi/files/zadig/ Zadig.exe]''', which is part of [http://libwdi.sf.net libwdi], the Windows Driver Installer library.[[BR]] 
     70  The current version, which is compatible with both 32 and 64 bit Windows platforms starting with Windows XP, can install a WinUSB driver for any USB device.[[BR]] 
     71  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 [https://sourceforge.net/apps/mediawiki/libwdi/index.php?title=Main_Page#Source the source])[[BR]] 
     72   * '''[https://sourceforge.net/projects/libwdi/files/zadig/ Zadig.exe]''' (You may have to install [http://www.7-zip.org/download.html 7-zip] to uncompress the .7z file)[[BR]] 
    7373     NB: When run in advanced mode, Zadig should allows the selection and installation of the latest [http://sourceforge.net/apps/trac/libusb-win32/wiki libusb-win32] and [http://code.google.com/p/usb-travis/ libusbK] drivers.[[BR]] 
    74   * Or you can download the [http://libusb-winusb-wip.googlecode.com/files/winusb%20driver.zip WinUSB driver files], then customize the .inf for your device and install the driver by following the instructions that are either provided [wiki:winusb_driver_installation here] or in the README file that comes with the driver archive. 
     74  * Or you can download the [http://libusb-winusb-wip.googlecode.com/files/winusb%20driver.zip WinUSB driver files], then customize the {{{.inf}}} for your device and install the driver by following the instructions that are either provided [wiki:winusb_driver_installation here] or in the {{{README}}} file that comes with the driver archive. 
    7575 
    7676== Latest Binary Snapshots == 
    … …  
    8080  * MinGW -> MinGW32 (32 bit) and MinGW64 (64 bit) directories 
    8181 
    82 Cygwin users should be able to use the MinGW (32 bit) library with the option -mno-cygwin[[BR]]Note that these archives are provided in the 7z format. If you need a decompressor, you can install [http://www.7-zip.org/ 7-zip]. 
     82Note that these archives are provided in the 7z format so you may have to install [http://www.7-zip.org/ 7-zip]. 
    8383 
    8484  * '''[http://libusb-winusb-wip.googlecode.com/files/libusb_2011.09.23.7z 2011.09.23 (pbr345)]''' 
    … …  
    9292== Development Considerations == 
    9393 
    94   * If you want to access devices outside of WinUSB [http://msdn.microsoft.com/en-us/library/aa476426.aspx WinUSB] or libusbK, such as HID ones, you can use the [http://git.libusb.org/?p=libusb-pbatard.git;a=shortlog;h=refs/heads/HID;js=1 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 [http://www.signal11.us/oss/hidapi/ HIDAPI]. 
    95   * 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. 
    96   * 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. 
     94  * If you want to access devices outside of WinUSB [http://msdn.microsoft.com/en-us/library/ff540196.aspx WinUSB], such as HID ones, you can use the [http://git.libusb.org/?p=libusb-pbatard.git;a=shortlog;h=refs/heads/HID;js=1 HID branch], which is maintained separately due to an executive decision by the libusb maintainer to remove HID support for Windows. Or you can use another library such as [http://www.signal11.us/oss/hidapi/ HIDAPI]. 
     95  * 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. 
     96  * 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. 
    9797 
    9898== Known Restrictions == 
    … …  
    100100  * WinUSB cannot be used to send an actual reset command to an USB device. This is a limitation of the Microsoft driver. 
    101101  * WinUSB cannot be used to set a device configuration that is different from the default one. This is a limitation of the Microsoft driver. 
    102   * WinUSB does not support multiple concurrent applications (as per the [http://download.microsoft.com/download/9/C/5/9C5B2167-8017-4BAE-9FDE-D599BAC8184A/WinUsb_HowTo.docx WinUSB Howto whitepaper]). 
     102  * WinUSB does not support multiple concurrent applications (as per the [http://msdn.microsoft.com/en-us/library/windows/hardware/ff540215.aspx MSDN documenation]). 
    103103  * WinUSB does not support isochronous transfers. 
    104   * Because there is no native poll on Windows, the ability to return externally pollable file descriptors on Windows (libusb_pollfd) has been disabled. 
     104  * Because there is no native poll on Windows, the ability to return externally pollable file descriptors on Windows ([http://libusb.sourceforge.net/api-1.0/group__poll.html#gab1a72869a926552b27a6c667695df3a2 libusb_get_pollfd]) returns an error. 
    105105 
    106106== To Do == 
    107107 
    108   * libusbK.sys integration 
     108  * libusb-win32/libusbK integration 
    109109  * hotplug detection 
    110110 
    … …  
    133133== Development Links == 
    134134 
    135   * [http://msdn.microsoft.com/en-us/windows/hardware/gg487341.aspx How to Use WinUSB to Communicate with a USB Device].[[BR]]Note that the inf file given in the howto has a typo. If you don't change SourceDisksFiles.'''NT'''amd64 to SourceDisksFiles.amd64, the driver installation will fail to copy the required DLLs on 64 bit systems... 
     135  * [http://msdn.microsoft.com/en-us/library/windows/hardware/ff540174.aspx How to Use WinUSB to Communicate with a USB Device] & [http://msdn.microsoft.com/en-us/library/windows/hardware/ff540283.aspx WinUSB (Winusb.sys) Installation].[[BR]]Note that the inf file given in the howto has a typo. If you don't change {{{SourceDisksFiles.NTamd64}}} to {{{SourceDisksFiles.amd64}}}, the driver installation will fail to copy the required DLLs on 64 bit systems... 
    136136  * [http://209.85.229.132/search?q=cache:3tk2Nqp0wfoJ:www.osronline.com/article.cfm%3Farticle%3D532+selecting+configuration+descriptor+winusb Using WinUSB for User-Mode to USB Device Communication] 
    137137  * [http://msdn.microsoft.com/en-us/library/ff540046.aspx#winusb WinUSB User-Mode Client Support Routines] 
    138138  * [http://blogs.msdn.com/usbcoreblog/ Microsoft's USB Core Team Blog] (including resources on instrumenting the USB stack in Windows 7) 
    139139  * [http://blogs.msdn.com/iliast/archive/2008/03/10/why-do-we-need-wdf-coinstallers.aspx additional] [http://blogs.msdn.com/iliast/archive/2009/08/13/wdf-logo-requirements-regarding-coinstallers.aspx information] about Windows Co-Installers 
    140   * [http://msdn.microsoft.com/en-us/library/e5ewb1h3%28v=vs.71%29.aspx Enabling Memory Leak Detection in Visual C++] 
     140  * [http://msdn.microsoft.com/en-us/library/x98tx3cf.aspx Finding Memory Leaks Using the CRT Library] 
    141141 
    142142== Mailing list ==