diff options
Diffstat (limited to 'Documentation/input')
-rw-r--r-- | Documentation/input/bcm5974.txt | 65 | ||||
-rw-r--r-- | Documentation/input/multi-touch-protocol.txt | 195 | ||||
-rw-r--r-- | Documentation/input/rotary-encoder.txt | 101 |
3 files changed, 361 insertions, 0 deletions
diff --git a/Documentation/input/bcm5974.txt b/Documentation/input/bcm5974.txt new file mode 100644 index 00000000000..5e22dcf6d48 --- /dev/null +++ b/Documentation/input/bcm5974.txt @@ -0,0 +1,65 @@ +BCM5974 Driver (bcm5974) +------------------------ + Copyright (C) 2008-2009 Henrik Rydberg <rydberg@euromail.se> + +The USB initialization and package decoding was made by Scott Shawcroft as +part of the touchd user-space driver project: + Copyright (C) 2008 Scott Shawcroft (scott.shawcroft@gmail.com) + +The BCM5974 driver is based on the appletouch driver: + Copyright (C) 2001-2004 Greg Kroah-Hartman (greg@kroah.com) + Copyright (C) 2005 Johannes Berg (johannes@sipsolutions.net) + Copyright (C) 2005 Stelian Pop (stelian@popies.net) + Copyright (C) 2005 Frank Arnold (frank@scirocco-5v-turbo.de) + Copyright (C) 2005 Peter Osterlund (petero2@telia.com) + Copyright (C) 2005 Michael Hanselmann (linux-kernel@hansmi.ch) + Copyright (C) 2006 Nicolas Boichat (nicolas@boichat.ch) + +This driver adds support for the multi-touch trackpad on the new Apple +Macbook Air and Macbook Pro laptops. It replaces the appletouch driver on +those computers, and integrates well with the synaptics driver of the Xorg +system. + +Known to work on Macbook Air, Macbook Pro Penryn and the new unibody +Macbook 5 and Macbook Pro 5. + +Usage +----- + +The driver loads automatically for the supported usb device ids, and +becomes available both as an event device (/dev/input/event*) and as a +mouse via the mousedev driver (/dev/input/mice). + +USB Race +-------- + +The Apple multi-touch trackpads report both mouse and keyboard events via +different interfaces of the same usb device. This creates a race condition +with the HID driver, which, if not told otherwise, will find the standard +HID mouse and keyboard, and claim the whole device. To remedy, the usb +product id must be listed in the mouse_ignore list of the hid driver. + +Debug output +------------ + +To ease the development for new hardware version, verbose packet output can +be switched on with the debug kernel module parameter. The range [1-9] +yields different levels of verbosity. Example (as root): + +echo -n 9 > /sys/module/bcm5974/parameters/debug + +tail -f /var/log/debug + +echo -n 0 > /sys/module/bcm5974/parameters/debug + +Trivia +------ + +The driver was developed at the ubuntu forums in June 2008 [1], and now has +a more permanent home at bitmath.org [2]. + +Links +----- + +[1] http://ubuntuforums.org/showthread.php?t=840040 +[2] http://http://bitmath.org/code/ diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt new file mode 100644 index 00000000000..a12ea3b586e --- /dev/null +++ b/Documentation/input/multi-touch-protocol.txt @@ -0,0 +1,195 @@ +Multi-touch (MT) Protocol +------------------------- + Copyright (C) 2009 Henrik Rydberg <rydberg@euromail.se> + + +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. + + +Usage +----- + +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. + +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_TOUCH_MAJOR, ABS_MT_POSITION_X and +ABS_MT_POSITION_Y, which allows for multiple fingers to be tracked. If the +device supports it, the ABS_MT_WIDTH_MAJOR may be used to provide the size +of the approaching finger. Anisotropy and direction may be specified with +ABS_MT_TOUCH_MINOR, ABS_MT_WIDTH_MINOR and ABS_MT_ORIENTATION. 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 +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_TOUCH_MAJOR + ABS_MT_POSITION_X + ABS_MT_POSITION_Y + SYN_MT_REPORT + ABS_MT_TOUCH_MAJOR + ABS_MT_POSITION_X + ABS_MT_POSITION_Y + SYN_MT_REPORT + SYN_REPORT + + +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 +surface units. If the surface has an X times Y resolution, the largest +possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [4]. + +ABS_MT_TOUCH_MINOR + +The length, in surface units, of the minor axis 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 major axis of the approaching +tool. This should be understood as the size of the tool itself. The +orientation of the contact and the approaching tool are assumed to be the +same [4]. + +ABS_MT_WIDTH_MINOR + +The length, in surface units, of the minor axis of the approaching +tool. Omit if circular [4]. + +The above four values can be used to derive additional information about +the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates +the notion of pressure. The fingers of the hand and the palm all have +different characteristic widths [1]. + +ABS_MT_ORIENTATION + +The orientation of the ellipse. The value should describe a signed quarter +of a revolution clockwise around the touch center. The signed value range +is arbitrary, but zero should be returned for a finger aligned along the Y +axis of the surface, a negative value when finger is turned to the left, and +a positive value when finger turned to the right. When completely aligned with +the X axis, the range max should be returned. Orientation can be omitted +if the touching object is circular, or if the information is not available +in the kernel driver. Partial orientation support is possible if the device +can distinguish between the two axis, but not (uniquely) any values in +between. In such cases, the range of ABS_MT_ORIENTATION should be [0, 1] +[4]. + +ABS_MT_POSITION_X + +The surface X coordinate of the center of the touching ellipse. + +ABS_MT_POSITION_Y + +The surface Y coordinate of the center of the touching ellipse. + +ABS_MT_TOOL_TYPE + +The type of approaching tool. A lot of kernel drivers cannot distinguish +between different tool types, such as a finger or a pen. In such cases, the +event should be omitted. The protocol currently supports MT_TOOL_FINGER and +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. + +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. + + +Event Computation +----------------- + +The flora of different hardware unavoidably leads to some devices fitting +better to the MT protocol than others. To simplify and unify the mapping, +this section gives recipes for how to compute certain events. + +For devices reporting contacts as rectangular shapes, signed orientation +cannot be obtained. Assuming X and Y are the lengths of the sides of the +touching rectangle, here is a simple formula that retains the most +information possible: + + 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 be set to [0, 1], to indicate that +the device can distinguish between a finger along the Y axis (0) and a +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. + + +Notes +----- + +In order to stay compatible with existing applications, the data +reported in a finger packet must not be recognized as single-touch +events. In addition, all finger data must bypass input filtering, +since subsequent events of the same type refer to different fingers. + +The first kernel driver to utilize the MT protocol is the bcm5974 driver, +where examples can be found. + +[1] With the extension ABS_MT_APPROACH_X and ABS_MT_APPROACH_Y, the +difference between the contact position and the approaching tool position +could be used to derive tilt. +[2] The list can of course be extended. +[3] The multi-touch X driver is currently in the prototyping stage. At the +time of writing (April 2009), the MT protocol is not yet merged, and the +prototype implements finger matching, basic mouse support and two-finger +scrolling. The project aims at improving the quality of current multi-touch +functionality available in the Synaptics X driver, and in addition +implement more advanced gestures. +[4] See the section on event computation. +[5] See the section on finger tracking. diff --git a/Documentation/input/rotary-encoder.txt b/Documentation/input/rotary-encoder.txt new file mode 100644 index 00000000000..435102a26d9 --- /dev/null +++ b/Documentation/input/rotary-encoder.txt @@ -0,0 +1,101 @@ +rotary-encoder - a generic driver for GPIO connected devices +Daniel Mack <daniel@caiaq.de>, Feb 2009 + +0. Function +----------- + +Rotary encoders are devices which are connected to the CPU or other +peripherals with two wires. The outputs are phase-shifted by 90 degrees +and by triggering on falling and rising edges, the turn direction can +be determined. + +The phase diagram of these two outputs look like this: + + _____ _____ _____ + | | | | | | + Channel A ____| |_____| |_____| |____ + + : : : : : : : : : : : : + __ _____ _____ _____ + | | | | | | | + Channel B |_____| |_____| |_____| |__ + + : : : : : : : : : : : : + Event a b c d a b c d a b c d + + |<-------->| + one step + + +For more information, please see + http://en.wikipedia.org/wiki/Rotary_encoder + + +1. Events / state machine +------------------------- + +a) Rising edge on channel A, channel B in low state + This state is used to recognize a clockwise turn + +b) Rising edge on channel B, channel A in high state + When entering this state, the encoder is put into 'armed' state, + meaning that there it has seen half the way of a one-step transition. + +c) Falling edge on channel A, channel B in high state + This state is used to recognize a counter-clockwise turn + +d) Falling edge on channel B, channel A in low state + Parking position. If the encoder enters this state, a full transition + should have happend, unless it flipped back on half the way. The + 'armed' state tells us about that. + +2. Platform requirements +------------------------ + +As there is no hardware dependent call in this driver, the platform it is +used with must support gpiolib. Another requirement is that IRQs must be +able to fire on both edges. + + +3. Board integration +-------------------- + +To use this driver in your system, register a platform_device with the +name 'rotary-encoder' and associate the IRQs and some specific platform +data with it. + +struct rotary_encoder_platform_data is declared in +include/linux/rotary-encoder.h and needs to be filled with the number of +steps the encoder has and can carry information about externally inverted +signals (because of used invertig buffer or other reasons). + +Because GPIO to IRQ mapping is platform specific, this information must +be given in seperately to the driver. See the example below. + +---------<snip>--------- + +/* board support file example */ + +#include <linux/input.h> +#include <linux/rotary_encoder.h> + +#define GPIO_ROTARY_A 1 +#define GPIO_ROTARY_B 2 + +static struct rotary_encoder_platform_data my_rotary_encoder_info = { + .steps = 24, + .axis = ABS_X, + .gpio_a = GPIO_ROTARY_A, + .gpio_b = GPIO_ROTARY_B, + .inverted_a = 0, + .inverted_b = 0, +}; + +static struct platform_device rotary_encoder_device = { + .name = "rotary-encoder", + .id = 0, + .dev = { + .platform_data = &my_rotary_encoder_info, + } +}; + |