Merge branch 'next' of git://git.kernel.org/pub/scm/linux/kernel/git/rydberg/input-mt into next

Multi-touch (MT) Protocol

-------------------------

	Copyright (C) 2009	Henrik Rydberg <rydberg@euromail.se>

	Copyright (C) 2009-2010	Henrik Rydberg <rydberg@euromail.se>

Introduction

major and minor axis of an ellipse. Finally, the orientation of the oval

shape can be describe with the ORIENTATION parameter.

For type A devices, further specification of the touch shape is possible

via ABS_MT_BLOB_ID.

The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a

contact or a pen or something else.  Devices with more granular information

may specify general shapes as blobs, i.e., as a sequence of rectangular

shapes grouped together by an ABS_MT_BLOB_ID. Finally, for the few devices

that currently support it, the ABS_MT_TRACKING_ID event may be used to

report contact tracking from hardware [5].

finger or a pen or something else. Finally, the ABS_MT_TRACKING_ID event

may be used to track identified contacts over time [5].

In the type B protocol, ABS_MT_TOOL_TYPE and ABS_MT_TRACKING_ID are

implicitly handled by input core; drivers should instead call

input_mt_report_slot_state().

Event Semantics

The type of approaching tool. A lot of kernel drivers cannot distinguish

between different tool types, such as a finger or a pen. In such cases, the

event should be omitted. The protocol currently supports MT_TOOL_FINGER and

MT_TOOL_PEN [2].

MT_TOOL_PEN [2]. For type B devices, this event is handled by input core;

drivers should instead use input_mt_report_slot_state().

ABS_MT_BLOB_ID

The BLOB_ID groups several packets together into one arbitrarily shaped

contact. This is a low-level anonymous grouping for type A devices, and

contact. The sequence of points forms a polygon which defines the shape of

the contact. This is a low-level anonymous grouping for type A devices, and

should not be confused with the high-level trackingID [5]. Most type A

devices do not have blob capability, so drivers can safely omit this event.

ABS_MT_TRACKING_ID

The TRACKING_ID identifies an initiated contact throughout its life cycle

[5]. This event is mandatory for type B devices. The value range of the

TRACKING_ID should be large enough to ensure unique identification of a

contact maintained over an extended period of time.

[5]. The value range of the TRACKING_ID should be large enough to ensure

unique identification of a contact maintained over an extended period of

time. For type B devices, this event is handled by input core; drivers

should instead use input_mt_report_slot_state().

Event Computation

Notes

-----

In order to stay compatible with existing applications, the data

reported in a finger packet must not be recognized as single-touch

events. In addition, all finger data must bypass input filtering,

since subsequent events of the same type refer to different fingers.

In order to stay compatible with existing applications, the data reported

in a finger packet must not be recognized as single-touch events.

For type A devices, all finger data bypasses input filtering, since

subsequent events of the same type refer to different fingers.

The first kernel driver to utilize the MT protocol is the bcm5974 driver,

where examples can be found.

For example usage of the type A protocol, see the bcm5974 driver. For

example usage of the type B protocol, see the hid-egalax driver.

[1] With the extension ABS_MT_APPROACH_X and ABS_MT_APPROACH_Y, the

difference between the contact position and the approaching tool position

could be used to derive tilt.

[2] The list can of course be extended.

[3] Multitouch X driver project: http://bitmath.org/code/multitouch/.

[3] The mtdev project: http://bitmath.org/code/mtdev/.

[4] See the section on event computation.

[5] See the section on finger tracking.

	{ HID_USB_DEVICE(USB_VENDOR_ID_DWAV, USB_DEVICE_ID_DWAV_EGALAX_MULTITOUCH1) },

	{ HID_USB_DEVICE(USB_VENDOR_ID_DWAV, USB_DEVICE_ID_DWAV_EGALAX_MULTITOUCH2) },

	{ HID_USB_DEVICE(USB_VENDOR_ID_DWAV, USB_DEVICE_ID_DWAV_EGALAX_MULTITOUCH3) },

	{ HID_USB_DEVICE(USB_VENDOR_ID_DWAV, USB_DEVICE_ID_DWAV_EGALAX_MULTITOUCH4) },

	{ HID_BLUETOOTH_DEVICE(USB_VENDOR_ID_ELECOM, USB_DEVICE_ID_ELECOM_BM084) },

	{ HID_USB_DEVICE(USB_VENDOR_ID_EZKEY, USB_DEVICE_ID_BTC_8193) },

	{ HID_USB_DEVICE(USB_VENDOR_ID_GAMERON, USB_DEVICE_ID_GAMERON_DUAL_PSX_ADAPTOR) },

			USB_DEVICE_ID_DWAV_EGALAX_MULTITOUCH2) },

	{ HID_USB_DEVICE(USB_VENDOR_ID_DWAV,

			USB_DEVICE_ID_DWAV_EGALAX_MULTITOUCH3) },

	{ HID_USB_DEVICE(USB_VENDOR_ID_DWAV,

			USB_DEVICE_ID_DWAV_EGALAX_MULTITOUCH4) },

	{ }

};

MODULE_DEVICE_TABLE(hid, egalax_devices);

#define USB_DEVICE_ID_DWAV_EGALAX_MULTITOUCH1	0x720c

#define USB_DEVICE_ID_DWAV_EGALAX_MULTITOUCH2	0x72a1

#define USB_DEVICE_ID_DWAV_EGALAX_MULTITOUCH3	0x480e

#define USB_DEVICE_ID_DWAV_EGALAX_MULTITOUCH4	0x726b

#define USB_VENDOR_ID_ELECOM		0x056e

#define USB_DEVICE_ID_ELECOM_BM084	0x0061

#define EVIOC_MASK_SIZE(nr)	((nr) & ~(_IOC_SIZEMASK << _IOC_SIZESHIFT))

	switch (EVIOC_MASK_SIZE(cmd)) {

	case EVIOCGPROP(0):

		return bits_to_user(dev->propbit, INPUT_PROP_MAX,

				    size, p, compat_mode);

	case EVIOCGKEY(0):

		return bits_to_user(dev->key, KEY_MAX, size, p, compat_mode);