【驱动】TP电容屏驱动—3.TP报点协议AB之2.多点触控协议（MTP）

【驱动】TP电容屏驱动—3.TP报点协议AB之2.多点触控协议
（MTP）
多点触控协议(MTP)
转载：https:///paul_liao/article/details/7085542
作者翻译⽔平有限，欢迎指正，感谢好友lapset和leo的帮助！
Multi-touch (MT) Protocol
-------------------------
Copyright (C)2009-2010
Henrik Rydberg<rydberg@euromail.se>
Introduction
------------
In order to utilize the full power of thenew multi-touch and multi-user devices, a way to report detailed data frommultiple contacts, i.e., objects in direct contact with the device surface, isneeded. This document describes themulti-touch (MT) protocol which allows kernel drivers to report details for anarbitrary number of contacts.
为了使⽤功能强⼤的多点触控设备，⼀种⽅案是上报多触点的详细数据。

本⽂档所描述的多点触控协议(MTP)可以让内核驱动向⽤户层上报任意多个触点的数据信息。

The protocol is divided into two types,depending on the capabilities of the hardware. For devices handling anonymouscontacts (type A), the protocol describes how to send the raw data for allcontacts to the receiver. For devices capable of tracking identifiable contacts(type B), the protocol describes how to send updates for individual contacts viaevent slots.
根据硬件功能，此协议分为两种类型。

A类型：对于处理未标识的触点的设备，此类协议描述如何将所有触点的原始数据上报给上层；B类型：对于能跟踪可标识的触点的设备，此类协议描述如何将单个触点的更新信息通过事件槽上报给上层。

Protocol Usage
--------------
Contact details are sent sequentially asseparate packets of ABS_MT events. Only the ABS_MT events are recognized as partof 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 protocolin an existing driver.
触点的详细数据作为单独的ABS_MT事件包按顺序发送，只有ABS_MT事件作为触控数据包时才能被识别。

由于这些事件会被单触点应⽤所忽略，MTP是在STP上实现的。

Drivers for type A devices separate contactpackets by calling input_mt_sync() at the end of each packet. This generates
aSYN_MT_REPORT event, which instructs the receiver to accept the data for thecurrent contact and prepare to receive another.
A类设备的驱动：它会在每个包的最后调⽤⼀次input_mt_sync()函数分离接收到的触点数据包，并且会产⽣⼀个SYN_MT_REPORT event ，该事件会告诉接收⽅接收当前触点数据，并准备接受其他的。

Drivers for type B devices separate contactpackets by calling input_mt_slot(), with a slot as argument, at the beginningof each packet. This generates an ABS_MT_SLOT event, which instructs thereceiver to prepare for updates of the given slot.
B类设备的驱动：在每个包的开头调⽤input_mt_slot()函数并携带⼀个槽作为参数，此时会
产⽣⼀个ABS_MT_SLOT event，该事件会告诉接收⽅准备更新给定的槽。

All drivers mark the end of a multi-touchtransfer by calling the usual input_sync() function. This instructs thereceiver to act upon events accumulated since last EV_SYN/SYN_REPORT andprepare to receive a new set of events/packets.
所有类型的驱动都会调⽤input_sync()函数来标记多点触摸传输的结束，并会告知接收⽅开始从最后⼀次EV_SYN/SYN_REPORT起作事件累计。

The main difference between the statelesstype A protocol and the stateful type B slot protocol lies in the usage ofidentifiable contacts to reduce the amount of data sent to userspace. The slotprotocol requires the use of the ABS_MT_TRACKING_ID, either provided by thehardware or computed from the raw data [5].
A类协议和B类协议的主要区别是B类协议使⽤ID来标识触点，减少了上报到⽤户空间的数据量。

B类协议需要使⽤
ABS_MT_TRACKING_ID，由硬件提供或者通过原始数据计算得来。

For type A devices, the kernel drivershould generate an arbitrary enumeration of the full set of anonymous contactscurrently on the surface. The order in which the packets appear in the eventstream is not important. Event filteringand finger tracking is left to user space [3].
对于A类设备，内核驱动需要对当前的所有触点进⾏任意枚举。

数据包在事件流⾥出现的顺序并不是很重要。

事件过滤和触点跟踪都由⽤户空间来处理。

For type B devices, the kernel drivershould associate a slot with each identified contact, and use that slot topropagate changes for the contact. Creation, replacement and destruction ofcontacts is achieved by modifying the ABS_MT_TRACKING_ID of the associatedslot. A non-negative tracking id isinterpreted as a contact, and the value -1 denotes an unused slot. A tracking id not previously present isconsidered new, and a tracking id no longer present is considered removed. Since only changes are propagated, the fullstate of each initiated contact has to reside in the receiving end. Upon receiving an MT event, one simplyupdates the appropriate attribute of the current slot.
对于B类设备，内核驱动需要将slot和每个已标识的触点关联，使⽤slot来传递触点的变化。

触点的创建，替换和销毁都是通过修改相应slot 的ABS_MT_TRACKING_ID来实现。

⾮零的跟踪ID表⽰已使⽤触点，⽽-1表⽰未使⽤的slot。

之前不存在的跟踪ID被认为是新的，再存在的跟踪ID被认为是已移除的。

由于只有触点变化才会被传递，每个被标识的触点会驻留接收端，⼀旦接收到MT事件，就会更新当前slot的相应属性。

Some devices identify and/or track morecontacts than they can report to the driver. A driver for such a device should associate one type B slot with eachcontact that is reported by the hardware. Whenever the identity of the contact associated with a slot changes, thedriver should invalidate that slot by changing its ABS_MT_TRACKING_ID. If the hardware signals that it is trackingmore contacts than it is currently reporting, the driver should use aBTN_TOOL_*TAP event to inform userspace of the total number of contacts beingtracked by the hardware at that moment. The driver should do this by explicitly sending the correspondingBTN_TOOL_*TAP event and setting use_count to false when callinginput_mt_report_pointer_emulation(). The driver should only advertise as manyslots as the hardware can report. Userspace can detect that a driver can reportmore total contacts than slots by noting that the largest supportedBTN_TOOL_*TAP event is larger than the total number of type B slots reported inthe absinfo for the ABS_MT_SLOT axis.
⼀些设备标识和跟踪的触点⽐上报给驱动的触点要多。

这种设备的驱动程序需要将⼀个B类型slot和每个由硬件上报的触点关联。

只要触点的标号更改，驱动应该通过改变ABS_MT_TRACKING_ID来使此触点关联的slot⽆效。

如果硬件信号跟踪的触点要⽐当前上报的多，此时，驱动应该使⽤⼀个BTN_TOOL_*TAP事件来通知⽤户空间实际上硬件跟踪触点的总数。

驱动需要显⽰的发送BTN_TOOL_*TAP事件和调⽤input_mt_report_pointer_emulation()函数设置use_count为false。

驱动最多只能上报硬件实现的slot总个数。

通过检查驱动⽀持的最⼤BTN_TOOL_* TAP事件⼤于ABS_MT_SLOT轴absinfo上报的B类slot总数，⽤户空间能检测出驱动程序可以报告⽐插槽更多的触点总数。

Protocol Example A
------------------
Here is what a minimal event sequence for atwo-contact touch would look like for a type A device:
对于A类型驱动，下⾯是报告两个触点的最⼩事件序列：
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 contactslooks exactly the same; the raw data for all present contacts are sent betweenevery synchronization with SYN_REPORT.
移动其中的⼀个触点后的序列也是⼀样的，所有的触点数据包发送完后，会⽤SYN_REPORT⽤来同步处理。

Here is the sequence after lifting thefirst contact:
当第⼀个触点弹起后的序列：
ABS_MT_POSITION_X x[1]
ABS_MT_POSITION_Y y[1]
SYN_MT_REPORT
And here is the sequence after lifting thesecond contact:
当第⼆个触点也弹起后的序列：
SYN_MT_REPORT
SYN_REPORT
If the driver reports one of BTN_TOUCH orABS_PRESSURE in addition to the ABS_MT events, the last SYN_MT_REPORT event maybe omitted. Otherwise, the last SYN_REPORT will be dropped by the input core,resulting in no zero-contact event reaching userland.
如果驱动上报BTN_TOUCH或ABS_PRESSURE事件，SYN_MT_REPORT事件可能会被忽略。

否则最后的SYN_REPORT事件会被输⼊核⼼层丢弃，导致没有产⽣同步事件。

Protocol Example B
------------------
Here is what a minimal event sequence for atwo-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 contact45 in the x direction:
在X⽅向上移动触点45后的序列：
ABS_MT_SLOT 0
ABS_MT_POSITION_X x[0]
SYN_REPORT
Here is the sequence after lifting thecontact in slot 0:
与slot 0关联的触点弹起后的序列：
ABS_MT_TRACKING_ID -1
SYN_REPORT
The slot being modified is already 0, sothe ABS_MT_SLOT is omitted. The messageremoves the association of slot 0 with contact 45, thereby destroying contact45 and freeing slot 0 to be reused for another contact.
被修改过的slot已经为0了，所以ABS_MT_SLOT会被忽略。

把触点45从slot 0上移除，因此销毁触点45和释放slot 0后，其他触点⼜可以重新使⽤。

Finally, here is the sequence after liftingthe second contact:
最后，第⼆个触点也弹起后的序列如下：
ABS_MT_SLOT 1
ABS_MT_TRACKING_ID-1
Event Usage
-----------
A set of ABS_MT events with the desiredproperties is defined. The events are divided into categories, to allow forpartial implementation. The minimum setconsists of ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which allows for multiplecontacts to be tracked. If the devicesupports it, the ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used toprovide the size of the contact area and approaching contact, respectively.
协议定义了⼀系列的ABS_MT事件，这些事件被分为⼏⼤类，允许只应⽤其中的⼀部分。

最⼩的事件集由ABS_MT_POSITION_X 和
ABS_MT_POSITION_Y组成，以此来实现多点触摸。

如果设备⽀持ABS_MT_TOUCH_MAJOR和 ABS_MT_WIDTH_MAJOR可以分别提供触点⼤⼩和接触⼯具的⼤⼩。

The TOUCH and WIDTH parameters have ageometrical interpretation; imagine looking through a window at someone gentlyholding a finger against the glass. Youwill see two regions, one inner region consisting of the part of the fingeractually touching the glass, and one outer region formed by the perimeter ofthe finger. The diameter of the inner region is the ABS_MT_TOUCH_MAJOR, thediameter of the outer region is ABS_MT_WIDTH_MAJOR. Now imagine the personpressing 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 isalways smaller than unity, is related to the contact pressure. Forpressure-based devices, ABS_MT_PRESSURE may be used to provide the pressure onthe contact area instead. Devices capable of contact hovering can useABS_MT_DISTANCE to indicate the distance between the contact and the surface. TOUCH和WIDTH参数。

想象⼀下，⼀个⼈⽤⼿指按在玻璃上，通过玻璃你将看到两个区域，⾥⾯是⼿指与玻璃实际接触的区域，区域的直径⽤ABS_MT_TOUCH_MAJOR参数来描述；外⾯是⼿指本⾝⼤⼩的区域，区域的直径⽤ABS_MT_WIDTH_MAJOR参数来描述。

⼿指与玻璃接触的⾯积要⼩于⼿指本⾝的⼤⼩，通过ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR的⽐值可以⽤来反映接触时的压⼒值。

对于⽀持压⼒的设备，也可通过 ABS_MT_PRESSURE参数直接提供⼿指的压⼒。

同样可以使⽤ABS_MT_DISTANCE参数提供接触点和表⾯的距离。

In addition to the MAJOR parameters, theoval shape of the contact can be described by adding the MINOR parameters, suchthat MAJOR and MINOR are the major and minor axis of an ellipse. Finally, theorientation of the oval shape can be describe with the ORIENTATION parameter.
另外MAJOR和MINOR参数⽤来描述椭圆的形状，触点的形状通常被认为是椭圆形。

MAJOR和MINOR参数分别是这个椭圆的长轴和短轴，椭圆的⽅向可以被 ORIENTATION这个参数描述。

For type A devices, further specificationof the touch shape is possible via ABS_MT_BLOB_ID.
The ABS_MT_TOOL_TYPE may be used to specifywhether the touching tool is a finger or a pen or something else. Finally,
theABS_MT_TRACKING_ID event may be used to track identified contacts over time[5].
对于A类设备，通过ABS_MT_BLOB_ID来进⼀步规范触点的形状，ABS_MT_TOOL_TYPE参数⽤来描述触摸⼯具的类型(⼿指，触控笔等)。

ABS_MT_TRACKING_ID参数⽤来跟踪标识的触点。

In the type B protocol, ABS_MT_TOOL_TYPEand ABS_MT_TRACKING_ID are implicitly handled by input core; drivers shouldinstead call input_mt_report_slot_state().
对于B类型协议，ABS_MT_TOOL_TYPE and ABS_MT_TRACKING_ID都已被输⼊核⼼层隐式处理，驱动程序只需要调⽤
input_mt_report_slot_state()。

Event Semantics
---------------
ABS_MT_TOUCH_MAJOR
The length of the major axis of thecontact. The length should be given in surface units. If the surface has an Xtimes Y resolution, the largest possible value of ABS_MT_TOUCH_MAJOR issqrt(X^2 + Y^2), the diagonal [4].
触点长轴长度
ABS_MT_TOUCH_MINOR
The length, in surface units, of the minoraxis of the contact. If the contact is circular, this event can be omitted [4].
触点短轴长度，如果触点是圆形，则忽略
ABS_MT_WIDTH_MAJOR
The length, in surface units, of the majoraxis of the approaching tool. This should be understood as the size of the toolitself. The orientation of the contact and the approaching tool are assumed tobe the same [4].
接触⼯具长轴长度
ABS_MT_WIDTH_MINOR
The length, in surface units, of the minoraxis of the approaching tool. Omit if circular [4].
接触⼯具短轴长度，接触⼯具切⾯是圆形，则忽略
The above four values can be used to deriveadditional information about the contact. The ratio ABS_MT_TOUCH_MAJOR
/ABS_MT_WIDTH_MAJOR approximates the notion of pressure. The fingers of the handand the palm all have different characteristic widths [1].
可以利⽤上⾯的四个值去获取触点其它的信息，ABS_MT_TOUCH_MAJOR/ ABS_MT_WIDTH_MAJOR的⽐值可以⽤来反应接触时的压⼒值
ABS_MT_PRESSURE
The pressure, in arbitrary units, on thecontact area. May be used instead of TOUCH and WIDTH for pressure-based devicesor any device with a spatial signal intensity distribution.
压⼒，如果设备⽀持压⼒功能或者空间信号分布强度功能，可⽤此参数来替代上⾯四个参数
ABS_MT_DISTANCE
The distance, in surface units, between thecontact and the surface. Zero distance means the contact is touching thesurface. A positive number means the contact is hovering above the surface.
触点和表⾯的距离，0表⽰触点接触到触摸屏表⾯，正数意味着触点在表⾯上⽅
ABS_MT_ORIENTATION
The orientation of the ellipse. The valueshould describe a signed quarter of a revolution clockwise around the touchcenter. The signed value range is arbitrary, but zero should be returned for afinger aligned along the Y axis of the surface, a negative value when finger isturned to the left, and a positive value when finger turned to the right. Whencompletely aligned with the X axis, the range max should be returned. Orientation can be omitted if the touchingobject is circular, or if the information is not available in the kerneldriver. Partial orientation support is possible if the device can distinguishbetween the two axis, but not (uniquely) any values in between. In such cases,the range of ABS_MT_ORIENTATION should be [0, 1] [4].
触点的⽅向。

此值的范围是任意的，0表⽰⼿指和Y轴对齐，负值表⽰⼿指向左移，正值表⽰⼿指向右移。

当和X轴完全对齐时，返回最⼤值。

如果接触⾯是圆形或在驱动中此值不可⽤，会被忽略。

如果设备能区分XY轴，部分的⽅向是有可能⽀持的。

在这种情况
下，ABS_MT_ORIENTATION的范围应该是[0,1]。

ABS_MT_POSITION_X
The surface X coordinate of the center ofthe touching ellipse.
接触⾯中⼼的X坐标值
ABS_MT_POSITION_Y
The surface Y coordinate of the center ofthe touching ellipse.
接触⾯中⼼的Y坐标值
ABS_MT_TOOL_TYPE
The type of approaching tool. A lot ofkernel drivers cannot distinguish between different tool types, such as afinger or a pen. In such cases, the event should be omitted. The protocolcurrently supports MT_TOOL_FINGER and MT_TOOL_PEN [2]. For type B devices, thisevent is
handled by input core; drivers should instead useinput_mt_report_slot_state().
触摸⼯具的类型，⼤多数的内核驱动都不能区分⼯具的类型，所以在这种情况下，应该被忽略。

MTP当前只⽀持MT_TOOL_FINGER(⼿指)和MT_TOOL_PEN(笔)。

对于B类设备，驱动调⽤input_mt_report_slot_state()函数将这些事件都交由输⼊核⼼层来处理。

ABS_MT_BLOB_ID
The BLOB_ID groups several packets togetherinto one arbitrarily shaped contact. The sequence of points forms a polygonwhich defines the shape of the contact. This is a low-level anonymous groupingfor 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 safelyomit this event.
BLOB_ID是形状集ID，可以⽤来组合任意的触点形状，⼤多数的A类设备没有形状属性，所以驱动应该将此事件忽略。

ABS_MT_TRACKING_ID
The TRACKING_ID identifies an initiatedcontact throughout its life cycle [5]. The value range of the TRACKING_IDshould be large enough to ensure unique identification of a contact maintainedover an extended period of time. For type B devices, this event is handled byinput core; drivers should instead use input_mt_report_slot_state().
TRACKING_ID⽤来标识触点的整个⽣命周期。

TRACKING_ID的范围必须⾜够⼤，以确保每个触点都有⼀个独⼀的标号。

对于B类设备，驱动调⽤input_mt_report_slot_state()函数将这些事件都交由输⼊核⼼层来处理。

Event Computation
-----------------
The flora of different hardware unavoidablyleads to some devices fitting better to the MT protocol than others. Tosimplify and unify the mapping, this section gives recipes for how to computecertain events.
由于硬件上的差异，导致⼀些设备不能更好的使⽤MTP。

为了简化和统⼀，本节给出来某些事件的计算⽅法。

For devices reporting contacts asrectangular shapes, signed orientation cannot be obtained. Assuming X and Y arethe lengths of the sides of the touching rectangle, here is a simple formulathat retains the most information possible:
⼀些设备将接触⾯作为⼀个矩形上报，假设X和Y是矩形接触⾯的边，可以通过下⾯⼀些公式获取⼀些信息：
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 beset to [0, 1], to indicate that the device can distinguish between a fingeralong the Y axis (0) and a finger along the X axis (1).
ABS_MT_ORIENTATION的取值范围为０⾄１，⽤来标识矩形接触⾯偏向Ｙ轴(0)或Ｘ轴(1)的程度。

Finger Tracking
---------------
The process of finger tracking, i.e., toassign a unique trackingID to each initiated contact on the surface, is aEuclidian Bipartite Matching problem. Ateach event synchronization, the set of actual contacts is matched to the set ofcontacts from the previous synchronization. A full implementation can be foundin [3].
触点跟踪过程，⽐如为每个触点分配⼀个独⼀的跟踪ID号。

每⼀个事件同步时，实际的触点集是和之前同步的触点集匹配的。

Gestures
--------
In the specific application of creating gestureevents, the TOUCH and WIDTH parameters can be used to, e.g., approximate fingerpressure or distinguish between index finger and thumb. With the addition ofthe MINOR parameters, one can also distinguish between a sweeping finger and apointing finger, and with ORIENTATION, one can detect twisting of fingers.
对于创建⼿势事件这类特殊的应⽤中，TOUCH和 WIDTH参数经常⽤来，例如区分拇指和⾷指或者⼿指⼤约的压⼒，另外 MINOR参数可以⽤来区别设备的接触⾯的⼤⼩(点接触还是⾯接触),ORIENTATION可以检测旋转⽅向。

Notes
-----
In order to staycompatible with existing applications, the data reported
in a finger packet mustnot be recognized as single-touch events.
为了和现有的应⽤兼容，在上报的触点数据包中的数据不能识别为单点触控事件。

For type A devices, allfinger data bypasses input filtering, since
subsequent events of thesame type refer to different fingers.
对于A类型的设备，由于随后相同类型的事件关联不同的触控，所有的数据会绕过输⼊过滤.
For example usage of thetype A protocol, see the bcm5974 driver. For
example usage of thetype B protocol, see the hid-egalax driver.
⽐如A类型协议的使⽤，可以参考内核中实现的bcm5974驱动。

再如B类型协议的使⽤，可以参考hid-egalax驱动。

[1] With the extensionABS_MT_APPROACH_X and ABS_MT_APPROACH_Y, the
difference between thecontact position and the approaching tool position
could be used to derivetilt.
有了ABS_MT_APPROACH_X 和 ABS_MT_APPROACH_Y 的扩展，在触控位置和触控⼯具的位置的差异可以推导出倾斜度。

[2] The list can ofcourse be extended.
[3] The mtdev project:/code/mtdev/.
[4] See the section onevent computation.
[5] See the section onfinger tracking.。