Preparing the System

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

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 — WD1640LN.tar.gz / WD1640LNx86_64.tar / WD1640LNARM.tar / WD1640LNARM64.tar

$ tar -xvzf /WD1640LN[x86_64/ARM/ARM64].tar.gz

Installing WinDriver on x86/x86_64

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 by entering 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 enter the following:

[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 /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/windrvr1640, 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: windrvr1640: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.

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 [email protected].

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:

1. 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.
2. Make sure you have installed the relevant gcc compiler for the platform (arm-linux-gnueabihf-gcc for ARM, aarch64-linux-gnu-gcc for ARM64).
3. Download the ARM/ARM64 WinDriver package to your Linux development machine (even if your development platform is of a different architecture!).
4. Untar the WinDriver package:

$ tar -xzvf WD1640LNARM.tar.gz
# or
$ tar -xzvf WD1640LNARM64.tar.gz

5. Go to the redist folder and run the cross compilation script:

For ARM:

$ cd WD1640LNARM/redist
$ sudo ./wd_arm_cross_compile.sh PATH_TO_YOUR_COMPILED_KERNEL_SOURCE

Or for ARM64:

$ cd WD1640LNARM64/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 [email protected] for further assistance.

On the ARM/ARM64 platform:
 

1. 1. Transfer the WinDriver package to your platform and untar it:

   $ tar -xzvf WD1640LNARM.tar.gz
   # or
   $ tar -xzvf WD1640LNARM64.tar.gz
   

   2. Go to the redist folder and install the driver:

   $ cd WD1640LNARM/redist
   

   3. Copy the directory WD1640/redist/LINUX.PRECOMPILED.ARM or WD1640/redist/LINUX.PRECOMPILED.ARM64 from the development machine to WD1640/redist/LINUX.PRECOMPILED.ARM or WD1640/redist/LINUX.PRECOMPILED.ARM64 on your platform.
   4. Install the precompiled kernel module(s):

   $ ./configure --enable-precompiled
   $ sudo make precompiled_install
   

    

   Restricting Hardware Access on Linux

   Since /dev/windrvr1640 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/windrvr1640 to trusted users.

   For security reasons the WinDriver installation script does not automatically perform the steps of changing the permissions on /dev/windrvr1640 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/windrvr1640 to your user name could be done using the chmod command in the Linux terminal.
    

   Uninstalling WinDriver

   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 windrvr1640.
   • 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 windrvr1640

   • 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/libwdapi1640.so (32-bit x86) / /usr/lib64/libwdapi1640.so (64-bit x86).

Preparing the System

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: ‍Disabling 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

Installation on MacOS x86_64

Then using a Terminal window, run the following commands:

# Unzipping
$ tar -xvzf WD1640MAC.tar.gz
# Driver install 
$ cd WD1640MAC/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

Installation on MacOS ARM64 (M1)

Then using a Terminal window, run the following commands:

# Unzipping 
$ tar -xvzf WD1640MACARM64.tar.gz
# Driver install 
$ cd WD1640MACARM64/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

⚠ 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.

 

Uninstalling WinDriver

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

$ cd WinDriver-1640-Darwin/redist/ 
$ sudo ./wd_mac_uninstall.sh