Technical Document #84

Technical Document #84        [Product Version: 8.1.1 and above]
Upgrading your WinDriver version

This document outlines the steps for upgrading from version 8.1.1 or newer to the latest WinDriver version. For upgrade instructions from an earlier version of WinDriver and/or to an earlier version, refer to Technical Document #131.

Upgrade Steps

  1. Install the new version
  2. Acquire a New WinDriver License (Registered Users)
  3. Upgrade Your Driver Project
  4. Upgrade Your Device INF File (Windows)
  5. Digitally Sign Your Driver Files (Windows)
  6. Upgrade Your Driver Distribution/Installation Package

  1. Install the new version
  2. Download and install a new version of WinDriver that matches your development platform and the operating systems and CPU configurations of the target platforms on which you intend the driver to be used.

  3. Acquire a New WinDriver License (Registered Users)
  4. If you are using a registered version of WinDriver, contact Jungo Connectivity at [email protected] to acquire a WinDriver license registration string for the new version. Then register the new license from DriverWizard (File | Register WinDriver) and from your code.

    Note that if you have a valid Support and Upgrade plan you are are entitled to receive a new license free of charge.
    If you do not have such a plan, contact [email protected] to request a temporary license that will allow you to evaluate the new version.

  5. Upgrade Your Driver Project
    • Register Your New License (Registered Users): Modify the driver code to register your new license — i.e., replace the license string in the call to WDU_Init() (USB) / WDC_DriverOpen() (PCI/ISA — WDC API) / WD_License() (low-level API) from your code.

      PCI users — if you created a Kernel PlugIn driver, make sure to also update the license string in your Kernel PlugIn code.

    • PCI/ISA users upgrading from v11.7.0 or below — refer to Technical Document #116 for information on API changes done in v11.8.0 of WinDriver, and edit your code accordingly.

    • 64-bit OS upgrade (Windows and Linux)
      • When developing a driver for a 64-bit platform, your project or makefile must include the KERNEL_64BIT preprocessor definition. In the makefiles, the definition is added using the -D flag: -DKERNEL_64BIT. The sample and wizard-generated Linux and Windows GCC makefiles and Windows MS Visual Studio projects in the 64-bit WinDriver toolkit already add this definition.

      • PCI Kernel PlugIn upgrade from v10.2.1- — to support execution of 32-bit applications with a 64-bit Kernel PlugIn driver, follow the instructions in Technical Document #112.

    • Rename your driver (Windows and Linux) — To avoid conflicts with other WinDriver-based drivers on the target platforms, we highly recommend that you rename the default WinDriver driver module — windrvr<version>.sys (e.g., windrvr1200.sys) on Windows / windrvr<version>.o/.ko (e.g., windrvr1200.o/.ko) on Linux (or windrvr6.sys / windrvr6.o/.ko in v11.8.0 and older) — to a unique name, by following the instructions in the new WinDriver User's Manual. The renaming procedure is simple and quick.
      The Linux USB GPL driverwindrvr<version>_usb.o/.ko (or windrvr6_usb.o/.ko in v11.8.0 and older) is automatically renamed when renaming the main WinDriver Linux driver.
      When creating a PCI Kernel PlugIn driver, select a unique name as well.

    • Ensure that your code uses the correct driver module — Verify that the call to WD_DriverName() in your driver code (if exists) uses the new driver-module name — windrvr<version> or your renamed version of this driver.
      In version 11.9.0 of WinDriver the default WinDriver driver-module name changed from windrvr6 to windrvr<version> (e.g., windrvr1200 in v12.0.0). Consequently, when using the default driver-module name old projects need to be updated to use the default name from the newer version. If you use the generated DriverWizard code or one of the samples from the new WinDriver version, the code will already use the default driver name from the new version. Also, if your code is based on generated/sample code from an earlier version of WinDriver, rebuilding the code with windrvr.h from the new version is sufficient to update the code to use the new default driver-module name (due to the use of the WD_DEFAULT_DRIVER_NAME_BASE definition).
      If you elect to rename the WinDriver driver module, ensure that your code calls WD_DriverName() with your custom driver name. If you rename the driver from the new version to a name already used in your old project, you do not need to modify your code.
      To apply a driver name change — whether using the default driver name or a custom name — your user-mode driver project must be built with the WD_DRIVER_NAME_CHANGE preprocessor flag (e.g., -DWD_DRIVER_NAME_CHANGE), as explained in the WinDriver WinDriver User's Manuals and demonstrated in the sample and generated DriverWizard WinDriver projects/makefiles.

    • Rebuild your updated driver project with the source files from the new version.

      PCI users who created a Kernel PlugIn driver must rebuild it with the files from the new version as well.

  6. Upgrade Your Device INF File (Windows)
  7. On Windows, if you have created a driver for a Plug-and-Play device (USB/PCI/CardBus/PCMCIA), we recommend that you create and install a new INF file for your device, which registers it with the driver module from the new version — windrvr<version>.sys (e.g., windrvr1200.sys) / windrvr6.sys in v11.8.0 and older — or your renamed version of this driver (in v9.x and newer). You can use DriverWizard from the new version to generate the new INF file, or change the driver version in your old INF file.

  8. Digitally Sign Your Driver Files (Windows)
  9. On 64-bit versions of Windows Vista and higher, Microsoft requires that kernel drivers be digitally signed. Therefore, if you use any of the following driver files you must digitally sign them: A renamed version of the WinDriver kernel driver (the default WinDriver driver — windrvr<version>.sys / windrvr6.sys in v11.8.0 and older — is already digitally signed), a Plug-and-Play device INF file, and/or a PCI Kernel PlugIn driver. You can bypass this restriction during the development stage (e.g., on Windows 7, by pressing F8 at boot time and selecting the relevant option), but the driver files must be signed before distribution. There are also advantages to signing your driver on other Windows OSs. For more information, refer to Micorsoft's Driver Signing Policy and to the Windows Digital Driver Signing and Certification section of the WinDriver User's Manuals.

    You can obtain digital signatures from third-party companies such as DigiCert or Symantec, or use Jungo Connectivity's digital driver signing service. Jungo Connectivity can also assist you in preparing your driver for Microsoft's Windows cetification.

  10. Upgrade Your Driver Distribution/Installation Package
  11. Create a new driver installation package that contains the relevant files from the new WinDriver distribution, depending on your hardware and target OS:

    • The WinDriver driver module — windrvr<version>.sys/.o/.ko/.dll (e.g., windrvr1200.sys/.o/.ko/.dll) in the newer WinDriver versions, or a renamed version of this driver
    • The WinDriver Linux USB GPL driverwindrvr<version>_usb.o/.ko (e.g., windrvr1200_usb.o/.ko) in the newer WinDriver versions, or a renamed version of this driver
    • Your rebuilt PCI Kernel PlugIn driver — <KP_driver_name>.sys (if created)
    • Any other files required for installing or using your driver — such as wdapi<new_version>.dll/.so, wdreg[.exe]/wdreg_gui.exe (and difxapi.dll on Windows), and Windows INF and catalog files
    • An installation program that installs the new driver

    Hardware- and OS-specific driver distribution instructions can be found in the Distributing Your Driver chapter of the new WinDriver User's Manuals. The instructions for Windows are also summarized in Technical Document #132.

    Version-Specific Installation Upgrade Notes:

    • Linux USB v9.2.1- to v10.0.0+ upgrade — the WinDriver USB Linux GPL driver: Beginning with v10.0.0, the WinDriver Linux USB driver was split into two modules, which are used together to provide the full driver functionality:
      • windrvr6.o/.ko, renamed in v11.9.0 to windrvr<version>.o/.ko (e.g., windrvr1200.o/.ko) — the traditional WinDriver driver module, which includes the product license.
      • windrvr6_usb.o/.ko, renamed in v11.9.0 to windrvr<version>_usb.o/.ko (e.g., windrvr1200_usb.o/.ko) — this driver implements Linux-specific USB driver functionality, and contains a GNU General Public License (GPL).