Technical Document #116

Technical Document #116        [Product Version: 6.0.2–7.x]
WinDriver Upgrade: Version 5.2.2 or earlier -> Version 6.0.2–7.x

This document outlines the steps for upgrading from version 5.2.2 or earlier to version 6.2.0–7.x of WinDriver.

The following documents describe the upgrade steps for other versions of WinDriver:

  • TD #131 — Version 7.x and above -> Version 8.x and above
  • TD #127 — Version 6.2.x -> Version 7.x and above
  • TD #84 — Version 6.0.x -> Version 6.2.x–7.x

NOTE
A driver developed with version 6.0.2 and above of WinDriver can co-exist, without any conflicts, with a driver developed with version 5.2.2 or earlier of WinDriver, since these versions use a different driver module — windrvr6.sys/.o/.dll in version 6.x and above versus windrvr.sys/.vxd/.o/.dll used in the earlier versions.


Upgrade Steps:

  1. Install the new WinDriver 6.x/7.x version to which you wish to upgrade. In order to avoid conflicts and simplify the upgrade, it is recommended that you first rename your existing WinDriver installation directory, and then use the previous WinDriver installation directory name (e.g., "WinDriver") for the new installation.

  2. Copy your old WinDriver project to the new WinDriver installation directory (for example from WinDriver_522/wizard/my_projects to the new WinDriver/wizard/my_projects directory).

  3. Consider upgrading your driver code to use the new USB WDU library API (from v6.0.0) or the new PCI/ISA WDC library API (from version 7.0.0). Alternatively, adjust your current project to the new version by following the guidelines below for your specific programming language:


  4. Registered users should acquire a license registration string for the new version and replace the old license registration string with the new one in calls to WD_License() in the existing code. When upgrading the code to use the new WinDriver USB WDU library (v6.0.0+) or the new PCI/ISA WDC library (v7.0.0+), use the new WDU_Init() (USB) or WDC_DriverOpen() (PCI/ISA) functions to register your new license string (see the documentation of these functions in the manual of your new WinDriver version).

  5. Rebuild the code with the files from the new version.

  6. On Windows 98/Me/2000/XP/Server 2003: Install a new INF file for your device: If you have developed a driver for a Plug-and-Play device (USB/PCI), when upgrading the driver you must also install a new INF file for your device, which registers it to work with windrvr6.sys from the new version, instead of windrvr.sys / wdpnp.sys / wdusb.sys from the old version. You can use DriverWizard from the new version to generate the new INF file.
    [NOTE: On Windows 2000 you should first delete from the %windir%\inf directory any previous INF files for the device, to prevent Windows from installing an old INF file in place of the new file that you created. Look for files containing your device's vendor and device IDs (these will generally be named oem*.inf, e.g., oem1.inf) and delete them. On Windows 98 you may also find that you need to delete old backup INF files for your device from the %windir%\inf\other directory in order to successfully replace the previous INF file with the new one. For more information on Windows 2000 INF selection algorithm, refer to Technical Document #49].

  7. Upgrade your driver distribution.



Adjusting your existing project code

To use your existing code, developed with WinDriver version 5.2.2 or earlier, with your new WinDriver version, follow these steps:

For C Programmers

  • Make sure the #include paths in your project point to the header files from the new version.

    NOTE:
    Beginning with version 7.0.1, the include path in the WinDriver project/make files contains the path to the WinDriver/ and WinDriver/include/ directories.
    The #include statements in the WinDriver source files and generated DriverWizard code were modified accordingly to indicate only the name of the header file to include, instead of the full/relative path to the file (as done in v7.0.0-).

    In light of these changes, when rebuilding a driver project from version 5.2.2 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.


  • wd_utils: On Windows, you can use the wd_utils DLL (found in the WinDriver\redist directory) by linking your project with WinDriver\lib\wd_utils.lib — for MS Visual Studio (Visual C++) projects, or with WinDriver\lib\wd_utils_borland.lib — for Borland C++ Builder projects. wd_utils_borland.lib is available beginning with v7.0.0.

    Windows CE projects can be linked with WinDriver\lib\wd_utils.lib beginning with version 7.0.1 of WinDriver.

    Linux projects can link with WinDriver/lib/libwd_utils.so beginning with version 7.0.0 of WinDriver (to link to this shared object, modify the makefile and add wd_utils to the link flags:
    LFLAGS += -l wd_utils).

    Solaris projects can link with WinDriver/lib/libwd_utils.so beginning with version 7.0.1 of WinDriver.

    You can examine the sample and generated DriverWizard project/make files in the newer versions of WinDriver to see how to link your project correctly with the wd_utils DLL/shared object.

    NOTE: When using wd_utils you do not need to include the WinDriver/src files in your project, therefore you can skip the following step.


  • Add the following source files to your C project (when not using wd_utils):
    • WinDriver/src/utils.c
    • WinDriver/src/status_strings.c
    • WinDriver/src/windrvr_int_thread.c
    • WinDriver/src/windrvr_events.c
    • WinDriver/src/windrvr_hotswap.c (v7.x)

    Linux and Solaris users should add these files by editing the project's makefile in two places, as described below (in the WinDriver samples and generated code the project makefile is normally found under a linux/ or solaris/ sub-directory, respectively, in your project directory):

    1. The file paths should be added to the SRCS source files list, as done for the source files already found in the list.

    2. For each new source file, add the following two lines to the makefile, as done for the source files already included in your project:

      <file_name>.o: ~/WinDriver/src/<file_name>.c
          $(CC) -c $(CFLAGS) -o $@ $<

      For example, for the windrvr_int_thread.c file, add the following lines:

      ~/WinDriver/src/windrvr_int_thread.c 
          $(CC) -c $(CFLAGS) -o $@ $<


  • For PCI/ISA drivers, beginning with version 7.0.0 WinDriver features the new WDC library, which provides convenient wrapper APIs to the standard WinDriver PCI/ISA APIs.
    To use the WDC APIs you will need to either include the relevant WinDriver/src/wdc_xxx.c source files in your project/makefile; or link your project with the wd_utils DLL/shared object.

  • For USB, if your driver project calls functions implemented in the WinDriver/samples/shared/usb_diag_lib.c file (as is the case for the sample and generated WinDriver USB diagnostic driver projects), perform the following additional steps:
    • Replace the WinDriver/samples/shared/usb_diag_lib.c file used in your existing project with the new WinDriver/samples/shared/usb_diag_lib_v52.c file.
    • Replace all references to usb_diag_lib.h in your project's source files with references to usb_diag_lib_v52.h from the new WinDriver/samples/shared directory.




For Delphi Programmers (Windows Only)

  • Verify that your project file (*.dpr) points to the WinDriver Delphi modules (*.pas files) found in the new version's WinDriver\delphi\include directory.

  • Add the following module to the "uses" section of your project file: WinDriver\delphi\include\status_strings.pas (where WinDriver is your new WinDriver installation directory).




For Visual Basic Programmers (Windows Only)

  • Verify that your project file (*.vbp) points to windrvr.bas — for version 6.2.2+, or windrvr.cls — for version 6.2.1-, found in the new version's WinDriver\vb\include directory.

  • Add wd_utils.bas (v6.2.2+) / wd_utils.cls (v6.2.1-) from the new version's WinDriver\vb\include directory to your project file (*.vbp).

  • Verify that wd_utils.dll from the WinDriver\redist directory of the new version (which replaces the previous wd_vb.dll) is copied to the %windir%\system32 directory on the target PC (this is done automatically on the development PC when installing WinDriver).




Upgrading your project to use new APIs

USB API Upgrade Recommendation (WDU library) — v6.0.0+

Beginning with version 6.0.0, WinDriver features a new and improved USB API, implemented in the new WDU library. (This library is part of the wd_utils DLL/shared object; the source files are found under the WinDriver/src directory).

In order to fully utilize the features of the new version and enjoy future fixes and improvements, it is recommended to port your code to use the new WDU USB API. General guidelines for upgrading your old WinDriver USB driver code to use the new WDU API can be found in the WinDriver User's Manual for the new version. In addition, when upgrading to v7.0.0 or above, if your project included the WinDriver/samples/shared/usb_diag_lib.c file, link the modified project with the new version of this file (found in the same directory of your new WinDriver toolkit) and also add the new WinDriver/samples/diag_lib.c file to your project/makefile.

To simplify the upgrade to the new API, consider using DriverWizard from your new 6.x/7.x version to generate a skeletal driver code for your device, which utilizes the new API, or refer to the WinDriver/samples/usb_diag sample from the new version (Delphi and Visual Basic samples can be found under WinDriver/delphi/samples and WinDriver/vb/samples directories, respectively.)

This is only a recommendation, since the old API is still supported by the new version after following the steps listed above. However, note that the old USB API is no longer in development since version 6.0.0 of WinDriver.





PCI/ISA API Upgrade (WDC library) — v7.0.0+

Beginning with version 7.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 wd_utils DLL/shared object; the source files are found under the WinDriver/src directory).

The new WDC APIs (currently provided only in C) are documented in the WinDriver v7.x PCI User's Manual. The generated DriverWizard v7.x+ projects utilize the WDC APIs instead of the lower-level standard WinDriver APIs. The new 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 new 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 WDC APIs.





Upgrading Your Driver Distribution

For detailed distribution instructions for the new version, refer to the Distributing Your Driver chapter in the WinDriver User's Manual of the new version. For Windows the distribution instructions are also summarized in Technical Document #117.

Note especially the following changes to the driver distribution process:

  • The name of the WinDriver kernel module was changed from windrvr to windrvr6.
  • For Windows, no additional *.sys files, apart from windrvr6.sys, are required (as opposed to wdpnp.sys or wdusb.sys used for Plug-and-Play Windows systems in earlier versions).
  • For Windows 98/Me/2000/XP/Server 2003: The wd_virtual.inf file, which was used in version 5.2X of WinDriver, was replaced with the windrvr6.inf file.
  • For Windows: The wdreg/wdreg_gui installation utility has been modified and improved and the installation/uninstallation commands have changed. For Windows 98/Me, a new wdreg16 utility is now used. For a detailed description of the current installation utilities, please refer to the WinDriver User's Manual of your new WinDriver version.
  • If your project was upgraded to use wd_utils, you must distribute this DLL/shared object with your driver.