10.2  Windows Dynamic Driver Loading

10.2.1  Windows Driver Types

Windows drivers can be implemented as either of the following types:

  • Windows Driver Model (WDM) drivers: Files with the extension *.sys on Windows 7/Vista/Server 2008/Server 2003/XP/2000/Me/98 (e.g., windrvr6.sys).
    WDM drivers are installed via the installation of an INF file (see below).
  • Non-WDM / Legacy drivers: These include drivers for non-Plug-and-Play Windows operating systems (Windows NT 4.0) and files with the extension *.vxd on Windows 98/Me.

The WinDriver Windows kernel module – windrvr6.sys – is a fully WDM driver, which can be installed using the wdreg utility, as explained in the following sections.

10.2.2  The wdreg Utility

WinDriver provides a utility for dynamically loading and unloading your driver, which replaces the slower manual process using Windows' Device Manager (which can still be used for the device INF). This utility is provided in two forms: wdreg and wdreg_gui. Both versions can be found in the WinDriver\util directory, can be run from the command line, and provide the same functionality. The difference is that wdreg_gui displays installation messages graphically, while wdreg displays them in console mode.

This section describes the use of wdreg/ wdreg_gui on Windows operating systems.

[Note]
  1. wdreg is dependent on the Driver Install Frameworks API (DIFxAPI) DLL – difxapi.dll, unless when run with the -compat option (described below). difxapi.dll is provided under the WinDriver\util directory.
  2. The explanations and examples below refer to wdreg, but any references to wdreg can be replaced with wdreg_gui.

10.2.2.1  Overview

This section explains how to use the wdreg utility to install the WDM windrvr6.sys driver on Windows, or to install INF files that register USB devices to work with this driver on Windows 7/Vista/Server 2008/Server 2003/XP/2000.

[Note]
You can rename the windrvr6.sys kernel module and modify your device INF file to register with your renamed driver, as explained in section 12.2.1. To install your modified INF files using wdreg, simply replace any references to windrvr6 below with the name of your new driver.

Usage: The wdreg utility can be used in two ways as demonstrated below:

  1. wdreg -inf <filename> [-silent] [-log <logfile>]
    [install | uninstall | enable | disable]
  2. wdreg -rescan <enumerator> [-silent] [-log <logfile>]

  • OPTIONS
    wdreg supports several basic OPTIONS from which you can choose one, some, or none:
    • -inf – The path of the INF file to be dynamically installed.
    • -rescan <enumerator> – Rescan enumerator (ROOT, USB, etc.) for hardware changes. Only one enumerator can be specified.
    • -silent – Suppress display of all messages (optional).
    • -log <logfile> – Log all messages to the specified file (optional).
    • -compat – Use the traditional SetupDi API instead of the newer Driver Install Frameworks API (DIFxAPI).
  • ACTIONS
    wdreg supports several basic ACTIONS:

    • install – Installs the INF file, copies the relevant files to their target locations, and dynamically loads the driver specified in the INF file name by replacing the older version (if needed).
    • preinstall Pre-installs the INF file for a non-present device.
    • uninstall – Removes your driver from the registry so that it will not load on next boot (see note below).
    • enable – Enables your driver.
    • disable – Disables your driver, i.e., dynamically unloads it, but the driver will reload after system boot (see note below).

[Note]
To successfully disable/uninstall your driver, make sure that there are no open handles to the WinDriver service (windrvr6.sys or your renamed driver (refer to section 12.2), and that there are no connected and enabled Plug-and-Play devices that are registered with this service.

10.2.3  Dynamically Loading/Unloading windrvr6.sys INF Files

When using WinDriver, you develop a user-mode application that controls and accesses your hardware by using the generic windrvr6.sys driver (WinDriver's kernel module). Therefore, you might want to dynamically load and unload the driver windrvr6.sys – which you can do using wdreg.
In addition, in WDM-compatible operating systems, you also need to dynamically load INF files for your Plug-and-Play devices. wdreg enables you to do so automatically on Windows 7/Vista/Server 2008/Server 2003/XP/2000.
This section includes wdreg usage examples, which are based on the detailed description of wdreg contained in the previous section.

  • To start windrvr6.sys on Windows 7/Vista/Server 2008/Server 2003/XP/2000:
    wdreg -inf <path to windrvr6.inf> install
    This command loads windrvr6.inf and starts the windrvr6.sys service.
  • To load an INF file named device.inf, located in the c:\tmp directory:
    wdreg -inf c:\tmp\device.inf install

    You can replace the install option in the example above with preinstall to pre-install the device INF file for a device that is not currently connected to the PC.

[Note]
If the installation fails with an ERROR_FILE_NOT_FOUND error, inspect the Windows registry to see if the RunOnce key exists in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion. This registry key is required by Windows Plug-and-Play in order to properly install drivers using INF files. If the RunOnce key is missing, create it; then try installing the INF file again.

To unload the driver/INF file, use the same commands, but simply replace install in the examples above with uninstall.