This chapter takes you through the process of installing WinDriver on your development platform, and shows you how to verify that your WinDriver is properly installed. The last section discusses the uninstall procedure.

To find out how to install a driver you created on target platforms, refer to Chapter 15: Distributing Your Driver.

3.1. System Requirements

You can find below system requirements for Windows, Linux, and Mac.

3.1.1. Windows System Requirements

Please make sure that your development machine fits the following requirements:

Any x86 32-bit or 64-bit (x64: AMD64 or Intel EM64T) processor, ARM, ARM64 processors supported by Microsoft.
Any compiler or development environment supporting C, .NET, Java or Python.

3.1.2. Linux System Requirements

Any of the following processor architectures, with a 2.6.x or higher Linux kernel:

32-bit x86.
64-bit x86 AMD64 or Intel EM64T (x86_64)
ARM Cortex-A7, A9, A15, A53, A57.

‍ℹ️ Note

‍Jungo strives to support new Linux kernel versions as close as possible to their release. To find out the latest supported kernel version, refer to the WinDriver release notes that can be found online at WinDriver Release Notes.

A GCC compiler. The version of the GCC compiler should match the compiler version used for building the running Linux kernel.
Any 32-bit or 64-bit development environment (depending on your target configuration) supporting C for user mode.
On your development PC: glibc2.14.x (or newer).
The following libraries are required for running GUI WinDriver application (e.g., DriverWizard (see more in Chapter 6: Using DriverWizard); Debug Monitor (see more in 8.2. Debug Monitor):
- libstdc++.so.6
- libpng12.so.0
- libQt5Gui.so
- libQt5Core.so
- libQt5Network.so
- libQt5PrintSupport5.so
- make, gcc, flex, bison (for installing WinDriver and Kernel Plugins)
- The kernel source of the running Linux kernel Optional dependencies:
- gcc-multilib (for compiling 32-bit applications on 64-bit systems)
- CMake (for compiling user mode samples)

Newer versions of Linux distributions, provide native support of Qt5 instead of Qt4. If your OS supports Qt4 instead of Qt5, use wdwizard_legacy, wddebug_gui_legacy, xdma_gui_legacy instead of the non-prefixed versions. Check out 3.2.2.1. Preparing the System for Installation for instructions how to install the above requirements on various Linux distributions.

3.1.3. MacOS System Requirements

Please make sure that your development machine fits the following requirements:

An Apple Macintosh computer running MacOS versions 10.10-11.
XCode Command Line Tools

3.2. WinDriver Installation Process

3.2.1. Windows WinDriver Installation Instructions

‍⚠ Attention

‍Driver installation on Windows requires administrator privileges.

Run the WinDriver installation — WD1630.EXE (for 32-bit) or WD1630X64.EXE (for 64-bit) or WD1630ARM64.EXE — and follow the installation instructions.
At the end of the installation, you may be prompted to reboot your computer.

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 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 in the sample Kernel PlugIn projects and makefiles.

If the installation fails with an ERROR_FILE_NOT_FOUND error, inspect the Windows registry to see if the RunOnce key exists in HKEY_LOCAL_MACHINE\SOFTWARE \Microsoft\Windows\CurrentVersion. This registry key is required by Windows Plug-and-Play in order to properly install drivers using INF files. If the RunOnce key is missing, create it; then try installing the INF file again.

The following steps are for registered users only:

To register your copy of WinDriver with the license you received from Jungo, follow these steps:

Start DriverWizard: Start | Programs | WinDriver | DriverWizard.
Select the Register WinDriver option from the File menu, and insert the license string you received from Jungo.
Click the Activate License button.
To register source code that you developed during the evaluation period, refer to the documentation of WDU_Init() / WDC_DriverOpen().

When using the low-level WD_xxx API instead of the WDC_xxx API (which is used by default), refer to the documentation of WD_License() in this manual.

3.2.1.1. Setting up Test Signing

One of the pages in the WinDriver installer is dedicated to setting up your machine for test signing a driver package. This section contains the following options:

Create test certificate checkbox: Checking this checkbox will create a self-signed test certificate. After the installation, you can view the certificate by double clicking the .cer file in: $WD_BASEDIR/WinDriver1630_development.cer, or by viewing the certificate store of the local machine. In order to do that, open the run dialog box (winkey+r) and enter certlm.msc. You will be able to see the WinDriver1630.development certificate under 'Personal', 'Trusted Root Certification Authorities' and 'Trusted Publishers'
Enable test sign mode checkbox: Checking this checkbox will switch your machine to test signing mode by enabling the testsigning boot configuration. This mode enables test-signed drivers to load.

‍⚠ Attention

‍After changing the testsigning boot configuration, a reboot is required for the changes to take effect. Once these changes take effect, you are not required to do anything else with Windows security settings during the development process (as opposed to disabling digital signature enforcement, which must be done after every reboot).

‍⚠ Attention

‍You must have administrative rights and disable Secure Boot to change the testsigning boot configuration.

Enabling or disabling this configuration can be done with wdreg.exe (see Chapter 17.3.5.1.1 Enabling and Disabling Test Signing Mode)

3.2.2. Linux WinDriver Installation Instructions

3.2.2.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 kernel modules, it must compile with the header files of the Linux kernel during the installation process.

In modern Linux distributions such as Ubuntu, CentOS and Fedora the kernel headers are usually either already installed with the OS, or are easily obtainable via the distribution's package manager. Our suggestion would be to skip to the next section and in case of failure there try the steps mentioned here.

On other less common Linux kernel/distributions, compiling the kernel itself may be neccesary. If you're using such a kernel, for more info on compiling it, check out the documentation of the Linux Kernel you're using.

The following instructions may vary according to different versions of the distributions.

CentOS:

# Prepare and update apt package manager databases
sudo yum update
 
# Install prerequistes for kernel development and kernel headers
sudo yum install kernel-devel kernel-headers
sudo yum groupinstall "Development Tools"
 
# qt5 install for GUI applications to work
sudo yum --enablerepo=extras install epel-release
sudo yum install qt5-qtbase qt5-qtbase-gui

Browse the web to find exact installation instructions of CMake for your CentOS version.

Ubuntu/Debian:

# Prepare and update apt package manager databases
sudo apt update
 
# Install prerequistes for kernel development and kernel headers
sudo apt install make gcc bison flex linux-headers-$(uname -r)
 
# CMake install for compiling user mode samples and generated code
sudo apt install cmake
 
# qt5 install for GUI applications to work
sudo apt install libqt5gui5 libqt5printsupport5

Fedora (tested on version 36):

# Prepare and update apt package manager databases
sudo dnf update
 
# Install prerequistes for kernel development and kernel headers
sudo dnf install kernel-devel kernel-headers
sudo dnf groupinstall "Development Tools"

On your development Linux machine, change directory to your preferred installation directory, for example, to your home directory:

$ cd ~

‍⚠ Attention

‍The path to the installation directory must not contain any spaces.

Extract the WinDriver distribution file — WD1630LN.tar.gz / WD1630LNx86_64.tar / WD1630LNARM.tar / WD1630LNARM64.tar

$ tar -xvzf <file location>/WD1630LN[x86_64/ARM/ARM64].tar.gz

3.2.2.2. Installing WinDriver on x86/x86_64 systems

Kindly make sure you've performed the appropriate preparations described in
3.2.2.1. Preparing the System for Installation in order for the following instructions to work.

Change directory to your WinDriver redist directory (the tar automatically creates a WinDriver directory):
$ cd <WinDriver directory path>/redist
Install WinDriver:
- Enter the following:

`<WinDriver directory>/redist`$ ./configure

‍⚠ Attention

‍The configuration script creates a makefile based on the running kernel. You may select to use another installed kernel source, by executing the script with the --with-kernel-source=<path> option, where <path> is the full path to the kernel source directory — e.g., /usr/src/linux. If the Linux kernel version is 2.6.26 or higher, the configuration script generates makefiles that use kbuild to compile the kernel modules. For a full list of the configuration script options, use the --help option: ./configure --help

‍⚠ Attention

‍If you are going to use WinDriver for multiple USB devices with the same VID/ PID, add -DMULTIPLE_SAME_DEVICES to the EXTRA_CFLAGS variable in makefile.usb.kbuild.

Then:

<WinDriver directory>/redist$ make

And install the driver (as root user):

<WinDriver directory>/redist$ sudo make install

Create a symbolic link so that you can easily launch the DriverWizard GUI:

$ ln -s <path to WinDriver>/wizard/wdwizard /usr/bin/wdwizard

On older Linux environments such as Ubuntu 16.04 that provide Qt4 instead of Qt5, run wdwizard_legacy instead of wdwizard.

Change the read and execute permissions on the file wdwizard so that ordinary users can access this program.
Change the user and group IDs and give read/write permissions to the device file /dev/windrvr1630, depending on how you wish to allow users to access hardware through the device. Due to security reasons, by default the device file is created with permissions only for the root user. 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: windrvr1630:root:root:0666
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 code, and is also used to determine the default directory for saving your generated DriverWizard projects. 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.
Exit super user mode:

# exit

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

‍⚠ Attention

‍Use the WinDriver/util/wdreg script to load the WinDriver kernel module.

The following steps are for registered users only:

To register your copy of WinDriver with the license you received from Jungo, follow these steps:

Start DriverWizard:

$ <path to WinDriver>/wizard/wdwizard

Select the Register WinDriver option from the File menu, and insert the license string you received from Jungo.
Click the Activate License button.
To register source code that you developed during the evaluation period, refer to the documentation of WDC_DriverOpen() . When using the low-level WD_xxx API instead of the WDC_xxx API (which is used by default), refer to the documentation of WD_License() in this manual.

3.2.2.3. Installing WinDriver on ARM/ARM64 systems

Kindly make sure you've performed the appropriate preparations described in
3.2.2.1. Preparing the System for Installation in order for the following instructions to work. The following steps assume you have the ability to compile WinDriver's kernel module on your ARM/ARM64 platform and link it with the running kernel's header. If that is not possible with your platform,
see 3.2.2.3.1. Cross compiling the WinDriver kernel module for Linux ARM/ARM64 systems

Starting from WinDriver 14.0.0, Jungo distributes unified ARM and ARM64 versions, in an attempt to support as much platforms as possible. We have tested different platforms to work with WinDriver, but we believe that other platforms with similar credentials should work with these setups.

Therefore we provide an installation script wd_arm_install.sh or wd_arm64_install.sh that allows the user to either try differently compiled WinDriver kernel modules manually or automatically, until the user hopefully succeeds in installing them.

In order to start:

Make sure you have all WinDriver dependencies for Linux (gcc, make, kernel sources/headers for your running kernel). Qt applications are currently not supported under ARM, therefore the Qt DLLs are not required.
Run the following:

cd WinDriver/redist && sudo ./wd_arm_install.sh

or depending on your platform.

cd WinDriver/redist && sudo ./wd_arm64_install.sh

Pick the platform type to install WinDriver for it, or choose automatic install to attempt installation of all available versions of WinDriver on your platform. If installation succeeded, the script will exit. You may modify the script’s source code to redistribute the driver if needed.
If all installations failed – feel free to contact Jungo’s support for assistance in getting WinDriver to run on your platform, or for porting WinDriver for it, at sales.nosp@m.@jun.nosp@m.go.co.nosp@m.m.

3.2.2.3.1. Cross compiling the WinDriver kernel module for Linux ARM/ARM64 systems

Some ARM/ARM64 platforms do not support compilation of kernel modules on the platform itself (which is the classic and recommended way to install WinDriver on Linux). For those cases, we provide a method to cross-compile the WinDriver kernel module on a development machine and then install it on an ARM/ARM64 platform. In order to do this perform the following steps:

On the development machine:

Obtain and cross compile your platform's Linux kernel source from the vendor's website. Search for your vendor's instructions on how to do so.
Make sure you have installed the relevant gcc compiler for the platform (arm-linux-gnueabihf-gcc for ARM, aarch64-linux-gnu-gcc for ARM64).
Download the ARM/ARM64 WinDriver package to your Linux development machine (even if your development platform is of a different architecture!).
Untar the WinDriver package
$ tar -xzvf WD1630LNARM.tar.gz

# or

$ tar -xzvf WD1630LNARM64.tar.gz
Go to the redist folder and run the cross compilation script:

for ARM:

$ cd WD1630LNARM/redist

$ sudo ./wd_arm_cross_compile.sh PATH_TO_YOUR_COMPILED_KERNEL_SOURCE

or for ARM64:

$ cd WD1630LNARM64/redist

$ sudo ./wd_arm64_cross_compile.sh PATH_TO_YOUR_COMPILED_KERNEL_SOURCE

Follow the instructions in the script and choose one of the options for which type of .ko file to build. Since your platform may be different from the platforms listed in the script (there are endless platforms and kernel types out there), you can try compiling with different options and trying to install the resulting kernel modules on your platform until you find a version that works. If after trying all versions you have not found a version which works with your platform, feel free to contact sales.nosp@m.@jun.nosp@m.go.co.nosp@m.m for further assistance.

On the ARM/ARM64 platform:

Transfer the WinDriver package to your platform and untar it:
$ tar -xzvf WD1630LNARM.tar.gz

# or

$ tar -xzvf WD1630LNARM64.tar.gz
Go to the redist folder and install the driver:
$ cd WD1630LNARM/redist
Copy the directory WD1630/redist/LINUX.PRECOMPILED.ARM or WD1630/redist/LINUX.PRECOMPILED.ARM64 from the development machine to WD1630/redist/LINUX.PRECOMPILED.ARM or WD1630/redist/LINUX.PRECOMPILED.ARM64 on your platform.
Install the precompiled kernel module(s):
$ ./configure --enable-precompiled

$ sudo make precompiled_install

3.2.2.4. Restricting Hardware Access on Linux

Since /dev/windrvr1630 gives direct hardware access to user programs, it may compromise kernel stability on multi-user Linux systems. Please restrict access to DriverWizard and the device file /dev/windrvr1630 to trusted users.

For security reasons the WinDriver installation script does not automatically perform the steps of changing the permissions on /dev/windrvr1630 and the DriverWizard application (wdwizard).

Therefore, the default way of running all WinDriver related user applications in Linux would require running them with sudo or as root. Some GUI features in the DriverWizard and the Debug Monitor that involve opening a web browser may not work if these applications are launched as root.

Changing the ownership of /dev/windrvr1630 to your user name could be done using the chmod command in the Linux terminal.

3.2.3. MacOS WinDriver Installation Instructions

3.2.3.1 Preparing the System for Installation

Firstly, disable System Integrity Protection (SIP). The instructions on how to do this may vary between different MacOS versions so find the instructions for your specific version.

On MacOS 11 (Big Sur) in order for WinDriver to be able to load you might also need to disable Apple Mobile File Integrity (AMFI). This could be done by adding "amfi_get_out_of_my_way=1" to your boot-args in the following manner:

# Print out the nvram variables to see if boot-args already contain other values
sudo nvram -p
# If boot-args doesn't exist in the list or is empty, run this
sudo nvram boot-args="amfi_get_out_of_my_way=1"
# Otherwise, modify the command such that it keeps all previous values and appends
 amfi_get_out_of_my_way=1 as well.

‍⚠ Attention

‍Disalbing SIP and AMFI weakens your system's security mechanisms but is mandatory for WinDriver to run on MacOS and to allow Driver Development in general. Disable these mechanisms at your own risk.

Afterwards, install the dependencies, these steps assume you have the Homebrew package manager installed. If it is not yet installed, kindly install it first, and then run the following commands:

Install Qt5 (required for DriverWizard, Debug Monitor)

$ brew install qt5

Then install CMake (required for compiling generated code and samples)

$ brew install cmake

3.2.3.2 Installation on MacOS x86_64

Then using a Terminal window, run the following commands:

# Unzipping
$ tar -xvzf WD1630MAC.tar.gz
# Driver install 
$ cd WD1630MAC/redist/ 
$ sudo ./wd_mac_install.sh

On MacOS version 11 (Big Sur) and higher, installing WinDriver using the install script will raise a pop-up message from the Security & Privacy section of the System Preferences to allow installing a kernel extnesion. In order for WinDriver to run, you must allow it to be installed. This will also require a restart. After restarting the system, you might need to run
$ sudo ./wd_mac_install.sh

again.

3.2.3.3 Installation on MacOS ARM64 (M1)

Then using a Terminal window, run the following commands:

# Unzipping 
$ tar -xvzf WD1630MACARM64.tar.gz
# Driver install 
$ cd WD1630MACARM64/redist/ 
$ sudo ./wd_mac_install.sh

The ARM64 version of WinDriver for MacOS requires that before installation the users will specify the Vendor ID(s) and Product ID(s) of the devices they wish to use. The install script will prompt the users to enter these parameters. For more information, search for Apple's documentation regarding IOPCIMatch.
On MacOS version 11 (Big Sur) and higher, installing WinDriver using the install script will raise a pop-up message from the Security & Privacy section of the System Preferences to allow installing a kernel extnesion. In order for WinDriver to run, you must allow it to be installed. This will also require a restart. After restarting the system, you might need to run
$ sudo ./wd_mac_install.sh

again.

‍⚠ Attention

‍If the users enter a VID/PID mask which is too "wide" (covers many devices) this might cause a system crash as MacOS Big Sur and higher does not allow WinDriver to access certain system-reserved devices. The system will reboot and remove the kernel extension and the user will have to run the installation script again and enter different, more specific parameters in order to install WinDriver. Performing a PCI scan on such systems (using the DriverWizard or WDC_PciScanDevices()) will show only the devices that answer to the parameters provided by the user in this stage.

3.3. Upgrading Your Installation

To upgrade to a new version of WinDriver, follow the installation steps for your target operating system, as outlined in the previous Section 3.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.

After the installation, start DriverWizard and enter the new license string, if you have received one. This completes the minimal upgrade steps.

To upgrade your source code:

Pass the new license string as a parameter to WDC_DriverOpen() / WDU_Init() (or to WD_License() when using the low-level API).
Verify that the call to WD_DriverName() in your driver code (if exists) uses the name of the new driver module — windrvr1630 or your renamed version of this driver.

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 (as outlined in Chapter 17.2), 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.

3.4. Checking Your Installation

3.4.1. Installation Check

Start DriverWizard — <path to WinDriver>/wizard/wdwizard. On Windows you can also run DriverWizard from the Start menu: Start | Programs | WinDriver | DriverWizard.
If you are a registered user, make sure that your WinDriver license is registered (refer to [Section 3.2] (3.2. WinDriver Installation Process), which explains how to install WinDriver and register your license).

If you are an evaluation version user, you do not need to register a license.

For PCI cards/USB devices — Insert your card into the PCI bus/your device into the USB slot, and verify that DriverWizard detects it. For ISA cards (Windows and Linux) — Insert your card into the ISA bus, configure DriverWizard with your card's resources and try to read/write to the card using DriverWizard.

3.5. Uninstalling WinDriver

This section will help you to uninstall either the evaluation or registered version of WinDriver

3.5.1. Windows WinDriver Uninstall Instructions

You can select to use the graphical wdreg_gui.exe utility instead of wdreg.exe.

wdreg.exe and wdreg_gui.exe are found in the WinDriver\util directory
(see Chapter 16: Dynamically Loading Your Driver for details regarding these utilities).

To uninstall WinDriver, please follow these steps:

Close any open WinDriver applications, including DriverWizard, the Debug Monitor, and user-specific applications.
If you created a Kernel PlugIn driver, uninstall and erase it:
- If your Kernel PlugIn driver is currently installed, uninstall it using the wdreg utility:

# The Kernel PlugIn driver name should be specified without the `*.sys` extension.

wdreg -name <Kernel PlugIn name> uninstall

Erase your Kernel PlugIn driver from the windir%\system32\drivers directory.
Uninstall all Plug-and-Play devices (USB/PCI) that have been registered with WinDriver via an INF file:

# Uninstall a device INF using the wdreg utility:

wdreg -inf <path to the INF file> uninstall

Verify that no INF files that register your device(s) with WinDriver's kernel module (windrvr1630.sys) are found in the windir%\inf directory.
Uninstall WinDriver:
- On the development PC, on which you installed the WinDriver toolkit: Start | WinDriver | Uninstall , OR run the uninstall.exe utility from the WinDriver installation directory. The uninstall will stop and unload the WinDriver kernel module (windrvr1630.sys); delete the copy of the windrvr1630.inf file from the windir%\inf directory; delete WinDriver from Windows' Start menu; delete the WinDriver installation directory (except for files that you added to this directory); and delete the shortcut icons to the DriverWizard and Debug Monitor utilities from the Desktop.
- On a target PC, on which you installed the WinDriver kernel module (windrvr1630.sys), but not the entire WinDriver toolkit. Use the wdreg utility to stop and unload the driver:
  wdreg -inf <path to windrvr1630.inf> uninstall

‍⚠ Attention

‍When running this command, windrvr1630.sys should reside in the same directory as windrvr1630.inf.

On the development PC, the relevant wdreg uninstall command is executed for you by the uninstall utility.

If you attempt to uninstall WinDriver while there are open handles to the WinDriver service (windrvr1630.sys or your renamed driver, or there are connected and enabled Plug-and-Play devices that are registered to work with this service, wdreg will fail to uninstall the driver. This ensures that you do not uninstall the driver while it is being used.

You can check if the WinDriver kernel module is loaded by running the Debug Monitor utility (WinDriver\util\wddebug_gui.exe). When the driver is loaded, the Debug Monitor log displays driver and OS information; otherwise, it displays a relevant error message. On the development PC, the uninstall command will delete the Debug Monitor executables; to use this utility after the uninstallation, create a copy of wddebug_gui.exe before performing the uninstall procedure.

If windrvr1630.sys was successfully unloaded, erase the following files (if they exist):
- windir%\system32\drivers\windrvr1630.sys
- windir%\inf\windrvr1630.inf
- windir%\system32\wdapi1630.dll
- windir%\system32\wdapi1630_arm64.dll (Windows ARM64)
- windir%\sysWOW64\wdapi1630_32.dll (Windows x64)
Reboot the computer.

3.5.2. Linux WinDriver Uninstall Instructions

The following commands must be executed with root privileges.

Verify that the WinDriver driver module is not being used by another program:
- View the list of modules and the programs using each of them:

> /sbin/lsmod "

Identify any applications and modules that are using the WinDriver driver module. By default, WinDriver module names begin with windrvr1630.
Close any applications that are using the WinDriver driver module.
If you created a Kernel PlugIn driver, unload the Kernel PlugIn driver module:

/sbin/rmmod kp_xxx_module

Run the following command to unload the WinDriver driver module:

/sbin/modprobe -r windrvr1630

If you created a Kernel PlugIn driver, remove it as well.
Remove the file .windriver.rc from the /etc directory:

rm -f /etc/.windriver.rc

Remove the file .windriver.rc from $HOME:

rm -f $HOME/.windriver.rc

If you created a symbolic link to DriverWizard, remove the link using the command:

rm -f /usr/bin/wdwizard

Remove the WinDriver installation directory using the command:

rm -rf (path to the WinDriver directory)

For example, # rm -rf ~/WinDriver.

Remove the WinDriver shared object file, if it exists:

/usr/lib/libwdapi1630.so (32-bit x86) / /usr/lib64/libwdapi1630.so (64-bit x86).

3.5.3. MacOS WinDriver Uninstall Instructions

To uninstall WinDriver on MacOS, open a terminal window and type the following commands:

$ cd WinDriver-1630-Darwin/redist/

$ sudo ./wd_mac_uninstall.sh