diff options
Diffstat (limited to 'Documentation/input')
| -rw-r--r-- | Documentation/input/appletouch.txt | 2 | ||||
| -rw-r--r-- | Documentation/input/bcm5974.txt | 2 | ||||
| -rw-r--r-- | Documentation/input/iforce-protocol.txt | 2 | ||||
| -rw-r--r-- | Documentation/input/multi-touch-protocol.txt | 218 | ||||
| -rw-r--r-- | Documentation/input/ntrig.txt | 126 | ||||
| -rw-r--r-- | Documentation/input/sentelic.txt | 2 | ||||
| -rw-r--r-- | Documentation/input/xpad.txt | 2 |
7 files changed, 280 insertions, 74 deletions
diff --git a/Documentation/input/appletouch.txt b/Documentation/input/appletouch.txt index 4f7c633a76d..b13de3f8910 100644 --- a/Documentation/input/appletouch.txt +++ b/Documentation/input/appletouch.txt @@ -82,4 +82,4 @@ Links: ------ [1]: http://johannes.sipsolutions.net/PowerBook/touchpad/ -[2]: http://web.telia.com/~u89404340/touchpad/index.html +[2]: http://web.archive.org/web/*/http://web.telia.com/~u89404340/touchpad/index.html diff --git a/Documentation/input/bcm5974.txt b/Documentation/input/bcm5974.txt index 5e22dcf6d48..74d3876d6f3 100644 --- a/Documentation/input/bcm5974.txt +++ b/Documentation/input/bcm5974.txt @@ -62,4 +62,4 @@ Links ----- [1] http://ubuntuforums.org/showthread.php?t=840040 -[2] http://http://bitmath.org/code/ +[2] http://bitmath.org/code/ diff --git a/Documentation/input/iforce-protocol.txt b/Documentation/input/iforce-protocol.txt index 3ac92413c87..2d5fbfd6023 100644 --- a/Documentation/input/iforce-protocol.txt +++ b/Documentation/input/iforce-protocol.txt @@ -251,7 +251,7 @@ Check www.immerse.com for Immersion Studio, and www.fcoder.com for ComPortSpy. ** Author of this document ** Johann Deneux <johann.deneux@gmail.com> -Home page at http://www.esil.univ-mrs.fr/~jdeneux/projects/ff/ +Home page at http://web.archive.org/web/*/http://www.esil.univ-mrs.fr Additions by Vojtech Pavlik. diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt index c0fc1c75fd8..bdcba154b83 100644 --- a/Documentation/input/multi-touch-protocol.txt +++ b/Documentation/input/multi-touch-protocol.txt @@ -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: + + 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. -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. + +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]. +report contact 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: - - 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 diff --git a/Documentation/input/ntrig.txt b/Documentation/input/ntrig.txt new file mode 100644 index 00000000000..be1fd981f73 --- /dev/null +++ b/Documentation/input/ntrig.txt @@ -0,0 +1,126 @@ +N-Trig touchscreen Driver +------------------------- + Copyright (c) 2008-2010 Rafi Rubin <rafi@seas.upenn.edu> + Copyright (c) 2009-2010 Stephane Chatty + +This driver provides support for N-Trig pen and multi-touch sensors. Single +and multi-touch events are translated to the appropriate protocols for +the hid and input systems. Pen events are sufficiently hid compliant and +are left to the hid core. The driver also provides additional filtering +and utility functions accessible with sysfs and module parameters. + +This driver has been reported to work properly with multiple N-Trig devices +attached. + + +Parameters +---------- + +Note: values set at load time are global and will apply to all applicable +devices. Adjusting parameters with sysfs will override the load time values, +but only for that one device. + +The following parameters are used to configure filters to reduce noise: + +activate_slack number of fingers to ignore before processing events + +activation_height size threshold to activate immediately +activation_width + +min_height size threshold bellow which fingers are ignored +min_width both to decide activation and during activity + +deactivate_slack the number of "no contact" frames to ignore before + propagating the end of activity events + +When the last finger is removed from the device, it sends a number of empty +frames. By holding off on deactivation for a few frames we can tolerate false +erroneous disconnects, where the sensor may mistakenly not detect a finger that +is still present. Thus deactivate_slack addresses problems where a users might +see breaks in lines during drawing, or drop an object during a long drag. + + +Additional sysfs items +---------------------- + +These nodes just provide easy access to the ranges reported by the device. +sensor_logical_height the range for positions reported during activity +sensor_logical_width + +sensor_physical_height internal ranges not used for normal events but +sensor_physical_width useful for tuning + +All N-Trig devices with product id of 1 report events in the ranges of +X: 0-9600 +Y: 0-7200 +However not all of these devices have the same physical dimensions. Most +seem to be 12" sensors (Dell Latitude XT and XT2 and the HP TX2), and +at least one model (Dell Studio 17) has a 17" sensor. The ratio of physical +to logical sizes is used to adjust the size based filter parameters. + + +Filtering +--------- + +With the release of the early multi-touch firmwares it became increasingly +obvious that these sensors were prone to erroneous events. Users reported +seeing both inappropriately dropped contact and ghosts, contacts reported +where no finger was actually touching the screen. + +Deactivation slack helps prevent dropped contact for single touch use, but does +not address the problem of dropping one of more contacts while other contacts +are still active. Drops in the multi-touch context require additional +processing and should be handled in tandem with tacking. + +As observed ghost contacts are similar to actual use of the sensor, but they +seem to have different profiles. Ghost activity typically shows up as small +short lived touches. As such, I assume that the longer the continuous stream +of events the more likely those events are from a real contact, and that the +larger the size of each contact the more likely it is real. Balancing the +goals of preventing ghosts and accepting real events quickly (to minimize +user observable latency), the filter accumulates confidence for incoming +events until it hits thresholds and begins propagating. In the interest in +minimizing stored state as well as the cost of operations to make a decision, +I've kept that decision simple. + +Time is measured in terms of the number of fingers reported, not frames since +the probability of multiple simultaneous ghosts is expected to drop off +dramatically with increasing numbers. Rather than accumulate weight as a +function of size, I just use it as a binary threshold. A sufficiently large +contact immediately overrides the waiting period and leads to activation. + +Setting the activation size thresholds to large values will result in deciding +primarily on activation slack. If you see longer lived ghosts, turning up the +activation slack while reducing the size thresholds may suffice to eliminate +the ghosts while keeping the screen quite responsive to firm taps. + +Contacts continue to be filtered with min_height and min_width even after +the initial activation filter is satisfied. The intent is to provide +a mechanism for filtering out ghosts in the form of an extra finger while +you actually are using the screen. In practice this sort of ghost has +been far less problematic or relatively rare and I've left the defaults +set to 0 for both parameters, effectively turning off that filter. + +I don't know what the optimal values are for these filters. If the defaults +don't work for you, please play with the parameters. If you do find other +values more comfortable, I would appreciate feedback. + +The calibration of these devices does drift over time. If ghosts or contact +dropping worsen and interfere with the normal usage of your device, try +recalibrating it. + + +Calibration +----------- + +The N-Trig windows tools provide calibration and testing routines. Also an +unofficial unsupported set of user space tools including a calibrator is +available at: +http://code.launchpad.net/~rafi-seas/+junk/ntrig_calib + + +Tracking +-------- + +As of yet, all tested N-Trig firmwares do not track fingers. When multiple +contacts are active they seem to be sorted primarily by Y position. diff --git a/Documentation/input/sentelic.txt b/Documentation/input/sentelic.txt index b35affd5c64..b2ef125b71f 100644 --- a/Documentation/input/sentelic.txt +++ b/Documentation/input/sentelic.txt @@ -341,7 +341,7 @@ Byte 5~8: Don't care (Absolute packet) FSP supports basic PS/2 commanding set and modes, refer to following URL for details about PS/2 commands: -http://www.computer-engineering.org/index.php?title=PS/2_Mouse_Interface +http://www.computer-engineering.org/ps2mouse/ ============================================================================== * Programming Sequence for Determining Packet Parsing Flow diff --git a/Documentation/input/xpad.txt b/Documentation/input/xpad.txt index aae0d404c56..7cc9a436e6a 100644 --- a/Documentation/input/xpad.txt +++ b/Documentation/input/xpad.txt @@ -150,7 +150,7 @@ the basic functionality. 1. http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki) 2. http://xpad.xbox-scene.com/ -3. http://www.xboxhackz.com/Hackz-Reference.htm +3. http://www.markosweb.com/www/xboxhackz.com/ 4. /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany): |