Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input (fe445c6e) · Commits · 戴 / test

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/plat-samsung/include/plat/keypad.h

0 → 100644

+43 −0

Original line number	Diff line number	Diff line
		/*
		* Samsung Platform - Keypad platform data definitions
		*
		* Copyright (C) 2010 Samsung Electronics Co.Ltd
		* Author: Joonyoung Shim <jy0922.shim@samsung.com>
		*
		* This program is free software; you can redistribute it and/or modify it
		* under the terms of the GNU General Public License as published by the
		* Free Software Foundation; either version 2 of the License, or (at your
		* option) any later version.
		*/

		#ifndef __PLAT_SAMSUNG_KEYPAD_H
		#define __PLAT_SAMSUNG_KEYPAD_H

		#include <linux/input/matrix_keypad.h>

		#define SAMSUNG_MAX_ROWS 8
		#define SAMSUNG_MAX_COLS 8

		/**
		* struct samsung_keypad_platdata - Platform device data for Samsung Keypad.
		* @keymap_data: pointer to &matrix_keymap_data.
		* @rows: number of keypad row supported.
		* @cols: number of keypad col supported.
		* @no_autorepeat: disable key autorepeat.
		* @wakeup: controls whether the device should be set up as wakeup source.
		* @cfg_gpio: configure the GPIO.
		*
		* Initialisation data specific to either the machine or the platform
		* for the device driver to use or call-back when configuring gpio.
		*/
		struct samsung_keypad_platdata {
		const struct matrix_keymap_data *keymap_data;
		unsigned int rows;
		unsigned int cols;
		bool no_autorepeat;
		bool wakeup;

		void (*cfg_gpio)(unsigned int rows, unsigned int cols);
		};

		#endif /* __PLAT_SAMSUNG_KEYPAD_H */

drivers/char/keyboard.c

+5 −1

Original line number	Diff line number	Diff line
		@@ -1315,10 +1315,14 @@ static bool kbd_match(struct input_handler handler, struct input_dev dev)
		if (test_bit(EV_SND, dev->evbit))
		return true;

		if (test_bit(EV_KEY, dev->evbit))
		if (test_bit(EV_KEY, dev->evbit)) {
		for (i = KEY_RESERVED; i < BTN_MISC; i++)
		if (test_bit(i, dev->keybit))
		return true;
		for (i = KEY_BRL_DOT1; i <= KEY_BRL_DOT10; i++)
		if (test_bit(i, dev->keybit))
		return true;
		}

		return false;
		}

drivers/hid/hid-core.c

+1 −0

Original line number	Diff line number	Diff line
		@@ -1586,6 +1586,7 @@ static const struct hid_device_id hid_ignore_list[] = {
		{ HID_USB_DEVICE(USB_VENDOR_ID_DELORME, USB_DEVICE_ID_DELORME_EM_LT20) },
		{ HID_USB_DEVICE(USB_VENDOR_ID_ESSENTIAL_REALITY, USB_DEVICE_ID_ESSENTIAL_REALITY_P5) },
		{ HID_USB_DEVICE(USB_VENDOR_ID_ETT, USB_DEVICE_ID_TC5UH) },
		{ HID_USB_DEVICE(USB_VENDOR_ID_ETT, USB_DEVICE_ID_TC4UM) },
		{ HID_USB_DEVICE(USB_VENDOR_ID_GENERAL_TOUCH, 0x0001) },
		{ HID_USB_DEVICE(USB_VENDOR_ID_GENERAL_TOUCH, 0x0002) },
		{ HID_USB_DEVICE(USB_VENDOR_ID_GENERAL_TOUCH, 0x0003) },

drivers/hid/hid-ids.h

+1 −0

Original line number	Diff line number	Diff line
		@@ -198,6 +198,7 @@

		#define USB_VENDOR_ID_ETT 0x0664
		#define USB_DEVICE_ID_TC5UH 0x0309
		#define USB_DEVICE_ID_TC4UM 0x0306

		#define USB_VENDOR_ID_EZKEY 0x0518
		#define USB_DEVICE_ID_BTC_8193 0x0002

Admin message