3.2 WinDriver Installation Process

The WinDriver CD contains all versions of WinDriver for all the different operating systems. The CD's root directory contains the Windows 98/Me/2000/XP/Server 2003/Vista and Windows CE version. This will automatically begin when you insert the CD into your CD drive. The other versions of WinDriver are located in sub-directories, i.e. Linux/, Wince/, etc.

3.2.1 Windows WinDriver Installation Instructions

****************************************************************************************

	NOTE
	You must have administrative privileges in order to install WinDriver on Windows 98/Me/2000/XP/Server 2003/Vista.

****************************************************************************************

1. Insert the WinDriver CD into your CD-ROM drive.
   When installing WinDriver by downloading it from Jungo's web site instead of using the WinDriver CD, double click the downloaded installation file - WD901.EXE - and go to step 3.

2. Wait a few seconds until the installation program starts automatically. If for some reason it does not start automatically, double-click the file WD901.EXE and click the Install WinDriver button.

3. Read the license agreement carefully, and click Yes if you accept its terms.

4. Choose the destination location in which to install WinDriver.

5. In the Setup Type screen, choose one of the following:
   • Typical - install all WinDriver modules (generic WinDriver toolkit + specific chipset APIs).
   • Compact - install only the generic WinDriver toolkit.
   • Custom - select which WinDriver modules to install.

6. After the installer finishes copying the required files, choose whether to view the Quick Start guides.

7. You may be prompted to reboot your computer.

   ****************************************************************************************

   NOTE

   The WinDriver installation defines a WD_BASEDIR environment variable, which is set to point to the location of your WinDriver directory, as selected during the installation. This variable is used during the DriverWizard [4] code generation - it determines the default directory for saving your generated code and is used in the include paths of the generated project/make files. This variable is also used from the sample Kernel PlugIn projects and makefiles. Therefore, if you decide to change the name and/or location of your WinDriver directory after the installation, you should also edit the value of the WD_BASEDIR environment variable and set it to point to the location of your new WinDriver directory. You can edit the value of WD_BASEDIR by following these steps: Open the System Properties dialogue: Start | System | Control Panel | System. In the Advanced tab, click the Environment Variables button. In the System variables box, select the WD_BASEDIR variable and click the Edit ... button or double-click the mouse on the variable. In the Edit System Variable dialogue, replace the Variable Value with the full path to your new WinDriver directory, then click OK, and click OK again from the System Properties dialogue.

   ****************************************************************************************

   The following steps are for registered users only:

   In order to register your copy of WinDriver with the license you received from Jungo, follow the steps below:

8. Activate DriverWizard GUI (Start | Programs | WinDriver | DriverWizard).

9. Select the Register WinDriver option from the File menu and insert the license string you received from Jungo. Click the Activate License button.

10. To register source code that you developed during the evaluation period, refer to the documentation of WDC_DriverOpen() [B.3.2].

    When using the low-level WD_xxx API instead of the WDC_xxx API [B.2] (which is used by default), refer to the documentation of WD_License() in the WinDriver PCI Low-Level API Reference.

3.2.2 Windows CE WinDriver Installation Instructions

3.2.2.1 Installing WinDriver CE when Building New CE-Based Platforms

****************************************************************************************

NOTES

The following instructions apply to platform developers who build Windows CE kernel images using Windows CE Platform Builder or using MSDEV 2005 with the Windows CE 6.0 plugin. The instructions use the notation ''Windows CE IDE'' to refer to either of these platforms. We recommend that you read Microsoft's documentation and understand the Windows CE and device driver integration procedure before you perform the installation.

****************************************************************************************

1. Edit the project registry file to match your target hardware. If you select to use the WinDriver component, as outlined in step 2, the registry file to modify is WinDriver$\backslash$samples$\backslash$wince_install $\backslash$<TARGET_CPU>$\backslash$WinDriver.reg (e.g. WinDriver$\backslash$samples$\backslash$wince_install$\backslash$ARMV4I$\backslash$ WinDriver.reg). Otherwise, modify the WinDriver$\backslash$samples$\backslash$wince_install$\backslash$project_wd.reg file.

2. You can simplify the driver integration into your Windows CE platform by following the procedure described in this step before the Sysgen platform compilation stage.

   NOTE:

   • The procedure described in this step is relevant only for developers who use Windows CE 4.x-5.x with Platform Builder. Developers who use Windows CE 6.x with MSDEV 2005 should skip to the next step [3].

   • This procedure provides a convenient method for integrating WinDriver into your Windows CE platform. If you select not to use this method, you will need to perform the manual integration steps described in step 4 below after the Sysgen stage.

   • The procedure described in this step also adds the WinDriver kernel module (windrvr6.dll) to your OS image. This is a necessary step if you want the WinDriver CE kernel file (windrvr6.dll) to be a permanent part of the Windows CE image (NK.BIN), which is the case if you select to transfer the file to your target platform using a floppy disk. However, if you prefer to have the file windrvr6.dll loaded on demand via the CESH/PPSH services, you need to perform the manual integration method described in step 4 instead of performing the procedure described in the present step.

   (a)

   Run the Windows CE IDE and open your platform.

   (b)

   From the File menu select Manage Catalog Items.... and then click the Import... button and select the WinDriver.cec file from the relevant WinDriver$\backslash$samples$\backslash$wince_install$\backslash$<TARGET_CPU>$\backslash$ directory (e.g. WinDriver$\backslash$samples$\backslash$wince_install$\backslash$ARMV4I$\backslash$).
   This will add a WinDriver component to the Platform Builder Catalog.

   (c)

   In the Catalog view, right-click the mouse on the WinDriver Component node in the Third Party tree and select Add to OS design.

3. Compile your Windows CE platform (Sysgen stage).

4. If you did not perform the procedure described in step 2 above, perform the following steps after the Sysgen stage in order to manually integrate the driver into your platform.

   NOTE: If you followed the procedure described in step 2, skip this step and go directly to step 5.

   (a)

   Run the Windows CE IDE and open your platform.

   (b)

   Select Open Release Directory from the Build menu.

   (c)

   Copy the WinDriver CE kernel file - WinDriver$\backslash$redist$\backslash$<TARGET_CPU>$\backslash$windrvr6.dll - to the %_FLATRELEASEDIR% sub-directory on the target development platform (should be the current directory in the new command window).

   (d)

   Append the contents of the project_wd.reg file in the WinDriver$\backslash$samples$\backslash$wince_install$\backslash$ directory to the project.reg file in the %_FLATRELEASEDIR% sub-directory.

   (e)

   Append the contents of the project_wd.bib file in the WinDriver$\backslash$samples$\backslash$wince_install$\backslash$ directory to the project.bib file in the %_FLATRELEASEDIR% sub-directory.

   This step is only necessary if you want the WinDriver CE kernel file (windrvr6.dll) to be a permanent part of the Windows CE image (NK.BIN), which is the case if you select to transfer the file to your target platform using a floppy disk. If you prefer to have the file windrvr6.dll loaded on demand via the CESH/PPSH services, you do not need to carry out this step until you build a permanent kernel.

5. Select Make Run-Time Image from the Build menu and name the new image NK.BIN.

6. Download your new kernel to the target platform and initialize it either by selecting Download/Initialize from the Target menu or by using a floppy disk.

7. Restart your target CE platform. The WinDriver CE kernel will automatically load.

8. Compile and run the sample programs to make sure that WinDriver CE is loaded and is functioning correctly (see section 3.4.2, which describes how to check your installation).

3.2.2.2 Installing WinDriver CE when Developing Applications for Windows CE Computers

****************************************************************************************

	NOTE
	Unless otherwise specified, ''Windows CE'' references in this section include all supported Windows CE platforms, including Windows Mobile.

****************************************************************************************

The following instructions apply to driver developers who do not build the Windows CE kernel, but only download their drivers, built using Microsoft eMbedded Visual C++ (Windows CE 4.x - 5.x) or MSDEV .NET 2005 (Windows Mobile or Windows CE 6.x) to a ready-made Windows CE platform:

1. Insert the WinDriver CD into your Windows host CD drive.

2. Exit the automatic installation.

3. Double click the CD_SETUP.EXE file found in the WINCE$\backslash$ directory on the CD. This will copy all required WinDriver files to your host development platform.

4. Copy WinDriver's kernel module - windrvr6.dll - from the WinDriver$\backslash$redist$\backslash$WINCE$\backslash$<TARGET_CPU> directory on the Windows host development PC to the Windows$\backslash$ directory on your target Windows CE platform.

5. Add WinDriver to the list of device drivers Windows CE loads on boot:
   • Modify the registry according to the entries documented in the file WinDriver$\backslash$samples$\backslash$wince_install$\backslash$ project_wd.reg. This can be done using the Windows CE Pocket Registry Editor on the hand-held CE computer or by using the Remote CE Registry Editor Tool supplied with MS eMbedded Visual C++ (Windows CE 4.x - 5.x) / MSDEV .NET 2005 (Windows Mobile or Windows CE 6.x). Note that in order to use the Remote CE Registry Editor tool you will need to have Windows CE Services installed on your Windows host platform.

   • On Windows Mobile the operating system's security scheme prevents the loading of unsigned drivers at boot time, therefore the WinDriver kernel module has to be reloaded after boot. To load WinDriver on the target Windows Mobile platform every time the OS is started, copy the WinDriver$\backslash$redist$\backslash$Windows_Mobile_5_ARMV4I$\backslash$ wdreg.exe utility to the Windows$\backslash$ StartUp$\backslash$ directory on the target.

6. Restart your target CE computer. The WinDriver CE kernel will automatically load. You will have to do a warm reset rather than just suspend/resume (use the reset or power button on your target CE computer).

7. Compile and run the sample programs to make sure that WinDriver CE is loaded and is functioning correctly (see section 3.4, which describes how to check your installation).

3.2.2.3 Windows CE Installation Note

The WinDriver installation on the host Windows 2000/XP/Server 2003/Vista PC defines a WD_BASEDIR environment variable, which is set to point to the location of your WinDriver directory, as selected during the installation. This variable is used during the DriverWizard [4] code generation - it determines the default directory for saving your generated code and is used in the include paths of the generated project/make files.

Therefore, if you decide to change the name and/or location of your host WinDriver directory after the installation, you should also edit the value of the WD_BASEDIR environment variable and set it to point to the location of your new WinDriver directory. You can edit the value of WD_BASEDIR by following these steps:

1. Open the System Properties dialogue: Start | System | Control Panel | System.
2. In the Advanced tab, click the Environment Variables button.
3. In the System variables box, select the WD_BASEDIR variable and click the Edit ... button or double-click the mouse on the variable.
4. In the Edit System Variable dialogue, replace the Variable Value with the full path to your new WinDriver directory, then click OK, and click OK again from the System Properties dialogue.

Note that if you install the WinDriver Windows 98/Me/2000/XP/Server 2003/Vista tool-kit on the same host PC, the installation will override the value of the WD_BASEDIR variable from the Windows CE installation.

3.2.3 Linux WinDriver Installation Instructions

3.2.3.1 Preparing the System for Installation

In Linux, kernel modules must be compiled with the same header files that the kernel itself was compiled with. Since WinDriver installs the kernel module windrvr6.o/.ko, it must compile with the header files of the Linux kernel during the installation process.

Therefore, before you install WinDriver for Linux, verify that the Linux source code and the file versions.h are installed on your machine:

Install the Linux kernel source code:

• If you have yet to install Linux, install it, including the kernel source code, by following the instructions for your Linux distribution.

• If Linux is already installed on your machine, check whether the Linux source code was installed. You can do this by looking for `linux' in the /usr/src directory. If the source code is not installed, either install it, or reinstall Linux with the source code, by following the instructions for your Linux distribution.

Install version.h:

• The file version.h is created when you first compile the Linux kernel source code. Some distributions provide a compiled kernel without the file version.h. Look under /usr/src/linux/include/linux to see if you have this file. If you do not, follow these steps in order to install the file:
  1. Type:
     $ make xconfig

  2. Save the configuration by choosing Save and Exit.

  3. Type:
     $ make dep

In order to run GUI WinDriver applications (e.g. DriverWizard [4] ; Debug Monitor [6.2]) you must also have version 5.0 of the libstdc++ library - libstdc++.so.5. If you do not have this file, install it from the relevant RPM in your Linux distribution (e.g. compat-libstdc++).

Before proceeding with the installation, you must also make sure that you have a `linux' symbolic link. If you do not, create one by typing:
/usr/src$ ln -s <target kernel>/ linux
For example, for the Linux 2.4 kernel type:
/usr/src$ ln -s linux-2.4/ linux

3.2.3.2 Installation

1. Insert the WinDriver CD into your Linux machine's CD drive or copy the downloaded file to your preferred directory.

2. Change directory to your preferred installation directory, for example to your home directory:
   $ cd ~

3. Extract the WinDriver distribution file - WD901LN.tgz:
   $ tar xvzf /<file location>/WD901LN.tgz

   For example:
   

   • From a CD:
     $ tar xvzf /mnt/cdrom/LINUX/WD901LN.tgz
     
   • From a downloaded file:
     $ tar xvzf /home/username/WD901LN.tgz

4. Change directory to your WinDriver redist/ directory (the tar automatically creates a WinDriver/ directory):
   $ cd <WinDriver directory path>/redist

5. Install WinDriver:

       (a)

   <WinDriver directory>/redist$ ./configure
   

   ****************************************************************************************

   	NOTE
   	The configure script creates a makefile based on your specific running kernel. You may run the configure script based on another kernel source you have installed, by adding the flag --with-kernel-source=<path> to the configure script. The <path> is the full path to the kernel source directory, e.g. /usr/src/linux.

   ****************************************************************************************

       (b)

   <WinDriver directory>/redist$ make

       (c)

   Become super user:
   <WinDriver directory>/redist$ su

       (d)

   Install the driver:
   <WinDriver directory>/redist# make install

6. Create a symbolic link so that you can easily launch the DriverWizard GUI:
   $ ln -s <full path to WinDriver>/wizard/wdwizard/ usr/bin/wdwizard

7. Change the read and execute permissions on the file wdwizard so that ordinary users can access this program.

8. Change the user and group IDs and give read/write permissions to the device file /dev/windrvr6 depending on how you wish to allow users to access hardware through the device.

   If you are using a Linux 2.6.x kernel that has the udev file system, change the permissions by modifying your /etc/udev/permissions.d/50-udev.permissions file. For example, add the following line to provide read and write permissions:
   windrvr6:root:root:0666

   Otherwise, use the chmod command, for example:
   chmod /dev/windrvr6 666

9. Define a new WD_BASEDIR environment variable and set it to point to the location of your WinDriver directory, as selected during the installation. This variable is used in the make and source files of the WinDriver samples and generated DriverWizard [4] code and is also used to determine the default directory for saving your generated DriverWizard project. If you do not define this variable you will be instructed to do so when attempting to build the sample/generated code using the WinDriver makefiles.
   NOTE: If you decide to change the name and/or location of your WinDriver directory after the installation, you should also edit the value of the WD_BASEDIR environment variable and set it to point to the location of your new WinDriver directory.

10. You can now start using WinDriver to access your hardware and generate your driver code!

    ****************************************************************************************

    	TIP
    	You can use the wdreg script to load the WinDriver kernel module [13.3]. To automatically load windrvr6.o/.ko on each boot, run the wdreg script from the target Linux /etc/rc.d/rc.local file: wdreg windrvr6

    ****************************************************************************************

    The following steps are for registered users only

    In order to register your copy of WinDriver with the license you received from Jungo, follow the steps below:

11. Activate the DriverWizard GUI:
    <path to WinDriver>/wizard/wdwizard

12. Select the Register WinDriver option from the File menu and insert the license string you received from Jungo.

13. Click the Activate License button.

14. To register source code that you developed during the evaluation period, refer to the documentation of WDC_DriverOpen() [B.3.2].

    When using the low-level WD_xxx API instead of the WDC_xxx API [B.2] (which is used by default), refer to the documentation of WD_License() in the WinDriver PCI Low-Level API Reference.

3.2.3.3 Restricting Hardware Access on Linux

****************************************************************************************

CAUTION!

Since /dev/windrvr6 gives direct hardware access to user programs, it may compromise kernel stability on multi-user Linux systems. Please restrict access to the DriverWizard and the device file /dev/windrvr6 to trusted users. For security reasons the WinDriver installation script does not automatically perform the steps of changing the permissions on /dev/windrvr6 and the DriverWizard executable (wdwizard).

****************************************************************************************

3.2.4 Solaris WinDriver Installation Instructions

Installation of WinDriver should be performed by the system administrator logged in as root, or with root privileges, since the WinDriver installation process includes installation of the kernel module windrvr6.

1. Insert your CD into your Solaris machine CD drive or copy the downloaded file to your preferred directory.

2. Change directory to your preferred installation directory, for example to your home directory,:
   $ cd ~

3. Copy the WinDriver distribution file - WD901SL.tgz (x86) / WD901SLS32.tgz (SPARC 32-bit) / WD901SLS64.tgz (SPARC 64-bit) - to the current directory:
   $ cp /home/username/WD901SL.tgz .

4. Extract the distribution file, for example:
   $ gunzip -c WD901SL.tgz | tar xvf -

5. Change directory to WinDriver.

6. Install WinDriver using the WinDriver/install_windrvr installation script:
   ~/WinDriver# ./install_windrvr

   To use WinDriver to handle PCI devices, specify the vendor and device IDs of your PCI devices in the installation command (where <vid> represents the device's vendor ID and <did> represents the device's device ID):
   ~/WinDriver# ./install_windrvr <vid>,<did> [<vid>,<did> ...]

   For example, to use WinDriver to handle PLX 9030 and 9054 devices, run:
   ~/WinDriver# ./install_windrvr 10b5,9030 10b5,9054

7. Install the libgcc package, available for download from the following URL: http://www.sunfreeware.com/.

8. Add an environment variable:
   
   • For SPARC 32-bit and x86 platforms:
     LD_LIBRARY_PATH=/usr/local/bin
   • For SPARC 64-bit platforms:
     LD_LIBRARY_PATH=/usr/local/lib:/usr/local/lib/sparcv9

   The following three steps are optional:

9. Create a symbolic link so that you can easily launch the DriverWizard GUI:
   ~/WinDriver# ln -s ~/WinDriver/wizard/wdwizard/ usr/bin/wdwizard

10. Change the read and execute permissions on the file wdwizard so that ordinary users can access this program.

11. Change the user and group IDs and give read/write permissions to the device file /dev/windrvr6 depending on how you wish to allow users to access hardware through the device.

    You can now start using WinDriver to access your hardware and generate your driver code!

    The following steps are for registered users only:

    In order to register your copy of WinDriver with the license you have received from Jungo, please follow the steps below:

12. Activate the DriverWizard GUI:
    ~/WinDriver/wizard$ ./wdwizard

13. Select the Register WinDriver option from the File menu and insert the license string you received from Jungo.

14. Click the Activate License button.

15. To register source code that you developed during the evaluation period, refer to the documentation of WDC_DriverOpen() [B.3.2].

    When using the low-level WD_xxx API instead of the WDC_xxx API [B.2] (which is used by default), refer to the documentation of WD_License() in the WinDriver PCI Low-Level API Reference.

3.2.4.1 Restricting Hardware Access on Solaris

****************************************************************************************

CAUTION!

Since /dev/windrvr6 gives direct hardware access to user programs, it may compromise kernel stability on multi-user Solaris systems. Please restrict access to DriverWizard and the device file /dev/windrvr6 to trusted users. For security reasons the WinDriver installation script does not automatically perform the steps of changing the permissions on /dev/windrvr6 and the DriverWizard executable (wdwizard).

****************************************************************************************