APPLICATIONS ENGINEERING NOTE
3M Touch Systems, Inc.
300 Griffin Brook Park Drive
Methuen, MA 01844
Phone:  978-659-9000
Fax:  978-659-9100
www.3Mtouch.com
Affected Product: The MicroTouch™  Software Suite TouchWare for Linux
© 2006 3M. 
All Rights Reserved.
TouchWare for Linux Kernel Module Issues
Date Originated: 3 August 2006
Created by: Damir Suljic
Date Revised:  21 May 2007
Revised by: Damir Suljic

Overview
The TouchWare for Linux Software, part of the MicroTouch™ Software Suite, uses a kernel module for the Linux kernel 2.4 and 2.6 operating system. This module is responsible for communicating with the touch screen controllers in a touch system.
This document details known issues with kernel module not jet resolved or incorporated into released product.  It gives basic steps to resolve the problems on users’ site, and describes suggested changes required on source RPMs.
The document first covers a build process of the kernel module and structure of source RPM. It explains how to customize the Source RPM and deploy it on target systems with new changes. The list of known issues will follow including problem description and details about system affected.   
Source RPM Build and Structure
TouchWare package is in form of Source RPM and main reason for this is Kernel module included in this package. In one Linux system the kernel module needs to be built and linked against current kernel version, and since Linux has vast number of kernel versions available we decided to allow users to build our package against their version. Now with every new version it is possible to hit a situation where kernel module will not build or will not load on target system.
After initial installation of source RPM into build directory (usually “/usr/src/<rpm directory>”) the building binary RPM (all this is described in Readme file included in package) will have either failure while building or while installing binary RPM. In both cases you will have to investigate in more details what and where in process the errors were happening. In case of build error the command line output will give more information what file did fail to build. If binary RPM build successfully but after installing it kernel module did not load, you can check this by issuing “lsmod” in command line and look for TWDrv, check “/var/log/messages” file for errors related to TWDrv (“invalid module format”, “unresolved sysmbols”, etc).
Customization of Source RPM
To make changes on source RPM you will have to extract TWDrvSoureces.tgz file (usually found in “/usr/src/<rpm directory>/SOURCES” directory) in temporary directory “/usr/tmp/mytemp”. After extracting sources change directory to “/usr/src/mytemp” and you will see directories and files from our package. One of the directories is TwDrvKit where the kernel module files are located. Make needed changes on TWDriver.c file. Test build it by issuing make command, and insert module with “insmod TWDrv.ko”.
If the changes were acceptable, change directory to “/usr/tmp/mytemp” and issue “tar –czf TWDrvSources.tgz *” (it is * for all files in current directory). Copy newly created .tgz file into SOURCES directory and build binary RPM again. For more questions about RPM customization consult Linux RPM documentation.

List of Known Issues:
In the list of known issues we will include distribution and kernel version, short description of problem and possible solution.
Fedora Core 5 kernel version 2.6.15-1.2054_FC5
This particular issue is probably only related to this specific kernel version. The package builds without error but after installation the kernel module fails to load. The log file contains following error related to TWDrv module: “unresolved symbol print_tainted”. The reason of failure is that function was not compiled into kernel.
Resolution: Change TWDriver.c file:
After the line:
static void TWDrv_ReleaseOpenLock (DEVICE_EXTENSION * pDevExit);
Add line
const char *print_tainted(void){ return NULL;};
This change is probably not needed for future kernel releases.
Fedora Core 5 kernel version 2.6.17-1.2157_FC5
CentOS 4.2  kernel version 2.6.9.22.EL
In this case the kernel module fails to build. The build errors point to TWDriver.c file starting line 108 “error: expected ')' before string constant”. The reason for this failure is change in kernel include files against which the module is built. The macro MODULE_PARM does not exist anymore.
Resolution:  Replace all MODULE_PARAM macros with new function call in TWDriver.c file:
1. Replace Lines:
MODULE_PARM (TWDrv_pszSerialPath, "s");
With lines:
#ifndef MODULE_PARM
module_param(TWDrv_pszSerialPath, charp, 0000);
#else
MODULE_PARM (TWDrv_pszSerialPath, "s");
#endif
2. Replace Line:
MODULE_PARM (TWDrv_nMaxSerial, "i");
With lines:
#ifndef MODULE_PARM
module_param(TWDrv_nMaxSerial, int, 0000);
#else  
MODULE_PARM (TWDrv_nMaxSerial, "i");
#endif
3. Replace Line:
MODULE_PARM (TWDrv_nMajorNumber, "i");
With lines:
#ifndef MODULE_PARM
module_param(TWDrv_nMajorNumber, int, 0000);
#else  
MODULE_PARM (TWDrv_nMajorNumber, "i");
#endif
4. Replace Line:
MODULE_PARM (TWDrv_nMinSerial, "i");
With lines:
#ifndef MODULE_PARM
module_param(TWDrv_nMinSerial, int, 0000);
#else  
MODULE_PARM (TWDrv_nMinSerial, "i");
#endif
5. Replace Line:
MODULE_PARM (TWDrv_nSerialTimeOut, "i");
With lines:
#ifndef MODULE_PARM
module_param(TWDrv_nSerialTimeOut, int, 0000);
#else  
MODULE_PARM (TWDrv_nSerialTimeOut, "i");
#endif

In addition to the previous changes the both distributions require changes to accommodate Xfree86 switch to Xorg. The binary driver will work but the driver’s installation tree has changed.  

Resolution:  In order to resolve this change TWDrv.spec file in SPECS directory before building binary RPM and new source RPM.
The changes in spec file are:
1. After line 81 (in "%install" section) add following two lines:

mkdir -p ${RPM_BUILD_ROOT}/usr/lib/xorg/modules/input
install -o root -g root -m444 Xfree4.0.3/TWXinput_drv.o  ${RPM_BUILD_ROOT}/usr/lib/xorg/modules/input

2. After line 173 in original file (in %files section) add one line:
/usr/lib/xorg/modules/input/TWXinput_drv.o
   
After completing all the changes rebuild binary RPM and new source RPM with following command:

	rpmbuld  -ba TWDrv.spec

Latest kernel from kernel.org starting with version 2.6.18
This particular issue is probably related to all newer kernel versions. The build errors point to TWDriver.c file with message “devfs_fs_kernel.h” file not found.
Resolution: Change TWDriver.c file:
Find and delete the line:
#include <linux/devfs_fs_kernel.h>;

Latest kernel from kernel.org starting with version 2.6.20
The macro “SLAB_ATOMIC” definition is abandoned in all newer kernel versions. The build errors point to TWDriver.c file with message: error: 'SLAB_ATOMIC' undeclared (first use in this function).
Resolution: Change TWDriver.c file:
Find and replace all instances of “SLAB_ATOMIC” with “GFP_ATOMIC” macro.

MicroTouch, the MicroTouch logo, and ClearTek are either registered trademarks or trademarks of 3M in the United States and/or other countries.  Windows and/or other Microsoft products referenced herein are either registered trademarks or trademarks of Microsoft Corporation in the U.S. and/or other countries. 









P/N xxxxx	3M Touch Systems Inc. Proprietary Information	     Page  PAGE 1

 AUTHOR MicroTouch Systems	Page  PAGE 1	 FILENAME TouchWare for Linux Driver IO.doc