Jungo WinDriver  
Official Documentation
Chapter 16: Dynamically Loading Your Driver

16.1. Why Do You Need a Dynamically Loadable Driver?

When adding a new driver, you may be required to reboot the system in order for it to load your new driver into the system. WinDriver is a dynamically loadable driver, which enables your customers to start your application immediately after installing it, without the need for reboot.

You can dynamically load your driver whether you have created a user-mode or a kernel-mode (see Kernel PlugIn in Chapter 12: Understanding the Kernel PlugIn) driver.

To successfully unload your driver, make sure that there are no open handles to the WinDriver service (windrvr1620.sys or your renamed driver), and that there are no connected and enabled Plug-and-Play devices that are registered with this service.

16.2. Windows Dynamic Driver Loading

Windows 7 and higher uses Windows Driver Model (WDM) drivers - files with the extension *.sys (e.g., windrvr1620.sys). WDM drivers are installed via the installation of an INF file (see below).

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

⚠ Attention

The wdreg.exe utility, included in the x64 version of WinDriver is different than the wdreg.exe utility included in the ARM64 version of WinDriver. To run the x64 version of wdreg.exe on an ARM64 platform, add the -compat flag to the cmmand.

16.2.1. The wdreg Utility

WinDriver provides an option 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 option appears in two separate utilities: wdreg and wdreg_gui.

Both utilities can be found in the WinDriver\util directory; they 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.

The explanations and examples below refer to wdreg, but any references to wdreg can be replaced with wdreg_gui.

16.2.1.1. WDM Drivers

This section explains how to use the wdreg utility to install the WDM windrvr1620.sys driver, or to install INF files that register Plug-and-Play devices to work with this driver, on Windows. You can rename the windrvr1620.sys kernel module and modify your device INF file to register with your renamed driver, as explained in 17.2.1. Windows Driver Renaming.

To install your modified INF files using wdreg, simply replace any references to windrvr1620 below with the name of your new driver.

This section is not relevant for Kernel PlugIn drivers, since these are not WDM drivers and are not installed via an INF file. For an explanation on how to use wdreg to install Kernel PlugIn drivers on Windows, refer to 16.2.1.2. Non-WDM Drivers.

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

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

OPTIONS wdreg supports several basic OPTIONS from which you can choose one, some, or none:

Options                             Description
-inf The path of the INF file to be dynamically installed.
-rescan <enumerator> Rescan enumerator (ROOT, ACPI, PCI, 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).

ACTIONS wdreg supports several basic ACTIONS:

Action                    Description
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).

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

16.2.1.2. Non-WDM Drivers

This section explains how to use the wdreg utility to install non-WDM drivers, namely Kernel PlugIn drivers, on Windows.

During development stages, it may be useful to use the wdreg_frontend GUI utility to quickly install/uninstall Kernel PlugIns.

USAGE:
wdreg [-file <filename>] [-name <drivername>] [-startup <level>] [-silent] [-log <logfile>] Action [Action ...]

OPTIONS wdreg supports several basic OPTIONS from which you can choose one, some, or none:

Option                    Description
-startup Specifies when to start the driver. Requires one of the following arguments:
-boot: Indicates a driver started by the operating system loader, and should only be used for drivers that are essential to loading the OS (for example, Atdisk).
-system: Indicates a driver started during OS initialization.
-automatic: Indicates a driver started by the Service Control Manager during system startup.
-demand: Indicates a driver started by the Service Control Manager on demand (i.e., when your device is plugged in).
-disabled: Indicates a driver that cannot be started.
The default setting for the -startup option is automatic.
-name Sets the symbolic name of the driver. This name is used by the user-mode application to get a handle to the driver. You must provide the driver's symbolic name (without the *.sys extension) as an argument with this option. The argument should be equivalent to the driver name as set in the KP_Init function of your Kernel PlugIn project: strcpy(kpInit->cDriverName, XXX_DRIVER_NAME)
-file wdreg allows you to install your driver in the registry under a different name than the physical file name. This option sets the file name of the driver. You must provide the driver's file name (without the *.sys extension) as an argument. wdreg looks for the driver in the Windows installation directory (windir%\system32\drivers). Therefore, you should verify that the driver file is located in the correct directory before attempting to install the driver.
USAGE:
wdreg -name <Your new driver name> -file <Your original driver name> install
Flag Description
-silent Suppresses the display of messages of any kind.
-log <logfile> Logs all messages to the specified file.

ACTIONS wdreg supports several basic ACTIONS:

Action Description
create Instructs Windows to load your driver next time it boots, by adding your driver to the registry.
delete Removes your driver from the registry so that it will not load on next boot.
start Dynamically loads your driver into memory for use. You must create your driver before starting it.
stop Dynamically unloads your driver from memory.

Shortcuts wdreg supports a few shortcut operations for your convenience:

Shortcut                                     Description
install Creates and starts your driver. This is the same as first using the wdreg stop action (if a version of the driver is currently loaded) or the wdreg create action (if no version of the driver is currently loaded), and then the wdreg start action.
preinstall Creates and starts your driver for a non-connected device.
uninstall Unloads your driver from memory and removes it from the registry so that it will not load on next boot. This is the same as first using the wdreg stop action and then the wdreg delete action.

16.2.2. Dynamically Loading/Unloading windrvr1620.sys INF Files

When using WinDriver, you develop a user-mode application that controls and accesses your hardware by using the generic windrvr1620.sys driver (WinDriver's kernel module). Therefore, you might want to dynamically load and unload the driver windrvr1620.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. This section includes wdreg usage examples, which are based on the detailed description of wdreg contained in the previous section.

Examples:

To load windrvr1620.inf and start the windrvr1620.sys service — wdreg -inf <path to [email protected]> install 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.

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.

16.2.3. Dynamically Loading/Unloading Your Kernel PlugIn Driver

If you used WinDriver to develop a Kernel PlugIn driver, you must load this driver only after loading the generic WinDriver driver — windrvr1620.sys.

When unloading the drivers, unload your Kernel PlugIn driver before unloading windrvr1620.sys.

Kernel PlugIn drivers are dynamically loadable — i.e., they can be loaded and unloaded without reboot. To load/unload your Kernel PlugIn driver (XXX_DRIVER_NAME.sys) use the wdreg command as described above for windrvr1620, with the addition of the name flag, after which you must add the name of your Kernel PlugIn driver.

⚠ Attention

You should not add the *.sys extension to the driver name.

💡 Recommendation

During development stages, it may be useful to use the wdreg_frontend GUI utility to quickly install/uninstall Kernel PlugIns.

Examples:

  • To load a Kernel PlugIn driver called KPDriver.sys, run this command:
wdreg -name KPDriver install
  • To load a Kernel PlugIn driver called MPEG_Encoder, with file name MPEGENC.sys, run this command:
wdreg -name MPEG_Encoder -file MPEGENC install
  • To uninstall a Kernel PlugIn driver called KPDriver.sys, run this command:
wdreg -name KPDriver uninstall
  • To uninstall a Kernel PlugIn driver called MPEG_Encoder, with file name MPEGENC.sys, run this command:
wdreg -name MPEG_Encoder -file MPEGENC uninstall

16.3. The wdreg_frontend utility

Under Windows, WinDriver features a GUI frontend utility that is designed to ease installataion / uninstallation of WinDriver and Kernel PlugIn drivers during development phases.

Every operation that can be performed with wdreg can also be performend from wdreg_frontend and their output is identical. wdreg_frontend prints out the complete wdreg command that it performed, making it easier for the developer to copy the desired command and integrate it in their own installation scripts.

⚠ Attention

Driver installation on Windows requires administrator privileges.

Loading wdreg_frontend:

The wdreg_frontend icon

Click the wdreg_frontend icon from the DriverWizard window, and then run WinDriver/util/wdreg_frontend.exe directly.

To install/uninstall an INF file:

  • Click File | Open and open the desired INF file.
  • If the file loaded correctly, all actions available for .inf files will become enabled: Install Driver, Uninstall Driver, Enable Driver, Disable Driver, Preinstall Driver.

To load/unload a Kernel PlugIn:

The dialog box wdreg_frontend will open if driver file is not located in the Windows system directory

wdreg_frontend after successfully loading a sys file

Click File | Open and open the desired sys file. If the sys file is not located in the Windows system directory, a dialog box will appear and ask if you wish wdreg_frontend to copy the sys file to the Windows system directory. If the file loaded correctly, all actions available for .sys files will become enabled: Install Driver, Uninstall Driver, Start Driver, Stop Driver, Create Driver, Delete Driver and choice of Startup level.

Further information on these actions is available on the wdreg 16.2.1.2. Non-WDM Drivers of this document:

wdreg_frontend upon successfully installing a Kernel PlugIn driver

Error message given by Windows when trying to install an unsigned driver

You may need to either digitally sign your sys file or disable digital signature enforcement for the driver to properly load and work under Windows.

16.4. Linux Dynamic Driver Loading

⚠ Attention

The following commands must be executed with root privileges.

To dynamically load WinDriver, run the following command:

# <path to wdreg> windrvr1620

To dynamically unload WinDriver, run the following command:

# /sbin/modprobe -r windrvr1620.

wdreg is provided in the WinDriver/util directory.

To automatically load WinDriver on each boot, add the following line to the target's Linux boot file (for example, /etc/rc.local):

<path to wdreg> windrvr1620

16.4.1. Dynamically Loading/Unloading Your Kernel PlugIn Driver

If you used WinDriver to develop a Kernel PlugIn driver, you must load this driver only after loading the generic WinDriver driver — windrvr1620.o/.ko.

When unloading the drivers, unload your Kernel PlugIn driver before unloading windrvr1620.o/.ko.

Kernel PlugIn drivers are dynamically loadable — i.e., they can be loaded and unloaded without reboot. Use the following commands to dynamically load or unload your Kernel PlugIn driver.

⚠ Attention

The following commands must be executed with root privileges.

xxx in the commands signifies your selected Kernel PlugIn driver project name.

To dynamically load your Kernel PlugIn driver, run this command:

# /sbin/insmod <path to kp_xxx_module.o/.ko>

When building the Kernel PlugIn driver on the development machine, the Kernel PlugIn driver module is created in your Kernel PlugIn project's kermode/linux/LINUX.<kernel version>.<CPU> directory (see 13.8.2. Linux Kernel PlugIn Driver Compilation). When building the driver on a target distribution machine, the driver module is normally created in an xxx_installation/redist/LINUX.<kernel version>.<CPU>.KP directory (see 15.3.3. Building and Installing Your Kernel PlugIn Driver on the Target).

To dynamically unload your Kernel PlugIn, run this command:

# /sbin/rmmod kp_xxx_module

To automatically load your Kernel PlugIn driver on each boot, add the following line to the target's Linux boot file (for example, /etc/rc.local), after the WinDriver driver module (windrvr1620) load command (replace <path to kp_xxx_module.o/.ko> with the path to your Kernel PlugIn driver module):

/sbin/insmod <path to kp_xxx_module.o/.ko>