Technical Document #127

Technical Document #127        [Product Version: 6.2.x and above]
WinDriver Upgrade: Version 6.2.x -> Version 7.x and above

This document outlines the steps for upgrading from version 6.2.x to version 7.x or newer of WinDriver.
If you are upgrading from version 8.1.1 or newer, refer to Technical Document #84 instead.
If you are upgrading from version 7.x, 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 — refer to Technical Document #116 for information on API changes done in v11.8.0 of WinDriver, and edit your code accordingly.

    • WinDriver-API DLL/shared object upgrade — Linking your projects with the high-level WinDriver-API DLL/shared object — wdapi<version> (v8.x+) / wd_utils (v7.x) — frees you of the need to include the source files from the WinDriver/src/wdapi directory (v8.x+) / WinDriver/src directory (v7.x) in your project (see also note below).

      In v8.0.0 the name of the DLL/shared object module was changed from wd_utils to wdapi<version> (e.g., wdapi800 in v8.0.0) as part of the addition of versioning support to this module. 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.

      On Windows and Windows CE, in v8.x and newer, you can use the WDAPI DLL — wdapi<version>.dll (found in the WinDriver\redist directory) by linking your project with the WinDriver\lib\<CPU>\wdapi<version>.lib library (e.g., WinDriver\lib\x86\wdapi800.lib) — for MS Visual Studio (Visual C++) projects; or with the WinDriver\lib\<CPU>\wdapi_borland<version>.lib library (e.g., WinDriver\lib\x86\wdapi_borland800.lib) — for Windows Borland C++ Builder projects (in v11.1.0 and below).

      On Linux and Solaris (Solaris was supported until 9.0.1), in v8.x and newer you can use libwdapi<version>.so by linking your driver project with WinDriver/lib/libwdapi<version>.so (e.g., in WinDriver v8.0.0).
      To link your Linux project with this shared object, add wdapi<version> to the makefile's link flag (LFLAGS += -l wdapi<version>; e.g., LFLAGS += -l wdap800), instead of listing all the source files from the WinDriver/src/wdapi directory (previously WinDriver/src/ — see below) in the makefile (under the SRCS flag).

      On all platforms, the sample and generated DriverWizard projects demonstrate how to correctly link the project with the relevant DLL/shared object for your WinDriver version and target OS.

      Note that if your code uses the high-level WinDriver-API DLL / shared object, you will need to distribute wdapi<version>.dll (v8.x+) / wd_utils.dll (v7.x) — for Windows and Windows CE, or wdapi<version>.so (v8.x+) / (v7.x) — for Linux and Solaris, with your driver, as explained in the driver distribution instructions of the new WinDriver User's Manual.

    • WinDriver source files location changes — In v8.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/ directory to the WinDriver/src/ directory.
      If you have selected to upgrade your v6.2.x project to use the wdapi (v8.x+) or wd_utils (v7.x) DLL/shared object (see above), this should not normally affect you. However, if your project directly includes WinDriver source files, you may need to modify your project/make file to point to the new source files location.

    • Update your project's files search paths: Beginning with v7.0.1, 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 v7.0.0 or earlier of WinDriver with the source files from v7.0.1 or newer, 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.

    • For USB, beginning with v7.0.0 of WinDriver, if you have created a console driver application/DLL/shared object that calls functions implemented in WinDriver/samples/shared/usb_diag_lib.c (as is the case for the sample and generated WinDriver USB diagnostic driver projects), to build your project with the usb_diag_lib.c file from the new version you must add the new WinDriver/samples/shared/diag_lib.c file to your project.

    • For PCI/ISA users, beginning with v7.0.0 WinDriver features the new WDC library, which provides convenient wrapper APIs to the standard WinDriver PCI/ISA APIs. (This library is part of the wdapi<version> (v8.x+) / wd_utils (v7.x) DLL / shared object (see above; the source files are found under the WinDriver/src/wdapi directory (v8.x+) / WinDriver/src directory (v7.x) (see note above).

      The WDC APIs are documented in the v7.x+ WinDriver PCI User's Manual. The generated DriverWizard v7.x+ projects use the WDC APIs instead of the low-level WD_xxx APIs. The WDC APIs are also used from the v7.x+ pci_diag, pcmcia_diag, pci_dump and PLX samples.

      Since WDC mainly provides wrappers to the standard WinDriver APIs, which are still supported, you do not need to modify your old code to use the new WDC library. Should you select to upgrade your code to use the WDC APIs, you can examine the new samples and generated code and compare them to those from your old WinDriver version for a better understanding of how to use the new APIs.

      Note that to use the WDC APIs you will need to either include the relevant wdc_xxx.c source files from the WinDriver/src/wdapi directory (v8.x+) / WinDriver/src directory (v7.x) in your project/makefile; or link your project with the wdapi<version> (v8.x+) / wd_utils (v7.x) WinDriver high-level API DLL/shared object.

    • 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 windrvr6 in v11.8.0 and below) 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. Digitally Sign Your Driver Files (Windows) 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, which contains the following files from the new WinDriver distribution:

    • 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 user manuals from the new version. The instructions for Windows are also summarized in Technical Document #132 (v8.1.x and newer) / Technical Document #130 (v8.0.x).

    Version-Specific Installation Upgrade Notes:

    • Linux USB upgrade to v10.0.0+ — 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).

    • Windows upgrade to v8.1.1+ — WDREG difxapi.dll dependency: Beginning with v8.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 v8.1.1 and newer 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 /

    • Windows upgrade to v8.1.0+ — the wd<version>.cat WinDriver catalog file: Beginning with v8.1.0, the WinDriver driver (windrvr<version>.sys / windrvr6.sys in v11.8.0 and older) has an Authenticode digital signature. 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 related INF file (windrvr<version>.inf / windrvr6.inf in v11.8.0 and older), which is used to install the driver. For more information, refer to the WinDriver User's Manuals of the new WinDriver version and to Technical Document #132.