diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2011-04-18 16:29:03 -0400 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2011-04-18 16:29:03 -0400 |
commit | 96fd2d57b8252e16dfacf8941f7a74a6119197f5 (patch) | |
tree | 095269c51def85fa1be27bb20ec8e562bdc5a564 /Documentation | |
parent | 8a83f33100c691f5a576dba259cc05502dc358f0 (diff) | |
parent | c36b58e8a9112017c2bcc322cc98e71241814303 (diff) |
Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input
* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input:
Input: xen-kbdfront - fix mouse getting stuck after save/restore
Input: estimate number of events per packet
Input: evdev - indicate buffer overrun with SYN_DROPPED
Input: document event types and codes and their intended use
Input: add KEY_IMAGES specifically for AL Image Browser
Input: twl4030_keypad - fix potential NULL dereference in twl4030_kp_probe()
Input: h3600_ts - fix error handling at connect
Input: twl4030_keypad - avoid potential NULL-pointer dereference
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/input/event-codes.txt | 262 |
1 files changed, 262 insertions, 0 deletions
diff --git a/Documentation/input/event-codes.txt b/Documentation/input/event-codes.txt new file mode 100644 index 00000000000..23fcb05175b --- /dev/null +++ b/Documentation/input/event-codes.txt | |||
@@ -0,0 +1,262 @@ | |||
1 | The input protocol uses a map of types and codes to express input device values | ||
2 | to userspace. This document describes the types and codes and how and when they | ||
3 | may be used. | ||
4 | |||
5 | A single hardware event generates multiple input events. Each input event | ||
6 | contains the new value of a single data item. A special event type, EV_SYN, is | ||
7 | used to separate input events into packets of input data changes occurring at | ||
8 | the same moment in time. In the following, the term "event" refers to a single | ||
9 | input event encompassing a type, code, and value. | ||
10 | |||
11 | The input protocol is a stateful protocol. Events are emitted only when values | ||
12 | of event codes have changed. However, the state is maintained within the Linux | ||
13 | input subsystem; drivers do not need to maintain the state and may attempt to | ||
14 | emit unchanged values without harm. Userspace may obtain the current state of | ||
15 | event code values using the EVIOCG* ioctls defined in linux/input.h. The event | ||
16 | reports supported by a device are also provided by sysfs in | ||
17 | class/input/event*/device/capabilities/, and the properties of a device are | ||
18 | provided in class/input/event*/device/properties. | ||
19 | |||
20 | Types: | ||
21 | ========== | ||
22 | Types are groupings of codes under a logical input construct. Each type has a | ||
23 | set of applicable codes to be used in generating events. See the Codes section | ||
24 | for details on valid codes for each type. | ||
25 | |||
26 | * EV_SYN: | ||
27 | - Used as markers to separate events. Events may be separated in time or in | ||
28 | space, such as with the multitouch protocol. | ||
29 | |||
30 | * EV_KEY: | ||
31 | - Used to describe state changes of keyboards, buttons, or other key-like | ||
32 | devices. | ||
33 | |||
34 | * EV_REL: | ||
35 | - Used to describe relative axis value changes, e.g. moving the mouse 5 units | ||
36 | to the left. | ||
37 | |||
38 | * EV_ABS: | ||
39 | - Used to describe absolute axis value changes, e.g. describing the | ||
40 | coordinates of a touch on a touchscreen. | ||
41 | |||
42 | * EV_MSC: | ||
43 | - Used to describe miscellaneous input data that do not fit into other types. | ||
44 | |||
45 | * EV_SW: | ||
46 | - Used to describe binary state input switches. | ||
47 | |||
48 | * EV_LED: | ||
49 | - Used to turn LEDs on devices on and off. | ||
50 | |||
51 | * EV_SND: | ||
52 | - Used to output sound to devices. | ||
53 | |||
54 | * EV_REP: | ||
55 | - Used for autorepeating devices. | ||
56 | |||
57 | * EV_FF: | ||
58 | - Used to send force feedback commands to an input device. | ||
59 | |||
60 | * EV_PWR: | ||
61 | - A special type for power button and switch input. | ||
62 | |||
63 | * EV_FF_STATUS: | ||
64 | - Used to receive force feedback device status. | ||
65 | |||
66 | Codes: | ||
67 | ========== | ||
68 | Codes define the precise type of event. | ||
69 | |||
70 | EV_SYN: | ||
71 | ---------- | ||
72 | EV_SYN event values are undefined. Their usage is defined only by when they are | ||
73 | sent in the evdev event stream. | ||
74 | |||
75 | * SYN_REPORT: | ||
76 | - Used to synchronize and separate events into packets of input data changes | ||
77 | occurring at the same moment in time. For example, motion of a mouse may set | ||
78 | the REL_X and REL_Y values for one motion, then emit a SYN_REPORT. The next | ||
79 | motion will emit more REL_X and REL_Y values and send another SYN_REPORT. | ||
80 | |||
81 | * SYN_CONFIG: | ||
82 | - TBD | ||
83 | |||
84 | * SYN_MT_REPORT: | ||
85 | - Used to synchronize and separate touch events. See the | ||
86 | multi-touch-protocol.txt document for more information. | ||
87 | |||
88 | * SYN_DROPPED: | ||
89 | - Used to indicate buffer overrun in the evdev client's event queue. | ||
90 | Client should ignore all events up to and including next SYN_REPORT | ||
91 | event and query the device (using EVIOCG* ioctls) to obtain its | ||
92 | current state. | ||
93 | |||
94 | EV_KEY: | ||
95 | ---------- | ||
96 | EV_KEY events take the form KEY_<name> or BTN_<name>. For example, KEY_A is used | ||
97 | to represent the 'A' key on a keyboard. When a key is depressed, an event with | ||
98 | the key's code is emitted with value 1. When the key is released, an event is | ||
99 | emitted with value 0. Some hardware send events when a key is repeated. These | ||
100 | events have a value of 2. In general, KEY_<name> is used for keyboard keys, and | ||
101 | BTN_<name> is used for other types of momentary switch events. | ||
102 | |||
103 | A few EV_KEY codes have special meanings: | ||
104 | |||
105 | * BTN_TOOL_<name>: | ||
106 | - These codes are used in conjunction with input trackpads, tablets, and | ||
107 | touchscreens. These devices may be used with fingers, pens, or other tools. | ||
108 | When an event occurs and a tool is used, the corresponding BTN_TOOL_<name> | ||
109 | code should be set to a value of 1. When the tool is no longer interacting | ||
110 | with the input device, the BTN_TOOL_<name> code should be reset to 0. All | ||
111 | trackpads, tablets, and touchscreens should use at least one BTN_TOOL_<name> | ||
112 | code when events are generated. | ||
113 | |||
114 | * BTN_TOUCH: | ||
115 | BTN_TOUCH is used for touch contact. While an input tool is determined to be | ||
116 | within meaningful physical contact, the value of this property must be set | ||
117 | to 1. Meaningful physical contact may mean any contact, or it may mean | ||
118 | contact conditioned by an implementation defined property. For example, a | ||
119 | touchpad may set the value to 1 only when the touch pressure rises above a | ||
120 | certain value. BTN_TOUCH may be combined with BTN_TOOL_<name> codes. For | ||
121 | example, a pen tablet may set BTN_TOOL_PEN to 1 and BTN_TOUCH to 0 while the | ||
122 | pen is hovering over but not touching the tablet surface. | ||
123 | |||
124 | Note: For appropriate function of the legacy mousedev emulation driver, | ||
125 | BTN_TOUCH must be the first evdev code emitted in a synchronization frame. | ||
126 | |||
127 | Note: Historically a touch device with BTN_TOOL_FINGER and BTN_TOUCH was | ||
128 | interpreted as a touchpad by userspace, while a similar device without | ||
129 | BTN_TOOL_FINGER was interpreted as a touchscreen. For backwards compatibility | ||
130 | with current userspace it is recommended to follow this distinction. In the | ||
131 | future, this distinction will be deprecated and the device properties ioctl | ||
132 | EVIOCGPROP, defined in linux/input.h, will be used to convey the device type. | ||
133 | |||
134 | * BTN_TOOL_FINGER, BTN_TOOL_DOUBLETAP, BTN_TOOL_TRIPLETAP, BTN_TOOL_QUADTAP: | ||
135 | - These codes denote one, two, three, and four finger interaction on a | ||
136 | trackpad or touchscreen. For example, if the user uses two fingers and moves | ||
137 | them on the touchpad in an effort to scroll content on screen, | ||
138 | BTN_TOOL_DOUBLETAP should be set to value 1 for the duration of the motion. | ||
139 | Note that all BTN_TOOL_<name> codes and the BTN_TOUCH code are orthogonal in | ||
140 | purpose. A trackpad event generated by finger touches should generate events | ||
141 | for one code from each group. At most only one of these BTN_TOOL_<name> | ||
142 | codes should have a value of 1 during any synchronization frame. | ||
143 | |||
144 | Note: Historically some drivers emitted multiple of the finger count codes with | ||
145 | a value of 1 in the same synchronization frame. This usage is deprecated. | ||
146 | |||
147 | Note: In multitouch drivers, the input_mt_report_finger_count() function should | ||
148 | be used to emit these codes. Please see multi-touch-protocol.txt for details. | ||
149 | |||
150 | EV_REL: | ||
151 | ---------- | ||
152 | EV_REL events describe relative changes in a property. For example, a mouse may | ||
153 | move to the left by a certain number of units, but its absolute position in | ||
154 | space is unknown. If the absolute position is known, EV_ABS codes should be used | ||
155 | instead of EV_REL codes. | ||
156 | |||
157 | A few EV_REL codes have special meanings: | ||
158 | |||
159 | * REL_WHEEL, REL_HWHEEL: | ||
160 | - These codes are used for vertical and horizontal scroll wheels, | ||
161 | respectively. | ||
162 | |||
163 | EV_ABS: | ||
164 | ---------- | ||
165 | EV_ABS events describe absolute changes in a property. For example, a touchpad | ||
166 | may emit coordinates for a touch location. | ||
167 | |||
168 | A few EV_ABS codes have special meanings: | ||
169 | |||
170 | * ABS_DISTANCE: | ||
171 | - Used to describe the distance of a tool from an interaction surface. This | ||
172 | event should only be emitted while the tool is hovering, meaning in close | ||
173 | proximity of the device and while the value of the BTN_TOUCH code is 0. If | ||
174 | the input device may be used freely in three dimensions, consider ABS_Z | ||
175 | instead. | ||
176 | |||
177 | * ABS_MT_<name>: | ||
178 | - Used to describe multitouch input events. Please see | ||
179 | multi-touch-protocol.txt for details. | ||
180 | |||
181 | EV_SW: | ||
182 | ---------- | ||
183 | EV_SW events describe stateful binary switches. For example, the SW_LID code is | ||
184 | used to denote when a laptop lid is closed. | ||
185 | |||
186 | Upon binding to a device or resuming from suspend, a driver must report | ||
187 | the current switch state. This ensures that the device, kernel, and userspace | ||
188 | state is in sync. | ||
189 | |||
190 | Upon resume, if the switch state is the same as before suspend, then the input | ||
191 | subsystem will filter out the duplicate switch state reports. The driver does | ||
192 | not need to keep the state of the switch at any time. | ||
193 | |||
194 | EV_MSC: | ||
195 | ---------- | ||
196 | EV_MSC events are used for input and output events that do not fall under other | ||
197 | categories. | ||
198 | |||
199 | EV_LED: | ||
200 | ---------- | ||
201 | EV_LED events are used for input and output to set and query the state of | ||
202 | various LEDs on devices. | ||
203 | |||
204 | EV_REP: | ||
205 | ---------- | ||
206 | EV_REP events are used for specifying autorepeating events. | ||
207 | |||
208 | EV_SND: | ||
209 | ---------- | ||
210 | EV_SND events are used for sending sound commands to simple sound output | ||
211 | devices. | ||
212 | |||
213 | EV_FF: | ||
214 | ---------- | ||
215 | EV_FF events are used to initialize a force feedback capable device and to cause | ||
216 | such device to feedback. | ||
217 | |||
218 | EV_PWR: | ||
219 | ---------- | ||
220 | EV_PWR events are a special type of event used specifically for power | ||
221 | mangement. Its usage is not well defined. To be addressed later. | ||
222 | |||
223 | Guidelines: | ||
224 | ========== | ||
225 | The guidelines below ensure proper single-touch and multi-finger functionality. | ||
226 | For multi-touch functionality, see the multi-touch-protocol.txt document for | ||
227 | more information. | ||
228 | |||
229 | Mice: | ||
230 | ---------- | ||
231 | REL_{X,Y} must be reported when the mouse moves. BTN_LEFT must be used to report | ||
232 | the primary button press. BTN_{MIDDLE,RIGHT,4,5,etc.} should be used to report | ||
233 | further buttons of the device. REL_WHEEL and REL_HWHEEL should be used to report | ||
234 | scroll wheel events where available. | ||
235 | |||
236 | Touchscreens: | ||
237 | ---------- | ||
238 | ABS_{X,Y} must be reported with the location of the touch. BTN_TOUCH must be | ||
239 | used to report when a touch is active on the screen. | ||
240 | BTN_{MOUSE,LEFT,MIDDLE,RIGHT} must not be reported as the result of touch | ||
241 | contact. BTN_TOOL_<name> events should be reported where possible. | ||
242 | |||
243 | Trackpads: | ||
244 | ---------- | ||
245 | Legacy trackpads that only provide relative position information must report | ||
246 | events like mice described above. | ||
247 | |||
248 | Trackpads that provide absolute touch position must report ABS_{X,Y} for the | ||
249 | location of the touch. BTN_TOUCH should be used to report when a touch is active | ||
250 | on the trackpad. Where multi-finger support is available, BTN_TOOL_<name> should | ||
251 | be used to report the number of touches active on the trackpad. | ||
252 | |||
253 | Tablets: | ||
254 | ---------- | ||
255 | BTN_TOOL_<name> events must be reported when a stylus or other tool is active on | ||
256 | the tablet. ABS_{X,Y} must be reported with the location of the tool. BTN_TOUCH | ||
257 | should be used to report when the tool is in contact with the tablet. | ||
258 | BTN_{STYLUS,STYLUS2} should be used to report buttons on the tool itself. Any | ||
259 | button may be used for buttons on the tablet except BTN_{MOUSE,LEFT}. | ||
260 | BTN_{0,1,2,etc} are good generic codes for unlabeled buttons. Do not use | ||
261 | meaningful buttons, like BTN_FORWARD, unless the button is labeled for that | ||
262 | purpose on the device. | ||