tablet: add touch arbitration

So far we've relied on the wacom kernel module to do touch arbitration for us
but that won't be the case in upcoming kernels. Implement touch arbitration in
userspace by pairing the two devices and suspending the touch device whenever
a tool comes into proximity.

In the future more sophisticated arbitration can be done (e.g. only touches
which are close to the pen) but let's burn that bridge when we have to cross
it.

Note that touch arbitration is "device suspend light", i.e. we leave the
device enabled and the fd is active. Tablet interactions are comparatively
short-lived, so closing the fd and asking logind for a new one every time the
pen changes proximity is suboptimal. Instead, we just keep a boolean around
and discard all events while it is set.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Jason Gerecke <jason.gerecke@wacom.com>

1 files changed, 13 insertions, 0 deletions

diff --git a/doc/tablet-support.dox b/doc/tablet-support.dox
index cda0d70..19c5d8f 100644
--- a/doc/tablet-support.dox
+++ b/doc/tablet-support.dox
@@ -331,4 +331,17 @@ button and ring events on the right. When one of the three mode toggle
 buttons on the right is pressed, the right mode switches to that button's
 mode but the left mode remains unchanged.
 
+@section tablet-touch-arbitration Tablet touch arbitration
+
+"Touch arbitration" is the terminology used when touch events are suppressed
+while the pen is in proximity. Since it is almost impossible to use a stylus
+or other tool without triggering touches with the hand holding the tool,
+touch arbitration serves to reduce the number of accidental inputs.
+The wacom kernel driver currently provides touch arbitration but for other
+devices arbitration has to be done in userspace.
+
+libinput uses the @ref libinput_device_group to decide on touch arbitration
+and automatically discards touch events whenever a tool is in proximity.
+The exact behavior is device-dependent.
+
 */