wiki:libwdi

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

--

Windows Driver Installer library for libusb (libwdi)

About

The aim of this project is to create a library that facilitates the foolproof installation of any USB driver required to use a libusb application on Windows.

Features

  • all required driver files are provided by the library - no need for additional downloads
  • automated inf generation or can be used to along with your own inf files (including signed ones)
  • compatible with 32 and 64 bit Windows platforms, starting with Windows XP, with the possibility to either produce 2 separate libraries, for 32 or 64 bit, or a single library that covers both 32 and 64 bit at the same time.
  • can either be integrated in your libusb application, so that a single executable application can be redistributed without the need for an additional installer, or to create a separate installer application (the library itself does not have any libusb dependency)

Status

As of 2010.04.29, libwdi (the library) is in functional beta. The installer applications are still in alpha.

Documentation

Coming soon!

Supported development environments

The following development environments are currently supported for libwdi on Windows:

  • ​MinGW (32 bit) or ​MinGW-w64. To compile a library that is both 32 and 64 bit compatible, you should use a version of MinGW-w64 that supports both -m32 and -m64
  • ​Microsoft Visual C++ (Visual Studio) 2008. Only the full version will allow you to produce 64 bit or or 32+64 bit binaries.
  • ​Windows DDK build environment, which is freely available, through the use of the 'ddk_build.cmd' file. This will also produce all of 32, 64 or 32+64 bits binaries. Note that if you want to produce libwdi applications that are compatible with all supported platforms, you will need to use the Windows XP DDK build environment
  • ​cygwin (32 bit only).

The recommended development environment to compile the library/apps is Windows DDK as it allows the building of a 32+64 bit compatible library, with UAC elevation, and ensures that the required WinUSB DLL files are available.

Source

The current development tree is available in the ​libusb main git repository under ​libusb-pbatard/wdi.

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 branch -a                                     ; list all the remote branches
git checkout -b wdi origin/wdi                    ; switch to the libwdi branch

If you don't want to use git from 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 libusb development tree, you need to run './autogen.sh' in order to have configure and Makefile created for you.

To create projects relying on libwdi, please refer to how the sample executables zadic (console) and zadig (GUI) are compiled.

Development Considerations

  • Because the driver installation requires administrative privileges, but enumeration does not, the library compiled and embeds a 32/64 bit installer, that requires UAC elevation on platforms supporting UAC (Windows Vista and later).
  • The project also uses a customer embedder to include the required driver resources (DLLs, 32 and 64 bit installer). Note that since most of the DLLs are already compressed, there's not much space to be gained in using compression in the embedder.
  • The reliance on DifXAPI.dll was dropped in w20, as the DLL is not available by default on XP and would increase the binary size.
  • It is possible to produce a 32 bit library that is 32+64 bit compatible, but the opposite is not true. As such, when compiling for 64 bit only, 32 bit compatibility will be removed to make the library smaller.

To Do

  • downloading vs embedding of the driver files
  • allow the editing of the device name
  • libusb0.sys driver support

Done

  • GUI sample application (alpha)
  • MinGW/cygwim/MSVC/DDK support
  • 32 and 64 bit support and compilation time detection
  • UAC elevation
  • retrieval of device name
  • automated inf generation

Development's status log

Please consult the ​git log or the WDI section of the raw Activity Log.