11.4  Linux Driver Distribution

[Note]
  • 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 that is checked against the version number encoded into the kernel. This forces Linux driver developers to facilitate recompilation of their driver based on the target system's kernel version.
  • If you have renamed the WinDriver driver modules (windrvr6.o/.ko and windrvr6_usb.o/.ko), as explained in section 12.2, replace windrvr6 references with your new driver name, and replace references to the WinDriver redist, lib and include directories with the path to your copy of the relevant directory. For example, when using the generated DriverWizard renamed driver files for your driver project, as explained in section 12.2.2, you can replace references to the WinDriver/redist directory with references to the generated xxx_installation/redist directory (where xxx is the name of your generated driver project).
  • If you wish to distribute drivers for both 32-bit and 64-bit target platforms, you must prepare a separate driver installation package for each platform. The required files for each package are located within the WinDriver installation directory for the respective platform.

11.4.1  Kernel Modules

WinDriver uses two kernel modules: the main WinDriver driver module, which implements the WinDriver API – windrvr6.o/.ko – and a driver module that implements the USB functionality – windrvr6_usb.o/.ko. Since these are kernel modules, they must be recompiled for every kernel version on which they are loaded.

To facilitate recompilation, we supply the following components, which are all provided under the WinDriver/redist directory, unless specified otherwise. You need to distribute these components along with your driver source/object code.

  • windrvr_gcc_v2.a, windrvr_gcc_v3.a and windrvr_gcc_v3_regparm.a: compiled object code for the WinDriver kernel module. windrvr_gcc_v2.a is used for kernels compiled with GCC v2.x.x, and windrvr_gcc_v3.a is used for kernels compiled with GCC v3.x.x. windrvr_gcc_v3_regparm.a is used for kernels compiled with GCC v3.x.x with the regparm flag.
  • linux_wrappers.c/h: wrapper library source code files that bind the WinDriver kernel module to the Linux kernel.
  • linux_common.h, windrvr.h, wd_ver.h, windrvr_usb.h, and wdusb_interface.h: header files required for building the WinDriver kernel module on the target.
  • wdusb_linux.c: used by WinDriver to utilize the USB stack.
  • configure: a configuration script that creates makefile from makefile.in and runs configure.wd and configure.usb (see below).

    [Note]
    If the Linux kernel is version 2.6.26 or higher, configure generates makefiles that use kbuild to compile the kernel modules. You can force the use of kbuild on earlier versions of Linux, by passing the --enable-kbuild flag to configure. The files that use kbuild include .kbuild in their names.
  • configure.wd: a configuration script that creates makefile.wd[.kbuild] from makefile.wd[.kbuild].in.
  • configure.usb: a configuration script that creates makefile.usb[.kbuild] from makefile.usb[.kbuild].in.
  • makefile.in: a template for the main WinDriver makefile, which compiles and installs WinDriver by making makefile.wd[.kbuild] and makefile.usb[.kbuild].
  • makefile.wd.in: a template for a makefile that compiles and installs the main WinDriver kernel module.
  • makefile.wd.kbuild.in: a template for a makefile that compiles the main WinDriver kernel module using kbuild, and then installs the module.
  • makefile.usb.in: a template for a makefile that compiles and installs the USB kernel module (windrvr6_usb.o/.ko).
  • makefile.usb.kbuild.in: a template for a makefile that compiles the USB kernel module using kbuild, and then installs the module.
  • setup_inst_dir: a script to install your driver modules.
  • wdreg (provided under the WinDriver/util directory): a script to load the WinDriver kernel driver modules (see section 10.3).
    Note: The setup_inst_dir script uses wdreg to load the driver modules.

11.4.2  User-Mode Hardware Control Application/Shared Objects

Copy the hardware control application/shared object that you created with WinDriver to the target.

If your hardware control application/shared object uses libwdapi1021.so (as is the case for the sample and generated DriverWizard WinDriver projects), copy this file from the WinDriver/lib directory on the development machine to the target's library directory – /usr/lib for 32-bit x86 targets, or /usr/lib64 for 64-bit x86 targets.
If you are distributing a 32-bit application/shared object to a target 64-bit platform [A.2] – copy libwdapi1021_32.so from the WinDriver/lib directory to your distribution package, rename the copy to libwdapi1021.so, and copy the renamed file to the target's /usr/lib directory.

Since your hardware control application/shared object does not have to be matched against the kernel version number, you are free to distribute it as binary code (if you wish to protect your source code from unauthorized copying) or as source code. Note that under the license agreement with Jungo you may not distribute the source code of the libwdapi1021.so shared object.

[Caution]
If you select to distribute your source code, make sure you do not distribute your WinDriver license string, which is used in the code.

11.4.3  Installation Script

We suggest that you supply an installation shell script to automate the build and installation processes on the target.