Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit d61bd77f authored by Kukjin Kim's avatar Kukjin Kim
Browse files

Merge branch 'next-samsung' into for-next 

Conflicts:
	arch/arm/mach-s5p6440/Kconfig
	arch/arm/mach-s5p6442/Kconfig
	arch/arm/mach-s5pc100/Kconfig
	arch/arm/mach-s5pv210/Kconfig
	arch/arm/mach-s5pv210/cpu.c
	arch/arm/plat-samsung/include/plat/sdhci.h
parents f2b7e3c5 1c739c7f

Documentation/input/multi-touch-protocol.txt

+149 −69
Original line number Diff line number Diff line
@@ -6,31 +6,149 @@ Multi-touch (MT) Protocol 
Introduction

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



In order to utilize the full power of the new multi-touch devices, a way to

report detailed finger data to user space is needed. This document

describes the multi-touch (MT) protocol which allows kernel drivers to

report details for an arbitrary number of fingers.

In order to utilize the full power of the new multi-touch and multi-user

devices, a way to report detailed data from multiple contacts, i.e.,

objects in direct contact with the device surface, is needed.  This

document describes the multi-touch (MT) protocol which allows kernel

drivers to report details for an arbitrary number of contacts.



The protocol is divided into two types, depending on the capabilities of the

hardware. For devices handling anonymous contacts (type A), the protocol

describes how to send the raw data for all contacts to the receiver. For

devices capable of tracking identifiable contacts (type B), the protocol

describes how to send updates for individual contacts via event slots.





Protocol Usage

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



Contact details are sent sequentially as separate packets of ABS_MT

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

packet. Since these events are ignored by current single-touch (ST)

applications, the MT protocol can be implemented on top of the ST protocol

in an existing driver.



Drivers for type A devices separate contact packets by calling

input_mt_sync() at the end of each packet. This generates a SYN_MT_REPORT

event, which instructs the receiver to accept the data for the current

contact and prepare to receive another.



Drivers for type B devices separate contact packets by calling

input_mt_slot(), with a slot as argument, at the beginning of each packet.

This generates an ABS_MT_SLOT event, which instructs the receiver to

prepare for updates of the given slot.



All drivers mark the end of a multi-touch transfer 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.



The main difference between the stateless type A protocol and the stateful

type B slot protocol lies in the usage of identifiable contacts to reduce

the amount of data sent to userspace. The slot protocol requires the use of

the ABS_MT_TRACKING_ID, either provided by the hardware or computed from

the raw data [5].



For type A devices, the kernel driver should generate an arbitrary

enumeration of the full set of anonymous contacts currently on the

surface. The order in which the packets appear in the event stream is not

important.  Event filtering and finger tracking is left to user space [3].



For type B devices, the kernel driver should associate a slot with each

identified contact, and use that slot to propagate changes for the contact.

Creation, replacement and destruction of contacts is achieved by modifying

the ABS_MT_TRACKING_ID of the associated slot.  A non-negative tracking id

is interpreted as a contact, and the value -1 denotes an unused slot.  A

tracking id not previously present is considered new, and a tracking id no

longer present is considered removed.  Since only changes are propagated,

the full state of each initiated contact has to reside in the receiving

end.  Upon receiving an MT event, one simply updates the appropriate

attribute of the current slot.





Protocol Example A

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



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

like for a type A device:



   ABS_MT_POSITION_X x[0]

   ABS_MT_POSITION_Y y[0]

   SYN_MT_REPORT

   ABS_MT_POSITION_X x[1]

   ABS_MT_POSITION_Y y[1]

   SYN_MT_REPORT

   SYN_REPORT



The sequence after moving one of the contacts looks exactly the same; the

raw data for all present contacts are sent between every synchronization

with SYN_REPORT.



Usage

-----

Here is the sequence after lifting the first contact:



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. 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.

   ABS_MT_POSITION_X x[1]

   ABS_MT_POSITION_Y y[1]

   SYN_MT_REPORT

   SYN_REPORT



And here is the sequence after lifting the second contact:



   SYN_MT_REPORT

   SYN_REPORT



If the driver reports one of BTN_TOUCH or ABS_PRESSURE in addition to the

ABS_MT events, the last SYN_MT_REPORT event may be omitted. Otherwise, the

last SYN_REPORT will be dropped by the input core, resulting in no

zero-contact event reaching userland.





Protocol Example B

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



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

like for a type B device:



   ABS_MT_SLOT 0

   ABS_MT_TRACKING_ID 45

   ABS_MT_POSITION_X x[0]

   ABS_MT_POSITION_Y y[0]

   ABS_MT_SLOT 1

   ABS_MT_TRACKING_ID 46

   ABS_MT_POSITION_X x[1]

   ABS_MT_POSITION_Y y[1]

   SYN_REPORT



Here is the sequence after moving contact 45 in the x direction:



   ABS_MT_SLOT 0

   ABS_MT_POSITION_X x[0]

   SYN_REPORT



Here is the sequence after lifting the contact in slot 0:



   ABS_MT_TRACKING_ID -1

   SYN_REPORT



The slot being modified is already 0, so the ABS_MT_SLOT is omitted.  The

message removes the association of slot 0 with contact 45, thereby

destroying contact 45 and freeing slot 0 to be reused for another contact.



Finally, here is the sequence after lifting the second contact:



   ABS_MT_SLOT 1

   ABS_MT_TRACKING_ID -1

   SYN_REPORT





Event Usage

-----------



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

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

minimum set consists of ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which

allows for multiple fingers to be tracked.  If the device supports it, the

allows for multiple contacts to be tracked.  If the device supports it, the

ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used to provide the size

of the contact area and approaching finger, respectively.

of the contact area and approaching contact, respectively.



The TOUCH and WIDTH parameters have a geometrical interpretation; imagine

looking through a window at someone gently holding a finger against the
@@ -41,56 +159,26 @@ ABS_MT_TOUCH_MAJOR, the diameter of the outer region is 
ABS_MT_WIDTH_MAJOR. Now imagine the person pressing the finger harder

against the glass. The inner region will increase, and in general, the

ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR, which is always smaller than

unity, is related to the finger pressure. For pressure-based devices,

unity, is related to the contact pressure. For pressure-based devices,

ABS_MT_PRESSURE may be used to provide the pressure on the contact area

instead.



In addition to the MAJOR parameters, the oval shape of the finger can be

In addition to the MAJOR parameters, the oval shape of the contact can be

described by adding the MINOR parameters, such that MAJOR and MINOR are the

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

shape can be describe with the ORIENTATION parameter.



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

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



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

like:



   ABS_MT_POSITION_X

   ABS_MT_POSITION_Y

   SYN_MT_REPORT

   ABS_MT_POSITION_X

   ABS_MT_POSITION_Y

   SYN_MT_REPORT

   SYN_REPORT



Here is the sequence after lifting one of the fingers:

report contact tracking from hardware [5].



   ABS_MT_POSITION_X

   ABS_MT_POSITION_Y

   SYN_MT_REPORT

   SYN_REPORT



And here is the sequence after lifting the remaining finger:



   SYN_MT_REPORT

   SYN_REPORT



If the driver reports one of BTN_TOUCH or ABS_PRESSURE in addition to the

ABS_MT events, the last SYN_MT_REPORT event may be omitted. Otherwise, the

last SYN_REPORT will be dropped by the input core, resulting in no

zero-finger event reaching userland.



Event Semantics

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



The word "contact" is used to describe a tool which is in direct contact

with the surface. A finger, a pen or a rubber all classify as contacts.



ABS_MT_TOUCH_MAJOR



The length of the major axis of the contact. The length should be given in
@@ -157,15 +245,16 @@ MT_TOOL_PEN [2]. 
ABS_MT_BLOB_ID



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 trackingID [5]. Most kernel drivers will not have blob

capability, and can safely omit the event.

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]. There are currently only a few devices that support it, so this event

should normally be omitted.

[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.





Event Computation
@@ -192,20 +281,11 @@ finger along the X axis (1). 
Finger Tracking

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



The kernel driver should generate an arbitrary enumeration of the set of

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 trackingID to each

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

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.

initiated contact on the surface, is a Euclidian Bipartite Matching

problem.  At each event synchronization, the set of actual contacts is

matched to the set of contacts from the previous synchronization. A full

implementation can be found in [3].





Gestures

arch/arm/Kconfig

+13 −0
Original line number Diff line number Diff line
@@ -634,6 +634,7 @@ config ARCH_S3C2410 
	select ARCH_HAS_CPUFREQ

	select HAVE_CLK

	select ARCH_USES_GETTIMEOFFSET

	select HAVE_S3C2410_I2C

	help

	  Samsung S3C2410X CPU based systems, such as the Simtec Electronics

	  BAST (<http://www.simtec.co.uk/products/EB110ITX/>), the IPAQ 1940 or
@@ -663,6 +664,8 @@ config ARCH_S3C64XX 
	select S3C_DEV_NAND

	select USB_ARCH_HAS_OHCI

	select SAMSUNG_GPIOLIB_4BIT

	select HAVE_S3C2410_I2C

	select HAVE_S3C2410_WATCHDOG

	help

	  Samsung S3C64XX series based systems
@@ -671,7 +674,10 @@ config ARCH_S5P6440 
	select CPU_V6

	select GENERIC_GPIO

	select HAVE_CLK

	select HAVE_S3C2410_WATCHDOG

	select ARCH_USES_GETTIMEOFFSET

	select HAVE_S3C2410_I2C

	select HAVE_S3C_RTC

	help

	  Samsung S5P6440 CPU based systems
@@ -681,6 +687,7 @@ config ARCH_S5P6442 
	select GENERIC_GPIO

	select HAVE_CLK

	select ARCH_USES_GETTIMEOFFSET

	select HAVE_S3C2410_WATCHDOG

	help

	  Samsung S5P6442 CPU based systems
@@ -691,6 +698,9 @@ config ARCH_S5PC100 
	select CPU_V7

	select ARM_L1_CACHE_SHIFT_6

	select ARCH_USES_GETTIMEOFFSET

	select HAVE_S3C2410_I2C

	select HAVE_S3C_RTC

	select HAVE_S3C2410_WATCHDOG

	help

	  Samsung S5PC100 series based systems
@@ -701,6 +711,9 @@ config ARCH_S5PV210 
	select HAVE_CLK

	select ARM_L1_CACHE_SHIFT_6

	select ARCH_USES_GETTIMEOFFSET

	select HAVE_S3C2410_I2C

	select HAVE_S3C_RTC

	select HAVE_S3C2410_WATCHDOG

	help

	  Samsung S5PV210/S5PC110 series based systems

arch/arm/mach-s3c64xx/Kconfig

+15 −0
Original line number Diff line number Diff line
@@ -57,11 +57,21 @@ config S3C64XX_SETUP_I2C1 
	help

	  Common setup code for i2c bus 1.



config S3C64XX_SETUP_IDE

	bool

	help

	  Common setup code for S3C64XX IDE.



config S3C64XX_SETUP_FB_24BPP

	bool

	help

	  Common setup code for S3C64XX with an 24bpp RGB display helper.



config S3C64XX_SETUP_KEYPAD

	bool

	help

	  Common setup code for S3C64XX KEYPAD GPIO configurations



config S3C64XX_SETUP_SDHCI_GPIO

	bool

	help
@@ -95,15 +105,20 @@ config MACH_SMDK6410 
	select S3C_DEV_HSMMC

	select S3C_DEV_HSMMC1

	select S3C_DEV_I2C1

	select SAMSUNG_DEV_IDE

	select S3C_DEV_FB

	select S3C_DEV_RTC

	select SAMSUNG_DEV_TS

	select S3C_DEV_USB_HOST

	select S3C_DEV_USB_HSOTG

	select S3C_DEV_WDT

	select SAMSUNG_DEV_KEYPAD

	select HAVE_S3C2410_WATCHDOG

	select S3C64XX_SETUP_SDHCI

	select S3C64XX_SETUP_I2C1

	select S3C64XX_SETUP_IDE

	select S3C64XX_SETUP_FB_24BPP

	select S3C64XX_SETUP_KEYPAD

	help

	  Machine support for the Samsung SMDK6410

arch/arm/mach-s3c64xx/Makefile

+2 −0
Original line number Diff line number Diff line
@@ -35,6 +35,8 @@ obj-$(CONFIG_S3C64XX_DMA) += dma.o 


obj-$(CONFIG_S3C64XX_SETUP_I2C0) += setup-i2c0.o

obj-$(CONFIG_S3C64XX_SETUP_I2C1) += setup-i2c1.o

obj-$(CONFIG_S3C64XX_SETUP_IDE) += setup-ide.o

obj-$(CONFIG_S3C64XX_SETUP_KEYPAD) += setup-keypad.o

obj-$(CONFIG_S3C64XX_SETUP_SDHCI) += setup-sdhci.o

obj-$(CONFIG_S3C64XX_SETUP_FB_24BPP) += setup-fb-24bpp.o

obj-$(CONFIG_S3C64XX_SETUP_SDHCI_GPIO) += setup-sdhci-gpio.o

arch/arm/mach-s3c64xx/clock.c

+18 −6
Original line number Diff line number Diff line
@@ -132,6 +132,12 @@ static struct clk init_clocks_disable[] = { 
		.name		= "nand",

		.id		= -1,

		.parent		= &clk_h,

	}, {

		.name		= "rtc",

		.id		= -1,

		.parent		= &clk_p,

		.enable		= s3c64xx_pclk_ctrl,

		.ctrlbit	= S3C_CLKCON_PCLK_RTC,

	}, {

		.name		= "adc",

		.id		= -1,
@@ -165,6 +171,12 @@ static struct clk init_clocks_disable[] = { 
		.ctrlbit	= S3C6410_CLKCON_PCLK_IIS2,

	}, {

#endif

		.name		= "keypad",

		.id		= -1,

		.parent		= &clk_p,

		.enable		= s3c64xx_pclk_ctrl,

		.ctrlbit	= S3C_CLKCON_PCLK_KEYPAD,

	}, {

		.name		= "spi",

		.id		= 0,

		.parent		= &clk_p,
@@ -294,12 +306,6 @@ static struct clk init_clocks[] = { 
		.parent		= &clk_p,

		.enable		= s3c64xx_pclk_ctrl,

		.ctrlbit	= S3C_CLKCON_PCLK_UART3,

	}, {

		.name		= "rtc",

		.id		= -1,

		.parent		= &clk_p,

		.enable		= s3c64xx_pclk_ctrl,

		.ctrlbit	= S3C_CLKCON_PCLK_RTC,

	}, {

		.name		= "watchdog",

		.id		= -1,
@@ -310,6 +316,12 @@ static struct clk init_clocks[] = { 
		.id		= -1,

		.parent		= &clk_p,

		.ctrlbit	= S3C_CLKCON_PCLK_AC97,

	}, {

		.name		= "cfcon",

		.id		= -1,

		.parent		= &clk_h,

		.enable		= s3c64xx_hclk_ctrl,

		.ctrlbit	= S3C_CLKCON_HCLK_IHOST,

	}

};