14.5  Linux Driver Distribution
Prev Chapter 14. Distributing Your Driver Next

14.5  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 module (windrvr6.o/.ko), as explained in section 15.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 15.2.3, 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.

14.5.1  Kernel Modules

Since (windrvr6.o/.ko) is a kernel module, it must be recompiled for every kernel version on which it is 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.
    Note that windrvr_usb.h and wdusb_interface.h are required even for non-USB drivers.

  • configure: a configuration script that creates makefile from makefile.in and runs configure.wd (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.
    [Note]
    When you configure WinDriver for compilation, be sure to exclude USB support:

    ./configure --disable-usb-support

  • configure.wd: a configuration script that creates makefile.wd[.kbuild] from makefile.wd[.kbuild].in.
  • makefile.in: a template for the main WinDriver makefile, which compiles and installs WinDriver by making makefile.wd[.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.
  • setup_inst_dir: a script to install your driver module.
  • wdreg (provided under the WinDriver/util directory): a script to load the WinDriver kernel driver module (see section 13.4).
    Note: The setup_inst_dir script uses wdreg to load the driver module.

14.5.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 or 32-bit PowerPC 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.

14.5.3  Kernel PlugIn Modules

This section lists the components that must be distributed together with your driver source/object code, to enable recompilation of a Kernel PlugIn module (kp_xxx_module.o/.ko).

Kernel PlugIn modules must be recompiled for every kernel version on which they are to be loaded. Therefore, you must supply the various Kernel PlugIn component files to your customers so that they can recompile the Kernel PlugIn. You can use the configure.kp script that DriverWizard created for you, during generation of the Kernel PlugIn, to build Kernel PlugIn modules for distribution.

[Note]
You may need to modify the configure.kp script – especially the file paths in it.

When building the Kernel PlugIn (using the make command [12.7.3]), before distribution, the object code for the WinDriver Kernel PlugIn module is created in the LINUX.<KERNEL_VER>.<CPU> directory. A different type of *.a file is generated, depending upon the gcc version used for its compilation. For building the Kernel PlugIn on the target machine, the .a file type must be compatible with the target kernel:

  • kp_xxx_gcc_v2.a is compatible with kernels compiled using GCC v2.x.x.
  • kp_xxx_gcc_v3.a is compatible with kernels compiled using GCC v3.x.x.
  • kp_xxx_gcc_v3_regparm.a is compatible with kernels compiled using GCC v3.x.x, with the regparm flag set.

[Note]
It is recommended to generate and distribute all of the types of .a object code files, to ensure compatibility with various target environments.

Copy the Kernel PlugIn *.a object files from the LINUX.<KERNEL_VER>.<CPU> directory to the WinDriver/lib directory, for distribution.

The following components, generated by DriverWizard, are provided in the WinDriver/redist directory:

  • configure.kp: a configuration script that creates makefile.kp from makefile.[kbuild].in.
    [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.
    • In general, the files for use with kbuild include .kbuild in their names. However, the output file makefile.kp is an exception to this rule.
    • If you have renamed the WinDriver kernel module, be sure to uncomment the ADDITIONAL_FLAGS line in each of the configuration scripts.
  • makefile.kp.in: a template for a makefile that compiles the Kernel PlugIn module and installs it.
  • makefile.kp.kbuild.in: a template for a makefile that compiles the Kernel PlugIn module using kbuild, and then installs the module.

The following components, generated by DriverWizard, are provided in the WinDriver/lib directory:

  • kp_wdapi1021_gcc_v2.a
  • kp_wdapi1021_gcc_v3.a
  • kp_wdapi1021_gcc_v3_regparm.a

The following components are provided in the WinDriver/redist directory:

  • linux_wrappers.c/h: wrapper library source code files that bind the WinDriver kernel module to the Linux kernel.
    [Note]
    These files must be in the same directory as configure.kp configuration script and the generated makefile.kp file. If the files are moved, modify the configuration script to refer to their new location.
  • Header files required for recompiling the WinDriver kernel module on the target platform: linux_common.h and wdusb_interface.h.
    Note that wdusb_interface.h is required, even for non-USB drivers.

The following components are provided in the WinDriver/include directory:

  • Header files required for recompiling the WinDriver kernel module on the target platform: windrvr.h, wd_ver.h, and windrvr_usb.h.
    Note that wdusb_interface.h is required, even for non-USB drivers.

14.5.3.1  Rebuilding the Kernel PlugIn

Distribute the Kernel PlugIn components to the target machine and then build the Kernel PlugIn module there. For example, run the following commands on the target machine, from the redist directory:

To generate the Kernel PlugIn makefile: 

$ ./configure.kp --disable-usb-support

To build the Kernel PlugIn module: 

$ make -f makefile.kp

A LINUX.<KERNEL_VER>.<CPU>.KP directory is created, containing the newly compiled module: kp_xxx_module.o/.ko.

[Note]
When using kbuild, make sure that there is a copy of the Module.symvers file in the same directory as the configure.kp script and the generated makefile.kp file. Module.symvers is generated during compilation of the WinDriver kernel module.

To install the Kernel PlugIn module: 

# make install -f makefile.kp

[Note]
Installation of a Kernel PlugIn must be performed with super user (root) privileges.

14.5.4  Installation Script

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

© Jungo Ltd. 2005–2010

Prev Up Next
14.4  Mac OS X Driver Distribution Home Chapter 15. Driver Installation – Advanced Issues