Technical Document #131

Technical Document #131        [Product Version: 8.x and above]
Upgrading your WinDriver version

This document outlines the steps for upgrading from version 7.x or above to a newer version of WinDriver. For upgrade instructions for earlier versions of WinDriver, refer to Technical Document #127 .


Upgrade Steps:

  1. Preliminary Step: Verify that the New Version Supports Your Target Platform(s)
  2. Acquire a New WinDriver License (Registered Users)
  3. Upgrade Your Driver Project
  4. Upgrade Your Device INF File (Windows)
  5. Upgrade Your Driver Distribution / Installation

  1. Preliminary Step: Verify that the New Version Supports Your Target Platform(s)

    2. Before upgrading to a newer version of WinDriver, verify that the newer version supports the operating system and CPU configurations for the target platforms on which you intend the driver to be used.
    For a list of configurations supported in the latest version of WinDriver, refer to Technical Document #4.
    For an historic overview, which lists configurations supported in earlier versions of WinDriver, refer to Technical Document #50.




  2. Acquire a New WinDriver License (Registered Users)

    3. If you are using a registered version of WinDriver, contact Jungo's sales department to acquire a WinDriver license registration string for the new version. Then register the new license from DriverWizard (File | Register WinDriver) and (if you select to rebuild your code).

    Note that if you have a valid Support & Upgrade Subscription you are entitled to receive a new license free of charge.




  3. Upgrade Your Driver Project

    4. WinDriver is backwards compatible, therefore code developed with an earlier version should generally work, without modification, with the WinDriver driver module(s), provided the code is not rebuilt with the files and license from the newer version. However, in order to fully utilize the new driver module and enjoy all bug fixes and enhancements provided by the newer version, it is recommended to also upgrade your driver project to use the new driver files.
    Note: The Kernel PlugIn is not backwards compatible. Therefore, when upgrading to a new version of WinDriver, you must also #kp_upgraderebuild your Kernel PlugIn driver (if you have created such a driver) using the new version.

    To upgrade your driver code, follow these steps:

    • WinDriver API DLL / Shared Object Upgrade:
      In version 8.0.0 we implemented versioning of the high-level WinDriver API DLL/shared object. Consequently, the name of this module has changed from wd_utils to wdapi<version> (e.g., wdapi800 for version 8.0.0 of WinDriver). This enables you to upgrade your driver, including the DLL/shared object, without worrying about the possible effects on other drivers, developed with earlier versions of WinDriver, which may be using the same module.

      To use the new WinDriver API DLL/shared object, simply build your code with the new version's library module — WinDriver\lib\<CPU>\wdapi<new_version>.lib (Windows — MS Visual Studio, Windows CE) / WinDriver\lib\<CPU>\wdapi_borland<new_version>.lib (Windows — Borland C++ Builder — in WinDriver v11.1.0 and below)) / WinDriver/lib/libwdapi<new_version>.so (Linux, Solaris — supported until 9.0.1) — as demonstrated in the sample and generated DriverWizard projects from version 8.x and above of WinDriver.

      Similarly, the name of the WinDriver API .NET DLL changed in version 8.0.0 from wdapi_dotnet.dll to wdapi<version>_dotnet.dll (e.g., wdapi800_dotnet.dll in version 8.0.0 of WinDriver) and the DLL was moved to the WinDriver\lib\<CPU>\<.NET version>\ directory (e.g., WinDriver\lib\x86\v1.1.4322\).

      Note that if your code uses the wdapi DLL/shared object, you will need to distribute wdapi<version>.dll (Windows, Windows CE) / libwdapi<version>.so (Linux, Solaris) with your driver. Windows .NET users should also distribute wdapi<version>_dotnet.dll.


    • Upgrading a Kernel PlugIn project (PCI):
      As indicated above, the Kernel PlugIn is not backwards compatible. Therefore, to use a Kernel PlugIn project from a previous version of WinDriver, you need to rebuild your Kernel PlugIn driver with the files and license from the new version.
      To upgrade a Kernel PlugIn project created with v10.2.1 or below of WinDriver, to v10.3.0 or above, follow the instructions in Technical Document #112.

    • Upgrading from v7.x to v8.x and above:
      When upgrading from v7.x to v8.0.0 or above, you should also be aware of the following issues:
      • WinDriver Source Files Location:
        In version 8.0.0 the WinDriver C source files were moved from the WinDriver/src directory to the WinDriver/src/wdapi/ directory. The .NET source files were moved from the WinDriver/wdapi.net/ directory to the WinDriver/src/wdapi.net/ directory.
        If your project uses the wdapi (previously wd_utils) DLL/shared object (see above), this should not normally affect you. However, if you have included any WinDriver source files directly in your project you may need to modify your project/make file to point to the new source files location.
      • When upgrading from version 7.0.0 — update your project's files search paths:
        Beginning with version 7.0.1 of WinDriver, the include path in the WinDriver project/make files contains the path to the WinDriver/ and WinDriver/include/ directories, and the #include statements in the WinDriver source files and generated DriverWizard code were consequently modified to indicate only the name of the header file to include, instead of the full/relative path to the file (as done in earlier versions).

        In light of these changes, when rebuilding a driver project from version 7.0.0 or earlier of WinDriver with the source files from version 7.0.1 or above, you may need to modify your project/make file and add the path to the WinDriver/ and WinDriver/include/ directories to the project's include path in order to successfully build the 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/PCMCIA — WDC API) / WD_License() (low-level API) from your code.

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




  4. Upgrade Your Device INF File (Windows)

    5. On Windows 2000/98/Me (in earlier WinDriver versions) and higher: If you have created a driver for a Plug-and-Play device (USB/PCI/CardBus/PCMCIA), it is recommended to create and install a new INF file for your device, which registers it with the driver module from the new version — windrvr6.sys (or your renamed version of this driver — in v9.x and above). You can use DriverWizard from the new version to generate the new INF file, or modify the driver version in your existing INF file.




  5. Upgrade Your Driver Distribution / Installation

    6. Create a new driver installation package, which contains the following items from the new WinDriver distribution:

    • The WinDriver driver module — windrvr6.sys/.dll/.o/.ko or WinDriver.kext, depending on the OS and the WinDriver version — or a renamed version of this driver.
    • On Linux, beginning with version 10.0.0 of WinDriver USB:
      The WinDriver USB Linux GPL driver — windrvr6_usb.o/.ko, or a renamed version of this driver.
    • Any other files required for installing or using your driver (e.g., Windows INF files).
    • An installation program that installs the new driver.

    For Windows 2000 and higher, for example, you would normally distribute the new windrvr6.sys, windrvr6.inf, and wd<new_version>.cat (v8.1.0+) files, the wdreg.exe or wdreg_gui.exe utility, difxapi.dll (v8.1.1+), your device INF file (if created), wdapi<new_version>.dll (v8.x+) (if used from your driver project), and your Kernel PlugIn driver (if you have created such a driver).

    Specific driver distribution instructions can be found in the Distributing Your Driver chapter of the new manual. The instructions for Windows are also summarized in Technical Document #132 (v81.x and above) / Technical Document #130 (v8.0.x).

    Version-Specific Installation Upgrade Notes:

    • Version 7.x to Version 8.1.0+ Windows Upgrade —
      The wd<version>.cat WinDriver Catalog File:
      Beginning with version 8.1.0, the windrvr6.sys driver has an Authenticode digital signature. In order to enjoy the advantages of this signature the wd<version>.cat catalog file, provided under the WinDriver\redist directory, needs to be distributed together with the windrvr6.inf file, which is used to install the driver. For more information, refer to the of the new WinDriver version and to Technical Document #132.

    • Version 8.1.0- to Version 8.1.1+ Windows Upgrade —
      WDREG difxapi.dll Dependency:
      Beginning with version 8.1.1, the wdreg installation utility uses the Driver Install Frameworks API (DIFxAPI) to perform driver installation and uninstallation. As a result, the wdreg utility in version 8.1.1 and above is dependent on the difxapi.dll DLL, which is provided under the WinDriver\util directory. This DLL must therefore be in wdreg's search path when using the utility to install / uninstall INF files.

    • Version 9.2.1- to Version 10.0.0 Linux USB Upgrade —
      The windrvr6_usb WinDriver USB Linux GPL Driver:
      Beginning with version 10.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 — the traditional WinDriver driver module, which includes the Jungo license.
      • windrvr6_usb.o/.ko — this driver implements Linux-specific USB driver functionality, and contains a GNU General Public License (GPL).