Commit | Line | Data |
---|---|---|
b1e064b8 CD |
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 | ||
9fb0f14e JB |
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 | ||
b1e064b8 CD |
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. |