Synaptics cPad Linux driver for kernel 2.6
==========================================

The latest version is available at:
	http://www.uni-jena.de/~p1stja/linux/cpad.html
A driver for kernel 2.4 is available at:
	http://www.janerob.com/rob/ts5100/cPad/index.shtml

The cPad is an USB touchpad with background display (240x160 mono). If you
don't want to use the display, you do not need this driver. The cPad emulates
an USB mouse by default, so you can use the usbhid kernel module. But you
will be able to use Synaptics TouchPad driver for XFree86 in combination with
this kernel module, which will greatly improve mouse movement. The Display can
be accessed via a frame buffer device and via a character device.


Problems with usbhid.ko
-----------------------
cpad.ko must be loaded before usbhid.ko, otherwise usbhid.ko will handle the
cPad. To avoid this, add the following line to hid_blacklist[] before { 0, 0 }
in file drivers/usb/input/hid-core.c in the Linux source:
	{ 0x06cb, 0x0003, HID_QUIRK_IGNORE },
And recompile usbhid.ko. There are also some kernel patches which do the work
for you at http://www.uni-jena.de/~p1stja/linux/cpad.html. To apply the patch,
do
	cat <patchfile> | patch -p1
in the kernel source directory.


Installation
------------
The sources of your kernel must be installed and configured.

Configuring the kernel:
	At least, you need USB support in the kernel:
		CONFIG_USB: y/m
			Device Drivers --->
			    USB support --->
				Support for Host-side USB

	USB will only work, if you have the right driver(s) for your USB host
	controller. My Toshiba Laptop needs both the EHCI and the OHCI driver.
	If unsure, just select all:
		CONFIG_USB_EHCI_HCD and/or
		CONFIG_USB_OHCI_HCD and/or
		CONFIG_USB_UHCI_HCD: y/m
			Device Drivers --->
			    USB support --->
				EHCI HCD (USB 2.0) support
				OHCI HCD support
				UHCI HCD (most Intel and VIA) support

	Synaptics TouchPad driver for XFree86 needs an evdev interface:
		CONFIG_INPUT_EVDEV: y/m
			Device Drivers --->
			    Input device support --->
				Event interface

	If you want to use the procfs interface, you also need this:
		CONFIG_PROC_FS: y
			File systems --->
			    Pseudo filesystems --->
				/proc file system support

	If you want to use the frame buffer you need:
		CONFIG_FB and CONFIG_FB_VESA: y
			Device Drivers --->
			    Graphics support --->
				Support for frame buffer devices
				VESA VGA graphics support

	Mapping a tty on the frame buffer needs this kernel option:
		CONFIG_FRAMEBUFFER_CONSOLE: y/m
			Device Drivers --->
			    Graphics support --->
				Console display driver support --->
				    Framebuffer Console support

Installing the cpad kernel module:
	To compile the module, run:
		make
	To install the module, run:
		make install
		depmod -a

Because this driver conflicts with usbhid.ko, you have to do
	rmmod usbhid
	modprobe cpad
to load the driver, or patch the kernel like described above.


Synaptics TouchPad driver for XFree86
-------------------------------------
To enable features like tap-to-click, vertical/horizontal scrolling,
multifinger taps, etc you need Synaptics TouchPad driver for XFree86
version >= 0.13.3 in addition to this kernel module. Get it at:
	http://w1.894.telia.com/~u89404340/touchpad/


Programs for the cPad character device
--------------------------------------
If you want to flash the backlight and display nice pictures on the cPad, then
the program usr_cpad is the best choice. It is included in the tarball of the
kernel 2.4 driver, available at:
	http://www.janerob.com/rob/ts5100/cPad/index.shtml
There is also a gallery with examples, scripts ...
I have written the tool cpadconsole, which can help developing programs for
the character device. Get it at:
	http://www.uni-jena.de/~p1stja/linux/cpadconsole.html


Using the procfs interface
--------------------------
The files /proc/driver/cpad/* show some information about the cPad.

Flashing the backlight:
	echo "flash:<time in 10ms>" > /proc/driver/cpad/0

Enabling the frame buffer (disabled by default):
	echo "framerate:<rate>" > /proc/driver/cpad/0

Disabling the frame buffer:
	echo "framerate:0" > /proc/driver/cpad/0

Frame buffer dithering mode (default is 3; only in 24 bpp mode):
	echo "dithering:<number from 0 to 3>" > /proc/driver/cpad/0

Frame buffer brightness (default is 200; only in 24 bpp mode):
	echo "brightness:<number from 0 to 10000>" > /proc/driver/cpad/0

Invert black and white:
	echo "invert:1" > /proc/driver/cpad/0

Send only changed image lines:
	echo "onlychanged:1" > /proc/driver/cpad/0

Update only visible part of cPad memory (only in 1 bpp mode):
	echo "onlyvisible:1" > /proc/driver/cpad/0

Draw only one frame:
	echo "oneframe" > /proc/driver/cpad/0


Using the frame buffer device
----------------------------
The framebuffer is disabled by default. You can enable it with
	echo "framerate:30" > /proc/driver/cpad/0
The following examples assume that your primary display is /dev/fb0, so your 
touchpad is the second frame buffer device /dev/fb1. If you don't use vesafb or
any other frame buffer, then your cPad will be /dev/fb0.

Emulate 24 bpp:
	Most applications do not like frame buffers with 1 bpp. The cPad frame
	buffer can emulate 24 bpp. You can switch to 24 bpp with fbset:
		fbset -fb /dev/fb1 -depth 24
	All examples below need 24 bpp.

Playing movies:
	mplayer -vo fbdev -fb /dev/fb1 -vf scale=240:160 <file>

Running XFree86:
	You just need the following lines in the driver section of your
	XF86Config file:
		Driver		"fbdev"
		Option		"fbdev"	"/dev/fb1"

Map a tty to the frame buffer:
	Some programs need a tty on the frame buffer to run correctly. You need
	the program con2fb to map a tty to a frame buffer device. Get it at:
	ftp://platan.vc.cvut.cz/pub/linux/matrox-latest/con2fb.c.gz
	You can also use fbgetty, wich gives you a login prompt automatically:
	ftp://ftp.debian.org/debian/pool/main/f/fbgetty/
	Example: Do "fbgetty /dev/tty9 /dev/fb1", then press <ALT>+<F9> and you
	should be able to login. It looks better if you invert the screen with:
		echo "invert:1" > /proc/driver/cpad/0

Other Software for frame buffer devices:
	http://linux-fbdev.sourceforge.net


Module parameters
-----------------
Disable input devices:
	modprobe cpad disable_input=1
Disable character device:
	modprobe cpad disable_cdev=1
Disable procfs interface:
	modprobe cpad disable_procfs=1
Disable frame buffer:
	modprobe cpad disable_fb=1
Set maximum bpp to 1 (saves 108k memory):
	modprobe cpad max_bpp=1


Bugs
----
- With kernel >= 2.6.7 rmmod hangs while the evdev device of the cPad 
  (/dev/input/event?) is in use. usbhid.ko seems to have the same problem.
  If you are using Synaptics TouchPad driver for XFree86 and do rmmod from
  xterm, it will hang. Switching to console and then back to X helps.
This was a bug in the input core, now fixed in kernel 2.6.10.

Changes
-------
version 0.10:
	Major kernel shakeup at or about 2.6.13.  If you need support
	for kernel 2.6.12 or earlier, you should stick to the 0.9 release.
	This version was tested with kernel 2.6.16 to date.  Moves the
	device rebinding logic to userspace.

version 0.9:
	Grab the cPad back from any driver that has already claimed it.
	Leap ahead a couple of versions to sync with the 2.4 driver, so
	people upgrading see a more or less monotonic increase in version
	numbers (and because the Debian build of 0.5 already released with
	DRIVER_VERSION of v0.8).  Let's aim for v1.0 to be accepted into
	the mainstream kernel tree.

version 0.6:
	invert screen now possible in 1 bpp mode too

version 0.5:
	Replaced deprecated MODULE_PARM and remap_page_range.
	Merged with the 2.4 package as the cpad-0.8 release.

version 0.4:
	replaced del_timer_sync with del_timer in interrupt context (bad bug)

version 0.3:
	replaced interruptible_sleep_on with wait_event_interruptible
	removed some inline's
	show more information in procfs
	add support for 1 bpp to frame buffer
	add ioctl's to frame buffer
	add oneframe, onlychanged and onlyvisible options to frame buffer

version 0.2:
	fixed a color to mono conversion bug
	added a pseudo_palette (needed by virtual terminals)

version 0.1:
	first release


Contact
-------
Jan Steinhoff <jan.steinhoff@uni-jena.de>
