Eric Lee / linux-smarc-t335x-v3.2

Download as
Browse Code ยป

Commit eacaad01b4e67336b5b3f4db6dc15ef92c64b47d

Authored by Henrik Rydberg
Committed by Dmitry Torokhov
1 parent 5e5ee686e3
Exists in master and in 4 other branches v3.2_AM335xPSP_04.06.00.11, v3.2_NEWT335xPSP_04.06.00.11, v3.2_SBC_SMARTMEN, v3.2_SMARCT335xPSP_04.06.00.11

Input: document the multi-touch (MT) protocol 

This patchs adds documentation for the multi-touch protocol to
Documentation/input/.

[randy.dunlap@oracle.com: grammar fixes]
Signed-off-by: Henrik Rydberg <rydberg@euromail.se>
Signed-off-by: Dmitry Torokhov <dtor@mail.ru>

Showing 1 changed file with 140 additions and 0 deletions Side-by-side Diff

Documentation/input/multi-touch-protocol.txt
Diff comments   View file @ eacaad0
  1 +Multi-touch (MT) Protocol
  2 +-------------------------
  3 + Copyright (C) 2009 Henrik Rydberg <rydberg@euromail.se>
  4 +
  5 +
  6 +Introduction
  7 +------------
  8 +
  9 +In order to utilize the full power of the new multi-touch devices, a way to
  10 +report detailed finger data to user space is needed. This document
  11 +describes the multi-touch (MT) protocol which allows kernel drivers to
  12 +report details for an arbitrary number of fingers.
  13 +
  14 +
  15 +Usage
  16 +-----
  17 +
  18 +Anonymous finger details are sent sequentially as separate packets of ABS
  19 +events. Only the ABS_MT events are recognized as part of a finger
  20 +packet. The end of a packet is marked by calling the input_mt_sync()
  21 +function, which generates a SYN_MT_REPORT event. The end of multi-touch
  22 +transfer is marked by calling the usual input_sync() function.
  23 +
  24 +A set of ABS_MT events with the desired properties is defined. The events
  25 +are divided into categories, to allow for partial implementation. The
  26 +minimum set consists of ABS_MT_TOUCH_MAJOR, ABS_MT_POSITION_X and
  27 +ABS_MT_POSITION_Y, which allows for multiple fingers to be tracked. If the
  28 +device supports it, the ABS_MT_WIDTH_MAJOR may be used to provide the size
  29 +of the approaching finger. Anisotropy and direction may be specified with
  30 +ABS_MT_TOUCH_MINOR, ABS_MT_WIDTH_MINOR and ABS_MT_ORIENTATION. Devices with
  31 +more granular information may specify general shapes as blobs, i.e., as a
  32 +sequence of rectangular shapes grouped together by an
  33 +ABS_MT_BLOB_ID. Finally, the ABS_MT_TOOL_TYPE may be used to specify
  34 +whether the touching tool is a finger or a pen or something else.
  35 +
  36 +
  37 +Event Semantics
  38 +---------------
  39 +
  40 +The word "contact" is used to describe a tool which is in direct contact
  41 +with the surface. A finger, a pen or a rubber all classify as contacts.
  42 +
  43 +ABS_MT_TOUCH_MAJOR
  44 +
  45 +The length of the major axis of the contact. The length should be given in
  46 +surface units. If the surface has an X times Y resolution, the largest
  47 +possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal.
  48 +
  49 +ABS_MT_TOUCH_MINOR
  50 +
  51 +The length, in surface units, of the minor axis of the contact. If the
  52 +contact is circular, this event can be omitted.
  53 +
  54 +ABS_MT_WIDTH_MAJOR
  55 +
  56 +The length, in surface units, of the major axis of the approaching
  57 +tool. This should be understood as the size of the tool itself. The
  58 +orientation of the contact and the approaching tool are assumed to be the
  59 +same.
  60 +
  61 +ABS_MT_WIDTH_MINOR
  62 +
  63 +The length, in surface units, of the minor axis of the approaching
  64 +tool. Omit if circular.
  65 +
  66 +The above four values can be used to derive additional information about
  67 +the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates
  68 +the notion of pressure. The fingers of the hand and the palm all have
  69 +different characteristic widths [1].
  70 +
  71 +ABS_MT_ORIENTATION
  72 +
  73 +The orientation of the ellipse. The value should describe half a revolution
  74 +clockwise around the touch center. The scale of the value is arbitrary, but
  75 +zero should be returned for an ellipse aligned along the Y axis of the
  76 +surface. As an example, an index finger placed straight onto the axis could
  77 +return zero orientation, something negative when twisted to the left, and
  78 +something positive when twisted to the right. This value can be omitted if
  79 +the touching object is circular, or if the information is not available in
  80 +the kernel driver.
  81 +
  82 +ABS_MT_POSITION_X
  83 +
  84 +The surface X coordinate of the center of the touching ellipse.
  85 +
  86 +ABS_MT_POSITION_Y
  87 +
  88 +The surface Y coordinate of the center of the touching ellipse.
  89 +
  90 +ABS_MT_TOOL_TYPE
  91 +
  92 +The type of approaching tool. A lot of kernel drivers cannot distinguish
  93 +between different tool types, such as a finger or a pen. In such cases, the
  94 +event should be omitted. The protocol currently supports MT_TOOL_FINGER and
  95 +MT_TOOL_PEN [2].
  96 +
  97 +ABS_MT_BLOB_ID
  98 +
  99 +The BLOB_ID groups several packets together into one arbitrarily shaped
  100 +contact. This is a low-level anonymous grouping, and should not be confused
  101 +with the high-level contactID, explained below. Most kernel drivers will
  102 +not have this capability, and can safely omit the event.
  103 +
  104 +
  105 +Finger Tracking
  106 +---------------
  107 +
  108 +The kernel driver should generate an arbitrary enumeration of the set of
  109 +anonymous contacts currently on the surface. The order in which the packets
  110 +appear in the event stream is not important.
  111 +
  112 +The process of finger tracking, i.e., to assign a unique contactID to each
  113 +initiated contact on the surface, is left to user space; preferably the
  114 +multi-touch X driver [3]. In that driver, the contactID stays the same and
  115 +unique until the contact vanishes (when the finger leaves the surface). The
  116 +problem of assigning a set of anonymous fingers to a set of identified
  117 +fingers is a euclidian bipartite matching problem at each event update, and
  118 +relies on a sufficiently rapid update rate.
  119 +
  120 +Notes
  121 +-----
  122 +
  123 +In order to stay compatible with existing applications, the data
  124 +reported in a finger packet must not be recognized as single-touch
  125 +events. In addition, all finger data must bypass input filtering,
  126 +since subsequent events of the same type refer to different fingers.
  127 +
  128 +The first kernel driver to utilize the MT protocol is the bcm5974 driver,
  129 +where examples can be found.
  130 +
  131 +[1] With the extension ABS_MT_APPROACH_X and ABS_MT_APPROACH_Y, the
  132 +difference between the contact position and the approaching tool position
  133 +could be used to derive tilt.
  134 +[2] The list can of course be extended.
  135 +[3] The multi-touch X driver is currently in the prototyping stage. At the
  136 +time of writing (April 2009), the MT protocol is not yet merged, and the
  137 +prototype implements finger matching, basic mouse support and two-finger
  138 +scrolling. The project aims at improving the quality of current multi-touch
  139 +functionality available in the synaptics X driver, and in addition
  140 +implement more advanced gestures.