| Message ID | 1302121172-16703-1-git-send-email-chase.douglas@canonical.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
Hi Chase, On Wed, Apr 06, 2011 at 04:19:31PM -0400, Chase Douglas wrote: > This commit adds the file Documentation/input/evdev-codes.txt. > > Cc: Henrik Rydberg <rydberg@euromail.se> > Cc: Peter Hutterer <peter.hutterer@who-t.net> > Cc: Nikolai Kondrashov <spbnick@gmail.com> > Cc: linux-input@vger.kernel.org > Cc: linux-kernel@vger.kernel.org > Acked-by: Henrik Rydberg <rydberg@euromail.se> > Signed-off-by: Chase Douglas <chase.douglas@canonical.com> > Signed-off-by: Chris Bagwell <chris@cnpbagwell.com> Thank you very much for doing this. I am very happy with the state of document at the moment and I want to apply it and get in .39. The only 2 changes I'd like (I'll do them on my side) is renaming the file from evdev-codes to event-codes and evdev protocol to input protocol since the data applicable not only to evdev but to entire input core. Thanks.
On Wed, Apr 06, 2011 at 04:19:31PM -0400, Chase Douglas wrote: > This commit adds the file Documentation/input/evdev-codes.txt. > > Cc: Henrik Rydberg <rydberg@euromail.se> > Cc: Peter Hutterer <peter.hutterer@who-t.net> > Cc: Nikolai Kondrashov <spbnick@gmail.com> > Cc: linux-input@vger.kernel.org > Cc: linux-kernel@vger.kernel.org > Acked-by: Henrik Rydberg <rydberg@euromail.se> > Signed-off-by: Chase Douglas <chase.douglas@canonical.com> > Signed-off-by: Chris Bagwell <chris@cnpbagwell.com> > --- > Documentation/input/evdev-codes.txt | 256 +++++++++++++++++++++++++++++++++++ > 1 files changed, 256 insertions(+), 0 deletions(-) > create mode 100644 Documentation/input/evdev-codes.txt > Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net> thanks! Cheers, Peter > diff --git a/Documentation/input/evdev-codes.txt b/Documentation/input/evdev-codes.txt > new file mode 100644 > index 0000000..b50bc49 > --- /dev/null > +++ b/Documentation/input/evdev-codes.txt > @@ -0,0 +1,256 @@ > +The evdev protocol uses a map of types and codes to express input device values > +to userspace. This document describes the types and codes and how and when they > +may be used. > + > +A single hardware event generates multiple input events. Each input event > +contains the new value of a single data item. A special event type, EV_SYN, is > +used to separate input events into packets of input data changes occurring at > +the same moment in time. In the following, the term "event" refers to a single > +input event encompassing a type, code, and value. > + > +The evdev protocol is a stateful protocol. Events are emitted only when values > +of evdev codes have changed. However, the state is maintained within the Linux > +input subsystem; drivers do not need to maintain the state and may attempt to > +emit unchanged values without harm. Userspace may obtain the current state of > +evdev code values using the EVIOCG* ioctls defined in linux/input.h. The evdev > +reports supported by a device are also provided by sysfs in > +class/input/event*/device/capabilities/, and the properties of a device are > +provided in class/input/event*/device/properties. > + > +Types: > +========== > +Types are groupings of codes under a logical input construct. Each type has a > +set of applicable codes to be used in generating events. See the Codes section > +for details on valid codes for each type. > + > +* EV_SYN: > + - Used as markers to separate events. Events may be separated in time or in > + space, such as with the multitouch protocol. > + > +* EV_KEY: > + - Used to describe state changes of keyboards, buttons, or other key-like > + devices. > + > +* EV_REL: > + - Used to describe relative axis value changes, e.g. moving the mouse 5 units > + to the left. > + > +* EV_ABS: > + - Used to describe absolute axis value changes, e.g. describing the > + coordinates of a touch on a touchscreen. > + > +* EV_MSC: > + - Used to describe miscellaneous input data that do not fit into other types. > + > +* EV_SW: > + - Used to describe binary state input switches. > + > +* EV_LED: > + - Used to turn LEDs on devices on and off. > + > +* EV_SND: > + - Used to output sound to devices. > + > +* EV_REP: > + - Used for autorepeating devices. > + > +* EV_FF: > + - Used to send force feedback commands to an input device. > + > +* EV_PWR: > + - A special type for power button and switch input. > + > +* EV_FF_STATUS: > + - Used to receive force feedback device status. > + > +Codes: > +========== > +Codes define the precise type of event. > + > +EV_SYN: > +---------- > +EV_SYN event values are undefined. Their usage is defined only by when they are > +sent in the evdev event stream. > + > +* SYN_REPORT: > + - Used to synchronize and separate events into packets of input data changes > + occurring at the same moment in time. For example, motion of a mouse may set > + the REL_X and REL_Y values for one motion, then emit a SYN_REPORT. The next > + motion will emit more REL_X and REL_Y values and send another SYN_REPORT. > + > +* SYN_CONFIG: > + - TBD > + > +* SYN_MT_REPORT: > + - Used to synchronize and separate touch events. See the > + multi-touch-protocol.txt document for more information. > + > +EV_KEY: > +---------- > +EV_KEY events take the form KEY_<name> or BTN_<name>. For example, KEY_A is used > +to represent the 'A' key on a keyboard. When a key is depressed, an event with > +the key's code is emitted with value 1. When the key is released, an event is > +emitted with value 0. Some hardware send events when a key is repeated. These > +events have a value of 2. In general, KEY_<name> is used for keyboard keys, and > +BTN_<name> is used for other types of momentary switch events. > + > +A few EV_KEY codes have special meanings: > + > +* BTN_TOOL_<name>: > + - These codes are used in conjunction with input trackpads, tablets, and > + touchscreens. These devices may be used with fingers, pens, or other tools. > + When an event occurs and a tool is used, the corresponding BTN_TOOL_<name> > + code should be set to a value of 1. When the tool is no longer interacting > + with the input device, the BTN_TOOL_<name> code should be reset to 0. All > + trackpads, tablets, and touchscreens should use at least one BTN_TOOL_<name> > + code when events are generated. > + > +* BTN_TOUCH: > + BTN_TOUCH is used for touch contact. While an input tool is determined to be > + within meaningful physical contact, the value of this property must be set > + to 1. Meaningful physical contact may mean any contact, or it may mean > + contact conditioned by an implementation defined property. For example, a > + touchpad may set the value to 1 only when the touch pressure rises above a > + certain value. BTN_TOUCH may be combined with BTN_TOOL_<name> codes. For > + example, a pen tablet may set BTN_TOOL_PEN to 1 and BTN_TOUCH to 0 while the > + pen is hovering over but not touching the tablet surface. > + > +Note: For appropriate function of the legacy mousedev emulation driver, > +BTN_TOUCH must be the first evdev code emitted in a synchronization frame. > + > +Note: Historically a touch device with BTN_TOOL_FINGER and BTN_TOUCH was > +interpreted as a touchpad by userspace, while a similar device without > +BTN_TOOL_FINGER was interpreted as a touchscreen. For backwards compatibility > +with current userspace it is recommended to follow this distinction. In the > +future, this distinction will be deprecated and the device properties ioctl > +EVIOCGPROP, defined in linux/input.h, will be used to convey the device type. > + > +* BTN_TOOL_FINGER, BTN_TOOL_DOUBLETAP, BTN_TOOL_TRIPLETAP, BTN_TOOL_QUADTAP: > + - These codes denote one, two, three, and four finger interaction on a > + trackpad or touchscreen. For example, if the user uses two fingers and moves > + them on the touchpad in an effort to scroll content on screen, > + BTN_TOOL_DOUBLETAP should be set to value 1 for the duration of the motion. > + Note that all BTN_TOOL_<name> codes and the BTN_TOUCH code are orthogonal in > + purpose. A trackpad event generated by finger touches should generate events > + for one code from each group. At most only one of these BTN_TOOL_<name> > + codes should have a value of 1 during any synchronization frame. > + > +Note: Historically some drivers emitted multiple of the finger count codes with > +a value of 1 in the same synchronization frame. This usage is deprecated. > + > +Note: In multitouch drivers, the input_mt_report_finger_count() function should > +be used to emit these codes. Please see multi-touch-protocol.txt for details. > + > +EV_REL: > +---------- > +EV_REL events describe relative changes in a property. For example, a mouse may > +move to the left by a certain number of units, but its absolute position in > +space is unknown. If the absolute position is known, EV_ABS codes should be used > +instead of EV_REL codes. > + > +A few EV_REL codes have special meanings: > + > +* REL_WHEEL, REL_HWHEEL: > + - These codes are used for vertical and horizontal scroll wheels, > + respectively. > + > +EV_ABS: > +---------- > +EV_ABS events describe absolute changes in a property. For example, a touchpad > +may emit coordinates for a touch location. > + > +A few EV_ABS codes have special meanings: > + > +* ABS_DISTANCE: > + - Used to describe the distance of a tool from an interaction surface. This > + event should only be emitted while the tool is hovering, meaning in close > + proximity of the device and while the value of the BTN_TOUCH code is 0. If > + the input device may be used freely in three dimensions, consider ABS_Z > + instead. > + > +* ABS_MT_<name>: > + - Used to describe multitouch input events. Please see > + multi-touch-protocol.txt for details. > + > +EV_SW: > +---------- > +EV_SW events describe stateful binary switches. For example, the SW_LID code is > +used to denote when a laptop lid is closed. > + > +Upon binding to a device or resuming from suspend, a driver must report the > +the current switch state. This ensures that the device, kernel, and userspace > +state is in sync. > + > +Upon resume, if the switch state is the same as before suspend, then the input > +subsystem will filter out the duplicate switch state reports. The driver does > +not need to keep the state of the switch at any time. > + > +EV_MSC: > +---------- > +EV_MSC events are used for input and output events that do not fall under other > +categories. > + > +EV_LED: > +---------- > +EV_LED events are used for input and output to set and query the state of > +various LEDs on devices. > + > +EV_REP: > +---------- > +EV_REP events are used for specifying autorepeating events. > + > +EV_SND: > +---------- > +EV_SND events are used for sending sound commands to simple sound output > +devices. > + > +EV_FF: > +---------- > +EV_FF events are used to initialize a force feedback capable device and to cause > +such device to feedback. > + > +EV_PWR: > +---------- > +EV_PWR events are a special type of event used specifically for power > +mangement. Its usage is not well defined. To be addressed later. > + > +Guidelines: > +========== > +The guidelines below ensure proper single-touch and multi-finger functionality. > +For multi-touch functionality, see the multi-touch-protocol.txt document for > +more information. > + > +Mice: > +---------- > +REL_{X,Y} must be reported when the mouse moves. BTN_LEFT must be used to report > +the primary button press. BTN_{MIDDLE,RIGHT,4,5,etc.} should be used to report > +further buttons of the device. REL_WHEEL and REL_HWHEEL should be used to report > +scroll wheel events where available. > + > +Touchscreens: > +---------- > +ABS_{X,Y} must be reported with the location of the touch. BTN_TOUCH must be > +used to report when a touch is active on the screen. > +BTN_{MOUSE,LEFT,MIDDLE,RIGHT} must not be reported as the result of touch > +contact. BTN_TOOL_<name> events should be reported where possible. > + > +Trackpads: > +---------- > +Legacy trackpads that only provide relative position information must report > +events like mice described above. > + > +Trackpads that provide absolute touch position must report ABS_{X,Y} for the > +location of the touch. BTN_TOUCH should be used to report when a touch is active > +on the trackpad. Where multi-finger support is available, BTN_TOOL_<name> should > +be used to report the number of touches active on the trackpad. > + > +Tablets: > +---------- > +BTN_TOOL_<name> events must be reported when a stylus or other tool is active on > +the tablet. ABS_{X,Y} must be reported with the location of the tool. BTN_TOUCH > +should be used to report when the tool is in contact with the tablet. > +BTN_{STYLUS,STYLUS2} should be used to report buttons on the tool itself. Any > +button may be used for buttons on the tablet except BTN_{MOUSE,LEFT}. > +BTN_{0,1,2,etc} are good generic codes for unlabeled buttons. Do not use > +meaningful buttons, like BTN_FORWARD, unless the button is labeled for that > +purpose on the device. > -- > 1.7.4.1 > -- To unsubscribe from this list: send the line "unsubscribe linux-input" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
diff --git a/Documentation/input/evdev-codes.txt b/Documentation/input/evdev-codes.txt new file mode 100644 index 0000000..b50bc49 --- /dev/null +++ b/Documentation/input/evdev-codes.txt @@ -0,0 +1,256 @@ +The evdev protocol uses a map of types and codes to express input device values +to userspace. This document describes the types and codes and how and when they +may be used. + +A single hardware event generates multiple input events. Each input event +contains the new value of a single data item. A special event type, EV_SYN, is +used to separate input events into packets of input data changes occurring at +the same moment in time. In the following, the term "event" refers to a single +input event encompassing a type, code, and value. + +The evdev protocol is a stateful protocol. Events are emitted only when values +of evdev codes have changed. However, the state is maintained within the Linux +input subsystem; drivers do not need to maintain the state and may attempt to +emit unchanged values without harm. Userspace may obtain the current state of +evdev code values using the EVIOCG* ioctls defined in linux/input.h. The evdev +reports supported by a device are also provided by sysfs in +class/input/event*/device/capabilities/, and the properties of a device are +provided in class/input/event*/device/properties. + +Types: +========== +Types are groupings of codes under a logical input construct. Each type has a +set of applicable codes to be used in generating events. See the Codes section +for details on valid codes for each type. + +* EV_SYN: + - Used as markers to separate events. Events may be separated in time or in + space, such as with the multitouch protocol. + +* EV_KEY: + - Used to describe state changes of keyboards, buttons, or other key-like + devices. + +* EV_REL: + - Used to describe relative axis value changes, e.g. moving the mouse 5 units + to the left. + +* EV_ABS: + - Used to describe absolute axis value changes, e.g. describing the + coordinates of a touch on a touchscreen. + +* EV_MSC: + - Used to describe miscellaneous input data that do not fit into other types. + +* EV_SW: + - Used to describe binary state input switches. + +* EV_LED: + - Used to turn LEDs on devices on and off. + +* EV_SND: + - Used to output sound to devices. + +* EV_REP: + - Used for autorepeating devices. + +* EV_FF: + - Used to send force feedback commands to an input device. + +* EV_PWR: + - A special type for power button and switch input. + +* EV_FF_STATUS: + - Used to receive force feedback device status. + +Codes: +========== +Codes define the precise type of event. + +EV_SYN: +---------- +EV_SYN event values are undefined. Their usage is defined only by when they are +sent in the evdev event stream. + +* SYN_REPORT: + - Used to synchronize and separate events into packets of input data changes + occurring at the same moment in time. For example, motion of a mouse may set + the REL_X and REL_Y values for one motion, then emit a SYN_REPORT. The next + motion will emit more REL_X and REL_Y values and send another SYN_REPORT. + +* SYN_CONFIG: + - TBD + +* SYN_MT_REPORT: + - Used to synchronize and separate touch events. See the + multi-touch-protocol.txt document for more information. + +EV_KEY: +---------- +EV_KEY events take the form KEY_<name> or BTN_<name>. For example, KEY_A is used +to represent the 'A' key on a keyboard. When a key is depressed, an event with +the key's code is emitted with value 1. When the key is released, an event is +emitted with value 0. Some hardware send events when a key is repeated. These +events have a value of 2. In general, KEY_<name> is used for keyboard keys, and +BTN_<name> is used for other types of momentary switch events. + +A few EV_KEY codes have special meanings: + +* BTN_TOOL_<name>: + - These codes are used in conjunction with input trackpads, tablets, and + touchscreens. These devices may be used with fingers, pens, or other tools. + When an event occurs and a tool is used, the corresponding BTN_TOOL_<name> + code should be set to a value of 1. When the tool is no longer interacting + with the input device, the BTN_TOOL_<name> code should be reset to 0. All + trackpads, tablets, and touchscreens should use at least one BTN_TOOL_<name> + code when events are generated. + +* BTN_TOUCH: + BTN_TOUCH is used for touch contact. While an input tool is determined to be + within meaningful physical contact, the value of this property must be set + to 1. Meaningful physical contact may mean any contact, or it may mean + contact conditioned by an implementation defined property. For example, a + touchpad may set the value to 1 only when the touch pressure rises above a + certain value. BTN_TOUCH may be combined with BTN_TOOL_<name> codes. For + example, a pen tablet may set BTN_TOOL_PEN to 1 and BTN_TOUCH to 0 while the + pen is hovering over but not touching the tablet surface. + +Note: For appropriate function of the legacy mousedev emulation driver, +BTN_TOUCH must be the first evdev code emitted in a synchronization frame. + +Note: Historically a touch device with BTN_TOOL_FINGER and BTN_TOUCH was +interpreted as a touchpad by userspace, while a similar device without +BTN_TOOL_FINGER was interpreted as a touchscreen. For backwards compatibility +with current userspace it is recommended to follow this distinction. In the +future, this distinction will be deprecated and the device properties ioctl +EVIOCGPROP, defined in linux/input.h, will be used to convey the device type. + +* BTN_TOOL_FINGER, BTN_TOOL_DOUBLETAP, BTN_TOOL_TRIPLETAP, BTN_TOOL_QUADTAP: + - These codes denote one, two, three, and four finger interaction on a + trackpad or touchscreen. For example, if the user uses two fingers and moves + them on the touchpad in an effort to scroll content on screen, + BTN_TOOL_DOUBLETAP should be set to value 1 for the duration of the motion. + Note that all BTN_TOOL_<name> codes and the BTN_TOUCH code are orthogonal in + purpose. A trackpad event generated by finger touches should generate events + for one code from each group. At most only one of these BTN_TOOL_<name> + codes should have a value of 1 during any synchronization frame. + +Note: Historically some drivers emitted multiple of the finger count codes with +a value of 1 in the same synchronization frame. This usage is deprecated. + +Note: In multitouch drivers, the input_mt_report_finger_count() function should +be used to emit these codes. Please see multi-touch-protocol.txt for details. + +EV_REL: +---------- +EV_REL events describe relative changes in a property. For example, a mouse may +move to the left by a certain number of units, but its absolute position in +space is unknown. If the absolute position is known, EV_ABS codes should be used +instead of EV_REL codes. + +A few EV_REL codes have special meanings: + +* REL_WHEEL, REL_HWHEEL: + - These codes are used for vertical and horizontal scroll wheels, + respectively. + +EV_ABS: +---------- +EV_ABS events describe absolute changes in a property. For example, a touchpad +may emit coordinates for a touch location. + +A few EV_ABS codes have special meanings: + +* ABS_DISTANCE: + - Used to describe the distance of a tool from an interaction surface. This + event should only be emitted while the tool is hovering, meaning in close + proximity of the device and while the value of the BTN_TOUCH code is 0. If + the input device may be used freely in three dimensions, consider ABS_Z + instead. + +* ABS_MT_<name>: + - Used to describe multitouch input events. Please see + multi-touch-protocol.txt for details. + +EV_SW: +---------- +EV_SW events describe stateful binary switches. For example, the SW_LID code is +used to denote when a laptop lid is closed. + +Upon binding to a device or resuming from suspend, a driver must report the +the current switch state. This ensures that the device, kernel, and userspace +state is in sync. + +Upon resume, if the switch state is the same as before suspend, then the input +subsystem will filter out the duplicate switch state reports. The driver does +not need to keep the state of the switch at any time. + +EV_MSC: +---------- +EV_MSC events are used for input and output events that do not fall under other +categories. + +EV_LED: +---------- +EV_LED events are used for input and output to set and query the state of +various LEDs on devices. + +EV_REP: +---------- +EV_REP events are used for specifying autorepeating events. + +EV_SND: +---------- +EV_SND events are used for sending sound commands to simple sound output +devices. + +EV_FF: +---------- +EV_FF events are used to initialize a force feedback capable device and to cause +such device to feedback. + +EV_PWR: +---------- +EV_PWR events are a special type of event used specifically for power +mangement. Its usage is not well defined. To be addressed later. + +Guidelines: +========== +The guidelines below ensure proper single-touch and multi-finger functionality. +For multi-touch functionality, see the multi-touch-protocol.txt document for +more information. + +Mice: +---------- +REL_{X,Y} must be reported when the mouse moves. BTN_LEFT must be used to report +the primary button press. BTN_{MIDDLE,RIGHT,4,5,etc.} should be used to report +further buttons of the device. REL_WHEEL and REL_HWHEEL should be used to report +scroll wheel events where available. + +Touchscreens: +---------- +ABS_{X,Y} must be reported with the location of the touch. BTN_TOUCH must be +used to report when a touch is active on the screen. +BTN_{MOUSE,LEFT,MIDDLE,RIGHT} must not be reported as the result of touch +contact. BTN_TOOL_<name> events should be reported where possible. + +Trackpads: +---------- +Legacy trackpads that only provide relative position information must report +events like mice described above. + +Trackpads that provide absolute touch position must report ABS_{X,Y} for the +location of the touch. BTN_TOUCH should be used to report when a touch is active +on the trackpad. Where multi-finger support is available, BTN_TOOL_<name> should +be used to report the number of touches active on the trackpad. + +Tablets: +---------- +BTN_TOOL_<name> events must be reported when a stylus or other tool is active on +the tablet. ABS_{X,Y} must be reported with the location of the tool. BTN_TOUCH +should be used to report when the tool is in contact with the tablet. +BTN_{STYLUS,STYLUS2} should be used to report buttons on the tool itself. Any +button may be used for buttons on the tablet except BTN_{MOUSE,LEFT}. +BTN_{0,1,2,etc} are good generic codes for unlabeled buttons. Do not use +meaningful buttons, like BTN_FORWARD, unless the button is labeled for that +purpose on the device.