10.3. Linux Driver Distribution

To distribute your driver, prepare a distribution package containing the required files — as outlined in Section 10.3.1 — and then build and install the required driver components on the target — as outlined in Sections 10.3.2–10.3.3.

[Note]
  • If you have renamed the WinDriver driver modules [11.2], replace references to windrvr1260 in the following instructions with the name of your renamed driver module.
  • It is recommended that you supply an installation shell script to automate the build and installation processes on the target.

10.3.1. Preparing the Distribution Package

Prepare a distribution package containing the required files, as described in this section.

[Note]
  • If you wish to distribute drivers for both 32-bit and 64-bit target platforms, you must prepare separate distribution packages for each platform. The required files for each package are provided in the WinDriver installation directory for the respective platform.
  • In the following instructions, <source_dir> represents the source directory from which to copy the distribution files. The default source directory is your WinDriver installation directory. However, if you have renamed the WinDriver driver modules [11.2], the source directory is a directory containing modified files for compiling and installing the renamed drivers; when using DriverWizard to generate the driver code, the source directory for the renamed driver is the generated xxx_installation directory, where xxx is the name of your generated driver project (see Section 11.2.2, Step 1).

10.3.1.1. Kernel Module Components

WinDriver uses two kernel modules: the main WinDriver driver module, which implements the WinDriver API — windrvr1260.o/.ko — and a driver module that implements the USB functionality — windrvr1260_usb.o/.ko.

[Note]
Your kernel driver modules cannot be distributed as-is; they must be recompiled on each target machine, to match the kernel version on the target. This is due to the following reason: The Linux kernel is continuously under development, and kernel data structures are subject to frequent changes. To support such a dynamic development environment, and still have kernel stability, the Linux kernel developers decided that kernel modules must be compiled with header files identical to those with which the kernel itself was compiled. They enforce this by including a version number in the kernel header files, which is checked against the version number encoded into the kernel. This forces Linux driver developers to support recompilation of their driver with the target system's kernel version.

Following is a list of the components you need to distribute to enable compilation of your kernel driver modules on the target machine.

[Note]
It is recommended that you copy the files to subdirectories in the distribution directory that match the source subdirectories, such as redist and include, except where otherwise specified. If you select not do so, you will need to modify the file paths in the configuration scripts and related makefile templates, to match the location of the files in your distribution directory.
  • From the <source_dir>/include directory, copy windrvr.h, wd_ver.h, and windrvr_usb.h — header files required for building the kernel modules on the target.
  • From the <WinDriver installation directory>/util directory (or from the generated DriverWizard xxx_installation/redist directory), copy wdreg — a script for loading the WinDriver kernel driver modules (see Section 9.3) — to the redist distribution directory.
  • From the <source_dir>/redist directory, unless where otherwise specified, copy the following files:
    • setup_inst_dir — a script for installing the WinDriver driver modules, using wdreg (see above).
    • linux_wrappers.c/.h — wrapper library source code files that bind the kernel module to the Linux kernel.
    • linux_common.h and wdusb_interface.h — header files required for building the kernel modules on the target.
    • wdusb_linux.c — source file used by WinDriver to utilize the USB stack.
    • The compiled object code for building the WinDriver kernel driver modules
      • windrvr_gcc_v3.a — for GCC v3.x.x compilation
      • windrvr_gcc_v3_regparm.a — for GCC v3.x.x compilation with the regparm flag
      • windrvr_gcc_v2.a — for GCC v2.x.x compilation; note that this file is not found in the 64-bit WinDriver installations, because 64-bit Linux architectures don't use GCC v2.
    • Configuration scripts and makefile templates for creating makefiles for building and installing the WinDriver kernel driver modules.
      [Note]
      Files that include .kbuild in their names use kbuild for the driver compilation.
      • configure — a configuration script that uses the makefile.in template to create a makefile for building and installing the WinDriver driver modules, and executes the configure.wd and configure.usb scripts (see below).
      • configure.wd — a configuration script that uses the makefile.wd[.kbuild].in template to create a makefile.wd[.kbuild] makefile for building the windrvr1260.o/.ko driver module.
      • configure.usb — a configuration script that uses the makefile.usb[.kbuild].in template to create a makefile.usb[.kbuild] makefile for building the windrvr1260_usb.o/.ko driver module.
      • makefile.in — a template for the main makefile for building and installing the WinDriver kernel driver modules, using makefile.wd[.kbuild] and makefile.usb[.kbuild].
      • makefile.wd.in and makefile.wd.kdbuild.in — templates for creating makefile.wd[.kbuild] makefiles for building and installing the windrvr1260.o/.ko driver module.
      • makefile.usb.in and makefile.usb.kdbuild.in — templates for creating makefile.usb[.kbuild] makefiles for building and installing the windrvr1260_usb.o/.ko driver module.

10.3.1.2. User-Mode Hardware-Control Application or Shared Object

Copy the user-mode hardware-control application or shared object that you created with WinDriver, to the distribution package.

If your hardware-control application/shared object uses libwdapi1260.so — as is the case for the WinDriver samples and generated DriverWizard projects — copy this file from the <source_dir>/lib directory to your distribution package.
If you are distributing a 32-bit application/shared object to a target 64-bit platform [A.2] — copy libwdapi1260_32.so from the WinDriver/lib directory to your distribution package, and rename the copy to libwdapi1260.so.

Since your hardware-control application/shared object does not have to be matched against the Linux kernel version number, you may distribute it as a binary object (to protect your code from unauthorized copying). If you select to distribute your driver's source code, note that under the license agreement with Jungo you may not distribute the source code of the libwdapi1260.so shared object, or the WinDriver license string used in your code.

10.3.2. Building and Installing the WinDriver Driver Modules on the Target

From the distribution package subdirectory containing the configure script and related build and installation files — normally the redist subdirectory [10.3.2] — perform the following steps to build and install the driver modules on the target:

  1. Generate the required makefiles:
    $ ./configure
    [Note]
    • 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. You can force the use of kbuild on earlier versions of Linux, by executing the configuration script with the --enable-kbuild flag.
    [Note]
    For a full list of the configuration script options, use the --help option:
    ./configure --help
  2. Build the WinDriver driver modules:
    $ make

    This will create a LINUX.<kernel version>.<CPU> directory, containing the newly compiled driver moduleswindrvr1260.o/.ko and windrvr1260_usb.o/.ko.

  3. Install the windrvr1260.o/.ko and windrvr1260_usb.o/.ko driver modules.
    [Note]
    The following command must be executed with root privileges.
    # make install

    The installation is performed using the setup_inst_dir script, which copies the driver modules to the target's loadable kernel modules directory, and uses the wdreg script [9.3] to load the driver modules.

  4. Change the user and group IDs and give read/write permissions to the device file /dev/windrvr1260, 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:
    windrvr1260:root:root:0666
[Tip]
Use the wdreg script to dynamically load the WinDriver driver modules on the target after each boot [9.3]. To automate this, copy wdreg to the target machine, and add the following line to the target's Linux boot file (for example, /etc/rc.local):
<path to wdreg> windrvr1260

10.3.3. Installing the User-Mode Hardware-Control Application or Shared Object

If your user-mode hardware-control application or shared object uses libwdapi1260.so [10.3.1.2], copy libwdapi1260.so from the distribution package to the target's library directory:

  • /usr/lib — when distributing a 32-bit application/shared object to a 32-bit or 64-bit target
  • /usr/lib64 — when distributing a 64-bit application/shared object to a 64-bit target

If you decided to distribute the source code of the application/shared object [10.3.1.2], copy the source code to the target as well.

[Caution]
Remember that you may not distribute the source code of the libwdapi1260.so shared object or your WinDriver license string as part of the source code distribution [10.3.1.2].