Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input

Anonymous finger details are sent sequentially as separate packets of ABS

events. Only the ABS_MT events are recognized as part of a finger

packet. The end of a packet is marked by calling the input_mt_sync()

function, which generates a SYN_MT_REPORT event. The end of multi-touch

transfer is marked by calling the usual input_sync() function.

function, which generates a SYN_MT_REPORT event. This instructs the

receiver to accept the data for the current finger and prepare to receive

another. The end of a multi-touch transfer is marked by calling the usual

input_sync() function. This instructs the receiver to act upon events

accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new

set of events/packets.

A set of ABS_MT events with the desired properties is defined. The events

are divided into categories, to allow for partial implementation.  The

ABS_MT_POSITION_Y, which allows for multiple fingers to be tracked.  If the

device supports it, the ABS_MT_WIDTH_MAJOR may be used to provide the size

of the approaching finger. Anisotropy and direction may be specified with

ABS_MT_TOUCH_MINOR, ABS_MT_WIDTH_MINOR and ABS_MT_ORIENTATION. 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, the ABS_MT_TOOL_TYPE may be used to specify

whether the touching tool is a finger or a pen or something else.

ABS_MT_TOUCH_MINOR, ABS_MT_WIDTH_MINOR and ABS_MT_ORIENTATION.  The

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

finger 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 finger tracking from hardware [5].

Here is what a minimal event sequence for a two-finger touch would look

like:

   ABS_MT_TOUCH_MAJOR

   ABS_MT_POSITION_X

   ABS_MT_POSITION_Y

   SYN_MT_REPORT

   ABS_MT_TOUCH_MAJOR

   ABS_MT_POSITION_X

   ABS_MT_POSITION_Y

   SYN_MT_REPORT

   SYN_REPORT

Event Semantics

The length of the major axis of the contact. The length should be given in

surface units. If the surface has an X times Y resolution, the largest

possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal.

possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [4].

ABS_MT_TOUCH_MINOR

The length, in surface units, of the minor axis of the contact. If the

contact is circular, this event can be omitted.

contact is circular, this event can be omitted [4].

ABS_MT_WIDTH_MAJOR

The length, in surface units, of the major axis of the approaching

tool. This should be understood as the size of the tool itself. The

orientation of the contact and the approaching tool are assumed to be the

same.

same [4].

ABS_MT_WIDTH_MINOR

The length, in surface units, of the minor axis of the approaching

tool. Omit if circular.

tool. Omit if circular [4].

The above four values can be used to derive additional information about

the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates

ABS_MT_ORIENTATION

The orientation of the ellipse. The value should describe half a revolution

clockwise around the touch center. The scale of the value is arbitrary, but

zero should be returned for an ellipse aligned along the Y axis of the

surface. As an example, an index finger placed straight onto the axis could

return zero orientation, something negative when twisted to the left, and

something positive when twisted to the right. This value can be omitted if

the touching object is circular, or if the information is not available in

the kernel driver.

The orientation of the ellipse. The value should describe a signed quarter

of a revolution clockwise around the touch center. The signed value range

is arbitrary, but zero should be returned for a finger aligned along the Y

axis of the surface, a negative value when finger is turned to the left, and

a positive value when finger turned to the right. When completely aligned with

the X axis, the range max should be returned.  Orientation can be omitted

if the touching object is circular, or if the information is not available

in the kernel driver. Partial orientation support is possible if the device

can distinguish between the two axis, but not (uniquely) any values in

between. In such cases, the range of ABS_MT_ORIENTATION should be [0, 1]

[4].

ABS_MT_POSITION_X

The BLOB_ID groups several packets together into one arbitrarily shaped

contact. This is a low-level anonymous grouping, and should not be confused

with the high-level contactID, explained below. Most kernel drivers will

not have this capability, and can safely omit the event.

with the high-level trackingID [5]. Most kernel drivers will not have blob

capability, and can safely omit the event.

ABS_MT_TRACKING_ID

The TRACKING_ID identifies an initiated contact throughout its life cycle

[5]. There are currently only a few devices that support it, so this event

should normally be omitted.

Event Computation

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

The flora of different hardware unavoidably leads to some devices fitting

better to the MT protocol than others. To simplify and unify the mapping,

this section gives recipes for how to compute certain events.

For devices reporting contacts as rectangular shapes, signed orientation

cannot be obtained. Assuming X and Y are the lengths of the sides of the

touching rectangle, here is a simple formula that retains the most

information possible:

   ABS_MT_TOUCH_MAJOR := max(X, Y)

   ABS_MT_TOUCH_MINOR := min(X, Y)

   ABS_MT_ORIENTATION := bool(X > Y)

The range of ABS_MT_ORIENTATION should be set to [0, 1], to indicate that

the device can distinguish between a finger along the Y axis (0) and a

finger along the X axis (1).

Finger Tracking

anonymous contacts currently on the surface. The order in which the packets

appear in the event stream is not important.

The process of finger tracking, i.e., to assign a unique contactID to each

The process of finger tracking, i.e., to assign a unique trackingID to each

initiated contact on the surface, is left to user space; preferably the

multi-touch X driver [3]. In that driver, the contactID stays the same and

multi-touch X driver [3]. In that driver, the trackingID stays the same and

unique until the contact vanishes (when the finger leaves the surface). The

problem of assigning a set of anonymous fingers to a set of identified

fingers is a euclidian bipartite matching problem at each event update, and

relies on a sufficiently rapid update rate.

There are a few devices that support trackingID in hardware. User space can

make use of these native identifiers to reduce bandwidth and cpu usage.

Notes

-----

time of writing (April 2009), the MT protocol is not yet merged, and the

prototype implements finger matching, basic mouse support and two-finger

scrolling. The project aims at improving the quality of current multi-touch

functionality available in the synaptics X driver, and in addition

functionality available in the Synaptics X driver, and in addition

implement more advanced gestures.

[4] See the section on event computation.

[5] See the section on finger tracking.

	ABS_MT_POSITION_Y,

	ABS_MT_TOOL_TYPE,

	ABS_MT_BLOB_ID,

	ABS_MT_TRACKING_ID,

	0

};

static unsigned long input_abs_bypass[BITS_TO_LONGS(ABS_CNT)];

	timeout = wait_event_timeout(ps2dev->wait,

				     !(ps2dev->flags & PS2_FLAG_CMD1), timeout);

	if (ps2dev->cmdcnt && timeout > 0) {

	if (ps2dev->cmdcnt && !(ps2dev->flags & PS2_FLAG_CMD1)) {

		timeout = ps2_adjust_timeout(ps2dev, command, timeout);

		wait_event_timeout(ps2dev->wait,

#ifdef CONFIG_PM

static int ucb1400_ts_resume(struct platform_device *dev)

{

	struct ucb1400_ts *ucb = platform_get_drvdata(dev);

	struct ucb1400_ts *ucb = dev->dev.platform_data;

	if (ucb->ts_task) {

		/*

#define ABS_MT_POSITION_Y	0x36	/* Center Y ellipse position */

#define ABS_MT_TOOL_TYPE	0x37	/* Type of touching device */

#define ABS_MT_BLOB_ID		0x38	/* Group a set of packets as a blob */

#define ABS_MT_TRACKING_ID	0x39	/* Unique ID of initiated contact */

#define ABS_MAX			0x3f

#define ABS_CNT			(ABS_MAX+1)