Skip to content

Home

Jump to bottom
Pete Batard edited this page Feb 5, 2014 · 39 revisions

libwdi: Windows Driver Installer library for USB devices

Table of Contents

Description

About

The aim of this project is to provide Windows application developers and driver makers, with a convenient way of extracting and installing USB drivers on end-users systems. Such drivers can then be used with, but not limited to, libusb applications using libusbx, libusb-win32 or libusbK.

Getting Support

If you have a question that cannot be answered in these pages, your best option is to send a mail to the libwdi-devel mailing list (registration required). Or you can also try to e-mail developers directly.

Alternatively, you can also use the github facility to log an issue.

Features

Main Features

  • Automated signed driver package creation and installation, using the name reported by the USB device
  • No security warnings during driver installation, when running in elevated mode
  • One-off WCID device driver installation support, so that no further driver installation is required for any WCID device of the same type
  • Dual 32 and 64 bit platform support
  • Supports any Windows platforms, from Windows XP up to Windows 8
  • Single library that can be statically or dynamically linked to your application in order to provide driver installation facilities at runtime

Additional Features

Downloads

Zadig is a standalone driver installer GUI application, built on libwdi and ready to run. You may have to install a decompressor, such as 7-zip, to be able to uncompress the .7z file.

Documentation

  1. FAQ

  2. Using Zadig (the GUI driver installer application)

  3. Library Installation & Configuration

  4. Library API Documentation & Usage

  5. Signed driver installation walkthrough

  6. WCID Devices

Reusable Code Parts: Can our code solve your problems?

As a FOSS developer, there's nothing more frustrating than having to reinvent the wheel while harbouring a strong suspicion that someone, somewhere, might already have solved a similar issue. On the other hand, googling around and looking through scores of FOSS code listings to find that particular section of code which might be of interest to you is quite time consuming. Wouldn't it be just swell if the developers simply gave an detailed, high level overview of the problems they solved, whose solutions they think you can reuse?

The following page does just that and goes through a list of the features we implemented, which you might be interested in (provided your license is compatible with LGPL):

Development

Supported 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 (a.k.a. "multilib"). TDM64 is a good MinGW-w64 distribution under Windows which fulfils this requirement.
  • Microsoft Visual C++ (Visual Studio) 2008 or later. If using the Express version, you may have to download and additional SDKs 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 from XP onwards, you will need to use the Windows XP WDK build environment for the 32bit builds and Windows Server 2003 build environment for the 64bit build.
The recommended development environment to compile the library/apps is the Windows 7 WDK as it allows the building of a 32+64 bit compatible library, and ensures that the required WinUSB DLL files are available.

Source

The current development tree is available from our github repository.

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

git clone git://github.com/pbatard/libwdi.git ; retrieve development branch (this only needs to be done once)
git pull                                      ; for further updates, once the clone has been done

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.

Also note that, for MinGW you need to run ./autogen.sh (after editing it according to your paths) or run the autotools creation utilities, in order to have configure and Makefile created for you.

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

Development Considerations

  • Because driver installation requires administrative privileges, but enumeration does not, the library compiles and embeds a 32/64 bit installer which will require 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) along with any files you want to add (eg. signed inf).
  • The reliance on DifXAPI.dll, which we originally used, was dropped early on as the DLL is not available by default on XP and embedding it would drastically 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, 32 bit compatibility will be removed to make the library smaller.

Progress

To Do

  • Downloading vs embedding of the driver files
  • 7z based improved embedder
Dropped until further notice
  • Standalone signing utilities for the MinGW-w64 project
Done
  • libusb-win32 filter driver support
  • WCID driver support
  • provision of a custom GUID and other inf features
  • self signed .cat creation, for promptless install
  • disabling of the creation of a restore point
  • libusbk.sys driver support
  • trusted publisher certificate installation for promptless install
  • cross-compilation & embedder improvements
  • GUI sample application (Zadig)
  • documentation
  • allow the editing of the device name
  • libusb0.sys driver support
  • MinGW/cygwim/MSVC/DDK support
  • 32 and 64 bit support and compilation time detection
  • UAC elevation
  • retrieval of device name
  • automated .inf generation

Status log

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

Links

CC-BY-SA 4.0
Copyright © 2012-2024 Pete Batard

Clone this wiki locally