【驱动】TP电容屏驱动—3.TP报点协议A/B 之 2.多点触控协议(MTP)
多点触控协议(MTP)
作者翻译水平有限，欢迎指正，感谢好友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
SYN_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
SYN_REPORT
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:http://bitmath.org/code/mtdev/.
[4] See the section onevent computation.
[5] See the section onfinger tracking.
