On Wed, Dec 15, 2010 at 5:59 PM, Peter Hutterer <peter.hutterer@xxxxxxxxx> wrote: > On Tue, Dec 14, 2010 at 01:21:10PM -0800, Chase Douglas wrote: >> This commit adds the file Documentation/input/evdev-codes.txt. >> >> Signed-off-by: Chase Douglas <chase.douglas@xxxxxxxxxxxxx> >> --- >> Documentation/input/evdev-codes.txt | 160 +++++++++++++++++++++++++++++++++++ >> 1 files changed, 160 insertions(+), 0 deletions(-) >> create mode 100644 Documentation/input/evdev-codes.txt >> >> diff --git a/Documentation/input/evdev-codes.txt b/Documentation/input/evdev-codes.txt >> new file mode 100644 >> index 0000000..69c810f >> --- /dev/null >> +++ b/Documentation/input/evdev-codes.txt >> @@ -0,0 +1,160 @@ >> +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. >> + >> +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 keyboard and other key-like input events. >> +* EV_REL: >> + - Used to describe relative input events, e.g. moving the mouse 5 units to the >> + left. >> +* EV_ABS: >> + - Used to describe absolute input events, e.g. describing the coordinates of a >> + touch on a touchscreen. >> +* EV_MSC: >> + - Used to describe miscellaneous input events 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 Codes: >> +---------- >> +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 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 depressed, an event is >> +emitted with value 0. In general, KEY_<name> is used for keyboard keys, and >> +BTN_<name> is used for other types of momentary switch events. > > repeat keys have value 2, might want to add this here. > >> + >> +A few EV_KEY codes have special meanings: >> + >> +* BTN_TOOL_<name>, BTN_TOUCH: >> + - 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. For non-tablet devices, the tool is usually >> + BTN_TOUCH. > > BTN_TOUCH is used as proximity delimiter. e.g. wacom sends BTN_TOOL_PEN when > the pen comes into proximity and (in addition) BTN_TOUCH when the pen > actually touches the tablet. synaptics does the same IIRC except that it > doesn't support hovering, so BTN_TOOL_FINGER and BTN_TOUCH are always > set/unset in the same EV_SYN frame. This area is where most special cases are so somehow I think it deserves extra attention. Either in paragraphs or in sample events. There is the special historical case of touchscreen were BTN_TOOL_FINGER is not sent; which mostly works because most touchscreens do not support proximity/hover concepts. It can recommend not to use this approach and to use new ioctl() to convey touchscreen vs. touchpad information. Just an FYI: Synaptics is only sending BTN_TOUCH when pressure is >30 for what ever historical reason (and duplicating logic in xf86-input-synaptics) so it usually won't be in same sync window as BTN_TOOL_FINGER. I think its only touchpad left doing this so I think we may want to recommend best practice is to have BTN_TOOL_FINGER/*TAP and BTN_TOUCH track each other when hover is not supported. > > >> + >> +* 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 these codes and the BTN_TOOL_<name> and BTN_TOUCH codes are >> + orthogonal in purpose. A trackpad event generated by finger touches should >> + generate events for one code from each group. We should probably recommend a best practice here. Almost all drivers today send only 1 of BTN_TOOL_FINGER/*TAP today. For example, if 1 touch then BTN_TOOL_FINGER=1 and BTN_TOOL_DOUBLETAP=0 and during 2 touch then BTN_TOOL_FINGER=0 and BTN_TOOL_DOUBLETAP=1. I think at least 1 driver sends them concurrently today and you must look for highest finger count tool. I'm pretty sure historically a lot of the drivers sent them concurrently as well. >> + >> +* KEY_SUSPEND, KEY_POWER: >> + - These codes are reserved for the EV_PWR type. >> + >> +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. > > I'm not sure they're special, other than in X where we still treat them as > buttons by convention. It's good to describe them here, just in case, but I > wouldn't call that a "special meaning". > >> + >> +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_PRESSURE: >> + - Used to describe the pressure of a touch interaction on an input device. > > again, that's not really special IMO. it pretty much does what it says on > the box :) :-) It may be worth noting though that this is optional event. When it doesn't exist then BTN_TOUCH indicates touch. When it does exist then this is preferred indication of touch and should be used to debounced touches because of fact that majority of touchpad/touchscreen will start detecting contact while hovering. But then that leads to optional ABS_DISTANCE... Chris > > fwiw, I know that even though the documentation should be enough as-is, > having a few simple examples are always really useful to form the picture in > one's head. especially for newcomers who don't understand the basic concepts > yet. > > just something like: > "for example, an absolute device moving to a new position and pressing and > releasing a button may send events like this: > code value > ----------------------- > ABS_X 10 > ABS_Y 100 > BTN_LEFT 1 > EV_SYN SYN_REPORT > BTN_LEFT 0 > EV_SYN SYN_REPORT > > This immediately makes it obvious that buttons and axes can be mixed in the > same frame. you may want to also point to a few tools that show the event > stream (evtest comes to mind as the most widely distributed). > > Cheers, > Peter > >> +* ABS_DISTANCE: >> + - Used to describe the distance of a tool from an interaction surface. This >> + should only be used while the tool is in close proximity of the device. 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. >> + >> +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 key event used specifically for monitoring >> +power buttons and switches. The two codes in use are: >> + >> +* KEY_POWER: >> + - Used to denote a power button event. >> +* KEY_SUSPEND: >> + - Used to denote a suspend button event. >> -- >> 1.7.1 > -- To unsubscribe from this list: send the line "unsubscribe linux-input" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
