Technical Document #113

Technical Document #113        [Product Version: 5.2.2–6.1.x]
Distributing your KernelDriver based driver to a target Windows machine (versions 5.2.x–6.1.x)

This technical document includes instructions on how to distribute your KernelDriver based driver to a target Windows machine.

NOTE
Distribution instructions for KernelDriver version 5.1.x — for USB on Windows NT 4.0 — can be found in Technical Document #114.

KernelDriver Version 6.1

Installing on Windows Target Computers — PCI/USB

This section refers to Windows 98/Me and Windows 2000/XP/Server 2003

The user must have administrative privileges on the target computer in order to install your driver.

  • Uninstalling old devices:
    To successfully disable/uninstall your driver, you must first close any open handles to <driver_file _name>.sys.

  • Installing your driver:

    1. Make sure your <your_driver>.sys and the specific INF file for your device driver are under the same directory.

    2. On Windows 2000/XP/Server 2003:
      Use the utility wdreg to install your driver on the target computer. From the command line type:
      \> wdreg -inf <full path to your driver's INF file> install

      For example, if <your_driver>.inf is in the d:\MyDevice\ directory on the target computer, the command should be:
      \> wdreg -inf d:\MyDevice\<your_driver>.inf

      You can find the executable of wdreg in the KernelDriver package under the \KernelDriver\util directory. For a general description of this utility and its usage, please refer to the KernelDriver User's Manual.


    3. On Windows 98/Me:
      Install the INF file manually using the Windows Add New Hardware Wizard or Upgrade Device Driver Wizard, as outlined in detail in the Kernel Driver User's Manual.
NOTE
  1. You must type the full path to the INF file when using wdreg (even if wdreg is located in the same directory as the INF file).
  2. wdreg is an interactive utility. If it fails, it will display a message instructing the user how to overcome the problem. In some cases the user may be asked to reboot the computer.
  3. Remember: On Windows 98/Me/2000/XP/Server 2003, if you wish to upgrade your driver for PCI/USB devices, we recommend that you first delete any INF file(s) for these devices from Windows INF directory. See the KernelDriver User's Manual for further explanations.

Installing on Windows Target Computers — ISA

This section refers to Windows 98/Me and Windows 2000/XP/Server 2003.

NOTE
The user must have administrative privileges on the target computer in order to install your driver.
  1. Copy the file <your_driver>.sys to the Windows installation directory on the target computer located at \<Windows Directory>\system32\drivers.

  2. Use the utility wdreg to add <your_driver>.sys to the list of device drivers Windows loads on boot. Use the following installation command:
    \> wdreg -name <my_driver_name> install

    You can find the executable of wdreg in the KernelDriver package under the \KernelDriver\util directory. For a general description of this utility and its usage, please refer to the KernelDriver User's Manual.


Installing on Windows NT 4.0 Target Computers

NOTE
The user must have administrative privileges on the target computer in order to install your driver.
  1. Copy the file <your_driver>.sys to the Windows installation directory on the target computer located at \<Windows Directory>\system32\drivers.

  2. Use the utility wdreg to add <your_driver>.sys to the list of device drivers Windows loads on boot. Use the following installation command:
    \> wdreg -name <my_driver_name> install

    You can find the executable of wdreg in the KernelDriver package under the \KernelDriver\util directory. For a general description of this utility and its usage, please refer to the KernelDriver User's Manual.


KernelDriver Version 5.2.x

  1. Copy the windrvr.sys or windrvr.vxd driver file (depending on your OS) and your SYS/VxD kernel driver to the target computer's drivers directory — %windir%\system32\drivers for SYS (e.g., WINNT\system32\drivers); Windows\system\vmm32 for VxD.

    When copying the files, take care not to overwrite a newer version of the file with an older one.

    windrvr.sys and windrvr.vxd are found under the KernelDriver\redist directory on the development machine.

    When distributing the driver to a target Windows 98/Me/2000/XP machine, also copy wd_virtual.inf (found under the KernelDriver\redist directory on the development machine) and the INF file for your device (which you have created with the DriverWizard on the development machine) to the target machine. It is recommended to copy the files to the <WINDIR>\inf directory (WINNT\inf — on Windows 2k; Windows\inf — on Windows 98/Me/XP) to enable Windows to find and load the files automatically.


  2. Copy wdreg.exe or wdreg_gui.exe from the KernelDriver\util directory on the development machine to the target machine.

    wdreg_gui.exe and wdreg.exe provide the same functionality. The difference is in the way the installation messages are displayed graphical message boxes (wdreg_gui.exe) or console messages (wdreg.exe). You can therefore replace any reference to wdreg.exe in the following instructions with wdreg_gui.exe if you wish.


  3. If there is already another kernel driver installed for your device, first uninstall the current driver. If the existing driver was developed with version 5.0.5b or earlier of KernelDriver, or if it was developed with WinDriver's Kernel PlugIn feature (described in the WinDriver User's Manual), use the wdreg.exe utility with the "remove" command to stop and delete the existing service:
        wdreg.exe -name <driver name> remove
    (When removing a VxD driver, add the -vxd flag before the -name flag.)

  4. Remove the existing windrvr.sys/windrvr.vxd service (if it exists) and install the new windrvr.sys/windrvr.vxd driver and wd_virtual.inf (on Windows 98/Me/2000/XP), using wdreg.exe:
    • To install windrvr.sys on Windows NT 4.0 or windrvr.vxd on Windows 95/98/Me, use the remove command to uninstall the existing service (if it exists) and then use the install command to install the new driver:
          wdreg.exe remove
          wdreg.exe install

      On Windows 98/Me, add the -vxd flag (this flag is set automatically on Windows 95):
          wdreg.exe vxd remove
          wdreg.exe vxd install


    • To install windrvr.sys on Windows 98/Me/2000/XP, use the reload command — which removes the current WinDriver service (if it exists), installs windrvr.sys and loads wd_virtual.inf:
          wdreg.exe -inf <full path to wd_virtual.inf> reload

      For example, if wd_virtual.inf has been copied to c:\WINNT\inf:
          wdreg.exe -inf c:\WINNT\inf\wd_virtual.inf reload

      NOTE: When upgrading from a previous version of KernelDriver/WinDriver, if there are currently PCI/USB devices registered to work with windrvr.sys or wdpnp.sys/wdusb.sys (which were used in previous versions), when wdreg.exe is run on Win2k/XP, it will display a message instructing the user to either uninstall all devices registered to work with WinDriver and select Retry, or select Cancel and reboot, in order to complete the installation. Therefore, before installing the new driver it is recommended to uninstall (from the Device Manager) any PCI/USB devices that are currently registered to work with WinDriver (via an INF file).
      Alternatively, to avoid this message you can run wdreg.exe with the loadinf command, instead of the "reload" command, in order to install the new windrvr.sys and wd_virtual.inf files:
          wdreg.exe -inf <full path to wd_virtual.inf> loadinf

      Please note, however, that this will require a reboot in order to complete the installation.

      To complete the installation of windrvr.sys (and wd_virtual.inf) on Windows 98/Me you must always reboot the PC, since dynamic loading of SYS drivers is not supported on Windows 98/Me.


  5. Install your own SYS/VxD kernel driver (my_kd.sys/vxd):

    • To install my_kd.sys on Windows NT 4.0 or my_kd.vxd on Windows 95/98/Me, use the wdreg.exe utility:
          wdreg.exe -name <my_kd> install

      When installing a VxD driver, add the vxd flag to the installation command (this flag is set automatically on Windows 95):
          wdreg.exe -vxd name <my_kd> install

      NOTE: Specify the driver name without the *.sys/*.vxd extension.


    • To install my_kd.sys on Windows 98/Me/2000/XP, install the specific INF file for your device (generated with the DriverWizard on the development machine).

      On Windows 2000/XP you can use the loadinf option of the wdreg.exe utility in order to automatically install the INF file:
          wdreg.exe -inf <full path to INF file> loadinf

      On Windows Me/98 you need to manually install the INF file from the Device Manager (using the Upgrade Device Driver Wizard: Properties --> Driver --> Upgrade Driver) or from Windows Add New Hardware Wizard, as explained in the driver distribution chapter of the KernelDriver User's Manual.

      NOTE

      1. When upgrading from a previous version of KernelDriver/WinDriver, before installing the new INF file, it is recommended to erase all backup INF files for any PCI/USB device that was previously registered to work with WinDriver, before installing the new INF file, in order to ensure that Windows does not install an old INF file your device, instead of the new file. (On Windows 2000/XP, look for the backup files in the %windir%/inf directory. On Windows 98/Me, look in the Windows\inf\other directory. Look for files containing the string "Jungo" and/or the vendor/device ID of your device/s and delete them. On Windows 2000/XP the files may be called oem*.inf (there will also be corresponding *.pnf files that you can erase or leave, as you wish). On Windows 98/Me the file names may begin with the string "Jungo".)

      2. In previous versions of KernelDriver/WinDriver (before v5.2.0) a separate driver file was used as the PnP driver (in addition to windrvr.sys) — wdpnp.sys and previously wdusb.sys. These drivers have become obsolete beginning with version 5.2.0 of KernelDriver/WinDriver.
    NOTE
    You must first install windrvr.sys/vxd (and wd_virtual.inf — when installing windrvr.sys on Windows 98/Me/2000/XP) before attempting to install your own kernel driver.

  6. Copy your user mode executable/DLL file (if you have created one) to the directory of you choice on the target machine and run it.