Install (original) (raw)

Installing and compiling libwdi

Table of Contents

• Latest official release
• Prerequisites
• Configuration & Compilation
• Using a custom driver file with libwdi

Latest official release

The latest official release of libwdi can be downloaded here. Or you can also use git to retrieve the latest development tree.

Prerequisites

Compilation of libwdi is supported for the following environments, with the restrictions indicated below:

• MinGW (32 bit):
  Will only allow the production of a 32 bit library, which is incompatible with 64 bit Windows platforms. The produced binary can be used on Windows 7 or later.
• MinGW-w64 (64 bit):
  By default, will only produce 64 bit binaries, that are incompatible with 32 bit platforms. However, you can recompile MinGW-w64 so that it supports the -m32 option (for production of 32 bit binaries) or try to find a pre-built (and working!) multilib version to produce 32 bit binaries that are compatible with 64 bit platforms.
• Microsoft Visual Studio, either 2019 or later:
  The Community Edition (CE) is recommended for anyone, even if you are a corporate/enterprise user, as libwdi is an Open Source project using an OSI-approved license, therefore, as long as you use Visual Studio CE with libwdi, there are no restriction to your ability to freely install and use Visual Studio.
  A very comprehensive walk-through on how to install Visual Studio Community Edition to compile and debug libwdi/Zadig is available here. Note that, even though Visual Studio comes with a partial WDK, you will also need to install the Redistributable WDK 8 Components from here to enable WinUSB installation.
• Cross compilation:
  Is supported, as per git revision w120 (or libwdi v1.0.3). The standard --host=<host-triplet> option can be applied to either configure or autogen.sh
  Because the building if libwdi relies on running a custom embedder during the build process, your build platform must be able to compile code that can run on the platform. As such, you might have to specify the CC_FOR_BUILD environment variable with the relevant options for your build environment. For more information, have a look at the FAQ.

Depending on the driver files you are planning to enable in libwdi, you may also require:

• The latest libusb0.sys driver files from libusb-win32
• The latest libusbK.sys driver files from libusbK.

MinGW compilation also requires the following packages to be installed:

• autotools (automake, autoconf, libtool), if running the autogen.sh from git
• getopt, to compile the wdi-simple sample

Configuration & Compilation

IMPORTANT: If you are not using the WDK 8 redistributable components, you must edit your config.h and set WDF_VER to the relevant WDF version. For instance, if you used the WinUSB installer files from WinDDK 7600.16385.0, you should use: WDF_VER=1009 (when compiling with MS compilers) or add the option --with-wdfver=1009 when invoking configure (MinGW).

Provided that you have one of the environments highlighted above and retrieved the source (either from a tarball or the git repository), you need to configure the building of libwdi as follows:

• MinGW, cygwin or cross compilation:
  • (Optional) If cross-compiling, and if the default CC (as detected by configure) does not produce executables that can run on your platform, define a CC_FOR_BUILD environment variable with the required options.
  • (Optional) If downloaded from git, from a shell prompt, run ./autogen.sh. This is required to create the configure and Makefile scripts. You can feed the same options to autogen.sh as the ones you feed to configure
  • Run configure --help to select your options, or refer to the list below, and then run configure:
    * --enable-shared: build shared libraries (default y)
    * --enable-static: build static libraries (default y)
    * --enable-32bit: build 32 bit compatible library if -m32 is available (default y)
    * --enable-64bit: build 64 bit compatible library if -m64 is available (default y)
    * --enable-log: enable library logging (default y)
    * --enable-debug-log: force debug logging (cannot be disabled, default n)
    * --enable-toggable-debug: enable switchable debug logging (default n)
    * --enable-debug: include debug symbols for gdb (default y)
    * --enable-examples-build: build example applications (default n)
    * --with-wdkdir="<dir>": embed WDK redistributable components files from the following location
    * --with-libusb0="<dir>": embed libusb0 driver files from the following location
    * --with-libusbk="<dir>": embed libusbK driver files from the following location
    * --with-userdir="<dir>": embed user defined driver files from the following location
    Notes:
    1. At least one of --with-wdkdir, --with-libusb0, --with-libusbK, --with-userdir must be specified when running configure.
    2. If not cross-compiling, configure will check the WDK, libusb0 and libusbK directories for the relevant driver files, and alert you if they are not found.
  • Run 'make'
  • The resulting library and examples can be retrieved in the .libs directory
• Visual Studio:
  • Edit the file msvc/config.h to set/modify your options, or refer to the list below:
    * #define WDK_DIR "<dir>": embed WDK redistributable components from the following location
    * #define LIBUSB0_DIR "<dir>": embed libusb-win32 driver files from the following location
    * #define LIBUSBK_DIR "<dir>": embed libusbK driver files from the following location
    * #define USER_DIR "<dir>": embed user defined driver files from the following location
    * #define OPT_M32: build 32 bit compatible library if possible
    * #define OPT_M64: build 64 bit compatible library if possible
    * #define ENABLE_LOGGING: enable library logging
    * #define ENABLE_DEBUG_LOGGING: force debug logging (cannot be disabled)
    * #define INCLUDE_DEBUG_LOGGING: enable switchable debug logging
    * #define WDF_VER: define the version of the WDF CoInstaller for WinUSB. If you are using the current version, this should be set to "01011"
    Notes:
    1. Make sure you edit msvc/config.h and set at least one of WDK_DIR, LIBUSB0_DIR, LIBUSBK_DIR or USER_DIR to a valid directory.
  • Select your target (Release/Debug, Win32/x64) and select 'Build'
  • The resulting library and examples can be retrieved from <arch>\<Release|Debug> (eg: .\x64\Release\)

Using a custom driver file with libwdi

If you have a custom driver that you would like to use with libwdi (eg, a custom USB .sys file and DLL, or a driver with a signed .inf+.cat), you can configure libwdi to install your driver instead of libusb0/libusbK/WinUSB:

1. Create a directory containing all the required driver files you need to embed in the library. This directory will be parsed recursively when creating the library, and recreated with the exact same structure (but in the libwdi user directory) before installation.
2. Use either the --with-userdir option when running configure (MinGW/cross-compilation) or set the #define USER_DIR in msvc/config.h (MS environments) to point to the directory above. You can also setup the WinUSB, libusb0 or libusbK directories if you want to include these driver files as well.
3. In your application, use wdi_prepare_driver() with the driver_type set to WDI_USER for the options parameter (or, if this is the only driver embedded, you can leave the options blank) and call wdi_install_driver with the name of your inf file.

Notes:

1. Unless you manually edit libdwi/embedder_files.h it is not possible to differentiate between a 32 bit or 64 bit install, so both the 32 and 64 bit driver files must be included in your directory
2. Because it is impossible for libwdi to guess how the inf file for a custom driver should be generated, you must provide your own inf file along with the driver, and set all its parameters accordingly.