Re: [PATCH 2/4] Documentation: Add evdev type and code definitions

From: Chase Douglas
Date: Fri Jan 07 2011 - 15:39:48 EST

On 12/16/2010 09:56 AM, Chris Bagwell wrote:
> 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:
>>> +* 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.

I have attempted to capture this in the document.

>>> + - 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
> 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.

I tried to convey both points in the documentation for these codes, and
hopefully examples added to the document will help as well.

>>> +
>>> +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:
>>> +
>>> + - 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...

All of the evdev codes are optional, unless stated somewhere in here
otherwise like BTN_TOUCH (in my next revision). I feel this falls into
how userspace should use the codes, not the definition of the codes.


-- Chase
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at
Please read the FAQ at